Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
TypeScript agentic-aiagentsaiai-agentsaiagentsdeveloper-toolsfunction-callinggpt-4javascriptjsllmllmopsmcppythonremote-mcp-serverssetypescript
docs: add v3.1 tool endpoints to API reference
Sushmithamalleshb8adad5c56e0
diff --git a/docs/content/reference/api-reference/tools/index.mdx b/docs/content/reference/api-reference/tools/index.mdxindex 5fa246f09..712898d42 100644--- a/docs/content/reference/api-reference/tools/index.mdx+++ b/docs/content/reference/api-reference/tools/index.mdx@@ -13,7 +13,8 @@ Tool execution endpoints|----------|------------|| `GET /api/v3/tools` | [List available tools](/reference/api-reference/tools/getTools) || `GET /api/v3/tools/enum` | [Get tool enum list](/reference/api-reference/tools/getToolsEnum) |-| `GET /api/v3/tools/{tool_slug}` | [Get tool by slug](/reference/api-reference/tools/getToolsByToolSlug) |-| `POST /api/v3/tools/execute/{tool_slug}` | [Execute tool](/reference/api-reference/tools/postToolsExecuteByToolSlug) |-| `POST /api/v3/tools/execute/{tool_slug}/input` | [Generate tool inputs from natural language](/reference/api-reference/tools/postToolsExecuteByToolSlugInput) || `POST /api/v3/tools/execute/proxy` | [Execute proxy request](/reference/api-reference/tools/postToolsExecuteProxy) |+| `GET /api/v3.1/tools/{tool_slug}` | [Get tool by slug](/reference/api-reference/tools/getV3_1ToolsByToolSlug) |+| `POST /api/v3.1/tools/execute/{tool_slug}` | [Execute tool](/reference/api-reference/tools/postV3_1ToolsExecuteByToolSlug) |+| `POST /api/v3.1/tools/execute/{tool_slug}/input` | [Generate tool inputs from natural language](/reference/api-reference/tools/postV3_1ToolsExecuteByToolSlugInput) |+| `POST /api/v3.1/tools/scopes/required` | [Get required scopes for tools](/reference/api-reference/tools/postV3_1ToolsScopesRequired) |diff --git a/docs/public/openapi.json b/docs/public/openapi.jsonindex a7c0fb8aa..59595fa27 100644--- a/docs/public/openapi.json+++ b/docs/public/openapi.json@@ -7937,133 +7937,6 @@}}},- "/api/v3/tools/{tool_slug}": {- "get": {- "summary": "Get tool by slug",- "description": "Retrieve detailed information about a specific tool using its slug identifier. This endpoint returns full metadata about a tool including input/output parameters, versions, and toolkit information.",- "tags": [- "Tools"- ],- "operationId": "getToolsByToolSlug",- "security": [- {- "ApiKeyAuth": []- },- {- "UserApiKeyAuth": []- }- ],- "parameters": [- {- "schema": {- "type": "string"- },- "required": true,- "description": "The unique slug identifier of the tool",- "name": "tool_slug",- "in": "path"- },- {- "schema": {- "type": "string"- },- "required": false,- "description": "Optional version of the tool to retrieve",- "name": "version",- "in": "query"- },- {- "schema": {- "oneOf": [- {- "type": "null"- },- {- "type": "string"- },- {- "type": "object",- "additionalProperties": {- "type": "string"- },- "description": "Object representation of parsed bracket notation"- }- ]- },- "required": false,- "description": "Toolkit version specification. Use \"latest\" for latest versions or bracket notation for specific versions per toolkit.",- "in": "query",- "name": "toolkit_versions",- "examples": {- "latest_version": {- "summary": "Latest version for all toolkits",- "value": "latest"- },- "bracket_notation": {- "summary": "Specific versions using bracket notation",- "value": "Use: toolkit_versions[gmail]=20250930_00&toolkit_versions[slack]=20250929_00"- },- "null_value": {- "summary": "No version specified (uses 00000000_00)",- "value": null- }- }- }- ],- "responses": {- "200": {- "description": "Successfully retrieved tool details",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/Tool"- }- }- }- },- "400": {- "description": "Bad request - Invalid tool slug format",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/Error"- }- }- }- },- "401": {- "description": "Unauthorized - Authentication credentials are missing or invalid",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/Error"- }- }- }- },- "404": {- "description": "Not found - Tool with the specified slug does not exist",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/Error"- }- }- }- },- "500": {- "description": "Internal server error - Something went wrong on the server",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/Error"- }- }- }- }- }- }- },"/api/v3/toolkits/multi": {"post": {"summary": "Fetch multiple toolkits",@@ -8365,14 +8238,14 @@}}},- "/api/v3/tools/execute/{tool_slug}": {+ "/api/v3/tools/execute/proxy": {"post": {- "summary": "Execute tool",- "description": "Execute a specific tool operation with provided arguments and authentication. This is the primary endpoint for integrating with third-party services and executing tools. You can provide structured arguments or use natural language processing by providing a text description of what you want to accomplish.",+ "summary": "Execute proxy request",+ "description": "Proxy an HTTP request to a third-party API using connected account credentials. This endpoint allows making authenticated API calls to external services while abstracting away authentication details.","tags": ["Tools"],- "operationId": "postToolsExecuteByToolSlug",+ "operationId": "postToolsExecuteProxy","security": [{"ApiKeyAuth": []@@ -8381,27 +8254,6 @@"UserApiKeyAuth": []}],- "parameters": [- {- "schema": {- "type": "string"- },- "required": true,- "description": "The tool slug to execute",- "name": "tool_slug",- "in": "path"- },- {- "schema": {- "type": "string",- "description": "JSON object containing custom headers to pass to LLM providers (OpenAI, Bedrock, etc.)",- "example": "{\"x-custom-header\": \"value\", \"authorization\": \"Bearer token\"}"- },- "required": false,- "name": "x-llm-gateway-headers",- "in": "header"- }- ],"requestBody": {"content": {"application/json": {@@ -8410,95 +8262,123 @@"properties": {"connected_account_id": {"type": "string",- "description": "Unique identifier for the connected account to use for authentication",+ "format": "connectedAccountId",+ "description": "The ID of the connected account to use for authentication (if not provided, will use the default account for the project)","example": "ca_1a2b3c4d5e6f"},- "entity_id": {+ "endpoint": {"type": "string",- "description": "Deprecated: please use user_id instead. Entity identifier for multi-entity connected accounts (e.g. multiple repositories, organizations)",- "example": "repo-123",- "deprecated": true+ "description": "The API endpoint to call (absolute URL or path relative to base URL of the connected account)",+ "example": "/api/v1/resources"},- "user_id": {+ "method": {"type": "string",- "description": "User id for multi-user connected accounts (e.g. multiple users, organizations)",- "example": "user-123"+ "enum": [+ "GET",+ "POST",+ "PUT",+ "DELETE",+ "PATCH",+ "HEAD"+ ],+ "description": "The HTTP method to use for the request",+ "example": "GET"},- "version": {- "type": "string",- "description": "Tool version to execute (defaults to \"00000000_00\" if not specified)",- "example": "latest"+ "body": {+ "nullable": true,+ "description": "The request body (for POST, PUT, and PATCH requests)",+ "example": {+ "name": "New Resource",+ "description": "This is a new resource"+ },+ "type": "object"},- "custom_auth_params": {- "type": "object",- "properties": {- "base_url": {- "type": "string",- "description": "The base URL (root address) what you should use while making http requests to the connected account. For example, for gmail, it would be 'https://gmail.googleapis.com'"- },- "parameters": {- "type": "array",- "items": {- "type": "object",- "properties": {- "name": {- "type": "string",- "description": "The name of the parameter. For example, 'x-api-key', 'Content-Type', etc."- },- "in": {- "type": "string",- "enum": [- "query",- "header"- ],- "description": "The location of the parameter. Can be 'query' or 'header'."- },- "value": {- "anyOf": [- {- "type": "string"- },- {- "type": "number"- }- ],- "description": "The value of the parameter. For example, '1234567890', 'application/json', etc."- }+ "binary_body": {+ "anyOf": [+ {+ "type": "object",+ "properties": {+ "url": {+ "type": "string",+ "format": "uri",+ "description": "URL to fetch binary content from"},- "required": [- "name",- "in",- "value"- ]- }+ "content_type": {+ "type": "string",+ "description": "Content-Type header to use for the request"+ }+ },+ "required": [+ "url"+ ]},- "body": {+ {"type": "object",- "additionalProperties": {},- "description": "The body to be sent to the endpoint for authentication. This is a JSON object. Note: This is very rarely needed and is only required by very few apps."- }- },- "description": "Custom authentication parameters for tools that support parameterized authentication",- "example": {- "base_url": "https://api.example.com",- "parameters": [- {- "name": "x-api-key",- "value": "secret-key",- "in": "header"+ "properties": {+ "base64": {+ "type": "string",+ "minLength": 1,+ "description": "Base64-encoded binary data"+ },+ "content_type": {+ "type": "string",+ "description": "Content-Type header to use for the request"+ }+ },+ "required": [+ "base64"+ ]+ }+ ],+ "description": "Binary body to send. For binary upload via URL: use {url: \"https://...\", content_type?: \"...\"}. For binary upload via base64: use {base64: \"...\", content_type?: \"...\"}."+ },+ "parameters": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "name": {+ "type": "string",+ "description": "Parameter name",+ "example": "x-api-key"+ },+ "value": {+ "type": "string",+ "description": "Parameter value",+ "example": "abc123def456"+ },+ "type": {+ "type": "string",+ "enum": [+ "header",+ "query"+ ],+ "description": "Parameter type (header or query)",+ "example": "header"}+ },+ "required": [+ "name",+ "value",+ "type"]- }+ },+ "description": "Additional HTTP headers or query parameters to include in the request",+ "example": [+ {+ "name": "x-api-key",+ "value": "abc123def456",+ "type": "header"+ },+ {+ "name": "filter",+ "value": "active",+ "type": "query"+ }+ ]},"custom_connection_data": {- "description": "Custom connection data for tools that support custom connection data",- "example": {- "authScheme": "OAUTH2",- "toolkitSlug": "github",- "val": {- "access_token": "secret-token"- }- },+ "deprecated": true,"type": "object","properties": {"authScheme": {@@ -8738,92 +8618,88 @@"val"],"additionalProperties": true- },- "arguments": {- "type": "object",- "additionalProperties": {},- "description": "Key-value pairs of arguments required by the tool (mutually exclusive with text)",- "example": {- "repository": "octocat/Hello-World",- "workflow_id": "main.yml",- "ref": "main",- "inputs": {- "environment": "production"- }- }- },- "text": {- "type": "string",- "description": "Natural language description of the task to perform (mutually exclusive with arguments)",- "example": "Trigger the main workflow in the octocat/Hello-World repository on the main branch for the production environment"- },- "allow_tracing": {- "type": "boolean",- "nullable": true,- "description": "Deprecated. Enable debug tracing for tool execution (useful for debugging)",- "deprecated": true,- "example": false}- }+ },+ "required": [+ "endpoint",+ "method"+ ]}}}},"responses": {"200": {- "description": "Successfully executed action and received response",+ "description": "Successfully executed proxy request and received response","content": {"application/json": {"schema": {"type": "object","properties": {"data": {- "type": "object",- "additionalProperties": {},- "description": "Tool execution output data that varies based on the specific tool",- "example": {- "run_id": 12345678,- "status": "queued",- "created_at": "2023-01-01T12:00:00Z",- "html_url": "https://github.com/octocat/Hello-World/actions/runs/12345678"- }- },- "error": {- "type": "string",- "nullable": true,- "description": "Error message if the tool execution was not successful (null if successful)"- },- "successful": {- "type": "boolean",- "description": "Indicates if the tool execution was successful",- "example": true- },- "session_info": {"nullable": true,- "description": "Optional session information for tools that return session context",+ "description": "The response data returned from the proxied API","example": {- "session_id": "session-12345",- "expires_at": "2023-01-01T13:00:00Z"+ "id": "123",+ "name": "Resource Name",+ "created_at": "2023-01-01T00:00:00Z"},"type": "object"},- "log_id": {- "type": "string",- "description": "Unique identifier for the execution log (useful for debugging and support)",- "example": "log_abc123def456"+ "binary_data": {+ "type": "object",+ "properties": {+ "url": {+ "type": "string",+ "description": "URL to download binary content"+ },+ "content_type": {+ "type": "string",+ "description": "Content-Type of the binary data"+ },+ "size": {+ "type": "number",+ "description": "File size in bytes"+ },+ "expires_at": {+ "type": "string",+ "description": "ISO 8601 timestamp when the URL expires"+ }+ },+ "required": [+ "url",+ "content_type",+ "size"+ ],+ "description": "Binary body response data. Present when the response is a binary file."+ },+ "status": {+ "type": "number",+ "description": "The HTTP status code returned from the proxied API",+ "example": 200+ },+ "headers": {+ "type": "object",+ "additionalProperties": {+ "type": "string"+ },+ "description": "The HTTP headers returned from the proxied API",+ "example": {+ "content-type": "application/json",+ "cache-control": "no-cache",+ "host": "api.example.com"+ }}},"required": [- "data",- "error",- "successful"+ "status"]}}}},"400": {- "description": "Bad request - Invalid request parameters, missing required arguments, or conflicting parameters",+ "description": "Bad request - Invalid request parameters or body format","content": {"application/json": {"schema": {@@ -8843,7 +8719,7 @@}},"403": {- "description": "Forbidden - Connected account does not have permission to execute this tool or access the requested resource",+ "description": "Forbidden - Connected account does not have permission to access the requested resource","content": {"application/json": {"schema": {@@ -8853,37 +8729,7 @@}},"404": {- "description": "Not found - Tool or connected account not found",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/Error"- }- }- }- },- "408": {- "description": "Request timeout - Tool execution exceeded the maximum allowed time",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/Error"- }- }- }- },- "410": {- "description": "Gone - Tool has been deprecated and is no longer available",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/Error"- }- }- }- },- "413": {- "description": "Payload too large - Request or response payload exceeds size limits",+ "description": "Not found - Resource not found or connected account not found","content": {"application/json": {"schema": {@@ -8903,7 +8749,7 @@}},"429": {- "description": "Rate limit exceeded - Too many requests to the tool or underlying API",+ "description": "Too many requests - Rate limit exceeded on the connected account or proxy service","content": {"application/json": {"schema": {@@ -8923,7 +8769,7 @@}},"501": {- "description": "Not implemented",+ "description": "Not implemented - This operation is not supported for the requested connected account or authentication scheme","content": {"application/json": {"schema": {@@ -8933,7 +8779,7 @@}},"502": {- "description": "Bad gateway - Error communicating with the tool provider API",+ "description": "Bad gateway - Error communicating with the upstream API","content": {"application/json": {"schema": {@@ -8942,8 +8788,8 @@}}},- "503": {- "description": "Upstream service unavailable - Tool provider API is currently down or unavailable",+ "504": {+ "description": "Gateway timeout - Upstream API timed out","content": {"application/json": {"schema": {@@ -8955,14 +8801,14 @@}}},- "/api/v3/tools/execute/{tool_slug}/input": {+ "/api/v3/trigger_instances/{slug}/upsert": {"post": {- "summary": "Generate tool inputs from natural language",- "description": "Uses AI to translate a natural language description into structured arguments for a specific tool. This endpoint is useful when you want to let users describe what they want to do in plain language instead of providing structured parameters.",+ "summary": "Create or update a trigger",+ "description": "Creates a new trigger instance or updates an existing one with the same configuration. Triggers listen for events from external services (webhooks or polling) and can invoke your workflows. If a matching trigger already exists and is disabled, it will be re-enabled. Requires a connected account ID to associate the trigger with a specific user connection.","tags": [- "Tools"+ "Triggers"],- "operationId": "postToolsExecuteByToolSlugInput",+ "operationId": "postTriggerInstancesBySlugUpsert","security": [{"ApiKeyAuth": []@@ -8974,11 +8820,12 @@"parameters": [{"schema": {- "type": "string"+ "type": "string",+ "description": "The slug of the trigger instance. Case-insensitive (internally normalized to uppercase)."},"required": true,- "description": "The tool slug to generate inputs for",- "name": "tool_slug",+ "description": "The slug of the trigger instance. Case-insensitive (internally normalized to uppercase).",+ "name": "slug","in": "path"}],@@ -8988,67 +8835,136 @@"schema": {"type": "object","properties": {- "text": {+ "connectedAuthId": {"type": "string",- "description": "Natural language description of what you want to accomplish with this tool",- "example": "I need to trigger the main workflow in the octocat/Hello-World repository to deploy to production"+ "format": "connectedAccountId",+ "description": "DEPRECATED: This parameter will be removed in a future version. Please use connected_account_id instead.",+ "deprecated": true},- "custom_description": {- "type": "string",- "description": "Custom description of the tool to help guide the LLM in generating more accurate inputs",- "example": "This tool triggers GitHub Actions workflows in a repository. It requires the repository name, workflow ID, and optional input parameters."+ "triggerConfig": {+ "type": "object",+ "additionalProperties": {},+ "description": "DEPRECATED: This parameter will be removed in a future version. Please use trigger_config instead.",+ "deprecated": true},- "system_prompt": {+ "connected_account_id": {"type": "string",- "description": "System prompt to control and guide the behavior of the LLM when generating inputs",- "example": "You are an expert assistant that generates precise GitHub Actions workflow parameters. Extract exact repository names, workflow IDs, and input values from user descriptions."+ "format": "connectedAccountId",+ "description": "Connected account nanoid"+ },+ "trigger_config": {+ "type": "object",+ "additionalProperties": {},+ "description": "Trigger configuration"},"version": {"type": "string",- "description": "Tool version to use when generating inputs (defaults to \"latest\" if not specified)",+ "description": "DEPRECATED: This parameter will be removed in a future version. Please use toolkit_versions instead.",+ "deprecated": true,+ "example": "latest"+ },+ "toolkit_versions": {+ "anyOf": [+ {+ "type": "string"+ },+ {+ "type": "object",+ "additionalProperties": {+ "type": "string"+ }+ },+ {+ "nullable": true,+ "type": "object"+ }+ ],+ "description": "Toolkit version specification. Supports \"latest\" string or a record mapping toolkit slugs to specific versions.","example": "latest"}- },- "required": [- "text"- ]+ }}}}},"responses": {"200": {- "description": "Successfully generated structured inputs for the action based on natural language description",+ "description": "Successfully upserted trigger instance","content": {"application/json": {"schema": {"type": "object","properties": {- "arguments": {+ "trigger_id": {+ "type": "string",+ "description": "ID of the updated trigger"+ },+ "deprecated": {"type": "object",- "additionalProperties": {},- "description": "Key-value pairs of arguments required by the tool to accomplish the described task",- "example": {- "repository": "octocat/Hello-World",- "workflow_id": "main.yml",- "ref": "main",- "inputs": {- "environment": "production"+ "properties": {+ "uuid": {+ "type": "string",+ "description": "ID of the updated trigger"}- }- },- "error": {+ },+ "required": [+ "uuid"+ ]+ }+ },+ "required": [+ "trigger_id",+ "deprecated"+ ]+ }+ }+ }+ },+ "201": {+ "description": "Successfully created trigger instance",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "trigger_id": {"type": "string",- "description": "Error message if the arguments could not be generated (null if successful)",- "example": "Unable to determine the repository name from the provided description"+ "description": "ID of the updated trigger"+ },+ "deprecated": {+ "type": "object",+ "properties": {+ "uuid": {+ "type": "string",+ "description": "ID of the updated trigger"+ }+ },+ "required": [+ "uuid"+ ]}- }+ },+ "required": [+ "trigger_id",+ "deprecated"+ ]+ }+ }+ }+ },+ "204": {+ "description": "No content",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {}}}}},"400": {- "description": "Bad request - Invalid input parameters or insufficient description to generate tool arguments",+ "description": "Bad request","content": {"application/json": {"schema": {@@ -9058,7 +8974,7 @@}},"401": {- "description": "Unauthorized - Authentication credentials are missing or invalid",+ "description": "Unauthorized","content": {"application/json": {"schema": {@@ -9068,7 +8984,7 @@}},"404": {- "description": "Not found - The specified tool does not exist",+ "description": "Trigger instance not found","content": {"application/json": {"schema": {@@ -9077,8 +8993,8 @@}}},- "422": {- "description": "Unprocessable entity - Invalid state of the connected account",+ "408": {+ "description": "Request timeout","content": {"application/json": {"schema": {@@ -9087,8 +9003,18 @@}}},- "429": {- "description": "Too many requests - Rate limit exceeded for natural language processing",+ "410": {+ "description": "Gone",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "422": {+ "description": "Unprocessable entity","content": {"application/json": {"schema": {@@ -9098,7 +9024,17 @@}},"500": {- "description": "Internal server error - AI processing failed or other server error occurred",+ "description": "Internal server error",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "501": {+ "description": "Not implemented","content": {"application/json": {"schema": {@@ -9110,822 +9046,14 @@}}},- "/api/v3/tools/execute/proxy": {- "post": {- "summary": "Execute proxy request",- "description": "Proxy an HTTP request to a third-party API using connected account credentials. This endpoint allows making authenticated API calls to external services while abstracting away authentication details.",+ "/api/v3/trigger_instances/active": {+ "get": {+ "summary": "List active triggers",+ "description": "Retrieves all active trigger instances for your project. Triggers listen for events from connected accounts (e.g., new emails, Slack messages, GitHub commits) and can invoke webhooks or workflows. Use filters to find triggers for specific users, connected accounts, or trigger types.","tags": [- "Tools"+ "Triggers"],- "operationId": "postToolsExecuteProxy",- "security": [- {- "ApiKeyAuth": []- },- {- "UserApiKeyAuth": []- }- ],- "requestBody": {- "content": {- "application/json": {- "schema": {- "type": "object",- "properties": {- "connected_account_id": {- "type": "string",- "format": "connectedAccountId",- "description": "The ID of the connected account to use for authentication (if not provided, will use the default account for the project)",- "example": "ca_1a2b3c4d5e6f"- },- "endpoint": {- "type": "string",- "description": "The API endpoint to call (absolute URL or path relative to base URL of the connected account)",- "example": "/api/v1/resources"- },- "method": {- "type": "string",- "enum": [- "GET",- "POST",- "PUT",- "DELETE",- "PATCH",- "HEAD"- ],- "description": "The HTTP method to use for the request",- "example": "GET"- },- "body": {- "nullable": true,- "description": "The request body (for POST, PUT, and PATCH requests)",- "example": {- "name": "New Resource",- "description": "This is a new resource"- },- "type": "object"- },- "binary_body": {- "anyOf": [- {- "type": "object",- "properties": {- "url": {- "type": "string",- "format": "uri",- "description": "URL to fetch binary content from"- },- "content_type": {- "type": "string",- "description": "Content-Type header to use for the request"- }- },- "required": [- "url"- ]- },- {- "type": "object",- "properties": {- "base64": {- "type": "string",- "minLength": 1,- "description": "Base64-encoded binary data"- },- "content_type": {- "type": "string",- "description": "Content-Type header to use for the request"- }- },- "required": [- "base64"- ]- }- ],- "description": "Binary body to send. For binary upload via URL: use {url: \"https://...\", content_type?: \"...\"}. For binary upload via base64: use {base64: \"...\", content_type?: \"...\"}."- },- "parameters": {- "type": "array",- "items": {- "type": "object",- "properties": {- "name": {- "type": "string",- "description": "Parameter name",- "example": "x-api-key"- },- "value": {- "type": "string",- "description": "Parameter value",- "example": "abc123def456"- },- "type": {- "type": "string",- "enum": [- "header",- "query"- ],- "description": "Parameter type (header or query)",- "example": "header"- }- },- "required": [- "name",- "value",- "type"- ]- },- "description": "Additional HTTP headers or query parameters to include in the request",- "example": [- {- "name": "x-api-key",- "value": "abc123def456",- "type": "header"- },- {- "name": "filter",- "value": "active",- "type": "query"- }- ]- },- "custom_connection_data": {- "deprecated": true,- "type": "object",- "properties": {- "authScheme": {- "type": "string",- "enum": [- "OAUTH2",- "DCR_OAUTH",- "API_KEY",- "BASIC_WITH_JWT",- "BASIC",- "BEARER_TOKEN",- "OAUTH1",- "NO_AUTH",- "SERVICE_ACCOUNT",- "GOOGLE_SERVICE_ACCOUNT",- "S2S_OAUTH2"- ]- },- "toolkitSlug": {- "type": "string"- },- "val": {- "type": "object",- "properties": {- "subdomain": {- "type": "string"- },- "your-domain": {- "type": "string"- },- "region": {- "type": "string"- },- "shop": {- "type": "string"- },- "account_url": {- "type": "string"- },- "COMPANYDOMAIN": {- "type": "string"- },- "extension": {- "type": "string"- },- "form_api_base_url": {- "type": "string"- },- "instanceEndpoint": {- "type": "string"- },- "api_url": {- "type": "string"- },- "borneo_dashboard_url": {- "type": "string"- },- "proxy_username": {- "type": "string"- },- "proxy_password": {- "type": "string"- },- "domain": {- "type": "string"- },- "version": {- "type": "string"- },- "dc": {- "type": "string"- },- "site_name": {- "type": "string"- },- "instanceName": {- "type": "string"- },- "account_id": {- "type": "string"- },- "your_server": {- "type": "string"- },- "server_location": {- "type": "string"- },- "base_url": {- "type": "string"- },- "state_prefix": {- "type": "string",- "maxLength": 40,- "description": "The oauth2 state prefix for the connection"- },- "long_redirect_url": {- "type": "boolean",- "description": "Whether to return the redirect url without shortening"- },- "access_token": {- "type": "string"- },- "id_token": {- "type": "string"- },- "token_type": {- "type": "string"- },- "refresh_token": {- "type": "string",- "nullable": true- },- "expires_in": {- "anyOf": [- {- "type": "number"- },- {- "type": "string"- },- {- "nullable": true,- "type": "object"- }- ]- },- "scope": {- "anyOf": [- {- "type": "string"- },- {- "type": "array",- "items": {- "type": "string"- }- },- {- "nullable": true,- "type": "object"- }- ]- },- "webhook_signature": {- "type": "string"- },- "authed_user": {- "type": "object",- "properties": {- "access_token": {- "type": "string"- },- "scope": {- "type": "string"- }- },- "description": "for slack user scopes"- },- "client_id": {- "type": "string",- "description": "Dynamically registered client ID"- },- "client_secret": {- "type": "string",- "description": "Dynamically registered client secret"- },- "client_id_issued_at": {- "type": "number"- },- "client_secret_expires_at": {- "type": "number"- },- "generic_api_key": {- "type": "string"- },- "api_key": {- "type": "string"- },- "bearer_token": {- "type": "string"- },- "basic_encoded": {- "type": "string"- },- "username": {- "type": "string"- },- "password": {- "type": "string"- },- "token": {- "type": "string"- },- "oauth_token": {- "type": "string"- },- "oauth_token_secret": {- "type": "string"- },- "oauth_verifier": {- "type": "string"- },- "consumer_key": {- "type": "string"- },- "redirectUrl": {- "type": "string"- },- "callback_url": {- "type": "string"- },- "application_id": {- "type": "string"- },- "installation_id": {- "type": "string"- },- "private_key": {- "type": "string"- },- "credentials_json": {- "type": "string"- },- "expires_at": {- "type": "string"- }- },- "required": [- "access_token"- ],- "additionalProperties": {}- }- },- "required": [- "authScheme",- "toolkitSlug",- "val"- ],- "additionalProperties": true- }- },- "required": [- "endpoint",- "method"- ]- }- }- }- },- "responses": {- "200": {- "description": "Successfully executed proxy request and received response",- "content": {- "application/json": {- "schema": {- "type": "object",- "properties": {- "data": {- "nullable": true,- "description": "The response data returned from the proxied API",- "example": {- "id": "123",- "name": "Resource Name",- "created_at": "2023-01-01T00:00:00Z"- },- "type": "object"- },- "binary_data": {- "type": "object",- "properties": {- "url": {- "type": "string",- "description": "URL to download binary content"- },- "content_type": {- "type": "string",- "description": "Content-Type of the binary data"- },- "size": {- "type": "number",- "description": "File size in bytes"- },- "expires_at": {- "type": "string",- "description": "ISO 8601 timestamp when the URL expires"- }- },- "required": [- "url",- "content_type",- "size"- ],- "description": "Binary body response data. Present when the response is a binary file."- },- "status": {- "type": "number",- "description": "The HTTP status code returned from the proxied API",- "example": 200- },- "headers": {- "type": "object",- "additionalProperties": {- "type": "string"- },- "description": "The HTTP headers returned from the proxied API",- "example": {- "content-type": "application/json",- "cache-control": "no-cache",- "host": "api.example.com"- }- }- },- "required": [- "status"- ]- }- }- }- },- "400": {- "description": "Bad request - Invalid request parameters or body format",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/Error"- }- }- }- },- "401": {- "description": "Unauthorized - Authentication credentials are missing or invalid",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/Error"- }- }- }- },- "403": {- "description": "Forbidden - Connected account does not have permission to access the requested resource",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/Error"- }- }- }- },- "404": {- "description": "Not found - Resource not found or connected account not found",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/Error"- }- }- }- },- "422": {- "description": "Unprocessable entity - Invalid state of the connected account",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/Error"- }- }- }- },- "429": {- "description": "Too many requests - Rate limit exceeded on the connected account or proxy service",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/Error"- }- }- }- },- "500": {- "description": "Internal server error - Something went wrong on the server",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/Error"- }- }- }- },- "501": {- "description": "Not implemented - This operation is not supported for the requested connected account or authentication scheme",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/Error"- }- }- }- },- "502": {- "description": "Bad gateway - Error communicating with the upstream API",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/Error"- }- }- }- },- "504": {- "description": "Gateway timeout - Upstream API timed out",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/Error"- }- }- }- }- }- }- },- "/api/v3/trigger_instances/{slug}/upsert": {- "post": {- "summary": "Create or update a trigger",- "description": "Creates a new trigger instance or updates an existing one with the same configuration. Triggers listen for events from external services (webhooks or polling) and can invoke your workflows. If a matching trigger already exists and is disabled, it will be re-enabled. Requires a connected account ID to associate the trigger with a specific user connection.",- "tags": [- "Triggers"- ],- "operationId": "postTriggerInstancesBySlugUpsert",- "security": [- {- "ApiKeyAuth": []- },- {- "UserApiKeyAuth": []- }- ],- "parameters": [- {- "schema": {- "type": "string",- "description": "The slug of the trigger instance. Case-insensitive (internally normalized to uppercase)."- },- "required": true,- "description": "The slug of the trigger instance. Case-insensitive (internally normalized to uppercase).",- "name": "slug",- "in": "path"- }- ],- "requestBody": {- "content": {- "application/json": {- "schema": {- "type": "object",- "properties": {- "connectedAuthId": {- "type": "string",- "format": "connectedAccountId",- "description": "DEPRECATED: This parameter will be removed in a future version. Please use connected_account_id instead.",- "deprecated": true- },- "triggerConfig": {- "type": "object",- "additionalProperties": {},- "description": "DEPRECATED: This parameter will be removed in a future version. Please use trigger_config instead.",- "deprecated": true- },- "connected_account_id": {- "type": "string",- "format": "connectedAccountId",- "description": "Connected account nanoid"- },- "trigger_config": {- "type": "object",- "additionalProperties": {},- "description": "Trigger configuration"- },- "version": {- "type": "string",- "description": "DEPRECATED: This parameter will be removed in a future version. Please use toolkit_versions instead.",- "deprecated": true,- "example": "latest"- },- "toolkit_versions": {- "anyOf": [- {- "type": "string"- },- {- "type": "object",- "additionalProperties": {- "type": "string"- }- },- {- "nullable": true,- "type": "object"- }- ],- "description": "Toolkit version specification. Supports \"latest\" string or a record mapping toolkit slugs to specific versions.",- "example": "latest"- }- }- }- }- }- },- "responses": {- "200": {- "description": "Successfully upserted trigger instance",- "content": {- "application/json": {- "schema": {- "type": "object",- "properties": {- "trigger_id": {- "type": "string",- "description": "ID of the updated trigger"- },- "deprecated": {- "type": "object",- "properties": {- "uuid": {- "type": "string",- "description": "ID of the updated trigger"- }- },- "required": [- "uuid"- ]- }- },- "required": [- "trigger_id",- "deprecated"- ]- }- }- }- },- "201": {- "description": "Successfully created trigger instance",- "content": {- "application/json": {- "schema": {- "type": "object",- "properties": {- "trigger_id": {- "type": "string",- "description": "ID of the updated trigger"- },- "deprecated": {- "type": "object",- "properties": {- "uuid": {- "type": "string",- "description": "ID of the updated trigger"- }- },- "required": [- "uuid"- ]- }- },- "required": [- "trigger_id",- "deprecated"- ]- }- }- }- },- "204": {- "description": "No content",- "content": {- "application/json": {- "schema": {- "type": "object",- "properties": {}- }- }- }- },- "400": {- "description": "Bad request",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/Error"- }- }- }- },- "401": {- "description": "Unauthorized",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/Error"- }- }- }- },- "404": {- "description": "Trigger instance not found",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/Error"- }- }- }- },- "408": {- "description": "Request timeout",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/Error"- }- }- }- },- "410": {- "description": "Gone",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/Error"- }- }- }- },- "422": {- "description": "Unprocessable entity",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/Error"- }- }- }- },- "500": {- "description": "Internal server error",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/Error"- }- }- }- },- "501": {- "description": "Not implemented",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/Error"- }- }- }- }- }- }- },- "/api/v3/trigger_instances/active": {- "get": {- "summary": "List active triggers",- "description": "Retrieves all active trigger instances for your project. Triggers listen for events from connected accounts (e.g., new emails, Slack messages, GitHub commits) and can invoke webhooks or workflows. Use filters to find triggers for specific users, connected accounts, or trigger types.",- "tags": [- "Triggers"- ],- "operationId": "getTriggerInstancesActive",+ "operationId": "getTriggerInstancesActive","security": [{"ApiKeyAuth": []@@ -14376,227 +13504,664 @@"description": "The identifier of the user who is initiating the session, ideally a unique identifier from your database like a user ID or email address","example": "user_123456789"},- "toolkits": {+ "toolkits": {+ "anyOf": [+ {+ "type": "object",+ "properties": {+ "enable": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "Only these specific toolkits will be enabled",+ "example": [+ "gmail",+ "slack",+ "github"+ ]+ }+ },+ "required": [+ "enable"+ ],+ "additionalProperties": false,+ "description": "Enable only specific toolkits (allowlist)"+ },+ {+ "type": "object",+ "properties": {+ "disable": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "These specific toolkits will be disabled",+ "example": [+ "gmail",+ "slack"+ ]+ }+ },+ "required": [+ "disable"+ ],+ "additionalProperties": false,+ "description": "Disable specific toolkits (denylist)"+ }+ ],+ "description": "Toolkit configuration - specify either enable toolkits (allowlist) or disable toolkits (denylist). Mutually exclusive."+ },+ "auth_configs": {+ "type": "object",+ "additionalProperties": {+ "type": "string",+ "format": "authConfigId"+ },+ "description": "The auth configs to use for the session. This will override the default behavior and use the given auth config when specific toolkits are being executed",+ "example": {+ "gmail": "ac_1223434343",+ "slack": "ac_23343434343434"+ }+ },+ "connected_accounts": {+ "type": "object",+ "additionalProperties": {+ "type": "string",+ "format": "connectedAccountId"+ },+ "description": "The connected accounts to use for the session. This will override the default behaviour and use the given connected account when specific toolkits are being executed",+ "example": {+ "github": "ca_34454545454545"+ }+ },+ "manage_connections": {+ "type": "object",+ "properties": {+ "enable": {+ "type": "boolean",+ "nullable": true,+ "default": true,+ "description": "Whether to enable the connection manager for automatic connection handling. If true, we will provide a tool your agent can use to initiate connections to toolkits if it doesnt exist. If set to false, then you have to manage connections manually.",+ "example": true+ },+ "callback_url": {+ "type": "string",+ "format": "uri",+ "description": "The URL to redirect to after a user completes authentication for a connected account. This allows you to handle the auth callback in your own application.",+ "example": "https://your-app.com/auth/callback"+ },+ "enable_wait_for_connections": {+ "type": "boolean",+ "nullable": true,+ "default": false,+ "description": "When true, the COMPOSIO_WAIT_FOR_CONNECTIONS tool is available for agents to poll connection status after sharing auth URLs. Default is false (disabled). May not work reliably with GPT models.",+ "example": false+ },+ "enable_connection_removal": {+ "type": "boolean",+ "nullable": true,+ "default": true,+ "description": "Enable the \"remove\" action in COMPOSIO_MANAGE_CONNECTIONS to allow deleting connected accounts. Default true."+ }+ },+ "default": {+ "enable": true,+ "enable_wait_for_connections": false,+ "enable_connection_removal": true+ },+ "additionalProperties": false,+ "description": "Configuration for connection management settings"+ },+ "tools": {+ "type": "object",+ "additionalProperties": {+ "anyOf": [+ {+ "type": "object",+ "properties": {+ "enable": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "Only these specific tools will be available for this toolkit",+ "example": [+ "GMAIL_SEND_EMAIL",+ "GMAIL_FETCH_EMAILS"+ ]+ }+ },+ "required": [+ "enable"+ ],+ "additionalProperties": false+ },+ {+ "type": "object",+ "properties": {+ "disable": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "These specific tools will be disabled for this toolkit",+ "example": [+ "SLACK_ADD_EMOJI"+ ]+ }+ },+ "required": [+ "disable"+ ],+ "additionalProperties": false+ },+ {+ "type": "object",+ "properties": {+ "tags": {+ "anyOf": [+ {+ "type": "array",+ "items": {+ "type": "string",+ "enum": [+ "readOnlyHint",+ "destructiveHint",+ "idempotentHint",+ "openWorldHint"+ ]+ }+ },+ {+ "type": "object",+ "properties": {+ "enable": {+ "type": "array",+ "items": {+ "type": "string",+ "enum": [+ "readOnlyHint",+ "destructiveHint",+ "idempotentHint",+ "openWorldHint"+ ]+ },+ "description": "Tags that the tool must have at least one of"+ },+ "disable": {+ "type": "array",+ "items": {+ "type": "string",+ "enum": [+ "readOnlyHint",+ "destructiveHint",+ "idempotentHint",+ "openWorldHint"+ ]+ },+ "description": "Tags that the tool must NOT have any of"+ }+ }+ }+ ],+ "description": "MCP tags to filter tools. Array format is treated as enabled list. Object format supports both enabled and disabled lists.",+ "example": {+ "enable": [+ "openWorldHint"+ ],+ "disable": [+ "destructiveHint"+ ]+ }+ }+ },+ "required": [+ "tags"+ ],+ "additionalProperties": false+ }+ ]+ },+ "description": "Tool-level configuration per toolkit - either specify enable tools (whitelist), disable tools (blacklist), or filter by MCP tags for each toolkit",+ "example": {+ "gmail": {+ "enable": [+ "GMAIL_SEND_EMAIL",+ "GMAIL_FETCH_EMAILS"+ ]+ },+ "slack": {+ "disable": [+ "SLACK_ADD_EMOJI"+ ]+ },+ "slack_bot": {+ "tags": {+ "enable": [+ "destructiveHint"+ ],+ "disable": [+ "openWorldHint"+ ]+ }+ }+ }+ },+ "tags": {"anyOf": [+ {+ "type": "array",+ "items": {+ "type": "string",+ "enum": [+ "readOnlyHint",+ "destructiveHint",+ "idempotentHint",+ "openWorldHint"+ ]+ }+ },{"type": "object","properties": {"enable": {"type": "array","items": {- "type": "string"+ "type": "string",+ "enum": [+ "readOnlyHint",+ "destructiveHint",+ "idempotentHint",+ "openWorldHint"+ ]+ },+ "description": "Tags that the tool must have at least one of"+ },+ "disable": {+ "type": "array",+ "items": {+ "type": "string",+ "enum": [+ "readOnlyHint",+ "destructiveHint",+ "idempotentHint",+ "openWorldHint"+ ]+ },+ "description": "Tags that the tool must NOT have any of"+ }+ }+ }+ ],+ "description": "Global MCP tool annotation hints for filtering. Array format is treated as enabled list. Object format supports both enabled (tool must have at least one) and disabled (tool must NOT have any) lists. Toolkit-level tags override this. Toolkit enabled/disabled lists take precedence over tag filtering.",+ "example": {+ "enable": [+ "openWorldHint"+ ],+ "disable": [+ "destructiveHint"+ ]+ }+ },+ "workbench": {+ "type": "object",+ "properties": {+ "enable": {+ "type": "boolean",+ "default": true,+ "description": "Set to false to disable the workbench entirely. When disabled, no code execution tools are available in the session.",+ "example": true+ },+ "enable_proxy_execution": {+ "type": "boolean",+ "default": true,+ "description": "Whether proxy execution is enabled. When enabled, workbench can call URLs and APIs directly.",+ "example": true+ },+ "auto_offload_threshold": {+ "type": "number",+ "minimum": 0,+ "exclusiveMinimum": true,+ "description": "Character threshold for automatic offloading. When workbench response exceeds this threshold, it will be automatically offloaded. Default is picked automatically based on the response size.",+ "example": 20000+ }+ },+ "default": {+ "enable": true,+ "enable_proxy_execution": true+ },+ "additionalProperties": false,+ "description": "Configuration for workbench behavior"+ },+ "experimental": {+ "type": "object",+ "properties": {+ "assistive_prompt_config": {+ "type": "object",+ "properties": {+ "user_timezone": {+ "type": "string",+ "description": "IANA timezone identifier (e.g., 'America/New_York', 'Europe/London'). Used to customize the system prompt with timezone-aware instructions.",+ "example": "America/New_York"+ }+ },+ "additionalProperties": false,+ "description": "Customize assistive prompt generation (e.g., timezone)."+ },+ "custom_toolkits": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "slug": {+ "type": "string",+ "minLength": 1,+ "pattern": "^[a-zA-Z0-9_-]+$",+ "description": "Unique slug for the toolkit. Must not conflict with existing Composio toolkit slugs. Alphanumeric, underscores, and hyphens only.",+ "example": "ecommerce"+ },+ "name": {+ "type": "string",+ "minLength": 1,+ "maxLength": 128,+ "description": "Display name shown to the LLM and in search results.",+ "example": "E-Commerce API"+ },+ "description": {+ "type": "string",+ "minLength": 1,+ "maxLength": 2048,+ "description": "Used for BM25 search matching and shown in toolkit connection statuses.",+ "example": "Internal e-commerce API for order management and fulfillment"+ },+ "tools": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "slug": {+ "type": "string",+ "minLength": 1,+ "pattern": "^[a-zA-Z0-9_-]+$",+ "description": "Tool slug. Combined with toolkit slug to form LOCAL_<TOOLKIT>_<TOOL> (max 60 chars total).",+ "example": "GET_CUSTOMER_ORDERS"+ },+ "name": {+ "type": "string",+ "minLength": 1,+ "maxLength": 128,+ "description": "Human-readable display name",+ "example": "Get Customer Orders"+ },+ "description": {+ "type": "string",+ "minLength": 1,+ "maxLength": 5120,+ "description": "Used for BM25 search matching and shown to the LLM.",+ "example": "Fetch recent orders for a customer by their email address"+ },+ "input_schema": {+ "type": "object",+ "additionalProperties": {},+ "description": "Must have type: \"object\" and a properties field.",+ "example": {+ "type": "object",+ "properties": {+ "email": {+ "type": "string",+ "description": "Customer email"+ }+ },+ "required": [+ "email"+ ]+ }+ },+ "output_schema": {+ "type": "object",+ "additionalProperties": {},+ "description": "Optional output schema for the tool response."+ }+ },+ "required": [+ "slug",+ "name",+ "description",+ "input_schema"+ ]+ },+ "minItems": 1,+ "maxItems": 100,+ "description": "Tools in this custom toolkit"+ }+ },+ "required": [+ "slug",+ "name",+ "description",+ "tools"+ ]+ },+ "description": "Custom toolkits with grouped tools. Toolkit slugs must not conflict with existing Composio toolkits. All tools are no-auth."+ },+ "custom_tools": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "slug": {+ "type": "string",+ "minLength": 1,+ "pattern": "^[a-zA-Z0-9_-]+$",+ "description": "Tool slug. Forms LOCAL_<TOOL> (standalone) or LOCAL_<TOOLKIT>_<TOOL> (extending). Max 60 chars total.",+ "example": "GET_IMPORTANT_EMAILS"+ },+ "name": {+ "type": "string",+ "minLength": 1,+ "maxLength": 128,+ "description": "Human-readable display name",+ "example": "Get Important Emails"+ },+ "description": {+ "type": "string",+ "minLength": 1,+ "maxLength": 5120,+ "description": "Used for BM25 search matching and shown to the LLM.",+ "example": "Fetch emails marked as important from the last 24 hours"},- "description": "Only these specific toolkits will be enabled",- "example": [- "gmail",- "slack",- "github"- ]- }- },- "required": [- "enable"- ],- "additionalProperties": false,- "description": "Enable only specific toolkits (allowlist)"- },- {- "type": "object",- "properties": {- "disable": {- "type": "array",- "items": {- "type": "string"+ "input_schema": {+ "type": "object",+ "additionalProperties": {},+ "description": "Must have type: \"object\" and a properties field.",+ "example": {+ "type": "object",+ "properties": {+ "limit": {+ "type": "number",+ "description": "Max results to return"+ }+ }+ }},- "description": "These specific toolkits will be disabled",- "example": [- "gmail",- "slack"- ]- }+ "output_schema": {+ "type": "object",+ "additionalProperties": {},+ "description": "JSON Schema describing tool output (optional)"+ },+ "extends_toolkit": {+ "type": "string",+ "minLength": 1,+ "description": "If set, must be a valid Composio toolkit slug. The tool inherits that toolkit's auth/connection status. If omitted, the tool is standalone (no-auth).",+ "example": "gmail"+ }+ },+ "required": [+ "slug",+ "name",+ "description",+ "input_schema"+ ]},- "required": [- "disable"- ],- "additionalProperties": false,- "description": "Disable specific toolkits (denylist)"+ "description": "Custom tools to include in search. Standalone tools need no auth. Tools with extends_toolkit inherit the Composio toolkit's connection."}- ],- "description": "Toolkit configuration - specify either enable toolkits (allowlist) or disable toolkits (denylist). Mutually exclusive."- },- "auth_configs": {- "type": "object",- "additionalProperties": {- "type": "string",- "format": "authConfigId"},- "description": "The auth configs to use for the session. This will override the default behavior and use the given auth config when specific toolkits are being executed",- "example": {+ "additionalProperties": false,+ "description": "Experimental features - not stable, may be modified or removed in future versions.",+ "x-experimental": true+ }+ },+ "required": [+ "user_id"+ ]+ },+ "examples": {+ "Session with all toolkits": {+ "value": {+ "user_id": "user_123456789"+ }+ },+ "Session with only specific toolkits": {+ "value": {+ "user_id": "user_123456789",+ "toolkits": {+ "enable": [+ "gmail",+ "slack"+ ]+ }+ }+ },+ "Session with only specific toolkits disabled": {+ "value": {+ "user_id": "user_123456789",+ "toolkits": {+ "disable": [+ "gmail",+ "slack"+ ]+ }+ }+ },+ "Session with connection manager enabled": {+ "value": {+ "user_id": "user_123456789",+ "manage_connections": {+ "enable": true+ }+ }+ },+ "Session with connection manager and specific toolkits": {+ "value": {+ "user_id": "user_123456789",+ "toolkits": {+ "enable": [+ "gmail",+ "slack"+ ]+ },+ "manage_connections": {+ "enable": true+ }+ }+ },+ "Session with custom callback URL": {+ "value": {+ "user_id": "user_123456789",+ "toolkits": {+ "enable": [+ "github",+ "slack"+ ]+ },+ "manage_connections": {+ "enable": true,+ "callback_url": "https://your-app.com/auth/callback"+ }+ }+ },+ "Session with workbench configuration": {+ "value": {+ "user_id": "user_123456789",+ "toolkits": {+ "enable": [+ "gmail"+ ]+ },+ "workbench": {+ "enable_proxy_execution": true,+ "auto_offload_threshold": 10000+ }+ }+ },+ "Session with global tags filter": {+ "value": {+ "user_id": "user_123456789",+ "toolkits": {+ "enable": [+ "gmail",+ "slack"+ ]+ },+ "tags": [+ "readOnlyHint",+ "idempotentHint"+ ]+ }+ },+ "Session with auth config overrides": {+ "value": {+ "user_id": "user_123456789",+ "toolkits": {+ "enable": [+ "gmail",+ "slack"+ ]+ },+ "auth_configs": {"gmail": "ac_1223434343","slack": "ac_23343434343434"}- },- "connected_accounts": {- "type": "object",- "additionalProperties": {- "type": "string",- "format": "connectedAccountId"+ }+ },+ "Session with connected account overrides": {+ "value": {+ "user_id": "user_123456789",+ "toolkits": {+ "enable": [+ "gmail",+ "slack"+ ]},- "description": "The connected accounts to use for the session. This will override the default behaviour and use the given connected account when specific toolkits are being executed",- "example": {- "github": "ca_34454545454545"+ "connected_accounts": {+ "gmail": "ca_1223434343",+ "slack": "ca_23344434343434"}- },- "manage_connections": {- "type": "object",- "properties": {- "enable": {- "type": "boolean",- "nullable": true,- "default": true,- "description": "Whether to enable the connection manager for automatic connection handling. If true, we will provide a tool your agent can use to initiate connections to toolkits if it doesnt exist. If set to false, then you have to manage connections manually.",- "example": true- },- "callback_url": {- "type": "string",- "format": "uri",- "description": "The URL to redirect to after a user completes authentication for a connected account. This allows you to handle the auth callback in your own application.",- "example": "https://your-app.com/auth/callback"- },- "enable_wait_for_connections": {- "type": "boolean",- "nullable": true,- "default": false,- "description": "When true, the COMPOSIO_WAIT_FOR_CONNECTIONS tool is available for agents to poll connection status after sharing auth URLs. Default is false (disabled). May not work reliably with GPT models.",- "example": false- },- "enable_connection_removal": {- "type": "boolean",- "nullable": true,- "default": true,- "description": "Enable the \"remove\" action in COMPOSIO_MANAGE_CONNECTIONS to allow deleting connected accounts. Default true."- }+ }+ },+ "Session with comprehensive configuration": {+ "value": {+ "user_id": "user_123456789",+ "toolkits": {+ "enable": [+ "gmail",+ "slack",+ "github"+ ]+ },+ "auth_configs": {+ "gmail": "ac_1223434343",+ "slack": "ac_23343434343434"},- "default": {- "enable": true,- "enable_wait_for_connections": false,- "enable_connection_removal": true+ "connected_accounts": {+ "github": "ca_34454545454545"},- "additionalProperties": false,- "description": "Configuration for connection management settings"- },- "tools": {- "type": "object",- "additionalProperties": {- "anyOf": [- {- "type": "object",- "properties": {- "enable": {- "type": "array",- "items": {- "type": "string"- },- "description": "Only these specific tools will be available for this toolkit",- "example": [- "GMAIL_SEND_EMAIL",- "GMAIL_FETCH_EMAILS"- ]- }- },- "required": [- "enable"- ],- "additionalProperties": false- },- {- "type": "object",- "properties": {- "disable": {- "type": "array",- "items": {- "type": "string"- },- "description": "These specific tools will be disabled for this toolkit",- "example": [- "SLACK_ADD_EMOJI"- ]- }- },- "required": [- "disable"- ],- "additionalProperties": false- },- {- "type": "object",- "properties": {- "tags": {- "anyOf": [- {- "type": "array",- "items": {- "type": "string",- "enum": [- "readOnlyHint",- "destructiveHint",- "idempotentHint",- "openWorldHint"- ]- }- },- {- "type": "object",- "properties": {- "enable": {- "type": "array",- "items": {- "type": "string",- "enum": [- "readOnlyHint",- "destructiveHint",- "idempotentHint",- "openWorldHint"- ]- },- "description": "Tags that the tool must have at least one of"- },- "disable": {- "type": "array",- "items": {- "type": "string",- "enum": [- "readOnlyHint",- "destructiveHint",- "idempotentHint",- "openWorldHint"- ]- },- "description": "Tags that the tool must NOT have any of"- }- }- }- ],- "description": "MCP tags to filter tools. Array format is treated as enabled list. Object format supports both enabled and disabled lists.",- "example": {- "enable": [- "openWorldHint"- ],- "disable": [- "destructiveHint"- ]- }- }- },- "required": [- "tags"- ],- "additionalProperties": false- }- ]+ "manage_connections": {+ "enable": true,+ "callback_url": "https://your-app.com/auth/callback"},- "description": "Tool-level configuration per toolkit - either specify enable tools (whitelist), disable tools (blacklist), or filter by MCP tags for each toolkit",- "example": {+ "tools": {"gmail": {"enable": ["GMAIL_SEND_EMAIL",@@ -14609,478 +14174,864 @@]},"slack_bot": {- "tags": {- "enable": [- "destructiveHint"- ],- "disable": [- "openWorldHint"- ]- }- }- }- },- "tags": {- "anyOf": [- {- "type": "array",- "items": {- "type": "string",- "enum": [- "readOnlyHint",- "destructiveHint",- "idempotentHint",- "openWorldHint"- ]- }- },- {- "type": "object",- "properties": {- "enable": {- "type": "array",- "items": {- "type": "string",- "enum": [- "readOnlyHint",- "destructiveHint",- "idempotentHint",- "openWorldHint"- ]- },- "description": "Tags that the tool must have at least one of"- },- "disable": {- "type": "array",- "items": {- "type": "string",- "enum": [- "readOnlyHint",- "destructiveHint",- "idempotentHint",- "openWorldHint"- ]- },- "description": "Tags that the tool must NOT have any of"- }- }+ "tags": [+ "destructiveHint"+ ]}+ },+ "tags": [+ "destructiveHint",+ "idempotentHint"],- "description": "Global MCP tool annotation hints for filtering. Array format is treated as enabled list. Object format supports both enabled (tool must have at least one) and disabled (tool must NOT have any) lists. Toolkit-level tags override this. Toolkit enabled/disabled lists take precedence over tag filtering.",- "example": {- "enable": [- "openWorldHint"- ],+ "workbench": {+ "enable_proxy_execution": true,+ "auto_offload_threshold": 10000+ }+ }+ },+ "Session with disabled toolkits and global tags": {+ "value": {+ "user_id": "user_123456789",+ "toolkits": {"disable": [- "destructiveHint"+ "gmail"]- }- },- "workbench": {- "type": "object",- "properties": {- "enable": {- "type": "boolean",- "default": true,- "description": "Set to false to disable the workbench entirely. When disabled, no code execution tools are available in the session.",- "example": true- },- "enable_proxy_execution": {- "type": "boolean",- "default": true,- "description": "Whether proxy execution is enabled. When enabled, workbench can call URLs and APIs directly.",- "example": true+ },+ "tags": [+ "readOnlyHint"+ ]+ }+ }+ }+ }+ }+ },+ "responses": {+ "201": {+ "description": "Session successfully created. Returns the session ID and MCP server URL for the created session.",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "session_id": {+ "type": "string",+ "format": "toolRouterSessionId",+ "description": "The identifier of the session",+ "example": "trs_123456789"+ },+ "mcp": {+ "type": "object",+ "properties": {+ "type": {+ "type": "string",+ "enum": [+ "http"+ ],+ "description": "The type of the MCP server. Can be http"+ },+ "url": {+ "type": "string",+ "format": "uri",+ "description": "The URL of the MCP server",+ "example": "https://app.composio.dev/tool_router/v3/trs_123456789/mcp"+ }},- "auto_offload_threshold": {- "type": "number",- "minimum": 0,- "exclusiveMinimum": true,- "description": "Character threshold for automatic offloading. When workbench response exceeds this threshold, it will be automatically offloaded. Default is picked automatically based on the response size.",- "example": 20000- }+ "required": [+ "type",+ "url"+ ]},- "default": {- "enable": true,- "enable_proxy_execution": true+ "tool_router_tools": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "List of available tools in this session"},- "additionalProperties": false,- "description": "Configuration for workbench behavior"- },- "experimental": {- "type": "object",- "properties": {- "assistive_prompt_config": {- "type": "object",- "properties": {- "user_timezone": {+ "config": {+ "type": "object",+ "properties": {+ "user_id": {+ "type": "string",+ "description": "User identifier for this session"+ },+ "toolkits": {+ "anyOf": [+ {+ "type": "object",+ "properties": {+ "enabled": {+ "type": "array",+ "items": {+ "type": "string"+ }+ }+ },+ "required": [+ "enabled"+ ],+ "additionalProperties": false+ },+ {+ "type": "object",+ "properties": {+ "disabled": {+ "type": "array",+ "items": {+ "type": "string"+ }+ }+ },+ "required": [+ "disabled"+ ],+ "additionalProperties": false+ }+ ],+ "description": "Toolkit configuration - either enabled list or disabled list"+ },+ "auth_configs": {+ "type": "object",+ "additionalProperties": {"type": "string",- "description": "IANA timezone identifier (e.g., 'America/New_York', 'Europe/London'). Used to customize the system prompt with timezone-aware instructions.",- "example": "America/New_York"- }+ "format": "authConfigId"+ },+ "description": "Auth config overrides per toolkit"},- "additionalProperties": false,- "description": "Customize assistive prompt generation (e.g., timezone)."- },- "custom_toolkits": {- "type": "array",- "items": {+ "connected_accounts": {+ "type": "object",+ "additionalProperties": {+ "type": "string",+ "format": "connectedAccountId"+ },+ "description": "Connected account overrides per toolkit"+ },+ "manage_connections": {"type": "object","properties": {- "slug": {- "type": "string",- "minLength": 1,- "pattern": "^[a-zA-Z0-9_-]+$",- "description": "Unique slug for the toolkit. Must not conflict with existing Composio toolkit slugs. Alphanumeric, underscores, and hyphens only.",- "example": "ecommerce"+ "enabled": {+ "type": "boolean",+ "default": true,+ "description": "Whether to enable the connection manager for automatic connection handling"},- "name": {+ "callback_url": {"type": "string",- "minLength": 1,- "maxLength": 128,- "description": "Display name shown to the LLM and in search results.",- "example": "E-Commerce API"+ "format": "uri",+ "description": "Custom callback URL for connected account auth flows"},- "description": {- "type": "string",- "minLength": 1,- "maxLength": 2048,- "description": "Used for BM25 search matching and shown in toolkit connection statuses.",- "example": "Internal e-commerce API for order management and fulfillment"+ "enable_wait_for_connections": {+ "type": "boolean",+ "default": false,+ "description": "Enable the COMPOSIO_WAIT_FOR_CONNECTIONS tool for polling connection status. Default false. May not work reliably with GPT models."},- "tools": {- "type": "array",- "items": {+ "enable_connection_removal": {+ "type": "boolean",+ "default": true,+ "description": "Enable the \"remove\" action in COMPOSIO_MANAGE_CONNECTIONS. Default true."+ }+ },+ "description": "Manage connections configuration"+ },+ "tools": {+ "type": "object",+ "additionalProperties": {+ "anyOf": [+ {"type": "object","properties": {- "slug": {- "type": "string",- "minLength": 1,- "pattern": "^[a-zA-Z0-9_-]+$",- "description": "Tool slug. Combined with toolkit slug to form LOCAL_<TOOLKIT>_<TOOL> (max 60 chars total).",- "example": "GET_CUSTOMER_ORDERS"- },- "name": {- "type": "string",- "minLength": 1,- "maxLength": 128,- "description": "Human-readable display name",- "example": "Get Customer Orders"- },- "description": {- "type": "string",- "minLength": 1,- "maxLength": 5120,- "description": "Used for BM25 search matching and shown to the LLM.",- "example": "Fetch recent orders for a customer by their email address"- },- "input_schema": {+ "enabled": {+ "type": "array",+ "items": {+ "type": "string"+ }+ }+ },+ "required": [+ "enabled"+ ],+ "additionalProperties": false+ },+ {+ "type": "object",+ "properties": {+ "disabled": {+ "type": "array",+ "items": {+ "type": "string"+ }+ }+ },+ "required": [+ "disabled"+ ],+ "additionalProperties": false+ },+ {+ "type": "object",+ "properties": {+ "tags": {"type": "object",- "additionalProperties": {},- "description": "Must have type: \"object\" and a properties field.",- "example": {- "type": "object",- "properties": {- "email": {+ "properties": {+ "enabled": {+ "type": "array",+ "items": {"type": "string",- "description": "Customer email"- }+ "enum": [+ "readOnlyHint",+ "destructiveHint",+ "idempotentHint",+ "openWorldHint"+ ]+ },+ "description": "Tags that the tool must have at least one of"},- "required": [- "email"- ]+ "disabled": {+ "type": "array",+ "items": {+ "type": "string",+ "enum": [+ "readOnlyHint",+ "destructiveHint",+ "idempotentHint",+ "openWorldHint"+ ]+ },+ "description": "Tags that the tool must NOT have any of"+ }}- },- "output_schema": {- "type": "object",- "additionalProperties": {},- "description": "Optional output schema for the tool response."}},"required": [- "slug",- "name",- "description",- "input_schema"+ "tags"+ ],+ "additionalProperties": false+ }+ ]+ },+ "description": "Tool-level configuration per toolkit"+ },+ "tags": {+ "type": "object",+ "properties": {+ "enabled": {+ "type": "array",+ "items": {+ "type": "string",+ "enum": [+ "readOnlyHint",+ "destructiveHint",+ "idempotentHint",+ "openWorldHint"]},- "minItems": 1,- "maxItems": 100,- "description": "Tools in this custom toolkit"+ "description": "Tags that the tool must have at least one of"+ },+ "disabled": {+ "type": "array",+ "items": {+ "type": "string",+ "enum": [+ "readOnlyHint",+ "destructiveHint",+ "idempotentHint",+ "openWorldHint"+ ]+ },+ "description": "Tags that the tool must NOT have any of"}},- "required": [- "slug",- "name",- "description",- "tools"- ]+ "description": "MCP tool annotation hints for filtering tools with enabled/disabled support. enabled: tags that the tool must have at least one of. disabled: tags that the tool must NOT have any of. Both conditions must be satisfied."},- "description": "Custom toolkits with grouped tools. Toolkit slugs must not conflict with existing Composio toolkits. All tools are no-auth."- },- "custom_tools": {- "type": "array",- "items": {+ "workbench": {"type": "object","properties": {- "slug": {- "type": "string",- "minLength": 1,- "pattern": "^[a-zA-Z0-9_-]+$",- "description": "Tool slug. Forms LOCAL_<TOOL> (standalone) or LOCAL_<TOOLKIT>_<TOOL> (extending). Max 60 chars total.",- "example": "GET_IMPORTANT_EMAILS"- },- "name": {- "type": "string",- "minLength": 1,- "maxLength": 128,- "description": "Human-readable display name",- "example": "Get Important Emails"- },- "description": {- "type": "string",- "minLength": 1,- "maxLength": 5120,- "description": "Used for BM25 search matching and shown to the LLM.",- "example": "Fetch emails marked as important from the last 24 hours"- },- "input_schema": {- "type": "object",- "additionalProperties": {},- "description": "Must have type: \"object\" and a properties field.",- "example": {- "type": "object",- "properties": {- "limit": {- "type": "number",- "description": "Max results to return"- }- }- }- },- "output_schema": {- "type": "object",- "additionalProperties": {},- "description": "JSON Schema describing tool output (optional)"+ "enable": {+ "type": "boolean",+ "description": "Whether the workbench (code execution sandbox) is enabled. When false, COMPOSIO_REMOTE_WORKBENCH and COMPOSIO_REMOTE_BASH_TOOL are not exposed."},- "extends_toolkit": {- "type": "string",- "minLength": 1,- "description": "If set, must be a valid Composio toolkit slug. The tool inherits that toolkit's auth/connection status. If omitted, the tool is standalone (no-auth).",- "example": "gmail"- }- },- "required": [- "slug",- "name",- "description",- "input_schema"- ]- },- "description": "Custom tools to include in search. Standalone tools need no auth. Tools with extends_toolkit inherit the Composio toolkit's connection."- }- },- "additionalProperties": false,- "description": "Experimental features - not stable, may be modified or removed in future versions.",- "x-experimental": true- }- },- "required": [- "user_id"- ]- },- "examples": {- "Session with all toolkits": {- "value": {- "user_id": "user_123456789"- }- },- "Session with only specific toolkits": {- "value": {- "user_id": "user_123456789",- "toolkits": {- "enable": [- "gmail",- "slack"- ]- }- }- },- "Session with only specific toolkits disabled": {- "value": {- "user_id": "user_123456789",- "toolkits": {- "disable": [- "gmail",- "slack"- ]- }- }- },- "Session with connection manager enabled": {- "value": {- "user_id": "user_123456789",- "manage_connections": {- "enable": true- }- }- },- "Session with connection manager and specific toolkits": {- "value": {- "user_id": "user_123456789",- "toolkits": {- "enable": [- "gmail",- "slack"- ]- },- "manage_connections": {- "enable": true- }- }- },- "Session with custom callback URL": {- "value": {- "user_id": "user_123456789",- "toolkits": {- "enable": [- "github",- "slack"- ]- },- "manage_connections": {- "enable": true,- "callback_url": "https://your-app.com/auth/callback"- }- }- },- "Session with workbench configuration": {- "value": {- "user_id": "user_123456789",- "toolkits": {- "enable": [- "gmail"- ]- },- "workbench": {- "enable_proxy_execution": true,- "auto_offload_threshold": 10000- }- }- },- "Session with global tags filter": {- "value": {- "user_id": "user_123456789",- "toolkits": {- "enable": [- "gmail",- "slack"- ]- },- "tags": [- "readOnlyHint",- "idempotentHint"- ]- }- },- "Session with auth config overrides": {- "value": {- "user_id": "user_123456789",- "toolkits": {- "enable": [- "gmail",- "slack"- ]- },- "auth_configs": {- "gmail": "ac_1223434343",- "slack": "ac_23343434343434"- }- }- },- "Session with connected account overrides": {- "value": {- "user_id": "user_123456789",- "toolkits": {- "enable": [- "gmail",- "slack"- ]- },- "connected_accounts": {- "gmail": "ca_1223434343",- "slack": "ca_23344434343434"- }- }- },- "Session with comprehensive configuration": {- "value": {- "user_id": "user_123456789",- "toolkits": {- "enable": [- "gmail",- "slack",- "github"- ]- },- "auth_configs": {- "gmail": "ac_1223434343",- "slack": "ac_23343434343434"- },- "connected_accounts": {- "github": "ca_34454545454545"- },- "manage_connections": {- "enable": true,- "callback_url": "https://your-app.com/auth/callback"- },- "tools": {- "gmail": {- "enable": [- "GMAIL_SEND_EMAIL",- "GMAIL_FETCH_EMAILS"- ]+ "proxy_execution_enabled": {+ "type": "boolean",+ "description": "Whether proxy execution is enabled in the workbench"+ },+ "auto_offload_threshold": {+ "type": "number",+ "minimum": 0,+ "exclusiveMinimum": true,+ "description": "Character threshold after which tool execution response are saved to a file in workbench. Default is 20k."+ }+ },+ "default": {+ "enable": true,+ "proxy_execution_enabled": true+ },+ "description": "Workbench configuration"+ }},- "slack": {- "disable": [- "SLACK_ADD_EMOJI"- ]+ "required": [+ "user_id"+ ],+ "description": "The session configuration including user, toolkits, and overrides"+ },+ "experimental": {+ "type": "object",+ "properties": {+ "assistive_prompt": {+ "type": "string",+ "description": "The assistive system prompt for the tool router session"+ },+ "custom_toolkits": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "slug": {+ "type": "string",+ "minLength": 1,+ "pattern": "^[a-zA-Z0-9_-]+$"+ },+ "name": {+ "type": "string",+ "minLength": 1,+ "maxLength": 128+ },+ "description": {+ "type": "string",+ "minLength": 1,+ "maxLength": 2048+ },+ "tools": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "slug": {+ "type": "string",+ "description": "Prefixed tool slug (e.g. LOCAL_CRM_FIND_CUSTOMER)"+ },+ "name": {+ "type": "string",+ "minLength": 1,+ "maxLength": 128+ },+ "description": {+ "type": "string",+ "minLength": 1,+ "maxLength": 5120+ },+ "input_schema": {+ "type": "object",+ "additionalProperties": {}+ },+ "output_schema": {+ "type": "object",+ "additionalProperties": {}+ },+ "original_slug": {+ "type": "string",+ "description": "Original tool slug as provided by the user"+ }+ },+ "required": [+ "slug",+ "name",+ "description",+ "input_schema",+ "original_slug"+ ]+ }+ }+ },+ "required": [+ "slug",+ "name",+ "description",+ "tools"+ ]+ },+ "description": "User-defined custom toolkits with grouped tools (no-auth)"+ },+ "custom_tools": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "slug": {+ "type": "string",+ "description": "Prefixed tool slug (e.g. LOCAL_GMAIL_GET_IMPORTANT_EMAILS)"+ },+ "name": {+ "type": "string",+ "minLength": 1,+ "maxLength": 128+ },+ "description": {+ "type": "string",+ "minLength": 1,+ "maxLength": 5120+ },+ "input_schema": {+ "type": "object",+ "additionalProperties": {}+ },+ "output_schema": {+ "type": "object",+ "additionalProperties": {}+ },+ "extends_toolkit": {+ "type": "string",+ "minLength": 1+ },+ "original_slug": {+ "type": "string",+ "description": "Original tool slug as provided by the user"+ }+ },+ "required": [+ "slug",+ "name",+ "description",+ "input_schema",+ "original_slug"+ ]+ },+ "description": "Custom tools — standalone or extending Composio toolkits"+ }},- "slack_bot": {- "tags": [- "destructiveHint"- ]+ "description": "Experimental features including the generated system prompt. Only returned on session creation, not on GET.",+ "x-experimental": true+ }+ },+ "required": [+ "session_id",+ "mcp",+ "tool_router_tools",+ "config"+ ]+ }+ }+ }+ },+ "400": {+ "description": "Bad request. This may occur if the user_id format is invalid, toolkit names are invalid, or auth_config_id IDs are malformed.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "401": {+ "description": "Unauthorized. Authentication is required or the provided credentials are invalid.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "403": {+ "description": "Forbidden. The user is not authorized to create a tool router session.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "500": {+ "description": "Internal server error. An unexpected error occurred while processing the request.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ }+ }+ }+ },+ "/api/v3/tool_router/session/{session_id}/execute": {+ "post": {+ "summary": "Execute a tool within a tool router session",+ "description": "Executes a specific tool within a tool router session. The toolkit is automatically inferred from the tool slug. The tool must belong to an allowed toolkit and must not be disabled in the session configuration. This endpoint validates permissions, resolves connected accounts, and executes the tool with the session context.",+ "tags": [+ "Tool Router"+ ],+ "operationId": "postToolRouterSessionBySessionIdExecute",+ "security": [+ {+ "ApiKeyAuth": []+ },+ {+ "UserApiKeyAuth": []+ },+ {+ "workbench_access_key": []+ }+ ],+ "parameters": [+ {+ "schema": {+ "type": "string",+ "format": "toolRouterSessionId",+ "description": "The unique identifier of the tool router session. Required for public API endpoints, optional for internal endpoints where it is injected by middleware.",+ "example": "trs_LX9uJKBinWWr"+ },+ "required": false,+ "description": "Tool router session ID (required for public API, optional for internal - injected by middleware)",+ "name": "session_id",+ "in": "path"+ }+ ],+ "requestBody": {+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "tool_slug": {+ "type": "string",+ "minLength": 1,+ "description": "The unique slug identifier of the tool to execute",+ "example": "GITHUB_CREATE_ISSUE"+ },+ "arguments": {+ "type": "object",+ "additionalProperties": {},+ "default": {},+ "description": "The arguments required by the tool",+ "example": {+ "repository": "octocat/Hello-World",+ "workflow_id": "main.yml",+ "ref": "main",+ "inputs": {+ "environment": "production"+ }+ }+ },+ "account": {+ "type": "string",+ "description": "Account identifier to specify which connected account to use. Use the account ID (e.g. \"coup_hurricane_dal_analytical\") or an alias. When omitted with a single account, the default is used. When omitted with multiple accounts, an error lists available accounts.",+ "example": "coup_hurricane_dal_analytical"+ }+ },+ "required": [+ "tool_slug"+ ]+ }+ }+ }+ },+ "responses": {+ "200": {+ "description": "Successfully executed the tool. Returns execution result, logs, and status.",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "data": {+ "type": "object",+ "additionalProperties": {},+ "description": "The data returned by the tool execution",+ "example": {+ "message": "Hello, World!",+ "status": "success"}},- "tags": [- "destructiveHint",- "idempotentHint"+ "error": {+ "type": "string",+ "nullable": true,+ "description": "Error message if the execution failed, null otherwise"+ },+ "log_id": {+ "type": "string",+ "description": "Unique identifier for the execution log",+ "example": "log_abc123xyz"+ }+ },+ "required": [+ "data",+ "error",+ "log_id"+ ]+ }+ }+ }+ },+ "400": {+ "description": "Bad request",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "401": {+ "description": "Unauthorized",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "403": {+ "description": "Forbidden",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "404": {+ "description": "Not found",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "413": {+ "description": "Payload too large",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "500": {+ "description": "Internal server error",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ }+ }+ }+ },+ "/api/v3/tool_router/session/{session_id}/execute_meta": {+ "post": {+ "summary": "Execute a meta tool within a tool router session",+ "description": "Executes a Composio meta tool (COMPOSIO_*) within a tool router session.",+ "tags": [+ "Tool Router"+ ],+ "operationId": "postToolRouterSessionBySessionIdExecuteMeta",+ "security": [+ {+ "ApiKeyAuth": []+ },+ {+ "UserApiKeyAuth": []+ }+ ],+ "parameters": [+ {+ "schema": {+ "type": "string",+ "format": "toolRouterSessionId",+ "description": "The unique identifier of the tool router session. Required for public API endpoints, optional for internal endpoints where it is injected by middleware.",+ "example": "trs_LX9uJKBinWWr"+ },+ "required": false,+ "description": "Tool router session ID (required for public API, optional for internal - injected by middleware)",+ "name": "session_id",+ "in": "path"+ }+ ],+ "requestBody": {+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "slug": {+ "type": "string",+ "enum": [+ "COMPOSIO_SEARCH_TOOLS",+ "COMPOSIO_MULTI_EXECUTE_TOOL",+ "COMPOSIO_MANAGE_CONNECTIONS",+ "COMPOSIO_WAIT_FOR_CONNECTIONS",+ "COMPOSIO_REMOTE_WORKBENCH",+ "COMPOSIO_REMOTE_BASH_TOOL",+ "COMPOSIO_GET_TOOL_SCHEMAS",+ "COMPOSIO_UPSERT_RECIPE",+ "COMPOSIO_GET_RECIPE"],- "workbench": {- "enable_proxy_execution": true,- "auto_offload_threshold": 10000+ "description": "The unique slug identifier of the meta tool to execute",+ "example": "COMPOSIO_MANAGE_CONNECTIONS"+ },+ "arguments": {+ "type": "object",+ "additionalProperties": {},+ "default": {},+ "description": "The arguments required by the meta tool",+ "example": {+ "toolkits": [+ "github"+ ],+ "reinitiate_all": false}}},- "Session with disabled toolkits and global tags": {- "value": {- "user_id": "user_123456789",- "toolkits": {- "disable": [- "gmail"- ]+ "required": [+ "slug"+ ]+ }+ }+ }+ },+ "responses": {+ "200": {+ "description": "Successfully executed the meta tool. Returns execution result, logs, and status.",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "data": {+ "type": "object",+ "additionalProperties": {},+ "description": "The data returned by the tool execution",+ "example": {+ "message": "Hello, World!",+ "status": "success"+ }},- "tags": [- "readOnlyHint"- ]- }+ "error": {+ "type": "string",+ "nullable": true,+ "description": "Error message if the execution failed, null otherwise"+ },+ "log_id": {+ "type": "string",+ "description": "Unique identifier for the execution log",+ "example": "log_abc123xyz"+ }+ },+ "required": [+ "data",+ "error",+ "log_id"+ ]+ }+ }+ }+ },+ "400": {+ "description": "Bad request",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "401": {+ "description": "Unauthorized",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "403": {+ "description": "Forbidden",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "404": {+ "description": "Not found",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "413": {+ "description": "Payload too large",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "500": {+ "description": "Internal server error",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"}}}}- },+ }+ }+ },+ "/api/v3/tool_router/session/{session_id}": {+ "get": {+ "summary": "Get a tool router session by ID",+ "description": "Retrieves an existing tool router session by its ID. Returns the session configuration, MCP server URL, and available tools.",+ "tags": [+ "Tool Router"+ ],+ "operationId": "getToolRouterSessionBySessionId",+ "security": [+ {+ "ApiKeyAuth": []+ },+ {+ "UserApiKeyAuth": []+ }+ ],+ "parameters": [+ {+ "schema": {+ "type": "string",+ "format": "toolRouterSessionId",+ "description": "The session ID returned when creating the session",+ "example": "trs_123456789"+ },+ "required": true,+ "description": "The unique identifier of the tool router session",+ "name": "session_id",+ "in": "path"+ }+ ],"responses": {- "201": {- "description": "Session successfully created. Returns the session ID and MCP server URL for the created session.",+ "200": {+ "description": "Session successfully retrieved. Returns the session details including configuration.","content": {"application/json": {"schema": {@@ -15452,192 +15403,40 @@},"extends_toolkit": {"type": "string",- "minLength": 1- },- "original_slug": {- "type": "string",- "description": "Original tool slug as provided by the user"- }- },- "required": [- "slug",- "name",- "description",- "input_schema",- "original_slug"- ]- },- "description": "Custom tools — standalone or extending Composio toolkits"- }- },- "description": "Experimental features including the generated system prompt. Only returned on session creation, not on GET.",- "x-experimental": true- }- },- "required": [- "session_id",- "mcp",- "tool_router_tools",- "config"- ]- }- }- }- },- "400": {- "description": "Bad request. This may occur if the user_id format is invalid, toolkit names are invalid, or auth_config_id IDs are malformed.",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/Error"- }- }- }- },- "401": {- "description": "Unauthorized. Authentication is required or the provided credentials are invalid.",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/Error"- }- }- }- },- "403": {- "description": "Forbidden. The user is not authorized to create a tool router session.",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/Error"- }- }- }- },- "500": {- "description": "Internal server error. An unexpected error occurred while processing the request.",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/Error"- }- }- }- }- }- }- },- "/api/v3/tool_router/session/{session_id}/execute": {- "post": {- "summary": "Execute a tool within a tool router session",- "description": "Executes a specific tool within a tool router session. The toolkit is automatically inferred from the tool slug. The tool must belong to an allowed toolkit and must not be disabled in the session configuration. This endpoint validates permissions, resolves connected accounts, and executes the tool with the session context.",- "tags": [- "Tool Router"- ],- "operationId": "postToolRouterSessionBySessionIdExecute",- "security": [- {- "ApiKeyAuth": []- },- {- "UserApiKeyAuth": []- },- {- "workbench_access_key": []- }- ],- "parameters": [- {- "schema": {- "type": "string",- "format": "toolRouterSessionId",- "description": "The unique identifier of the tool router session. Required for public API endpoints, optional for internal endpoints where it is injected by middleware.",- "example": "trs_LX9uJKBinWWr"- },- "required": false,- "description": "Tool router session ID (required for public API, optional for internal - injected by middleware)",- "name": "session_id",- "in": "path"- }- ],- "requestBody": {- "content": {- "application/json": {- "schema": {- "type": "object",- "properties": {- "tool_slug": {- "type": "string",- "minLength": 1,- "description": "The unique slug identifier of the tool to execute",- "example": "GITHUB_CREATE_ISSUE"- },- "arguments": {- "type": "object",- "additionalProperties": {},- "default": {},- "description": "The arguments required by the tool",- "example": {- "repository": "octocat/Hello-World",- "workflow_id": "main.yml",- "ref": "main",- "inputs": {- "environment": "production"- }- }- },- "account": {- "type": "string",- "description": "Account identifier to specify which connected account to use. Use the account ID (e.g. \"coup_hurricane_dal_analytical\") or an alias. When omitted with a single account, the default is used. When omitted with multiple accounts, an error lists available accounts.",- "example": "coup_hurricane_dal_analytical"- }- },- "required": [- "tool_slug"- ]- }- }- }- },- "responses": {- "200": {- "description": "Successfully executed the tool. Returns execution result, logs, and status.",- "content": {- "application/json": {- "schema": {- "type": "object",- "properties": {- "data": {- "type": "object",- "additionalProperties": {},- "description": "The data returned by the tool execution",- "example": {- "message": "Hello, World!",- "status": "success"- }- },- "error": {- "type": "string",- "nullable": true,- "description": "Error message if the execution failed, null otherwise"- },- "log_id": {- "type": "string",- "description": "Unique identifier for the execution log",- "example": "log_abc123xyz"+ "minLength": 1+ },+ "original_slug": {+ "type": "string",+ "description": "Original tool slug as provided by the user"+ }+ },+ "required": [+ "slug",+ "name",+ "description",+ "input_schema",+ "original_slug"+ ]+ },+ "description": "Custom tools — standalone or extending Composio toolkits"+ }+ },+ "description": "Experimental features",+ "x-experimental": true}},"required": [- "data",- "error",- "log_id"+ "session_id",+ "mcp",+ "tool_router_tools",+ "config"]}}}},"400": {- "description": "Bad request",+ "description": "Bad request. This may occur if the session_id format is invalid, please pass this in trs_ prefix format","content": {"application/json": {"schema": {@@ -15647,17 +15446,7 @@}},"401": {- "description": "Unauthorized",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/Error"- }- }- }- },- "403": {- "description": "Forbidden",+ "description": "Unauthorized. Authentication is required or the provided credentials are invalid.","content": {"application/json": {"schema": {@@ -15667,17 +15456,7 @@}},"404": {- "description": "Not found",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/Error"- }- }- }- },- "413": {- "description": "Payload too large",+ "description": "Not found. The session with the provided ID does not exist or has been deleted.","content": {"application/json": {"schema": {@@ -15687,7 +15466,7 @@}},"500": {- "description": "Internal server error",+ "description": "Internal server error. An unexpected error occurred while processing the request.","content": {"application/json": {"schema": {@@ -15699,14 +15478,14 @@}}},- "/api/v3/tool_router/session/{session_id}/execute_meta": {+ "/api/v3/tool_router/session/{session_id}/link": {"post": {- "summary": "Execute a meta tool within a tool router session",- "description": "Executes a Composio meta tool (COMPOSIO_*) within a tool router session.",+ "summary": "Create a link session for a toolkit in a tool router session",+ "description": "Initiates an authentication link session for a specific toolkit within a tool router session. Returns a link token and redirect URL that users can use to complete the OAuth flow.","tags": ["Tool Router"],- "operationId": "postToolRouterSessionBySessionIdExecuteMeta",+ "operationId": "postToolRouterSessionBySessionIdLink","security": [{"ApiKeyAuth": []@@ -15720,11 +15499,11 @@"schema": {"type": "string","format": "toolRouterSessionId",- "description": "The unique identifier of the tool router session. Required for public API endpoints, optional for internal endpoints where it is injected by middleware.",+ "description": "The session ID returned when creating the session","example": "trs_LX9uJKBinWWr"},- "required": false,- "description": "Tool router session ID (required for public API, optional for internal - injected by middleware)",+ "required": true,+ "description": "The unique identifier of the tool router session","name": "session_id","in": "path"}@@ -15735,81 +15514,63 @@"schema": {"type": "object","properties": {- "slug": {+ "toolkit": {"type": "string",- "enum": [- "COMPOSIO_SEARCH_TOOLS",- "COMPOSIO_MULTI_EXECUTE_TOOL",- "COMPOSIO_MANAGE_CONNECTIONS",- "COMPOSIO_WAIT_FOR_CONNECTIONS",- "COMPOSIO_REMOTE_WORKBENCH",- "COMPOSIO_REMOTE_BASH_TOOL",- "COMPOSIO_GET_TOOL_SCHEMAS",- "COMPOSIO_UPSERT_RECIPE",- "COMPOSIO_GET_RECIPE"- ],- "description": "The unique slug identifier of the meta tool to execute",- "example": "COMPOSIO_MANAGE_CONNECTIONS"+ "minLength": 1,+ "description": "The unique slug identifier of the toolkit to connect",+ "example": "github"},- "arguments": {- "type": "object",- "additionalProperties": {},- "default": {},- "description": "The arguments required by the meta tool",- "example": {- "toolkits": [- "github"- ],- "reinitiate_all": false- }+ "callback_url": {+ "type": "string",+ "format": "uri",+ "description": "URL where users will be redirected after completing auth",+ "example": "https://myapp.com/callback"}},"required": [- "slug"+ "toolkit"]}}}},"responses": {- "200": {- "description": "Successfully executed the meta tool. Returns execution result, logs, and status.",+ "201": {+ "description": "Successfully created link session. Returns link token, redirect URL, and connected account ID.","content": {"application/json": {"schema": {"type": "object","properties": {- "data": {- "type": "object",- "additionalProperties": {},- "description": "The data returned by the tool execution",- "example": {- "message": "Hello, World!",- "status": "success"- }+ "link_token": {+ "type": "string",+ "description": "Token used to complete the authentication flow",+ "example": "lt_abc123xyz"},- "error": {+ "redirect_url": {"type": "string",- "nullable": true,- "description": "Error message if the execution failed, null otherwise"+ "format": "uri",+ "description": "The URL where users should be redirected to complete OAuth",+ "example": "https://app.composio.dev/link/lt_abc123xyz"},- "log_id": {+ "connected_account_id": {"type": "string",- "description": "Unique identifier for the execution log",- "example": "log_abc123xyz"+ "format": "connectedAccountId",+ "description": "The unique identifier for the connected account",+ "example": "ca_abc123xyz"}},"required": [- "data",- "error",- "log_id"+ "link_token",+ "redirect_url",+ "connected_account_id"]}}}},"400": {- "description": "Bad request",+ "description": "Bad request. This may occur if the toolkit slug is invalid, request parameters are malformed, or a connected account is already defined for this toolkit in the session configuration.","content": {"application/json": {"schema": {@@ -15819,7 +15580,7 @@}},"401": {- "description": "Unauthorized",+ "description": "Unauthorized. Authentication is required or the provided credentials are invalid.","content": {"application/json": {"schema": {@@ -15829,7 +15590,7 @@}},"403": {- "description": "Forbidden",+ "description": "Forbidden. The session does not belong to the authenticated user.","content": {"application/json": {"schema": {@@ -15839,17 +15600,7 @@}},"404": {- "description": "Not found",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/Error"- }- }- }- },- "413": {- "description": "Payload too large",+ "description": "Not found. The session does not exist, toolkit not found, or no auth config exists for the toolkit.","content": {"application/json": {"schema": {@@ -15859,7 +15610,7 @@}},"500": {- "description": "Internal server error",+ "description": "Internal server error. An unexpected error occurred while creating the link session.","content": {"application/json": {"schema": {@@ -15871,20 +15622,23 @@}}},- "/api/v3/tool_router/session/{session_id}": {- "get": {- "summary": "Get a tool router session by ID",- "description": "Retrieves an existing tool router session by its ID. Returns the session configuration, MCP server URL, and available tools.",+ "/api/v3/tool_router/session/{session_id}/proxy_execute": {+ "post": {+ "summary": "Execute proxy request within a tool router session",+ "description": "Execute any native API call on a toolkit with authentication automatically injected from Composio. This endpoint proxies HTTP requests to third-party APIs using connected account credentials resolved from the session context. Provide the toolkit slug, API endpoint, and HTTP method — Composio handles authentication injection, abstracting away credential management. Supports all HTTP methods, custom headers/query parameters, and binary request/response bodies.","tags": ["Tool Router"],- "operationId": "getToolRouterSessionBySessionId",+ "operationId": "postToolRouterSessionBySessionIdProxyExecute","security": [{"ApiKeyAuth": []},{"UserApiKeyAuth": []+ },+ {+ "workbench_access_key": []}],"parameters": [@@ -15892,423 +15646,621 @@"schema": {"type": "string","format": "toolRouterSessionId",- "description": "The session ID returned when creating the session",- "example": "trs_123456789"+ "description": "The unique identifier of the tool router session. Required for public API endpoints, optional for internal endpoints where it is injected by middleware.",+ "example": "trs_LX9uJKBinWWr"},- "required": true,- "description": "The unique identifier of the tool router session",+ "required": false,+ "description": "Tool router session ID (required for public API, optional for internal - injected by middleware)","name": "session_id","in": "path"}],- "responses": {- "200": {- "description": "Session successfully retrieved. Returns the session details including configuration.",- "content": {- "application/json": {- "schema": {- "type": "object",- "properties": {- "session_id": {- "type": "string",- "format": "toolRouterSessionId",- "description": "The identifier of the session",- "example": "trs_123456789"+ "requestBody": {+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "toolkit_slug": {+ "type": "string",+ "description": "The slug of the toolkit to use for the request",+ "example": "gmail"+ },+ "endpoint": {+ "type": "string",+ "description": "The API endpoint to call (absolute URL or path relative to base URL of the connected account)",+ "example": "/api/v1/resources"+ },+ "method": {+ "type": "string",+ "enum": [+ "GET",+ "POST",+ "PUT",+ "DELETE",+ "PATCH",+ "HEAD"+ ],+ "description": "The HTTP method to use for the request",+ "example": "GET"+ },+ "body": {+ "nullable": true,+ "description": "The request body (for POST, PUT, and PATCH requests)",+ "example": {+ "name": "New Resource",+ "description": "This is a new resource"},- "mcp": {+ "type": "object"+ },+ "binary_body": {+ "anyOf": [+ {+ "type": "object",+ "properties": {+ "url": {+ "type": "string",+ "format": "uri",+ "description": "URL to fetch binary content from"+ },+ "content_type": {+ "type": "string",+ "description": "Content-Type header to use for the request"+ }+ },+ "required": [+ "url"+ ]+ },+ {+ "type": "object",+ "properties": {+ "base64": {+ "type": "string",+ "minLength": 1,+ "description": "Base64-encoded binary data"+ },+ "content_type": {+ "type": "string",+ "description": "Content-Type header to use for the request"+ }+ },+ "required": [+ "base64"+ ]+ }+ ],+ "description": "Binary body to send. For binary upload via URL: use {url: \"https://...\", content_type?: \"...\"}. For binary upload via base64: use {base64: \"...\", content_type?: \"...\"}."+ },+ "parameters": {+ "type": "array",+ "items": {"type": "object","properties": {+ "name": {+ "type": "string",+ "description": "Parameter name",+ "example": "x-api-key"+ },+ "value": {+ "type": "string",+ "description": "Parameter value",+ "example": "abc123def456"+ },"type": {"type": "string","enum": [- "http"+ "header",+ "query"],- "description": "The type of the MCP server. Can be http"- },- "url": {- "type": "string",- "format": "uri",- "description": "The URL of the MCP server",- "example": "https://app.composio.dev/tool_router/v3/trs_123456789/mcp"+ "description": "Parameter type (header or query)",+ "example": "header"}},"required": [- "type",- "url"+ "name",+ "value",+ "type"]},- "tool_router_tools": {- "type": "array",- "items": {+ "description": "Additional HTTP headers or query parameters to include in the request",+ "example": [+ {+ "name": "x-api-key",+ "value": "abc123def456",+ "type": "header"+ },+ {+ "name": "filter",+ "value": "active",+ "type": "query"+ }+ ]+ },+ "custom_connection_data": {+ "type": "object",+ "properties": {+ "authScheme": {+ "type": "string",+ "enum": [+ "OAUTH2",+ "DCR_OAUTH",+ "API_KEY",+ "BASIC_WITH_JWT",+ "BASIC",+ "BEARER_TOKEN",+ "OAUTH1",+ "NO_AUTH",+ "SERVICE_ACCOUNT",+ "GOOGLE_SERVICE_ACCOUNT",+ "S2S_OAUTH2"+ ]+ },+ "toolkitSlug": {"type": "string"},- "description": "List of available tools in this session"- },- "config": {- "type": "object",- "properties": {- "user_id": {- "type": "string",- "description": "User identifier for this session"- },- "toolkits": {- "anyOf": [- {- "type": "object",- "properties": {- "enabled": {- "type": "array",- "items": {- "type": "string"- }- }- },- "required": [- "enabled"- ],- "additionalProperties": false- },- {- "type": "object",- "properties": {- "disabled": {- "type": "array",- "items": {- "type": "string"- }- }- },- "required": [- "disabled"- ],- "additionalProperties": false- }- ],- "description": "Toolkit configuration - either enabled list or disabled list"- },- "auth_configs": {- "type": "object",- "additionalProperties": {- "type": "string",- "format": "authConfigId"+ "val": {+ "type": "object",+ "properties": {+ "subdomain": {+ "type": "string"},- "description": "Auth config overrides per toolkit"- },- "connected_accounts": {- "type": "object",- "additionalProperties": {+ "your-domain": {+ "type": "string"+ },+ "region": {+ "type": "string"+ },+ "shop": {+ "type": "string"+ },+ "account_url": {+ "type": "string"+ },+ "COMPANYDOMAIN": {+ "type": "string"+ },+ "extension": {+ "type": "string"+ },+ "form_api_base_url": {+ "type": "string"+ },+ "instanceEndpoint": {+ "type": "string"+ },+ "api_url": {+ "type": "string"+ },+ "borneo_dashboard_url": {+ "type": "string"+ },+ "proxy_username": {+ "type": "string"+ },+ "proxy_password": {+ "type": "string"+ },+ "domain": {+ "type": "string"+ },+ "version": {+ "type": "string"+ },+ "dc": {+ "type": "string"+ },+ "site_name": {+ "type": "string"+ },+ "instanceName": {+ "type": "string"+ },+ "account_id": {+ "type": "string"+ },+ "your_server": {+ "type": "string"+ },+ "server_location": {+ "type": "string"+ },+ "base_url": {+ "type": "string"+ },+ "state_prefix": {"type": "string",- "format": "connectedAccountId"+ "maxLength": 40,+ "description": "The oauth2 state prefix for the connection"},- "description": "Connected account overrides per toolkit"- },- "manage_connections": {- "type": "object",- "properties": {- "enabled": {- "type": "boolean",- "default": true,- "description": "Whether to enable the connection manager for automatic connection handling"- },- "callback_url": {- "type": "string",- "format": "uri",- "description": "Custom callback URL for connected account auth flows"- },- "enable_wait_for_connections": {- "type": "boolean",- "default": false,- "description": "Enable the COMPOSIO_WAIT_FOR_CONNECTIONS tool for polling connection status. Default false. May not work reliably with GPT models."- },- "enable_connection_removal": {- "type": "boolean",- "default": true,- "description": "Enable the \"remove\" action in COMPOSIO_MANAGE_CONNECTIONS. Default true."- }+ "long_redirect_url": {+ "type": "boolean",+ "description": "Whether to return the redirect url without shortening"},- "description": "Manage connections configuration"- },- "tools": {- "type": "object",- "additionalProperties": {+ "access_token": {+ "type": "string"+ },+ "id_token": {+ "type": "string"+ },+ "token_type": {+ "type": "string"+ },+ "refresh_token": {+ "type": "string",+ "nullable": true+ },+ "expires_in": {"anyOf": [{- "type": "object",- "properties": {- "enabled": {- "type": "array",- "items": {- "type": "string"- }- }- },- "required": [- "enabled"- ],- "additionalProperties": false+ "type": "number"},{- "type": "object",- "properties": {- "disabled": {- "type": "array",- "items": {- "type": "string"- }- }- },- "required": [- "disabled"- ],- "additionalProperties": false+ "type": "string"},{- "type": "object",- "properties": {- "tags": {- "type": "object",- "properties": {- "enabled": {- "type": "array",- "items": {- "type": "string",- "enum": [- "readOnlyHint",- "destructiveHint",- "idempotentHint",- "openWorldHint"- ]- },- "description": "Tags that the tool must have at least one of"- },- "disabled": {- "type": "array",- "items": {- "type": "string",- "enum": [- "readOnlyHint",- "destructiveHint",- "idempotentHint",- "openWorldHint"- ]- },- "description": "Tags that the tool must NOT have any of"- }- }- }- },- "required": [- "tags"- ],- "additionalProperties": false+ "nullable": true,+ "type": "object"}]},- "description": "Tool-level configuration per toolkit"- },- "tags": {- "type": "object",- "properties": {- "enabled": {- "type": "array",- "items": {- "type": "string",- "enum": [- "readOnlyHint",- "destructiveHint",- "idempotentHint",- "openWorldHint"- ]+ "scope": {+ "anyOf": [+ {+ "type": "string"},- "description": "Tags that the tool must have at least one of"- },- "disabled": {- "type": "array",- "items": {- "type": "string",- "enum": [- "readOnlyHint",- "destructiveHint",- "idempotentHint",- "openWorldHint"- ]+ {+ "type": "array",+ "items": {+ "type": "string"+ }},- "description": "Tags that the tool must NOT have any of"- }+ {+ "nullable": true,+ "type": "object"+ }+ ]},- "description": "MCP tool annotation hints for filtering tools with enabled/disabled support. enabled: tags that the tool must have at least one of. disabled: tags that the tool must NOT have any of. Both conditions must be satisfied."- },- "workbench": {- "type": "object",- "properties": {- "enable": {- "type": "boolean",- "description": "Whether the workbench (code execution sandbox) is enabled. When false, COMPOSIO_REMOTE_WORKBENCH and COMPOSIO_REMOTE_BASH_TOOL are not exposed."- },- "proxy_execution_enabled": {- "type": "boolean",- "description": "Whether proxy execution is enabled in the workbench"+ "webhook_signature": {+ "type": "string"+ },+ "authed_user": {+ "type": "object",+ "properties": {+ "access_token": {+ "type": "string"+ },+ "scope": {+ "type": "string"+ }},- "auto_offload_threshold": {- "type": "number",- "minimum": 0,- "exclusiveMinimum": true,- "description": "Character threshold after which tool execution response are saved to a file in workbench. Default is 20k."- }+ "description": "for slack user scopes"},- "default": {- "enable": true,- "proxy_execution_enabled": true+ "client_id": {+ "type": "string",+ "description": "Dynamically registered client ID"},- "description": "Workbench configuration"- }- },- "required": [- "user_id"- ],- "description": "The session configuration including user, toolkits, and overrides"+ "client_secret": {+ "type": "string",+ "description": "Dynamically registered client secret"+ },+ "client_id_issued_at": {+ "type": "number"+ },+ "client_secret_expires_at": {+ "type": "number"+ },+ "generic_api_key": {+ "type": "string"+ },+ "api_key": {+ "type": "string"+ },+ "bearer_token": {+ "type": "string"+ },+ "basic_encoded": {+ "type": "string"+ },+ "username": {+ "type": "string"+ },+ "password": {+ "type": "string"+ },+ "token": {+ "type": "string"+ },+ "oauth_token": {+ "type": "string"+ },+ "oauth_token_secret": {+ "type": "string"+ },+ "oauth_verifier": {+ "type": "string"+ },+ "consumer_key": {+ "type": "string"+ },+ "redirectUrl": {+ "type": "string"+ },+ "callback_url": {+ "type": "string"+ },+ "application_id": {+ "type": "string"+ },+ "installation_id": {+ "type": "string"+ },+ "private_key": {+ "type": "string"+ },+ "credentials_json": {+ "type": "string"+ },+ "expires_at": {+ "type": "string"+ }+ },+ "required": [+ "access_token"+ ],+ "additionalProperties": {}+ }+ },+ "required": [+ "authScheme",+ "toolkitSlug",+ "val"+ ],+ "additionalProperties": true+ }+ },+ "required": [+ "toolkit_slug",+ "endpoint",+ "method"+ ]+ }+ }+ }+ },+ "responses": {+ "200": {+ "description": "Successfully executed proxy request and received response",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "data": {+ "nullable": true,+ "description": "The response data returned from the proxied API",+ "example": {+ "id": "123",+ "name": "Resource Name",+ "created_at": "2023-01-01T00:00:00Z"+ },+ "type": "object"},- "experimental": {+ "binary_data": {"type": "object","properties": {- "assistive_prompt": {+ "url": {"type": "string",- "description": "The assistive system prompt for the tool router session"+ "description": "URL to download binary content"},- "custom_toolkits": {- "type": "array",- "items": {- "type": "object",- "properties": {- "slug": {- "type": "string",- "minLength": 1,- "pattern": "^[a-zA-Z0-9_-]+$"- },- "name": {- "type": "string",- "minLength": 1,- "maxLength": 128- },- "description": {- "type": "string",- "minLength": 1,- "maxLength": 2048- },- "tools": {- "type": "array",- "items": {- "type": "object",- "properties": {- "slug": {- "type": "string",- "description": "Prefixed tool slug (e.g. LOCAL_CRM_FIND_CUSTOMER)"- },- "name": {- "type": "string",- "minLength": 1,- "maxLength": 128- },- "description": {- "type": "string",- "minLength": 1,- "maxLength": 5120- },- "input_schema": {- "type": "object",- "additionalProperties": {}- },- "output_schema": {- "type": "object",- "additionalProperties": {}- },- "original_slug": {- "type": "string",- "description": "Original tool slug as provided by the user"- }- },- "required": [- "slug",- "name",- "description",- "input_schema",- "original_slug"- ]- }- }- },- "required": [- "slug",- "name",- "description",- "tools"- ]- },- "description": "User-defined custom toolkits with grouped tools (no-auth)"+ "content_type": {+ "type": "string",+ "description": "Content-Type of the binary data"},- "custom_tools": {- "type": "array",- "items": {- "type": "object",- "properties": {- "slug": {- "type": "string",- "description": "Prefixed tool slug (e.g. LOCAL_GMAIL_GET_IMPORTANT_EMAILS)"- },- "name": {- "type": "string",- "minLength": 1,- "maxLength": 128- },- "description": {- "type": "string",- "minLength": 1,- "maxLength": 5120- },- "input_schema": {- "type": "object",- "additionalProperties": {}- },- "output_schema": {- "type": "object",- "additionalProperties": {}- },- "extends_toolkit": {- "type": "string",- "minLength": 1- },- "original_slug": {- "type": "string",- "description": "Original tool slug as provided by the user"- }- },- "required": [- "slug",- "name",- "description",- "input_schema",- "original_slug"- ]- },- "description": "Custom tools — standalone or extending Composio toolkits"+ "size": {+ "type": "number",+ "description": "File size in bytes"+ },+ "expires_at": {+ "type": "string",+ "description": "ISO 8601 timestamp when the URL expires"}},- "description": "Experimental features",- "x-experimental": true+ "required": [+ "url",+ "content_type",+ "size"+ ],+ "description": "Binary body response data. Present when the response is a binary file."+ },+ "status": {+ "type": "number",+ "description": "The HTTP status code returned from the proxied API",+ "example": 200+ },+ "headers": {+ "type": "object",+ "additionalProperties": {+ "type": "string"+ },+ "description": "The HTTP headers returned from the proxied API",+ "example": {+ "content-type": "application/json",+ "cache-control": "no-cache"+ }}},"required": [- "session_id",- "mcp",- "tool_router_tools",- "config"+ "status"]}}}},"400": {- "description": "Bad request. This may occur if the session_id format is invalid, please pass this in trs_ prefix format",+ "description": "Bad request",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "401": {+ "description": "Unauthorized",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "403": {+ "description": "Forbidden",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "404": {+ "description": "Not found",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "413": {+ "description": "Payload too large",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "500": {+ "description": "Internal server error",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ }+ }+ }+ },+ "/api/v3/tool_router/session/{session_id}/toolkits": {+ "get": {+ "summary": "Get toolkits for a tool router session",+ "description": "Retrieves a cursor-paginated list of toolkits available in the tool router session. Includes toolkit metadata, composio-managed auth schemes, and connected accounts if available. Optionally filter by specific toolkit slugs.",+ "tags": [+ "Tool Router"+ ],+ "operationId": "getToolRouterSessionBySessionIdToolkits",+ "security": [+ {+ "ApiKeyAuth": []+ },+ {+ "UserApiKeyAuth": []+ }+ ],+ "parameters": [+ {+ "schema": {+ "type": "string",+ "format": "toolRouterSessionId",+ "description": "The session ID returned when creating the session",+ "example": "trs_123456789"+ },+ "required": true,+ "description": "The unique identifier of the tool router session",+ "name": "session_id",+ "in": "path"+ },+ {+ "schema": {+ "type": "integer",+ "minimum": 1,+ "maximum": 50+ },+ "required": false,+ "description": "Number of items per page, max allowed is 50",+ "name": "limit",+ "in": "query"+ },+ {+ "schema": {+ "type": "string"+ },+ "required": false,+ "description": "Cursor for pagination. The cursor is a base64 encoded string of the page and limit. The page is the page number and the limit is the number of items per page. The cursor is used to paginate through the items. The cursor is not required for the first page.",+ "name": "cursor",+ "in": "query"+ },+ {+ "schema": {+ "type": "array",+ "nullable": true,+ "items": {+ "type": "string"+ },+ "description": "Filter toolkits by specific slugs (comma-separated). Overrides session toolkit configuration if provided.",+ "example": "gmail,slack,github"+ },+ "required": false,+ "description": "Optional comma-separated list of toolkit slugs to filter by. If provided, only these toolkits will be returned, overriding the session configuration.",+ "name": "toolkits",+ "in": "query"+ },+ {+ "schema": {+ "type": "boolean",+ "nullable": true,+ "default": false,+ "description": "Whether to filter by connected toolkits. If provided, only connected toolkits will be returned."+ },+ "required": false,+ "description": "Whether to filter by connected toolkits. If provided, only connected toolkits will be returned.",+ "name": "is_connected",+ "in": "query"+ },+ {+ "schema": {+ "type": "string",+ "description": "Search query to filter toolkits by name, slug, or description",+ "example": "gmail"+ },+ "required": false,+ "description": "Search query to filter toolkits by name, slug, or description",+ "name": "search",+ "in": "query"+ }+ ],+ "responses": {+ "200": {+ "description": "Toolkits successfully retrieved. Returns a paginated list of toolkits with their metadata and connected accounts.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/ToolRouterToolkitsListResponse"+ }+ }+ }+ },+ "400": {+ "description": "Bad request. This may occur if pagination parameters are invalid or the session_id format is incorrect.","content": {"application/json": {"schema": {@@ -16327,6 +16279,16 @@}}},+ "403": {+ "description": "Forbidden. The session does not belong to the authenticated user.",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },"404": {"description": "Not found. The session with the provided ID does not exist or has been deleted.","content": {@@ -16350,14 +16312,14 @@}}},- "/api/v3/tool_router/session/{session_id}/link": {- "post": {- "summary": "Create a link session for a toolkit in a tool router session",- "description": "Initiates an authentication link session for a specific toolkit within a tool router session. Returns a link token and redirect URL that users can use to complete the OAuth flow.",+ "/api/v3/tool_router/session/{session_id}/tools": {+ "get": {+ "summary": "List meta tools with schemas for a tool router session",+ "description": "Returns the meta tools available in a tool router session with their complete schemas. This includes request and response schemas specific to the session context.","tags": ["Tool Router"],- "operationId": "postToolRouterSessionBySessionIdLink",+ "operationId": "getToolRouterSessionBySessionIdTools","security": [{"ApiKeyAuth": []@@ -16371,11 +16333,10 @@"schema": {"type": "string","format": "toolRouterSessionId",- "description": "The session ID returned when creating the session",- "example": "trs_LX9uJKBinWWr"+ "description": "Tool router session ID"},- "required": true,- "description": "The unique identifier of the tool router session",+ "required": false,+ "description": "Tool router session ID","name": "session_id","in": "path"}@@ -16385,64 +16346,36 @@"application/json": {"schema": {"type": "object",- "properties": {- "toolkit": {- "type": "string",- "minLength": 1,- "description": "The unique slug identifier of the toolkit to connect",- "example": "github"- },- "callback_url": {- "type": "string",- "format": "uri",- "description": "URL where users will be redirected after completing auth",- "example": "https://myapp.com/callback"- }- },- "required": [- "toolkit"- ]+ "properties": {}}}}},"responses": {- "201": {- "description": "Successfully created link session. Returns link token, redirect URL, and connected account ID.",+ "200": {+ "description": "Successfully retrieved meta tools with their complete schemas.","content": {"application/json": {"schema": {"type": "object","properties": {- "link_token": {- "type": "string",- "description": "Token used to complete the authentication flow",- "example": "lt_abc123xyz"- },- "redirect_url": {- "type": "string",- "format": "uri",- "description": "The URL where users should be redirected to complete OAuth",- "example": "https://app.composio.dev/link/lt_abc123xyz"- },- "connected_account_id": {- "type": "string",- "format": "connectedAccountId",- "description": "The unique identifier for the connected account",- "example": "ca_abc123xyz"+ "items": {+ "type": "array",+ "items": {+ "$ref": "#/components/schemas/Tool"+ },+ "description": "List of tools with their complete schemas"}},"required": [- "link_token",- "redirect_url",- "connected_account_id"+ "items"]}}}},"400": {- "description": "Bad request. This may occur if the toolkit slug is invalid, request parameters are malformed, or a connected account is already defined for this toolkit in the session configuration.",+ "description": "Bad request","content": {"application/json": {"schema": {@@ -16452,7 +16385,7 @@}},"401": {- "description": "Unauthorized. Authentication is required or the provided credentials are invalid.",+ "description": "Unauthorized","content": {"application/json": {"schema": {@@ -16462,7 +16395,7 @@}},"403": {- "description": "Forbidden. The session does not belong to the authenticated user.",+ "description": "Forbidden","content": {"application/json": {"schema": {@@ -16472,7 +16405,17 @@}},"404": {- "description": "Not found. The session does not exist, toolkit not found, or no auth config exists for the toolkit.",+ "description": "Not found",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "413": {+ "description": "Payload too large","content": {"application/json": {"schema": {@@ -16482,7 +16425,7 @@}},"500": {- "description": "Internal server error. An unexpected error occurred while creating the link session.",+ "description": "Internal server error","content": {"application/json": {"schema": {@@ -16494,23 +16437,20 @@}}},- "/api/v3/tool_router/session/{session_id}/proxy_execute": {+ "/api/v3/tool_router/session/{session_id}/search": {"post": {- "summary": "Execute proxy request within a tool router session",- "description": "Execute any native API call on a toolkit with authentication automatically injected from Composio. This endpoint proxies HTTP requests to third-party APIs using connected account credentials resolved from the session context. Provide the toolkit slug, API endpoint, and HTTP method — Composio handles authentication injection, abstracting away credential management. Supports all HTTP methods, custom headers/query parameters, and binary request/response bodies.",+ "summary": "Search for tools using a query",+ "description": "Search for tools matching a given use case query within a tool router session. Returns matching tool slugs, full tool schemas, toolkit connection statuses, and workflow guidance in a predictable format.","tags": ["Tool Router"],- "operationId": "postToolRouterSessionBySessionIdProxyExecute",+ "operationId": "postToolRouterSessionBySessionIdSearch","security": [{"ApiKeyAuth": []},{"UserApiKeyAuth": []- },- {- "workbench_access_key": []}],"parameters": [@@ -16518,11 +16458,11 @@"schema": {"type": "string","format": "toolRouterSessionId",- "description": "The unique identifier of the tool router session. Required for public API endpoints, optional for internal endpoints where it is injected by middleware.",+ "description": "Tool router session ID (trs_*)","example": "trs_LX9uJKBinWWr"},- "required": false,- "description": "Tool router session ID (required for public API, optional for internal - injected by middleware)",+ "required": true,+ "description": "Tool router session ID (trs_*)","name": "session_id","in": "path"}@@ -16533,437 +16473,591 @@"schema": {"type": "object","properties": {- "toolkit_slug": {- "type": "string",- "description": "The slug of the toolkit to use for the request",- "example": "gmail"- },- "endpoint": {- "type": "string",- "description": "The API endpoint to call (absolute URL or path relative to base URL of the connected account)",- "example": "/api/v1/resources"- },- "method": {- "type": "string",- "enum": [- "GET",- "POST",- "PUT",- "DELETE",- "PATCH",- "HEAD"- ],- "description": "The HTTP method to use for the request",- "example": "GET"- },- "body": {- "nullable": true,- "description": "The request body (for POST, PUT, and PATCH requests)",- "example": {- "name": "New Resource",- "description": "This is a new resource"- },- "type": "object"- },- "binary_body": {- "anyOf": [- {- "type": "object",- "properties": {- "url": {- "type": "string",- "format": "uri",- "description": "URL to fetch binary content from"- },- "content_type": {- "type": "string",- "description": "Content-Type header to use for the request"- }- },- "required": [- "url"- ]- },- {- "type": "object",- "properties": {- "base64": {- "type": "string",- "minLength": 1,- "description": "Base64-encoded binary data"- },- "content_type": {- "type": "string",- "description": "Content-Type header to use for the request"- }- },- "required": [- "base64"- ]- }- ],- "description": "Binary body to send. For binary upload via URL: use {url: \"https://...\", content_type?: \"...\"}. For binary upload via base64: use {base64: \"...\", content_type?: \"...\"}."- },- "parameters": {+ "queries": {"type": "array","items": {"type": "object","properties": {- "name": {- "type": "string",- "description": "Parameter name",- "example": "x-api-key"- },- "value": {+ "use_case": {"type": "string",- "description": "Parameter value",- "example": "abc123def456"+ "minLength": 1,+ "description": "The task or use case to search tools for. Provide a detailed description to get the best results.",+ "example": "Send an email to [email protected] with a summary of my last 5 slack messages"},- "type": {+ "known_fields": {"type": "string",- "enum": [- "header",- "query"- ],- "description": "Parameter type (header or query)",- "example": "header"+ "description": "Known field hints as key:value pairs (e.g., \"channel_name:general, user_email:[email protected]\")",+ "example": "channel_name:general"}},"required": [- "name",- "value",- "type"+ "use_case"]},- "description": "Additional HTTP headers or query parameters to include in the request",+ "minItems": 1,+ "maxItems": 7,+ "description": "List of search queries to execute in parallel. Up to 7 queries supported.","example": [{- "name": "x-api-key",- "value": "abc123def456",- "type": "header"- },- {- "name": "filter",- "value": "active",- "type": "query"+ "use_case": "Send a slack message to a channel"}]},- "custom_connection_data": {- "type": "object",- "properties": {- "authScheme": {- "type": "string",- "enum": [- "OAUTH2",- "DCR_OAUTH",- "API_KEY",- "BASIC_WITH_JWT",- "BASIC",- "BEARER_TOKEN",- "OAUTH1",- "NO_AUTH",- "SERVICE_ACCOUNT",- "GOOGLE_SERVICE_ACCOUNT",- "S2S_OAUTH2"- ]- },- "toolkitSlug": {- "type": "string"- },- "val": {+ "model": {+ "type": "string",+ "description": "Optional model hint for search/planning behavior (e.g., \"gpt-4o\"). Ignored if invalid.",+ "example": "gpt-4o"+ }+ },+ "required": [+ "queries"+ ]+ }+ }+ }+ },+ "responses": {+ "200": {+ "description": "Successfully executed the search. Returns matching tool slugs, schemas, connection statuses, and guidance.",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "success": {+ "type": "boolean",+ "description": "Whether all searches completed successfully. False if any query failed."+ },+ "error": {+ "type": "string",+ "nullable": true,+ "description": "Error message if any searches failed, null if all succeeded. Format: \"X out of Y searches failed, reasons: <details>\""+ },+ "results": {+ "type": "array",+ "items": {"type": "object","properties": {- "subdomain": {- "type": "string"- },- "your-domain": {- "type": "string"- },- "region": {- "type": "string"- },- "shop": {- "type": "string"- },- "account_url": {- "type": "string"- },- "COMPANYDOMAIN": {- "type": "string"- },- "extension": {- "type": "string"- },- "form_api_base_url": {- "type": "string"- },- "instanceEndpoint": {- "type": "string"- },- "api_url": {- "type": "string"- },- "borneo_dashboard_url": {- "type": "string"- },- "proxy_username": {- "type": "string"- },- "proxy_password": {- "type": "string"- },- "domain": {- "type": "string"- },- "version": {- "type": "string"- },- "dc": {- "type": "string"- },- "site_name": {- "type": "string"- },- "instanceName": {- "type": "string"- },- "account_id": {- "type": "string"- },- "your_server": {- "type": "string"- },- "server_location": {- "type": "string"- },- "base_url": {- "type": "string"+ "index": {+ "type": "number",+ "description": "1-based index of the query in the request"},- "state_prefix": {+ "use_case": {"type": "string",- "maxLength": 40,- "description": "The oauth2 state prefix for the connection"- },- "long_redirect_url": {- "type": "boolean",- "description": "Whether to return the redirect url without shortening"- },- "access_token": {- "type": "string"- },- "id_token": {- "type": "string"+ "description": "The use case that was searched"},- "token_type": {- "type": "string"+ "execution_guidance": {+ "type": "string",+ "description": "Guidance message about the search results, particularly when a cached plan is available"},- "refresh_token": {+ "difficulty": {"type": "string",- "nullable": true+ "description": "Task difficulty assessment (e.g., \"easy - Simple single-tool operation with known parameters\")"},- "expires_in": {- "anyOf": [- {- "type": "number"- },- {- "type": "string"- },- {- "nullable": true,- "type": "object"- }- ]+ "recommended_plan_steps": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "Workflow steps from cached plan (only present when cached plan is available)"},- "scope": {- "anyOf": [- {- "type": "string"- },- {- "type": "array",- "items": {- "type": "string"+ "known_pitfalls": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "Common pitfalls and considerations (only present when cached plan is available)"+ },+ "reference_workbench_snippets": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "description": {+ "type": "string",+ "description": "Description of what the code snippet does"+ },+ "code": {+ "type": "string",+ "description": "Python code snippet for the workbench"}},- {- "nullable": true,- "type": "object"- }- ]+ "required": [+ "description",+ "code"+ ]+ },+ "description": "Reference Python code snippets for processing tool responses in the workbench (only present when cached plan is available)"+ },+ "primary_tool_slugs": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "List of main tool slugs matching the search criteria"+ },+ "related_tool_slugs": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "List of related tool slugs that might be useful"},- "webhook_signature": {- "type": "string"+ "toolkits": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "List of unique toolkit slugs used by tools in this query"},- "authed_user": {+ "plan_id": {+ "type": "string",+ "description": "ID of cached plan if available"+ },+ "error": {+ "type": "string",+ "nullable": true,+ "description": "Error message if the search for this query failed, null otherwise. Always present for failed queries."+ },+ "memory": {"type": "object",- "properties": {- "access_token": {- "type": "string"- },- "scope": {+ "additionalProperties": {+ "type": "array",+ "items": {"type": "string"}},- "description": "for slack user scopes"- },- "client_id": {+ "description": "Memory data relevant to this query, grouped by app. Only present for non-cached search results."+ }+ },+ "required": [+ "index",+ "use_case",+ "primary_tool_slugs",+ "related_tool_slugs",+ "toolkits"+ ]+ },+ "description": "Per-query search results with tools, reasoning, and memory. One entry per query in request order."+ },+ "toolkit_connection_statuses": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "toolkit": {"type": "string",- "description": "Dynamically registered client ID"+ "description": "The toolkit slug identifier (e.g., \"gmail\", \"slack\")"},- "client_secret": {+ "description": {"type": "string",- "description": "Dynamically registered client secret"- },- "client_id_issued_at": {- "type": "number"- },- "client_secret_expires_at": {- "type": "number"- },- "generic_api_key": {- "type": "string"- },- "api_key": {- "type": "string"- },- "bearer_token": {- "type": "string"- },- "basic_encoded": {- "type": "string"- },- "username": {- "type": "string"- },- "password": {- "type": "string"+ "description": "Description of what the toolkit does and its capabilities"},- "token": {- "type": "string"+ "has_active_connection": {+ "type": "boolean",+ "description": "Whether an active connection exists for this toolkit"},- "oauth_token": {- "type": "string"+ "connection_details": {+ "type": "object",+ "additionalProperties": {},+ "description": "Connection details including auth config and connected account IDs. Only present when has_active_connection is true."},- "oauth_token_secret": {- "type": "string"+ "current_user_info": {+ "type": "object",+ "additionalProperties": {},+ "description": "Information about the currently connected user (email, name, etc.)"},- "oauth_verifier": {- "type": "string"+ "accounts": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "id": {+ "type": "string",+ "description": "Unique identifier for this account"+ },+ "alias": {+ "type": "string",+ "description": "User-assigned alias for this account"+ },+ "user_info": {+ "type": "object",+ "additionalProperties": {},+ "description": "Information about the connected user (email, name, etc.)"+ },+ "status": {+ "type": "string",+ "description": "Connection status (e.g., \"active\")"+ },+ "created_at": {+ "type": "string",+ "description": "ISO 8601 timestamp of when the account was connected"+ },+ "is_default": {+ "type": "boolean",+ "description": "Whether this is the default account for the toolkit"+ }+ },+ "required": [+ "id",+ "status",+ "created_at",+ "is_default"+ ]+ },+ "description": "List of connected accounts for this toolkit. Present when multi-account is enabled."},- "consumer_key": {- "type": "string"+ "account_selection": {+ "type": "string",+ "enum": [+ "required"+ ],+ "description": "When \"required\", the agent must specify which account to use. Present only when multiple accounts exist."},- "redirectUrl": {- "type": "string"+ "status_message": {+ "type": "string",+ "description": "Human-readable message about the connection status and next steps"+ }+ },+ "required": [+ "toolkit",+ "description",+ "has_active_connection",+ "status_message"+ ]+ },+ "description": "Connection status for all toolkits mentioned across all queries, with descriptions merged in."+ },+ "tool_schemas": {+ "type": "object",+ "additionalProperties": {+ "type": "object",+ "properties": {+ "toolkit": {+ "type": "string",+ "description": "The slug of the toolkit that provides this tool"},- "callback_url": {- "type": "string"+ "tool_slug": {+ "type": "string",+ "description": "The slug of the tool"},- "application_id": {- "type": "string"+ "description": {+ "type": "string",+ "description": "Description of the tool"},- "installation_id": {- "type": "string"+ "input_schema": {+ "type": "object",+ "additionalProperties": {},+ "description": "Input schema for the tool (only present when hasFullSchema is true)"},- "private_key": {- "type": "string"+ "output_schema": {+ "type": "object",+ "additionalProperties": {},+ "description": "Output/response schema for the tool. Only included when include_output_schemas is true."},- "credentials_json": {- "type": "string"+ "hasFullSchema": {+ "type": "boolean",+ "description": "Whether the full input_schema is included in this response"},- "expires_at": {- "type": "string"+ "schemaRef": {+ "type": "object",+ "properties": {+ "tool": {+ "type": "string",+ "enum": [+ "COMPOSIO_GET_TOOL_SCHEMAS"+ ],+ "description": "Tool to call"+ },+ "args": {+ "type": "object",+ "properties": {+ "tool_slugs": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "Tool slugs to fetch schemas for"+ }+ },+ "required": [+ "tool_slugs"+ ],+ "description": "Arguments to pass to the tool"+ },+ "message": {+ "type": "string",+ "description": "Instruction message for the LLM"+ }+ },+ "required": [+ "tool",+ "args"+ ],+ "description": "Reference to fetch full schema when hasFullSchema is false"}},- "required": [- "access_token"- ],- "additionalProperties": {}- }+ "required": [+ "toolkit",+ "tool_slug"+ ]+ },+ "description": "Deduplicated tool definitions keyed by tool_slug for O(1) lookup. Each tool appears once even if used in multiple queries."+ },+ "time_info": {+ "type": "object",+ "properties": {+ "current_time_utc": {+ "type": "string",+ "description": "Current time in ISO format (UTC)"+ },+ "current_time_utc_epoch_seconds": {+ "type": "number",+ "description": "Current time as Unix epoch timestamp in seconds"+ },+ "message": {+ "type": "string",+ "description": "Important message about time handling and timezone considerations"+ }+ },+ "required": [+ "current_time_utc",+ "current_time_utc_epoch_seconds",+ "message"+ ],+ "description": "Time information for the query"+ },+ "session": {+ "type": "object",+ "properties": {+ "id": {+ "type": "string",+ "description": "Session identifier to be passed to subsequent meta tool calls as session_id."+ },+ "generate_id": {+ "type": "boolean",+ "description": "Whether a fresh session id was generated in this call."+ },+ "instructions": {+ "type": "string",+ "description": "LLM-facing guidance on how to reuse this session id"+ }+ },+ "required": [+ "id",+ "generate_id",+ "instructions"+ ],+ "description": "Session info for correlating meta tool calls"},- "required": [- "authScheme",- "toolkitSlug",- "val"- ],- "additionalProperties": true- }- },- "required": [- "toolkit_slug",- "endpoint",- "method"- ]+ "next_steps_guidance": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "Combined workflow guidance covering connections, planner, and memory usage. Each element is a step instruction."+ }+ },+ "required": [+ "success",+ "error",+ "results",+ "toolkit_connection_statuses",+ "tool_schemas",+ "time_info",+ "session",+ "next_steps_guidance"+ ]+ }+ }+ }+ },+ "400": {+ "description": "Bad request",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "401": {+ "description": "Unauthorized",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "403": {+ "description": "Forbidden",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "404": {+ "description": "Not found",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "413": {+ "description": "Payload too large",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "500": {+ "description": "Internal server error",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }}}}- },+ }+ }+ },+ "/api/v3/tool_router/session/{session_id}/mounts/{mount_id}/items": {+ "get": {+ "summary": "List files in a session mount",+ "description": "Lists files in a workbench session storage mount with cursor-based pagination. Use the download_url endpoint with the returned mount_relative_path to get a presigned download URL.",+ "tags": [+ "Tool Router"+ ],+ "operationId": "getToolRouterSessionBySessionIdMountsByMountIdItems",+ "security": [+ {+ "ApiKeyAuth": []+ },+ {+ "UserApiKeyAuth": []+ }+ ],+ "parameters": [+ {+ "schema": {+ "type": "string",+ "format": "toolRouterSessionId",+ "description": "The unique identifier of the tool router session",+ "example": "trs_123456789"+ },+ "required": true,+ "description": "The unique identifier of the tool router session",+ "name": "session_id",+ "in": "path"+ },+ {+ "schema": {+ "type": "string",+ "minLength": 1,+ "description": "ID of the storage mount",+ "example": "files"+ },+ "required": true,+ "description": "ID of the storage mount",+ "name": "mount_id",+ "in": "path"+ },+ {+ "schema": {+ "type": "string",+ "description": "Pagination cursor from the previous response next_cursor field"+ },+ "required": false,+ "description": "Pagination cursor from the previous response next_cursor field",+ "name": "cursor",+ "in": "query"+ },+ {+ "schema": {+ "type": "number",+ "minimum": 1,+ "maximum": 500,+ "default": 100,+ "description": "Maximum number of files to return per page (1-500)"+ },+ "required": false,+ "description": "Maximum number of files to return per page (1-500)",+ "name": "limit",+ "in": "query"+ },+ {+ "schema": {+ "type": "string",+ "minLength": 1,+ "description": "Filter results to files under this mount-relative path prefix (e.g. \"data/\" lists only files in the data/ subdirectory)",+ "example": "data/"+ },+ "required": false,+ "description": "Relative path prefix within the mount for filtering",+ "name": "mount_relative_prefix",+ "in": "query"+ }+ ],"responses": {"200": {- "description": "Successfully executed proxy request and received response",+ "description": "Files listed successfully","content": {"application/json": {"schema": {"type": "object","properties": {- "data": {- "nullable": true,- "description": "The response data returned from the proxied API",- "example": {- "id": "123",- "name": "Resource Name",- "created_at": "2023-01-01T00:00:00Z"- },- "type": "object"- },- "binary_data": {- "type": "object",- "properties": {- "url": {- "type": "string",- "description": "URL to download binary content"- },- "content_type": {- "type": "string",- "description": "Content-Type of the binary data"- },- "size": {- "type": "number",- "description": "File size in bytes"+ "items": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "mount_relative_path": {+ "type": "string",+ "description": "Relative file path within the mount (e.g. \"report.pdf\")"+ },+ "sandbox_mount_prefix": {+ "type": "string",+ "description": "Absolute mount path inside the sandbox (e.g. /mnt/files)"+ },+ "size": {+ "type": "number",+ "description": "File size in bytes"+ },+ "last_modified": {+ "type": "string",+ "description": "ISO 8601 timestamp of last modification"+ }},- "expires_at": {- "type": "string",- "description": "ISO 8601 timestamp when the URL expires"- }+ "required": [+ "mount_relative_path",+ "sandbox_mount_prefix",+ "size",+ "last_modified"+ ]},- "required": [- "url",- "content_type",- "size"- ],- "description": "Binary body response data. Present when the response is a binary file."- },- "status": {- "type": "number",- "description": "The HTTP status code returned from the proxied API",- "example": 200+ "description": "List of files in the mount"},- "headers": {- "type": "object",- "additionalProperties": {- "type": "string"- },- "description": "The HTTP headers returned from the proxied API",- "example": {- "content-type": "application/json",- "cache-control": "no-cache"- }+ "next_cursor": {+ "type": "string",+ "description": "Cursor for the next page of results. If absent, there are no more pages."}},"required": [- "status"+ "items"]}}@@ -16989,8 +17083,8 @@}}},- "403": {- "description": "Forbidden",+ "404": {+ "description": "Session or mount not found","content": {"application/json": {"schema": {@@ -16999,8 +17093,8 @@}}},- "404": {- "description": "Not found",+ "500": {+ "description": "Internal server error","content": {"application/json": {"schema": {@@ -17008,9 +17102,129 @@}}}+ }+ }+ }+ },+ "/api/v3/tool_router/session/{session_id}/mounts/{mount_id}/download_url": {+ "post": {+ "summary": "Create a presigned download URL for a mount file",+ "description": "Generates a presigned download URL for a file in a workbench session mount. Accepts a relative path within the mount.",+ "tags": [+ "Tool Router"+ ],+ "operationId": "postToolRouterSessionBySessionIdMountsByMountIdDownloadUrl",+ "security": [+ {+ "ApiKeyAuth": []},- "413": {- "description": "Payload too large",+ {+ "UserApiKeyAuth": []+ }+ ],+ "parameters": [+ {+ "schema": {+ "type": "string",+ "format": "toolRouterSessionId",+ "description": "The unique identifier of the tool router session",+ "example": "trs_123456789"+ },+ "required": true,+ "description": "The unique identifier of the tool router session",+ "name": "session_id",+ "in": "path"+ },+ {+ "schema": {+ "type": "string",+ "minLength": 1,+ "description": "ID of the storage mount",+ "example": "files"+ },+ "required": true,+ "description": "ID of the storage mount",+ "name": "mount_id",+ "in": "path"+ }+ ],+ "requestBody": {+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "mount_relative_path": {+ "type": "string",+ "minLength": 1,+ "description": "Relative file path within the mount",+ "example": "report.pdf"+ }+ },+ "required": [+ "mount_relative_path"+ ]+ }+ }+ }+ },+ "responses": {+ "201": {+ "description": "Download URL created successfully",+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "download_url": {+ "type": "string",+ "description": "Presigned download URL for the file"+ },+ "mount_relative_path": {+ "type": "string",+ "description": "Relative file path within the mount (e.g. \"report.pdf\")"+ },+ "sandbox_mount_prefix": {+ "type": "string",+ "description": "Absolute mount path inside the sandbox (e.g. /mnt/files)"+ },+ "expires_at": {+ "type": "string",+ "description": "ISO 8601 timestamp when the download URL expires"+ }+ },+ "required": [+ "download_url",+ "mount_relative_path",+ "sandbox_mount_prefix",+ "expires_at"+ ]+ }+ }+ }+ },+ "400": {+ "description": "Bad request",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "401": {+ "description": "Unauthorized",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "404": {+ "description": "Session or mount not found","content": {"application/json": {"schema": {@@ -17032,14 +17246,14 @@}}},- "/api/v3/tool_router/session/{session_id}/toolkits": {- "get": {- "summary": "Get toolkits for a tool router session",- "description": "Retrieves a cursor-paginated list of toolkits available in the tool router session. Includes toolkit metadata, composio-managed auth schemes, and connected accounts if available. Optionally filter by specific toolkit slugs.",+ "/api/v3/tool_router/session/{session_id}/mounts/{mount_id}/upload_url": {+ "post": {+ "summary": "Create a presigned upload URL for a mount file",+ "description": "Generates a presigned upload URL for uploading a file to a workbench session mount. The caller should PUT the file content directly to the returned URL.","tags": ["Tool Router"],- "operationId": "getToolRouterSessionBySessionIdToolkits",+ "operationId": "postToolRouterSessionBySessionIdMountsByMountIdUploadUrl","security": [{"ApiKeyAuth": []@@ -17053,7 +17267,7 @@"schema": {"type": "string","format": "toolRouterSessionId",- "description": "The session ID returned when creating the session",+ "description": "The unique identifier of the tool router session","example": "trs_123456789"},"required": true,@@ -17061,78 +17275,82 @@"name": "session_id","in": "path"},- {- "schema": {- "type": "integer",- "minimum": 1,- "maximum": 50- },- "required": false,- "description": "Number of items per page, max allowed is 50",- "name": "limit",- "in": "query"- },- {- "schema": {- "type": "string"- },- "required": false,- "description": "Cursor for pagination. The cursor is a base64 encoded string of the page and limit. The page is the page number and the limit is the number of items per page. The cursor is used to paginate through the items. The cursor is not required for the first page.",- "name": "cursor",- "in": "query"- },- {- "schema": {- "type": "array",- "nullable": true,- "items": {- "type": "string"- },- "description": "Filter toolkits by specific slugs (comma-separated). Overrides session toolkit configuration if provided.",- "example": "gmail,slack,github"- },- "required": false,- "description": "Optional comma-separated list of toolkit slugs to filter by. If provided, only these toolkits will be returned, overriding the session configuration.",- "name": "toolkits",- "in": "query"- },- {- "schema": {- "type": "boolean",- "nullable": true,- "default": false,- "description": "Whether to filter by connected toolkits. If provided, only connected toolkits will be returned."- },- "required": false,- "description": "Whether to filter by connected toolkits. If provided, only connected toolkits will be returned.",- "name": "is_connected",- "in": "query"- },{"schema": {"type": "string",- "description": "Search query to filter toolkits by name, slug, or description",- "example": "gmail"+ "minLength": 1,+ "description": "ID of the storage mount",+ "example": "files"},- "required": false,- "description": "Search query to filter toolkits by name, slug, or description",- "name": "search",- "in": "query"+ "required": true,+ "description": "ID of the storage mount",+ "name": "mount_id",+ "in": "path"+ }+ ],+ "requestBody": {+ "content": {+ "application/json": {+ "schema": {+ "type": "object",+ "properties": {+ "mount_relative_path": {+ "type": "string",+ "minLength": 1,+ "description": "Supports subdirectories (e.g. \"data/output.csv\", \"images/charts/chart.png\")",+ "example": "report.pdf"+ },+ "mimetype": {+ "type": "string",+ "minLength": 1,+ "description": "MIME type of the file being uploaded",+ "example": "application/pdf"+ }+ },+ "required": [+ "mount_relative_path"+ ]+ }+ }}- ],+ },"responses": {- "200": {- "description": "Toolkits successfully retrieved. Returns a paginated list of toolkits with their metadata and connected accounts.",+ "201": {+ "description": "Upload URL created successfully","content": {"application/json": {"schema": {- "$ref": "#/components/schemas/ToolRouterToolkitsListResponse"+ "type": "object",+ "properties": {+ "upload_url": {+ "type": "string",+ "description": "Presigned upload URL — PUT the file content here"+ },+ "mount_relative_path": {+ "type": "string",+ "description": "Relative file path within the mount (e.g. \"report.pdf\")"+ },+ "sandbox_mount_prefix": {+ "type": "string",+ "description": "Absolute mount path inside the sandbox (e.g. /mnt/files)"+ },+ "expires_at": {+ "type": "string",+ "description": "ISO 8601 timestamp when the upload URL expires"+ }+ },+ "required": [+ "upload_url",+ "mount_relative_path",+ "sandbox_mount_prefix",+ "expires_at"+ ]}}}},"400": {- "description": "Bad request. This may occur if pagination parameters are invalid or the session_id format is incorrect.",+ "description": "Bad request","content": {"application/json": {"schema": {@@ -17142,17 +17360,7 @@}},"401": {- "description": "Unauthorized. Authentication is required or the provided credentials are invalid.",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/Error"- }- }- }- },- "403": {- "description": "Forbidden. The session does not belong to the authenticated user.",+ "description": "Unauthorized","content": {"application/json": {"schema": {@@ -17162,7 +17370,7 @@}},"404": {- "description": "Not found. The session with the provided ID does not exist or has been deleted.",+ "description": "Session or mount not found","content": {"application/json": {"schema": {@@ -17172,7 +17380,7 @@}},"500": {- "description": "Internal server error. An unexpected error occurred while processing the request.",+ "description": "Internal server error","content": {"application/json": {"schema": {@@ -17184,14 +17392,14 @@}}},- "/api/v3/tool_router/session/{session_id}/tools": {- "get": {- "summary": "List meta tools with schemas for a tool router session",- "description": "Returns the meta tools available in a tool router session with their complete schemas. This includes request and response schemas specific to the session context.",+ "/api/v3/tool_router/session/{session_id}/mounts/{mount_id}/delete": {+ "post": {+ "summary": "Delete a file from a session mount",+ "description": "Deletes a file from a workbench session storage mount. S3 delete is idempotent — deleting a non-existent file succeeds silently.","tags": ["Tool Router"],- "operationId": "getToolRouterSessionBySessionIdTools",+ "operationId": "postToolRouterSessionBySessionIdMountsByMountIdDelete","security": [{"ApiKeyAuth": []@@ -17205,12 +17413,25 @@"schema": {"type": "string","format": "toolRouterSessionId",- "description": "Tool router session ID"+ "description": "The unique identifier of the tool router session",+ "example": "trs_123456789"},- "required": false,- "description": "Tool router session ID",+ "required": true,+ "description": "The unique identifier of the tool router session","name": "session_id","in": "path"+ },+ {+ "schema": {+ "type": "string",+ "minLength": 1,+ "description": "ID of the storage mount",+ "example": "files"+ },+ "required": true,+ "description": "ID of the storage mount",+ "name": "mount_id",+ "in": "path"}],"requestBody": {@@ -17218,29 +17439,41 @@"application/json": {"schema": {"type": "object",- "properties": {}+ "properties": {+ "mount_relative_path": {+ "type": "string",+ "minLength": 1,+ "description": "Relative file path within the mount",+ "example": "report.pdf"+ }+ },+ "required": [+ "mount_relative_path"+ ]}}}},"responses": {"200": {- "description": "Successfully retrieved meta tools with their complete schemas.",+ "description": "File deleted successfully","content": {"application/json": {"schema": {"type": "object","properties": {- "items": {- "type": "array",- "items": {- "$ref": "#/components/schemas/Tool"- },- "description": "List of tools with their complete schemas"+ "mount_relative_path": {+ "type": "string",+ "description": "Relative file path that was deleted"+ },+ "sandbox_mount_prefix": {+ "type": "string",+ "description": "Absolute mount path inside the sandbox (e.g. /mnt/files)"}},"required": [- "items"+ "mount_relative_path",+ "sandbox_mount_prefix"]}}@@ -17266,8 +17499,8 @@}}},- "403": {- "description": "Forbidden",+ "404": {+ "description": "Session or mount not found","content": {"application/json": {"schema": {@@ -17276,8 +17509,8 @@}}},- "404": {- "description": "Not found",+ "500": {+ "description": "Internal server error","content": {"application/json": {"schema": {@@ -17285,9 +17518,116 @@}}}+ }+ }+ }+ },+ "/api/v3.1/tools/{tool_slug}": {+ "get": {+ "summary": "Get tool by slug",+ "description": "Retrieve detailed information about a specific tool using its slug identifier. This endpoint returns full metadata about a tool including input/output parameters, versions, and toolkit information.",+ "tags": [+ "Tools"+ ],+ "operationId": "getV3_1ToolsByToolSlug",+ "security": [+ {+ "ApiKeyAuth": []},- "413": {- "description": "Payload too large",+ {+ "UserApiKeyAuth": []+ }+ ],+ "parameters": [+ {+ "schema": {+ "type": "string"+ },+ "required": true,+ "description": "The unique slug identifier of the tool",+ "name": "tool_slug",+ "in": "path"+ },+ {+ "schema": {+ "type": "string"+ },+ "required": false,+ "description": "Optional version of the tool to retrieve",+ "name": "version",+ "in": "query"+ },+ {+ "schema": {+ "oneOf": [+ {+ "type": "null"+ },+ {+ "type": "string"+ },+ {+ "type": "object",+ "additionalProperties": {+ "type": "string"+ },+ "description": "Object representation of parsed bracket notation"+ }+ ]+ },+ "required": false,+ "description": "Toolkit version specification. Use \"latest\" for latest versions or bracket notation for specific versions per toolkit.",+ "in": "query",+ "name": "toolkit_versions",+ "examples": {+ "latest_version": {+ "summary": "Latest version for all toolkits",+ "value": "latest"+ },+ "bracket_notation": {+ "summary": "Specific versions using bracket notation",+ "value": "Use: toolkit_versions[gmail]=20250930_00&toolkit_versions[slack]=20250929_00"+ },+ "null_value": {+ "summary": "No version specified (uses 00000000_00)",+ "value": null+ }+ }+ }+ ],+ "responses": {+ "200": {+ "description": "Successfully retrieved tool details",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Tool"+ }+ }+ }+ },+ "400": {+ "description": "Bad request - Invalid tool slug format",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "401": {+ "description": "Unauthorized - Authentication credentials are missing or invalid",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "404": {+ "description": "Not found - Tool with the specified slug does not exist","content": {"application/json": {"schema": {@@ -17297,7 +17637,7 @@}},"500": {- "description": "Internal server error",+ "description": "Internal server error - Something went wrong on the server","content": {"application/json": {"schema": {@@ -17309,14 +17649,14 @@}}},- "/api/v3/tool_router/session/{session_id}/search": {+ "/api/v3.1/tools/execute/{tool_slug}": {"post": {- "summary": "Search for tools using a query",- "description": "Search for tools matching a given use case query within a tool router session. Returns matching tool slugs, full tool schemas, toolkit connection statuses, and workflow guidance in a predictable format.",+ "summary": "Execute tool",+ "description": "Execute a specific tool operation with provided arguments and authentication. This is the primary endpoint for integrating with third-party services and executing tools. You can provide structured arguments or use natural language processing by providing a text description of what you want to accomplish.","tags": [- "Tool Router"+ "Tools"],- "operationId": "postToolRouterSessionBySessionIdSearch",+ "operationId": "postV3_1ToolsExecuteByToolSlug","security": [{"ApiKeyAuth": []@@ -17326,17 +17666,24 @@}],"parameters": [+ {+ "schema": {+ "type": "string"+ },+ "required": true,+ "description": "The tool slug to execute",+ "name": "tool_slug",+ "in": "path"+ },{"schema": {"type": "string",- "format": "toolRouterSessionId",- "description": "Tool router session ID (trs_*)",- "example": "trs_LX9uJKBinWWr"+ "description": "JSON object containing custom headers to pass to LLM providers (OpenAI, Bedrock, etc.)",+ "example": "{\"x-custom-header\": \"value\", \"authorization\": \"Bearer token\"}"},- "required": true,- "description": "Tool router session ID (trs_*)",- "name": "session_id",- "in": "path"+ "required": false,+ "name": "x-llm-gateway-headers",+ "in": "header"}],"requestBody": {@@ -17345,599 +17692,422 @@"schema": {"type": "object","properties": {- "queries": {- "type": "array",- "items": {- "type": "object",- "properties": {- "use_case": {- "type": "string",- "minLength": 1,- "description": "The task or use case to search tools for. Provide a detailed description to get the best results.",- "example": "Send an email to [email protected] with a summary of my last 5 slack messages"- },- "known_fields": {- "type": "string",- "description": "Known field hints as key:value pairs (e.g., \"channel_name:general, user_email:[email protected]\")",- "example": "channel_name:general"+ "connected_account_id": {+ "type": "string",+ "description": "Unique identifier for the connected account to use for authentication",+ "example": "ca_1a2b3c4d5e6f"+ },+ "entity_id": {+ "type": "string",+ "description": "Deprecated: please use user_id instead. Entity identifier for multi-entity connected accounts (e.g. multiple repositories, organizations)",+ "example": "repo-123",+ "deprecated": true+ },+ "user_id": {+ "type": "string",+ "description": "User id for multi-user connected accounts (e.g. multiple users, organizations)",+ "example": "user-123"+ },+ "version": {+ "type": "string",+ "description": "Tool version to execute (defaults to \"00000000_00\" if not specified)",+ "example": "latest"+ },+ "custom_auth_params": {+ "type": "object",+ "properties": {+ "base_url": {+ "type": "string",+ "description": "The base URL (root address) what you should use while making http requests to the connected account. For example, for gmail, it would be 'https://gmail.googleapis.com'"+ },+ "parameters": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "name": {+ "type": "string",+ "description": "The name of the parameter. For example, 'x-api-key', 'Content-Type', etc."+ },+ "in": {+ "type": "string",+ "enum": [+ "query",+ "header"+ ],+ "description": "The location of the parameter. Can be 'query' or 'header'."+ },+ "value": {+ "anyOf": [+ {+ "type": "string"+ },+ {+ "type": "number"+ }+ ],+ "description": "The value of the parameter. For example, '1234567890', 'application/json', etc."+ }+ },+ "required": [+ "name",+ "in",+ "value"+ ]}},- "required": [- "use_case"- ]- },- "minItems": 1,- "maxItems": 7,- "description": "List of search queries to execute in parallel. Up to 7 queries supported.",- "example": [- {- "use_case": "Send a slack message to a channel"+ "body": {+ "type": "object",+ "additionalProperties": {},+ "description": "The body to be sent to the endpoint for authentication. This is a JSON object. Note: This is very rarely needed and is only required by very few apps."}- ]- },- "model": {- "type": "string",- "description": "Optional model hint for search/planning behavior (e.g., \"gpt-4o\"). Ignored if invalid.",- "example": "gpt-4o"- }- },- "required": [- "queries"- ]- }- }- }- },- "responses": {- "200": {- "description": "Successfully executed the search. Returns matching tool slugs, schemas, connection statuses, and guidance.",- "content": {- "application/json": {- "schema": {- "type": "object",- "properties": {- "success": {- "type": "boolean",- "description": "Whether all searches completed successfully. False if any query failed."},- "error": {- "type": "string",- "nullable": true,- "description": "Error message if any searches failed, null if all succeeded. Format: \"X out of Y searches failed, reasons: <details>\""+ "description": "Custom authentication parameters for tools that support parameterized authentication",+ "example": {+ "base_url": "https://api.example.com",+ "parameters": [+ {+ "name": "x-api-key",+ "value": "secret-key",+ "in": "header"+ }+ ]+ }+ },+ "custom_connection_data": {+ "description": "Custom connection data for tools that support custom connection data",+ "example": {+ "authScheme": "OAUTH2",+ "toolkitSlug": "github",+ "val": {+ "access_token": "secret-token"+ }},- "results": {- "type": "array",- "items": {+ "type": "object",+ "properties": {+ "authScheme": {+ "type": "string",+ "enum": [+ "OAUTH2",+ "DCR_OAUTH",+ "API_KEY",+ "BASIC_WITH_JWT",+ "BASIC",+ "BEARER_TOKEN",+ "OAUTH1",+ "NO_AUTH",+ "SERVICE_ACCOUNT",+ "GOOGLE_SERVICE_ACCOUNT",+ "S2S_OAUTH2"+ ]+ },+ "toolkitSlug": {+ "type": "string"+ },+ "val": {"type": "object","properties": {- "index": {- "type": "number",- "description": "1-based index of the query in the request"+ "subdomain": {+ "type": "string"},- "use_case": {- "type": "string",- "description": "The use case that was searched"+ "your-domain": {+ "type": "string"},- "execution_guidance": {- "type": "string",- "description": "Guidance message about the search results, particularly when a cached plan is available"+ "region": {+ "type": "string"},- "difficulty": {- "type": "string",- "description": "Task difficulty assessment (e.g., \"easy - Simple single-tool operation with known parameters\")"+ "shop": {+ "type": "string"},- "recommended_plan_steps": {- "type": "array",- "items": {- "type": "string"- },- "description": "Workflow steps from cached plan (only present when cached plan is available)"+ "account_url": {+ "type": "string"+ },+ "COMPANYDOMAIN": {+ "type": "string"+ },+ "extension": {+ "type": "string"+ },+ "form_api_base_url": {+ "type": "string"+ },+ "instanceEndpoint": {+ "type": "string"+ },+ "api_url": {+ "type": "string"+ },+ "borneo_dashboard_url": {+ "type": "string"+ },+ "proxy_username": {+ "type": "string"+ },+ "proxy_password": {+ "type": "string"+ },+ "domain": {+ "type": "string"+ },+ "version": {+ "type": "string"+ },+ "dc": {+ "type": "string"+ },+ "site_name": {+ "type": "string"+ },+ "instanceName": {+ "type": "string"+ },+ "account_id": {+ "type": "string"+ },+ "your_server": {+ "type": "string"+ },+ "server_location": {+ "type": "string"+ },+ "base_url": {+ "type": "string"},- "known_pitfalls": {- "type": "array",- "items": {- "type": "string"- },- "description": "Common pitfalls and considerations (only present when cached plan is available)"+ "state_prefix": {+ "type": "string",+ "maxLength": 40,+ "description": "The oauth2 state prefix for the connection"},- "reference_workbench_snippets": {- "type": "array",- "items": {- "type": "object",- "properties": {- "description": {- "type": "string",- "description": "Description of what the code snippet does"- },- "code": {- "type": "string",- "description": "Python code snippet for the workbench"- }- },- "required": [- "description",- "code"- ]- },- "description": "Reference Python code snippets for processing tool responses in the workbench (only present when cached plan is available)"+ "long_redirect_url": {+ "type": "boolean",+ "description": "Whether to return the redirect url without shortening"},- "primary_tool_slugs": {- "type": "array",- "items": {- "type": "string"- },- "description": "List of main tool slugs matching the search criteria"+ "access_token": {+ "type": "string"},- "related_tool_slugs": {- "type": "array",- "items": {- "type": "string"- },- "description": "List of related tool slugs that might be useful"+ "id_token": {+ "type": "string"},- "toolkits": {- "type": "array",- "items": {- "type": "string"- },- "description": "List of unique toolkit slugs used by tools in this query"+ "token_type": {+ "type": "string"},- "plan_id": {+ "refresh_token": {"type": "string",- "description": "ID of cached plan if available"+ "nullable": true},- "error": {- "type": "string",- "nullable": true,- "description": "Error message if the search for this query failed, null otherwise. Always present for failed queries."+ "expires_in": {+ "anyOf": [+ {+ "type": "number"+ },+ {+ "type": "string"+ },+ {+ "nullable": true,+ "type": "object"+ }+ ]},- "memory": {+ "scope": {+ "anyOf": [+ {+ "type": "string"+ },+ {+ "type": "array",+ "items": {+ "type": "string"+ }+ },+ {+ "nullable": true,+ "type": "object"+ }+ ]+ },+ "webhook_signature": {+ "type": "string"+ },+ "authed_user": {"type": "object",- "additionalProperties": {- "type": "array",- "items": {+ "properties": {+ "access_token": {+ "type": "string"+ },+ "scope": {"type": "string"}},- "description": "Memory data relevant to this query, grouped by app. Only present for non-cached search results."- }- },- "required": [- "index",- "use_case",- "primary_tool_slugs",- "related_tool_slugs",- "toolkits"- ]- },- "description": "Per-query search results with tools, reasoning, and memory. One entry per query in request order."- },- "toolkit_connection_statuses": {- "type": "array",- "items": {- "type": "object",- "properties": {- "toolkit": {+ "description": "for slack user scopes"+ },+ "client_id": {"type": "string",- "description": "The toolkit slug identifier (e.g., \"gmail\", \"slack\")"+ "description": "Dynamically registered client ID"},- "description": {+ "client_secret": {"type": "string",- "description": "Description of what the toolkit does and its capabilities"+ "description": "Dynamically registered client secret"},- "has_active_connection": {- "type": "boolean",- "description": "Whether an active connection exists for this toolkit"+ "client_id_issued_at": {+ "type": "number"},- "connection_details": {- "type": "object",- "additionalProperties": {},- "description": "Connection details including auth config and connected account IDs. Only present when has_active_connection is true."+ "client_secret_expires_at": {+ "type": "number"},- "current_user_info": {- "type": "object",- "additionalProperties": {},- "description": "Information about the currently connected user (email, name, etc.)"+ "generic_api_key": {+ "type": "string"},- "accounts": {- "type": "array",- "items": {- "type": "object",- "properties": {- "id": {- "type": "string",- "description": "Unique identifier for this account"- },- "alias": {- "type": "string",- "description": "User-assigned alias for this account"- },- "user_info": {- "type": "object",- "additionalProperties": {},- "description": "Information about the connected user (email, name, etc.)"- },- "status": {- "type": "string",- "description": "Connection status (e.g., \"active\")"- },- "created_at": {- "type": "string",- "description": "ISO 8601 timestamp of when the account was connected"- },- "is_default": {- "type": "boolean",- "description": "Whether this is the default account for the toolkit"- }- },- "required": [- "id",- "status",- "created_at",- "is_default"- ]- },- "description": "List of connected accounts for this toolkit. Present when multi-account is enabled."+ "api_key": {+ "type": "string"},- "account_selection": {- "type": "string",- "enum": [- "required"- ],- "description": "When \"required\", the agent must specify which account to use. Present only when multiple accounts exist."+ "bearer_token": {+ "type": "string"},- "status_message": {- "type": "string",- "description": "Human-readable message about the connection status and next steps"- }- },- "required": [- "toolkit",- "description",- "has_active_connection",- "status_message"- ]- },- "description": "Connection status for all toolkits mentioned across all queries, with descriptions merged in."- },- "tool_schemas": {- "type": "object",- "additionalProperties": {- "type": "object",- "properties": {- "toolkit": {- "type": "string",- "description": "The slug of the toolkit that provides this tool"+ "basic_encoded": {+ "type": "string"},- "tool_slug": {- "type": "string",- "description": "The slug of the tool"+ "username": {+ "type": "string"},- "description": {- "type": "string",- "description": "Description of the tool"+ "password": {+ "type": "string"},- "input_schema": {- "type": "object",- "additionalProperties": {},- "description": "Input schema for the tool (only present when hasFullSchema is true)"+ "token": {+ "type": "string"},- "output_schema": {- "type": "object",- "additionalProperties": {},- "description": "Output/response schema for the tool"+ "oauth_token": {+ "type": "string"},- "hasFullSchema": {- "type": "boolean",- "description": "Whether the full input_schema is included in this response"+ "oauth_token_secret": {+ "type": "string"+ },+ "oauth_verifier": {+ "type": "string"},- "schemaRef": {- "type": "object",- "properties": {- "tool": {- "type": "string",- "enum": [- "COMPOSIO_GET_TOOL_SCHEMAS"- ],- "description": "Tool to call"- },- "args": {- "type": "object",- "properties": {- "tool_slugs": {- "type": "array",- "items": {- "type": "string"- },- "description": "Tool slugs to fetch schemas for"- }- },- "required": [- "tool_slugs"- ],- "description": "Arguments to pass to the tool"- },- "message": {- "type": "string",- "description": "Instruction message for the LLM"- }- },- "required": [- "tool",- "args",- "message"- ],- "description": "Reference to fetch full schema when hasFullSchema is false"- }- },- "required": [- "toolkit",- "tool_slug"- ]- },- "description": "Deduplicated tool definitions keyed by tool_slug for O(1) lookup. Each tool appears once even if used in multiple queries."- },- "time_info": {- "type": "object",- "properties": {- "current_time_utc": {- "type": "string",- "description": "Current time in ISO format (UTC)"- },- "current_time_utc_epoch_seconds": {- "type": "number",- "description": "Current time as Unix epoch timestamp in seconds"- },- "message": {- "type": "string",- "description": "Important message about time handling and timezone considerations"- }- },- "required": [- "current_time_utc",- "current_time_utc_epoch_seconds",- "message"- ],- "description": "Time information for the query"- },- "session": {- "type": "object",- "properties": {- "id": {- "type": "string",- "description": "Session identifier to be passed to subsequent meta tool calls as session_id."- },- "generate_id": {- "type": "boolean",- "description": "Whether a fresh session id was generated in this call."- },- "instructions": {- "type": "string",- "description": "LLM-facing guidance on how to reuse this session id"- }- },- "required": [- "id",- "generate_id",- "instructions"- ],- "description": "Session info for correlating meta tool calls"- },- "next_steps_guidance": {- "type": "array",- "items": {- "type": "string"- },- "description": "Combined workflow guidance covering connections, planner, and memory usage. Each element is a step instruction."- }- },- "required": [- "success",- "error",- "results",- "toolkit_connection_statuses",- "tool_schemas",- "time_info",- "session",- "next_steps_guidance"- ]- }- }- }- },- "400": {- "description": "Bad request",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/Error"- }- }- }- },- "401": {- "description": "Unauthorized",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/Error"- }- }- }- },- "403": {- "description": "Forbidden",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/Error"- }- }- }- },- "404": {- "description": "Not found",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/Error"- }- }- }- },- "413": {- "description": "Payload too large",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/Error"- }- }- }- },- "500": {- "description": "Internal server error",- "content": {- "application/json": {- "schema": {- "$ref": "#/components/schemas/Error"- }- }- }- }- }- }- },- "/api/v3/tool_router/session/{session_id}/mounts/{mount_id}/items": {- "get": {- "summary": "List files in a session mount",- "description": "Lists files in a workbench session storage mount with cursor-based pagination. Use the download_url endpoint with the returned mount_relative_path to get a presigned download URL.",- "tags": [- "Tool Router"- ],- "operationId": "getToolRouterSessionBySessionIdMountsByMountIdItems",- "security": [- {- "ApiKeyAuth": []- },- {- "UserApiKeyAuth": []- }- ],- "parameters": [- {- "schema": {- "type": "string",- "format": "toolRouterSessionId",- "description": "The unique identifier of the tool router session",- "example": "trs_123456789"- },- "required": true,- "description": "The unique identifier of the tool router session",- "name": "session_id",- "in": "path"- },- {- "schema": {- "type": "string",- "minLength": 1,- "description": "ID of the storage mount",- "example": "files"- },- "required": true,- "description": "ID of the storage mount",- "name": "mount_id",- "in": "path"- },- {- "schema": {- "type": "string",- "description": "Pagination cursor from the previous response next_cursor field"- },- "required": false,- "description": "Pagination cursor from the previous response next_cursor field",- "name": "cursor",- "in": "query"- },- {- "schema": {- "type": "number",- "minimum": 1,- "maximum": 500,- "default": 100,- "description": "Maximum number of files to return per page (1-500)"- },- "required": false,- "description": "Maximum number of files to return per page (1-500)",- "name": "limit",- "in": "query"- },- {- "schema": {- "type": "string",- "minLength": 1,- "description": "Filter results to files under this mount-relative path prefix (e.g. \"data/\" lists only files in the data/ subdirectory)",- "example": "data/"- },- "required": false,- "description": "Relative path prefix within the mount for filtering",- "name": "mount_relative_prefix",- "in": "query"+ "consumer_key": {+ "type": "string"+ },+ "redirectUrl": {+ "type": "string"+ },+ "callback_url": {+ "type": "string"+ },+ "application_id": {+ "type": "string"+ },+ "installation_id": {+ "type": "string"+ },+ "private_key": {+ "type": "string"+ },+ "credentials_json": {+ "type": "string"+ },+ "expires_at": {+ "type": "string"+ }+ },+ "required": [+ "access_token"+ ],+ "additionalProperties": {}+ }+ },+ "required": [+ "authScheme",+ "toolkitSlug",+ "val"+ ],+ "additionalProperties": true+ },+ "arguments": {+ "type": "object",+ "additionalProperties": {},+ "description": "Key-value pairs of arguments required by the tool (mutually exclusive with text)",+ "example": {+ "repository": "octocat/Hello-World",+ "workflow_id": "main.yml",+ "ref": "main",+ "inputs": {+ "environment": "production"+ }+ }+ },+ "text": {+ "type": "string",+ "description": "Natural language description of the task to perform (mutually exclusive with arguments)",+ "example": "Trigger the main workflow in the octocat/Hello-World repository on the main branch for the production environment"+ },+ "allow_tracing": {+ "type": "boolean",+ "nullable": true,+ "description": "Deprecated. Enable debug tracing for tool execution (useful for debugging)",+ "deprecated": true,+ "example": false+ }+ }+ }+ }}- ],+ },"responses": {"200": {- "description": "Files listed successfully",+ "description": "Successfully executed action and received response","content": {"application/json": {"schema": {"type": "object","properties": {- "items": {- "type": "array",- "items": {- "type": "object",- "properties": {- "mount_relative_path": {- "type": "string",- "description": "Relative file path within the mount (e.g. \"report.pdf\")"- },- "sandbox_mount_prefix": {- "type": "string",- "description": "Absolute mount path inside the sandbox (e.g. /mnt/files)"- },- "size": {- "type": "number",- "description": "File size in bytes"- },- "last_modified": {- "type": "string",- "description": "ISO 8601 timestamp of last modification"- }- },- "required": [- "mount_relative_path",- "sandbox_mount_prefix",- "size",- "last_modified"- ]+ "data": {+ "type": "object",+ "additionalProperties": {},+ "description": "Tool execution output data that varies based on the specific tool",+ "example": {+ "run_id": 12345678,+ "status": "queued",+ "created_at": "2023-01-01T12:00:00Z",+ "html_url": "https://github.com/octocat/Hello-World/actions/runs/12345678"+ }+ },+ "error": {+ "type": "string",+ "nullable": true,+ "description": "Error message if the tool execution was not successful (null if successful)"+ },+ "successful": {+ "type": "boolean",+ "description": "Indicates if the tool execution was successful",+ "example": true+ },+ "session_info": {+ "nullable": true,+ "description": "Optional session information for tools that return session context",+ "example": {+ "session_id": "session-12345",+ "expires_at": "2023-01-01T13:00:00Z"},- "description": "List of files in the mount"+ "type": "object"},- "next_cursor": {+ "log_id": {"type": "string",- "description": "Cursor for the next page of results. If absent, there are no more pages."+ "description": "Unique identifier for the execution log (useful for debugging and support)",+ "example": "log_abc123def456"}},"required": [- "items"+ "data",+ "error",+ "successful"]}}}},"400": {- "description": "Bad request",+ "description": "Bad request - Invalid request parameters, missing required arguments, or conflicting parameters","content": {"application/json": {"schema": {@@ -17947,7 +18117,7 @@}},"401": {- "description": "Unauthorized",+ "description": "Unauthorized - Authentication credentials are missing or invalid","content": {"application/json": {"schema": {@@ -17956,8 +18126,8 @@}}},- "404": {- "description": "Session or mount not found",+ "403": {+ "description": "Forbidden - Connected account does not have permission to execute this tool or access the requested resource","content": {"application/json": {"schema": {@@ -17966,8 +18136,8 @@}}},- "500": {- "description": "Internal server error",+ "404": {+ "description": "Not found - Tool or connected account not found","content": {"application/json": {"schema": {@@ -17975,109 +18145,49 @@}}}- }- }- }- },- "/api/v3/tool_router/session/{session_id}/mounts/{mount_id}/download_url": {- "post": {- "summary": "Create a presigned download URL for a mount file",- "description": "Generates a presigned download URL for a file in a workbench session mount. Accepts a relative path within the mount.",- "tags": [- "Tool Router"- ],- "operationId": "postToolRouterSessionBySessionIdMountsByMountIdDownloadUrl",- "security": [- {- "ApiKeyAuth": []},- {- "UserApiKeyAuth": []- }- ],- "parameters": [- {- "schema": {- "type": "string",- "format": "toolRouterSessionId",- "description": "The unique identifier of the tool router session",- "example": "trs_123456789"- },- "required": true,- "description": "The unique identifier of the tool router session",- "name": "session_id",- "in": "path"+ "408": {+ "description": "Request timeout - Tool execution exceeded the maximum allowed time",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }},- {- "schema": {- "type": "string",- "minLength": 1,- "description": "ID of the storage mount",- "example": "files"- },- "required": true,- "description": "ID of the storage mount",- "name": "mount_id",- "in": "path"- }- ],- "requestBody": {- "content": {- "application/json": {- "schema": {- "type": "object",- "properties": {- "mount_relative_path": {- "type": "string",- "minLength": 1,- "description": "Relative file path within the mount",- "example": "report.pdf"- }- },- "required": [- "mount_relative_path"- ]+ "410": {+ "description": "Gone - Tool has been deprecated and is no longer available",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }}}- }- },- "responses": {- "201": {- "description": "Download URL created successfully",+ },+ "413": {+ "description": "Payload too large - Request or response payload exceeds size limits","content": {"application/json": {"schema": {- "type": "object",- "properties": {- "download_url": {- "type": "string",- "description": "Presigned download URL for the file"- },- "mount_relative_path": {- "type": "string",- "description": "Relative file path within the mount (e.g. \"report.pdf\")"- },- "sandbox_mount_prefix": {- "type": "string",- "description": "Absolute mount path inside the sandbox (e.g. /mnt/files)"- },- "expires_at": {- "type": "string",- "description": "ISO 8601 timestamp when the download URL expires"- }- },- "required": [- "download_url",- "mount_relative_path",- "sandbox_mount_prefix",- "expires_at"- ]+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "422": {+ "description": "Unprocessable entity - Invalid state of the connected account",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"}}}},- "400": {- "description": "Bad request",+ "429": {+ "description": "Rate limit exceeded - Too many requests to the tool or underlying API","content": {"application/json": {"schema": {@@ -18086,8 +18196,8 @@}}},- "401": {- "description": "Unauthorized",+ "500": {+ "description": "Internal server error - Something went wrong on the server","content": {"application/json": {"schema": {@@ -18096,8 +18206,8 @@}}},- "404": {- "description": "Session or mount not found",+ "501": {+ "description": "Not implemented","content": {"application/json": {"schema": {@@ -18106,8 +18216,18 @@}}},- "500": {- "description": "Internal server error",+ "502": {+ "description": "Bad gateway - Error communicating with the tool provider API",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "503": {+ "description": "Upstream service unavailable - Tool provider API is currently down or unavailable","content": {"application/json": {"schema": {@@ -18119,14 +18239,14 @@}}},- "/api/v3/tool_router/session/{session_id}/mounts/{mount_id}/upload_url": {+ "/api/v3.1/tools/execute/{tool_slug}/input": {"post": {- "summary": "Create a presigned upload URL for a mount file",- "description": "Generates a presigned upload URL for uploading a file to a workbench session mount. The caller should PUT the file content directly to the returned URL.",+ "summary": "Generate tool inputs from natural language",+ "description": "Uses AI to translate a natural language description into structured arguments for a specific tool. This endpoint is useful when you want to let users describe what they want to do in plain language instead of providing structured parameters.","tags": [- "Tool Router"+ "Tools"],- "operationId": "postToolRouterSessionBySessionIdMountsByMountIdUploadUrl",+ "operationId": "postV3_1ToolsExecuteByToolSlugInput","security": [{"ApiKeyAuth": []@@ -18138,26 +18258,11 @@"parameters": [{"schema": {- "type": "string",- "format": "toolRouterSessionId",- "description": "The unique identifier of the tool router session",- "example": "trs_123456789"- },- "required": true,- "description": "The unique identifier of the tool router session",- "name": "session_id",- "in": "path"- },- {- "schema": {- "type": "string",- "minLength": 1,- "description": "ID of the storage mount",- "example": "files"+ "type": "string"},"required": true,- "description": "ID of the storage mount",- "name": "mount_id",+ "description": "The tool slug to generate inputs for",+ "name": "tool_slug","in": "path"}],@@ -18167,63 +18272,67 @@"schema": {"type": "object","properties": {- "mount_relative_path": {+ "text": {"type": "string",- "minLength": 1,- "description": "Supports subdirectories (e.g. \"data/output.csv\", \"images/charts/chart.png\")",- "example": "report.pdf"+ "description": "Natural language description of what you want to accomplish with this tool",+ "example": "I need to trigger the main workflow in the octocat/Hello-World repository to deploy to production"},- "mimetype": {+ "custom_description": {"type": "string",- "minLength": 1,- "description": "MIME type of the file being uploaded",- "example": "application/pdf"+ "description": "Custom description of the tool to help guide the LLM in generating more accurate inputs",+ "example": "This tool triggers GitHub Actions workflows in a repository. It requires the repository name, workflow ID, and optional input parameters."+ },+ "system_prompt": {+ "type": "string",+ "description": "System prompt to control and guide the behavior of the LLM when generating inputs",+ "example": "You are an expert assistant that generates precise GitHub Actions workflow parameters. Extract exact repository names, workflow IDs, and input values from user descriptions."+ },+ "version": {+ "type": "string",+ "description": "Tool version to use when generating inputs (defaults to \"latest\" if not specified)",+ "example": "latest"}},"required": [- "mount_relative_path"+ "text"]}}}},"responses": {- "201": {- "description": "Upload URL created successfully",+ "200": {+ "description": "Successfully generated structured inputs for the action based on natural language description","content": {"application/json": {"schema": {"type": "object","properties": {- "upload_url": {- "type": "string",- "description": "Presigned upload URL — PUT the file content here"- },- "mount_relative_path": {- "type": "string",- "description": "Relative file path within the mount (e.g. \"report.pdf\")"- },- "sandbox_mount_prefix": {- "type": "string",- "description": "Absolute mount path inside the sandbox (e.g. /mnt/files)"+ "arguments": {+ "type": "object",+ "additionalProperties": {},+ "description": "Key-value pairs of arguments required by the tool to accomplish the described task",+ "example": {+ "repository": "octocat/Hello-World",+ "workflow_id": "main.yml",+ "ref": "main",+ "inputs": {+ "environment": "production"+ }+ }},- "expires_at": {+ "error": {"type": "string",- "description": "ISO 8601 timestamp when the upload URL expires"+ "description": "Error message if the arguments could not be generated (null if successful)",+ "example": "Unable to determine the repository name from the provided description"}- },- "required": [- "upload_url",- "mount_relative_path",- "sandbox_mount_prefix",- "expires_at"- ]+ }}}}},"400": {- "description": "Bad request",+ "description": "Bad request - Invalid input parameters or insufficient description to generate tool arguments","content": {"application/json": {"schema": {@@ -18233,7 +18342,7 @@}},"401": {- "description": "Unauthorized",+ "description": "Unauthorized - Authentication credentials are missing or invalid","content": {"application/json": {"schema": {@@ -18243,7 +18352,27 @@}},"404": {- "description": "Session or mount not found",+ "description": "Not found - The specified tool does not exist",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "422": {+ "description": "Unprocessable entity - Invalid state of the connected account",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/Error"+ }+ }+ }+ },+ "429": {+ "description": "Too many requests - Rate limit exceeded for natural language processing","content": {"application/json": {"schema": {@@ -18253,7 +18382,7 @@}},"500": {- "description": "Internal server error",+ "description": "Internal server error - AI processing failed or other server error occurred","content": {"application/json": {"schema": {@@ -18265,14 +18394,14 @@}}},- "/api/v3/tool_router/session/{session_id}/mounts/{mount_id}/delete": {+ "/api/v3.1/tools/scopes/required": {"post": {- "summary": "Delete a file from a session mount",- "description": "Deletes a file from a workbench session storage mount. S3 delete is idempotent — deleting a non-existent file succeeds silently.",+ "summary": "Get required scopes for tools",+ "description": "Resolves required scopes for the specified tools at a given toolkit version. All requested tools must belong to the same toolkit. Returns the flat scope union plus per-tool structured scope requirements when available.","tags": [- "Tool Router"+ "Tools"],- "operationId": "postToolRouterSessionBySessionIdMountsByMountIdDelete",+ "operationId": "postV3_1ToolsScopesRequired","security": [{"ApiKeyAuth": []@@ -18281,47 +18410,32 @@"UserApiKeyAuth": []}],- "parameters": [- {- "schema": {- "type": "string",- "format": "toolRouterSessionId",- "description": "The unique identifier of the tool router session",- "example": "trs_123456789"- },- "required": true,- "description": "The unique identifier of the tool router session",- "name": "session_id",- "in": "path"- },- {- "schema": {- "type": "string",- "minLength": 1,- "description": "ID of the storage mount",- "example": "files"- },- "required": true,- "description": "ID of the storage mount",- "name": "mount_id",- "in": "path"- }- ],"requestBody": {"content": {"application/json": {"schema": {"type": "object","properties": {- "mount_relative_path": {+ "tools": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "minItems": 1,+ "description": "Tool slugs to resolve scopes for. All tools must belong to the same toolkit.",+ "example": [+ "gmail_view_email",+ "gmail_send_email"+ ]+ },+ "version": {"type": "string",- "minLength": 1,- "description": "Relative file path within the mount",- "example": "report.pdf"+ "description": "Toolkit version to resolve scopes against for the requested toolkit. Defaults to the pinned HTTP version when omitted.",+ "example": "latest"}},"required": [- "mount_relative_path"+ "tools"]}}@@ -18329,31 +18443,87 @@},"responses": {"200": {- "description": "File deleted successfully",+ "description": "Successfully retrieved scopes for the specified tools","content": {"application/json": {"schema": {"type": "object","properties": {- "mount_relative_path": {- "type": "string",- "description": "Relative file path that was deleted"+ "scopes_required": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "A combined list of all unique scopes required by the specified tools",+ "example": [+ "channels:read",+ "chat:write",+ "https://www.googleapis.com/auth/gmail.modify",+ "repo",+ "user:email"+ ]},- "sandbox_mount_prefix": {- "type": "string",- "description": "Absolute mount path inside the sandbox (e.g. /mnt/files)"+ "per_tool_requirements": {+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "tool": {+ "type": "string"+ },+ "scope_requirements": {+ "type": "object",+ "nullable": true,+ "properties": {+ "all_of": {+ "type": "array",+ "items": {+ "anyOf": [+ {+ "type": "string"+ },+ {+ "type": "object",+ "properties": {+ "any_of": {+ "type": "array",+ "items": {+ "type": "string"+ },+ "minItems": 1+ }+ },+ "required": [+ "any_of"+ ]+ }+ ]+ }+ }+ },+ "required": [+ "all_of"+ ]+ }+ },+ "required": [+ "tool",+ "scope_requirements"+ ]+ },+ "description": "Per-tool structured scope requirements. Null scope_requirements marks unmigrated legacy tools."}},"required": [- "mount_relative_path",- "sandbox_mount_prefix"+ "scopes_required",+ "per_tool_requirements"]}}}},"400": {- "description": "Bad request",+ "description": "Bad request - Invalid body parameters or tools from different toolkits","content": {"application/json": {"schema": {@@ -18363,7 +18533,7 @@}},"401": {- "description": "Unauthorized",+ "description": "Unauthorized - Authentication credentials are missing or invalid","content": {"application/json": {"schema": {@@ -18373,7 +18543,7 @@}},"404": {- "description": "Session or mount not found",+ "description": "Not found - One or more tools could not be resolved for the requested version","content": {"application/json": {"schema": {@@ -18383,7 +18553,7 @@}},"500": {- "description": "Internal server error",+ "description": "Internal server error - Something went wrong on the server","content": {"application/json": {"schema": {diff --git a/docs/scripts/fetch-openapi.mjs b/docs/scripts/fetch-openapi.mjsindex c55fb8b45..7d9c436b9 100644--- a/docs/scripts/fetch-openapi.mjs+++ b/docs/scripts/fetch-openapi.mjs@@ -66,6 +66,30 @@ async function fetchAndFilterSpec() {}}+ // For endpoints that exist under multiple API versions (e.g. /api/v3/ and /api/v3.1/),+ // only keep the latest version to avoid duplicate sidebar entries.+ const versionedPaths = new Map();+ for (const path of Object.keys(filteredPaths)) {+ const match = path.match(/^\/api\/v([\d.]+)\/(.+)$/);+ if (!match) continue;+ const [, version, rest] = match;+ if (!versionedPaths.has(rest)) versionedPaths.set(rest, []);+ versionedPaths.get(rest).push({ version, fullPath: path });+ }++ let versionDedupCount = 0;+ for (const entries of versionedPaths.values()) {+ if (entries.length <= 1) continue;+ entries.sort((a, b) => parseFloat(b.version) - parseFloat(a.version));+ for (const entry of entries.slice(1)) {+ delete filteredPaths[entry.fullPath];+ versionDedupCount++;+ }+ }+ if (versionDedupCount > 0) {+ console.log(`Removed ${versionDedupCount} endpoints superseded by newer API versions`);+ }+spec.paths = filteredPaths;// Filter tags listdiff --git a/docs/scripts/generate-api-index.ts b/docs/scripts/generate-api-index.tsindex 0a906f6b1..a58ed2ab9 100644--- a/docs/scripts/generate-api-index.ts+++ b/docs/scripts/generate-api-index.ts@@ -37,8 +37,32 @@ function generateIndexPages() {tagOperations[tag.name] = [];}+ // For endpoints that exist under multiple API versions (e.g. /api/v3/ and /api/v3.1/),+ // only show the latest version. Extract version from path like /api/v3.1/tools/... → "3.1"+ const supersededPaths: Set<string> = new Set();+ const versionedPaths = new Map<string, { version: string; fullPath: string }[]>();++ for (const path of Object.keys(spec.paths)) {+ const match = path.match(/^\/api\/v([\d.]+)\/(.+)$/);+ if (!match) continue;+ const [, version, rest] = match;+ if (!versionedPaths.has(rest)) versionedPaths.set(rest, []);+ versionedPaths.get(rest)!.push({ version, fullPath: path });+ }++ for (const entries of versionedPaths.values()) {+ if (entries.length <= 1) continue;+ // Sort by version descending; keep only the latest+ entries.sort((a, b) => parseFloat(b.version) - parseFloat(a.version));+ for (const entry of entries.slice(1)) {+ supersededPaths.add(entry.fullPath);+ }+ }+// Group operations by tagfor (const [path, methods] of Object.entries(spec.paths)) {+ // Skip endpoints superseded by a newer API version+ if (supersededPaths.has(path)) continue;for (const [method, operation] of Object.entries(methods)) {if (operation.tags) {for (const tag of operation.tags) {