Skip to content

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

docs: show nested parameter schemas on toolkit detail pages

Sushmithamallesh267200c0ef9a
diff --git a/docs/app/(home)/toolkits/[[...slug]]/page.tsx b/docs/app/(home)/toolkits/[[...slug]]/page.tsx
index 7ee4cf284..550f46f8c 100644
--- a/docs/app/(home)/toolkits/[[...slug]]/page.tsx
+++ b/docs/app/(home)/toolkits/[[...slug]]/page.tsx
@@ -12,9 +12,54 @@ import type { Toolkit, Tool, Trigger } from '@/types/toolkit';
const API_BASE = process.env.COMPOSIO_API_BASE || 'https://backend.composio.dev/api/v3';
const API_KEY = process.env.COMPOSIO_API_KEY;
+// Add required flag to each property based on the required array
+// Preserves nested properties/items for object and array types
+function processParams(props: any, requiredList: string[]): Record<string, any> | undefined {
+ if (!props || typeof props !== 'object') return undefined;
+ const result: Record<string, any> = {};
+ for (const [key, value] of Object.entries(props)) {
+ if (typeof value === 'object' && value !== null) {
+ const param = value as any;
+ result[key] = {
+ type: param.type,
+ description: param.description,
+ default: param.default,
+ example: param.example,
+ enum: param.enum,
+ required: requiredList.includes(key),
+ ...(param.properties ? { properties: param.properties } : {}),
+ ...(param.required ? { requiredFields: param.required } : {}),
+ ...(param.items ? { items: param.items } : {}),
+ };
+ }
+ }
+ return Object.keys(result).length > 0 ? result : undefined;
+}
+
+function toolFromApi(tool: any): Tool {
+ const inputSchema = tool.input_parameters || tool.parameters;
+ const outputSchema = tool.output_parameters || tool.response;
+
+ const inputProps = inputSchema?.properties || inputSchema;
+ const inputRequired = inputSchema?.required || [];
+ const outputProps = outputSchema?.properties || outputSchema;
+ const outputRequired = outputSchema?.required || [];
+
+ return {
+ slug: tool.slug || '',
+ name: tool.name || tool.display_name || tool.slug || '',
+ description: tool.description || '',
+ input_parameters: processParams(inputProps, inputRequired),
+ output_parameters: processParams(outputProps, outputRequired),
+ scopes: tool.scopes || undefined,
+ tags: tool.tags || undefined,
+ is_deprecated: tool.is_deprecated || false,
+ };
+}
+
// Fetch detailed tool info from Composio API (server-side only)
// Returns null on failure, empty array if toolkit has no tools
-async function fetchDetailedTools(toolkitSlug: string): Promise<Tool[] | null> {
+async function fetchDetailedTools(toolkitSlug: string, version?: string | null): Promise<Tool[] | null> {
if (!API_KEY) {
console.warn('[Toolkits] COMPOSIO_API_KEY not set, skipping detailed tool fetch');
return null;
@@ -22,13 +67,13 @@ async function fetchDetailedTools(toolkitSlug: string): Promise<Tool[] | null> {
try {
const response = await fetch(
- `${API_BASE}/tools?toolkit_slug=${toolkitSlug.toUpperCase()}&limit=1000`,
+ `${API_BASE}/tools?toolkit_slug=${toolkitSlug.toUpperCase()}&limit=10000${version ? `&version=${encodeURIComponent(version)}` : ''}`,
{
headers: {
'Content-Type': 'application/json',
'x-api-key': API_KEY,
},
- next: { revalidate: 3600 }, // Cache for 1 hour
+ next: { revalidate: 3600 },
}
);
@@ -41,43 +86,7 @@ async function fetchDetailedTools(toolkitSlug: string): Promise<Tool[] | null> {
const rawItems = data.items || data;
const items = Array.isArray(rawItems) ? rawItems : [];
- return items.filter((tool: any) => tool && typeof tool === 'object').map((tool: any) => {
- // Extract parameters from JSON Schema format
- const inputSchema = tool.input_parameters || tool.parameters;
- const outputSchema = tool.output_parameters || tool.response;
-
- // Get properties and required array from JSON Schema
- const inputProps = inputSchema?.properties || inputSchema;
- const inputRequired = inputSchema?.required || [];
- const outputProps = outputSchema?.properties || outputSchema;
- const outputRequired = outputSchema?.required || [];
-
- // Add required flag to each property based on the required array
- const processParams = (props: any, requiredList: string[]) => {
- if (!props || typeof props !== 'object') return undefined;
- const result: Record<string, any> = {};
- for (const [key, value] of Object.entries(props)) {
- if (typeof value === 'object' && value !== null) {
- result[key] = {
- ...(value as object),
- required: requiredList.includes(key),
- };
- }
- }
- return Object.keys(result).length > 0 ? result : undefined;
- };
-
- return {
- slug: tool.slug || '',
- name: tool.name || tool.display_name || tool.slug || '',
- description: tool.description || '',
- input_parameters: processParams(inputProps, inputRequired),
- output_parameters: processParams(outputProps, outputRequired),
- scopes: tool.scopes || undefined,
- tags: tool.tags || undefined,
- is_deprecated: tool.is_deprecated || false,
- };
- });
+ return items.filter((tool: any) => tool && typeof tool === 'object').map(toolFromApi);
} catch (error) {
console.error(`[Toolkits] Error fetching detailed tools for ${toolkitSlug}:`, error);
return null;
@@ -86,7 +95,7 @@ async function fetchDetailedTools(toolkitSlug: string): Promise<Tool[] | null> {
// Fetch detailed trigger info from Composio API (server-side only)
// Returns null on failure, empty array if toolkit has no triggers
-async function fetchDetailedTriggers(toolkitSlug: string): Promise<Trigger[] | null> {
+async function fetchDetailedTriggers(toolkitSlug: string, version?: string | null): Promise<Trigger[] | null> {
if (!API_KEY) {
console.warn('[Toolkits] COMPOSIO_API_KEY not set, skipping detailed trigger fetch');
return null;
@@ -94,7 +103,7 @@ async function fetchDetailedTriggers(toolkitSlug: string): Promise<Trigger[] | n
try {
const response = await fetch(
- `${API_BASE}/triggers_types?toolkit_slugs=${toolkitSlug.toUpperCase()}&limit=1000`,
+ `${API_BASE}/triggers_types?toolkit_slugs=${toolkitSlug.toUpperCase()}&limit=10000${version ? `&version=${encodeURIComponent(version)}` : ''}`,
{
headers: {
'Content-Type': 'application/json',
@@ -114,31 +123,14 @@ async function fetchDetailedTriggers(toolkitSlug: string): Promise<Trigger[] | n
const items = Array.isArray(rawItems) ? rawItems : [];
return items.filter((trigger: any) => trigger && typeof trigger === 'object').map((trigger: any) => {
- // Extract config and payload schemas
const configSchema = trigger.config;
const payloadSchema = trigger.payload;
- // Get properties and required array from JSON Schema
const configProps = configSchema?.properties || configSchema;
const configRequired = configSchema?.required || [];
const payloadProps = payloadSchema?.properties || payloadSchema;
const payloadRequired = payloadSchema?.required || [];
- // Add required flag to each property based on the required array
- const processParams = (props: any, requiredList: string[]) => {
- if (!props || typeof props !== 'object') return undefined;
- const result: Record<string, any> = {};
- for (const [key, value] of Object.entries(props)) {
- if (typeof value === 'object' && value !== null) {
- result[key] = {
- ...(value as object),
- required: requiredList.includes(key),
- };
- }
- }
- return Object.keys(result).length > 0 ? result : undefined;
- };
-
return {
slug: trigger.slug || '',
name: trigger.name || trigger.display_name || trigger.slug || '',
@@ -277,8 +269,8 @@ export default async function ToolkitsPage({ params }: { params: Promise<{ slug?
if (toolkit) {
// Fetch detailed tool and trigger info from API (includes input/output params)
const [detailedTools, detailedTriggers] = await Promise.all([
- fetchDetailedTools(toolkitSlug),
- fetchDetailedTriggers(toolkitSlug),
+ fetchDetailedTools(toolkitSlug, toolkit.version),
+ fetchDetailedTriggers(toolkitSlug, toolkit.version),
]);
// Use detailed data if fetch succeeded, otherwise fall back to static data
diff --git a/docs/app/api/tools/[slug]/route.ts b/docs/app/api/tools/[slug]/route.ts
new file mode 100644
index 000000000..b4d5f127b
--- /dev/null
+++ b/docs/app/api/tools/[slug]/route.ts
@@ -0,0 +1,50 @@
+import { NextRequest, NextResponse } from 'next/server';
+
+const API_BASE = process.env.COMPOSIO_API_BASE || 'https://backend.composio.dev/api/v3';
+const API_KEY = process.env.COMPOSIO_API_KEY;
+
+export async function GET(
+ request: NextRequest,
+ { params }: { params: Promise<{ slug: string }> }
+) {
+ const { slug } = await params;
+ const version = request.nextUrl.searchParams.get('version') || 'latest';
+
+ if (!API_KEY) {
+ return NextResponse.json({ error: 'API key not configured' }, { status: 500 });
+ }
+
+ if (!slug || !/^[A-Z0-9_]+$/i.test(slug)) {
+ return NextResponse.json({ error: 'Invalid tool slug' }, { status: 400 });
+ }
+
+ try {
+ const response = await fetch(
+ `${API_BASE}/tools/${slug.toUpperCase()}?version=${encodeURIComponent(version)}`,
+ {
+ headers: {
+ 'Content-Type': 'application/json',
+ 'x-api-key': API_KEY,
+ },
+ next: { revalidate: 3600 },
+ }
+ );
+
+ if (!response.ok) {
+ return NextResponse.json({ error: 'Tool not found' }, { status: response.status });
+ }
+
+ const tool = await response.json();
+
+ // Return just the schemas
+ const inputSchema = tool.input_parameters || tool.parameters;
+ const outputSchema = tool.output_parameters || tool.response;
+
+ return NextResponse.json({
+ input_parameters: inputSchema || null,
+ output_parameters: outputSchema || null,
+ });
+ } catch {
+ return NextResponse.json({ error: 'Failed to fetch tool' }, { status: 500 });
+ }
+}
diff --git a/docs/components/toolkits/toolkit-detail.tsx b/docs/components/toolkits/toolkit-detail.tsx
index 848990bda..085e95c7b 100644
--- a/docs/components/toolkits/toolkit-detail.tsx
+++ b/docs/components/toolkits/toolkit-detail.tsx
@@ -1,6 +1,6 @@
'use client';
-import { useState, useMemo } from 'react';
+import { useState, useMemo, useEffect, useCallback, type ReactNode } from 'react';
import Link from 'next/link';
import { ExternalLink, Search, Copy, Check, ChevronDown, ChevronRight, ArrowLeft } from 'lucide-react';
import { TypeTable } from 'fumadocs-ui/components/type-table';
@@ -40,6 +40,12 @@ function formatDefault(value: unknown): string | undefined {
function formatType(param: ParameterSchema): string {
let typeStr = param.type || 'string';
+ // Show array item type
+ if (typeStr === 'array' && param.items) {
+ const itemType = param.items.type || 'unknown';
+ typeStr = `array<${itemType}>`;
+ }
+
// Include enum values in type display
if (param.enum && param.enum.length > 0) {
const enumValues = param.enum.map(v => `"${v}"`).join(' | ');
@@ -49,32 +55,83 @@ function formatType(param: ParameterSchema): string {
return typeStr;
}
-// Convert parameter schema to TypeTable format
+// Get children from a param (object properties or array item properties)
+function getChildren(param: ParameterSchema): Record<string, ParameterSchema> | null {
+ const props = param.properties || param.items?.properties;
+ if (!props || typeof props !== 'object') return null;
+
+ const requiredList: string[] = param.requiredFields || param.items?.requiredFields || param.items?.required as string[] || [];
+ const result: Record<string, ParameterSchema> = {};
+ for (const [key, value] of Object.entries(props)) {
+ if (typeof value === 'object' && value !== null) {
+ result[key] = {
+ ...(value as ParameterSchema),
+ required: Array.isArray(requiredList) ? requiredList.includes(key) : false,
+ };
+ }
+ }
+ return Object.keys(result).length > 0 ? result : null;
+}
+
+// Build a ReactNode description that includes text + nested TypeTable for children
+function buildDescription(param: ParameterSchema): ReactNode {
+ const children = getChildren(param);
+ if (!children) return param.description || undefined;
+
+ return (
+ <div className="space-y-2">
+ {param.description && <p>{param.description}</p>}
+ <TypeTable type={paramsToTypeTable(children)} />
+ </div>
+ );
+}
+
+// Convert parameter schema to TypeTable format, recursively nesting child TypeTables in descriptions
function paramsToTypeTable(params: Record<string, ParameterSchema>): Record<string, {
type: string;
- description?: string;
+ description?: ReactNode;
default?: string;
required?: boolean;
}> {
- const result: Record<string, {
- type: string;
- description?: string;
- default?: string;
- required?: boolean;
- }> = {};
-
+ const result: Record<string, { type: string; description?: ReactNode; default?: string; required?: boolean }> = {};
for (const [name, param] of Object.entries(params)) {
result[name] = {
type: formatType(param),
- description: param.description || undefined,
+ description: buildDescription(param),
default: formatDefault(param.default),
required: param.required,
};
}
-
return result;
}
+// Process raw API schema into ParameterSchema records
+function processApiSchema(schema: any): Record<string, ParameterSchema> | undefined {
+ if (!schema) return undefined;
+ const props = schema.properties || schema;
+ const required = schema.required || [];
+ if (!props || typeof props !== 'object') return undefined;
+
+ const result: Record<string, ParameterSchema> = {};
+ for (const [key, value] of Object.entries(props)) {
+ if (typeof value === 'object' && value !== null) {
+ const param = value as any;
+ result[key] = {
+ type: param.type,
+ description: param.description,
+ default: param.default,
+ example: param.example,
+ enum: param.enum,
+ required: required.includes(key),
+ ...(param.properties ? { properties: param.properties } : {}),
+ ...(param.required ? { requiredFields: param.required } : {}),
+ ...(param.items ? { items: param.items } : {}),
+ };
+ }
+ }
+ return Object.keys(result).length > 0 ? result : undefined;
+}
+
// Check if item is a Tool with parameters
function isTool(item: Tool | Trigger): item is Tool {
return 'input_parameters' in item || 'output_parameters' in item;
@@ -85,9 +142,14 @@ function isTrigger(item: Tool | Trigger): item is Trigger {
return 'config' in item || 'payload' in item || 'type' in item;
}
-function ToolItem({ item }: { item: Tool | Trigger }) {
+function ToolItem({ item, toolkitVersion }: { item: Tool | Trigger; toolkitVersion?: string | null }) {
const [expanded, setExpanded] = useState(false);
const [copied, setCopied] = useState(false);
+ const [detailedParams, setDetailedParams] = useState<{
+ input?: Record<string, ParameterSchema>;
+ output?: Record<string, ParameterSchema>;
+ } | null>(null);
+ const [loading, setLoading] = useState(false);
const copySlug = (e: React.MouseEvent) => {
e.stopPropagation();
@@ -99,8 +161,38 @@ function ToolItem({ item }: { item: Tool | Trigger }) {
const tool = isTool(item) ? item : null;
const trigger = isTrigger(item) ? item : null;
- const hasInputParams = tool?.input_parameters && Object.keys(tool.input_parameters).length > 0;
- const hasOutputParams = tool?.output_parameters && Object.keys(tool.output_parameters).length > 0;
+ // Fetch detailed schema when a tool is expanded
+ const fetchDetailedSchema = useCallback(async () => {
+ if (!tool || detailedParams || loading) return;
+ setLoading(true);
+ try {
+ const versionParam = toolkitVersion ? `?version=${encodeURIComponent(toolkitVersion)}` : '';
+ const res = await fetch(`/api/tools/${item.slug}${versionParam}`);
+ if (res.ok) {
+ const data = await res.json();
+ setDetailedParams({
+ input: processApiSchema(data.input_parameters),
+ output: processApiSchema(data.output_parameters),
+ });
+ }
+ } catch {
+ // silently fall back to basic params
+ } finally {
+ setLoading(false);
+ }
+ }, [tool, item.slug, toolkitVersion, detailedParams, loading]);
+
+ useEffect(() => {
+ if (expanded && tool) {
+ fetchDetailedSchema();
+ }
+ }, [expanded, tool, fetchDetailedSchema]);
+
+ const inputParams = detailedParams?.input || tool?.input_parameters;
+ const outputParams = detailedParams?.output || tool?.output_parameters;
+
+ const hasInputParams = inputParams && Object.keys(inputParams).length > 0;
+ const hasOutputParams = outputParams && Object.keys(outputParams).length > 0;
const hasConfig = trigger?.config && Object.keys(trigger.config).length > 0;
const hasPayload = trigger?.payload && Object.keys(trigger.payload).length > 0;
@@ -144,14 +236,14 @@ function ToolItem({ item }: { item: Tool | Trigger }) {
{hasInputParams && (
<div className="space-y-2">
<h4 className="text-xs font-semibold uppercase tracking-wide text-fd-muted-foreground">Input Parameters</h4>
- <TypeTable type={paramsToTypeTable(tool.input_parameters!)} />
+ <TypeTable type={paramsToTypeTable(inputParams!)} />
</div>
)}
{hasOutputParams && (
<div className="space-y-2">
<h4 className="text-xs font-semibold uppercase tracking-wide text-fd-muted-foreground">Output</h4>
- <TypeTable type={paramsToTypeTable(tool.output_parameters!)} />
+ <TypeTable type={paramsToTypeTable(outputParams!)} />
</div>
)}
@@ -341,7 +433,7 @@ export function ToolkitDetail({ toolkit, tools, triggers, path }: ToolkitDetailP
{activeTab === 'tools' && (
filteredTools.length > 0 ? (
filteredTools.map((tool) => (
- <ToolItem key={tool.slug} item={tool} />
+ <ToolItem key={tool.slug} item={tool} toolkitVersion={toolkit.version} />
))
) : (
<p className="px-4 py-8 text-center text-sm text-fd-muted-foreground">
@@ -352,7 +444,7 @@ export function ToolkitDetail({ toolkit, tools, triggers, path }: ToolkitDetailP
{activeTab === 'triggers' && (
filteredTriggers.length > 0 ? (
filteredTriggers.map((trigger) => (
- <ToolItem key={trigger.slug} item={trigger} />
+ <ToolItem key={trigger.slug} item={trigger} toolkitVersion={toolkit.version} />
))
) : (
<p className="px-4 py-8 text-center text-sm text-fd-muted-foreground">
diff --git a/docs/types/toolkit.ts b/docs/types/toolkit.ts
index 84502d803..bb9cbe8b8 100644
--- a/docs/types/toolkit.ts
+++ b/docs/types/toolkit.ts
@@ -6,6 +6,12 @@ export interface ParameterSchema {
default?: unknown;
example?: unknown;
enum?: string[];
+ // Nested object properties (JSON Schema)
+ properties?: Record<string, ParameterSchema>;
+ // Required fields within this object
+ requiredFields?: string[];
+ // Array item schema
+ items?: ParameterSchema;
}
export interface Tool {