{ "openapi": "3.0.0", "info": { "version": "3.1.0", "title": "Composio Platform API v3.1", "description": "Composio v3.1 API — all endpoints available under /api/v3.1/. Tool endpoints default to the latest tool version.", "contact": { "name": "Composio Support", "url": "https://composio.dev/support", "email": "support@composio.dev" }, "license": { "name": "Proprietary", "url": "https://composio.dev/terms" } }, "servers": [ { "url": "https://backend.composio.dev", "description": "PRODUCTION API" } ], "tags": [ { "name": "Authentication", "description": "Authentication related endpoints" }, { "name": "Auth Configs", "description": "Authentication configuration management" }, { "name": "Connected Accounts", "description": "Connected account management" }, { "name": "Logs", "description": "Logging and monitoring" }, { "name": "OpenAPI", "description": "OpenAPI specification management" }, { "name": "Organization", "description": "Organization management" }, { "name": "API Keys", "description": "API key management" }, { "name": "Webhooks", "description": "Webhook configuration" }, { "name": "Webhook Endpoints", "description": "Per-OAuth-app webhook ingress endpoints. Inbound URLs the provider posts to, plus signing secret storage and verification." }, { "name": "Webhook Subscriptions", "description": "Webhook delivery subscriptions. Outbound URLs Composio posts trigger events to, plus signing secret rotation and event-type filters." }, { "name": "Team", "description": "Team member management" }, { "name": "Toolkits", "description": "Toolkit and tool management" }, { "name": "Tools", "description": "Tool execution endpoints" }, { "name": "Recipes", "description": "Recipe management and execution. Recipes are reusable code modules that combine multiple tools." }, { "name": "Triggers", "description": "Trigger management and execution" }, { "name": "Payments", "description": "Payment and subscription management" }, { "name": "Files", "description": "File management" }, { "name": "MCP", "description": "MCP server management" }, { "name": "Migration", "description": "Endpoints to help with migration from v1 to v3" }, { "name": "MCP Partner", "description": "MCP partner management" }, { "name": "Recipe", "description": "Recipe endpoints" }, { "name": "Tool Router", "description": "(Labs) Tool router endpoints" } ], "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "Project API key authentication" }, "UserApiKeyAuth": { "type": "apiKey", "in": "header", "name": "x-user-api-key", "description": "User API key authentication" }, "OrgApiKeyAuth": { "type": "apiKey", "in": "header", "name": "x-org-api-key", "description": "Organization API key authentication" } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "number" }, "slug": { "type": "string" }, "status": { "type": "number" }, "request_id": { "type": "string" }, "suggested_fix": { "type": "string" }, "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "message", "code", "slug", "status" ] } }, "required": [ "error" ] }, "Tool": { "type": "object", "properties": { "slug": { "type": "string", "description": "Unique identifier for the tool", "example": "GITHUB_CREATE_A_WORKFLOW_DISPATCH_EVENT" }, "name": { "type": "string", "description": "Human-readable display name of the tool", "example": "GitHub Actions" }, "description": { "type": "string", "description": "Detailed explanation of the tool's functionality and purpose", "example": "Automate GitHub workflows including CI/CD, issue management, and release processes" }, "toolkit": { "type": "object", "properties": { "slug": { "type": "string", "description": "Unique identifier of the parent toolkit", "example": "github" }, "name": { "type": "string", "description": "Human-readable name of the parent toolkit", "example": "GitHub" }, "logo": { "type": "string", "description": "URL to the toolkit logo image", "example": "https://github.githubassets.com/assets/GitHub-Mark-ea2971cee799.png" } }, "required": [ "slug", "name", "logo" ] }, "input_parameters": { "type": "object", "additionalProperties": {}, "description": "Schema definition of required input parameters for the tool", "example": { "repo_name": { "type": "string", "description": "GitHub repository name in owner/repo format", "required": true, "example": "octocat/Hello-World" }, "workflow_id": { "type": "string", "description": "ID or filename of the workflow to trigger", "required": true, "example": "main.yml" } } }, "no_auth": { "type": "boolean", "description": "Indicates if the tool can be used without authentication", "example": false }, "available_versions": { "type": "array", "items": { "type": "string" }, "description": "List of all available versions for this tool", "example": [ "20250905_00", "20250906_00" ] }, "version": { "type": "string", "description": "Current version of the tool", "example": "20250905_00" }, "output_parameters": { "type": "object", "additionalProperties": {}, "description": "Schema definition of return values from the tool", "example": { "run_id": { "type": "number", "description": "ID of the workflow run that was triggered", "example": 12345678 }, "status": { "type": "string", "description": "Status of the workflow run", "example": "completed", "enum": [ "queued", "in_progress", "completed", "failed" ] } } }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "List of scopes associated with the tool", "example": [ "https://www.googleapis.com/auth/gmail.modify" ] }, "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" ], "description": "Structured scope requirements for the tool. Null means the tool is legacy and only exposes flat scopes.", "example": { "all_of": [ "read:user", { "any_of": [ "repo", "public_repo" ] } ] } }, "tags": { "type": "array", "items": { "type": "string" }, "description": "List of tags associated with the tool for categorization and filtering", "example": [ "ci-cd", "github", "automation", "devops" ] }, "human_description": { "type": "string", "description": "Human-friendly description of the tool, if available", "example": "Create a new issue in a GitHub repository" }, "is_deprecated": { "type": "boolean", "description": "Indicates if this tool is deprecated and may be removed in the future", "example": false }, "deprecated": { "type": "object", "properties": { "displayName": { "type": "string", "description": "The display name of the tool", "example": "GitHub Actions" }, "version": { "type": "string", "description": "Current version identifier of the tool", "example": "20250905_00" }, "available_versions": { "type": "array", "items": { "type": "string" }, "description": "List of all available versions for this tool", "example": [ "20250905_00", "20250906_00" ] }, "is_deprecated": { "type": "boolean", "description": "Indicates if this tool is deprecated and may be removed in the future", "example": false }, "toolkit": { "type": "object", "properties": { "logo": { "type": "string", "description": "URL to the toolkit logo image", "example": "https://github.githubassets.com/assets/GitHub-Mark-ea2971cee799.png" } }, "required": [ "logo" ] } }, "required": [ "displayName", "version", "available_versions", "is_deprecated", "toolkit" ] } }, "required": [ "slug", "name", "description", "toolkit", "input_parameters", "no_auth", "available_versions", "version", "output_parameters", "scopes", "scope_requirements", "tags", "is_deprecated", "deprecated" ] }, "ToolsPaginated": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Tool" } }, "next_cursor": { "type": "string", "nullable": true }, "total_pages": { "type": "number" }, "current_page": { "type": "number" }, "total_items": { "type": "number" } }, "required": [ "items", "total_pages", "current_page", "total_items" ] }, "ToolRouterSessionV31ConfigHistoryListResponse": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "version": { "type": "integer", "description": "The config version this entry represents" }, "created_at": { "type": "string", "format": "date-time", "description": "ISO timestamp. For history rows, when the entry was archived (i.e. the moment the version was superseded by a PATCH)." }, "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" }, "description": "Auth config 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." } }, "description": "Manage connections configuration" }, "tools": { "type": "object", "additionalProperties": { "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 }, { "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 } ] }, "description": "Tool-level configuration per toolkit" }, "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" } }, "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" }, "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." }, "sandbox_size": { "type": "string", "enum": [ "standard", "medium", "large", "xlarge" ], "description": "Sandbox compute tier: standard (1 vCPU / 1 GB), medium (2 vCPU / 2 GB), large (4 vCPU / 4 GB), xlarge (8 vCPU / 8 GB). Defaults to standard." } }, "default": { "enable": true, "proxy_execution_enabled": true }, "description": "Workbench configuration" }, "multi_account": { "type": "object", "properties": { "enable": { "type": "boolean", "description": "When true, enables multi-account mode for this session. When not set, falls back to org/project-level configuration." }, "max_accounts_per_toolkit": { "type": "integer", "description": "Maximum number of connected accounts allowed per toolkit. Defaults to 5 when multi-account is enabled." }, "require_explicit_selection": { "type": "boolean", "description": "When true, require explicit account selection when multiple accounts are connected. When false (default), use the first/default account." } }, "description": "Multi-account configuration for this session." }, "preload": { "type": "object", "properties": { "tools": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "string", "enum": [ "all" ] } ], "description": "Explicit preloaded tool slugs, or \"all\" when the session dynamically exposes all app tools allowed by its filters." } }, "required": [ "tools" ], "additionalProperties": false, "description": "Preload configuration. Explicit slugs are returned as an array; dynamic preload is returned as \"all\"." }, "connected_accounts": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string", "format": "connectedAccountId" }, "minItems": 1 }, "description": "Per-toolkit connected account overrides (array of nano-IDs). Multi-account sessions can pin more than one account per toolkit; otherwise length is 1." }, "search": { "type": "object", "properties": { "enable": { "type": "boolean", "default": true } }, "description": "Search helper configuration" }, "execute": { "type": "object", "properties": { "enable_multi_execute": { "type": "boolean", "default": true } }, "description": "Execute helper configuration" } }, "required": [ "user_id", "preload", "search", "execute" ], "description": "The session configuration at this version" }, "is_current": { "type": "boolean", "description": "True only for the live (current) session config, present on the first page. False for archived history rows." } }, "required": [ "version", "created_at", "config", "is_current" ] } }, "next_cursor": { "type": "string", "nullable": true }, "total_pages": { "type": "number" }, "current_page": { "type": "number" }, "total_items": { "type": "number" } }, "required": [ "items", "total_pages", "current_page", "total_items" ] }, "PatchConnectedAccountBody": { "type": "object", "properties": { "alias": { "type": "string", "description": "A human-readable alias for this connected account. Pass an empty string to clear the alias. Must be unique per entity and toolkit within the project." }, "connection": { "type": "object", "properties": { "state": { "type": "object", "properties": { "authScheme": { "type": "string", "enum": [ "BEARER_TOKEN", "API_KEY", "BASIC", "BASIC_WITH_JWT", "GOOGLE_SERVICE_ACCOUNT", "SERVICE_ACCOUNT" ], "description": "The auth scheme of the connected account. Must match the connection's actual auth scheme." }, "val": { "type": "object", "properties": { "subdomain": { "type": "string", "nullable": true }, "your-domain": { "type": "string", "nullable": true }, "region": { "type": "string", "nullable": true }, "shop": { "type": "string", "nullable": true }, "account_url": { "type": "string", "nullable": true }, "COMPANYDOMAIN": { "type": "string", "nullable": true }, "extension": { "type": "string", "nullable": true }, "form_api_base_url": { "type": "string", "nullable": true }, "instanceEndpoint": { "type": "string", "nullable": true }, "api_url": { "type": "string", "nullable": true }, "borneo_dashboard_url": { "type": "string", "nullable": true }, "proxy_username": { "type": "string", "nullable": true }, "proxy_password": { "type": "string", "nullable": true }, "domain": { "type": "string", "nullable": true }, "version": { "type": "string", "nullable": true }, "dc": { "type": "string", "nullable": true }, "site_name": { "type": "string", "nullable": true }, "instanceName": { "type": "string", "nullable": true }, "account_id": { "type": "string", "nullable": true }, "your_server": { "type": "string", "nullable": true }, "server_location": { "type": "string", "nullable": true }, "base_url": { "type": "string", "nullable": true }, "token": { "type": "string", "nullable": true }, "generic_api_key": { "type": "string", "nullable": true }, "api_key": { "type": "string", "nullable": true }, "bearer_token": { "type": "string", "nullable": true }, "basic_encoded": { "type": "string", "nullable": true }, "username": { "type": "string", "nullable": true }, "password": { "type": "string", "nullable": true }, "credentials_json": { "type": "string", "nullable": true }, "application_id": { "type": "string", "nullable": true }, "installation_id": { "type": "string", "nullable": true }, "private_key": { "type": "string", "nullable": true } }, "additionalProperties": {}, "description": "Credential fields to update. Only provided fields are changed — omitted fields are preserved. Set a field to null to remove it." } }, "required": [ "authScheme", "val" ] } }, "required": [ "state" ] }, "experimental": { "type": "object", "properties": { "acl_config_for_shared": { "type": "object", "properties": { "allow_all_users": { "type": "boolean", "description": "Wildcard \"any user_id in the project\" allow toggle. Only valid on SHARED connections." }, "allowed_user_ids": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 256 }, "maxItems": 1000, "description": "Explicit allow list of user_ids who can use this SHARED connection." }, "not_allowed_user_ids": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 256 }, "maxItems": 1000, "description": "Explicit deny list. Wins on conflict with allow_all_users and allowed_user_ids." } }, "description": "Access control for SHARED connections. Resolution rule (only fires when caller != creator): user in not_allowed_user_ids → DENY; allow_all_users=true → ALLOW; user in allowed_user_ids → ALLOW; else DENY. Default state (omitted or {}) is deny-by-default — only the creator can use.", "x-experimental": true } }, "description": "Experimental features - not stable, may be modified or removed in future versions.", "x-experimental": true } } }, "DeprecatedToolkitInfo": { "type": "object", "properties": { "toolkitId": { "type": "string" } }, "required": [ "toolkitId" ], "description": "Deprecated toolkit ID", "deprecated": true, "example": { "toolkitId": "550e8400-e29b-41d4-a716-446655440000" } }, "ToolRouterToolkitsListResponse": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Display name of the toolkit" }, "slug": { "type": "string", "description": "Unique slug identifier" }, "enabled": { "type": "boolean", "description": "Whether the toolkit is enabled" }, "is_no_auth": { "type": "boolean", "description": "Whether the toolkit is no-auth" }, "composio_managed_auth_schemes": { "type": "array", "items": { "type": "string" }, "description": "Available Composio-managed auth schemes" }, "meta": { "type": "object", "properties": { "logo": { "type": "string", "format": "uri", "description": "URL to the toolkit logo" }, "description": { "type": "string", "description": "Description of the toolkit" } }, "required": [ "logo", "description" ], "description": "Toolkit metadata" }, "connected_account": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "format": "connectedAccountId", "description": "Connected account identifier" }, "user_id": { "type": "string", "description": "User identifier" }, "status": { "type": "string", "description": "Connection status" }, "created_at": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "auth_config": { "type": "object", "properties": { "id": { "type": "string", "description": "Auth config identifier" }, "auth_scheme": { "type": "string", "description": "Authentication scheme type" }, "is_composio_managed": { "type": "boolean", "description": "Whether this is a Composio-managed auth config" } }, "required": [ "id", "auth_scheme", "is_composio_managed" ], "description": "Auth config details" } }, "required": [ "id", "user_id", "status", "created_at", "auth_config" ], "description": "Connected account if available" } }, "required": [ "name", "slug", "enabled", "is_no_auth", "composio_managed_auth_schemes", "meta", "connected_account" ] } }, "next_cursor": { "type": "string", "nullable": true }, "total_pages": { "type": "number" }, "current_page": { "type": "number" }, "total_items": { "type": "number" } }, "required": [ "items", "total_pages", "current_page", "total_items" ] } }, "parameters": {} }, "paths": { "/api/v3.1/consumer/connected_accounts/{nanoid}/permissions": { "get": { "summary": "Get consumer tool permissions for a connected account", "description": "Returns durable Enhanced Control per-tool permission rows for a connected account.", "tags": [ "Consumer" ], "operationId": "getConsumerConnectedAccountsByNanoidPermissions", "security": [ { "ApiKeyAuth": [] }, { "UserApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "format": "connectedAccountId" }, "required": true, "description": "Connected account nano ID.", "example": "ca_1a2b3c4d5e6f", "name": "nanoid", "in": "path" } ], "responses": { "200": { "description": "Connected account tool permissions retrieved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "permissions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "connected_account_id": { "type": "string" }, "tool_slug": { "type": "string" }, "toolkit_slug": { "type": "string", "description": "Normalized toolkit slug that owns this tool permission. Use this to group permissions by app/toolkit, for example `gmail` or `slack`." }, "risk_group": { "type": "string", "enum": [ "read", "write", "destructive" ] }, "state": { "type": "string", "enum": [ "always_allow", "always_deny", "ask_once", "ask_always" ] }, "source": { "type": "string", "enum": [ "initial_connect", "settings", "elicitation", "migration" ] }, "permission_config_version": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "connected_account_id", "tool_slug", "toolkit_slug", "risk_group", "state", "source", "permission_config_version", "created_at", "updated_at" ] } } }, "required": [ "permissions" ] } } } }, "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": "Connected account not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-api-version": "3.1" }, "patch": { "summary": "Upsert consumer tool permissions for a connected account", "description": "Upserts durable Enhanced Control per-tool permission rows for a connected account. This is a scaffolded write path for initial connect/settings flows.", "tags": [ "Consumer" ], "operationId": "patchConsumerConnectedAccountsByNanoidPermissions", "security": [ { "ApiKeyAuth": [] }, { "UserApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "format": "connectedAccountId" }, "required": true, "description": "Connected account nano ID.", "example": "ca_1a2b3c4d5e6f", "name": "nanoid", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "permissions": { "type": "array", "items": { "type": "object", "properties": { "tool_slug": { "type": "string", "minLength": 1 }, "toolkit_slug": { "type": "string", "minLength": 1, "description": "Toolkit slug that owns this tool permission. Use this to group and query connected-account permissions by app/toolkit, for example `gmail` or `slack`." }, "risk_group": { "type": "string", "enum": [ "read", "write", "destructive" ] }, "state": { "type": "string", "enum": [ "always_allow", "always_deny", "ask_once", "ask_always" ] }, "source": { "type": "string", "enum": [ "initial_connect", "settings", "elicitation", "migration" ], "default": "settings" }, "permission_config_version": { "type": "string", "minLength": 1 } }, "required": [ "tool_slug", "toolkit_slug", "risk_group", "state" ] }, "minItems": 1, "description": "Tool permission rows to upsert for this connected account." } }, "required": [ "permissions" ] } } } }, "responses": { "200": { "description": "Connected account tool permissions updated successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "permissions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "connected_account_id": { "type": "string" }, "tool_slug": { "type": "string" }, "toolkit_slug": { "type": "string", "description": "Normalized toolkit slug that owns this tool permission. Use this to group permissions by app/toolkit, for example `gmail` or `slack`." }, "risk_group": { "type": "string", "enum": [ "read", "write", "destructive" ] }, "state": { "type": "string", "enum": [ "always_allow", "always_deny", "ask_once", "ask_always" ] }, "source": { "type": "string", "enum": [ "initial_connect", "settings", "elicitation", "migration" ] }, "permission_config_version": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "connected_account_id", "tool_slug", "toolkit_slug", "risk_group", "state", "source", "permission_config_version", "created_at", "updated_at" ] } } }, "required": [ "permissions" ] } } } }, "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": "Connected account not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-api-version": "3.1" } }, "/api/v3.1/consumer/connected_accounts/{nanoid}/permissions/tools/{tool_slug}": { "patch": { "summary": "Upsert one consumer tool permission for a connected account", "description": "Upserts a single durable Enhanced Control permission row for a connected account/tool pair.", "tags": [ "Consumer" ], "operationId": "patchConsumerConnectedAccountsByNanoidPermissionsToolsByToolSlug", "security": [ { "ApiKeyAuth": [] }, { "UserApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "format": "connectedAccountId" }, "required": true, "description": "Connected account nano ID.", "example": "ca_1a2b3c4d5e6f", "name": "nanoid", "in": "path" }, { "schema": { "type": "string", "minLength": 1 }, "required": true, "description": "Tool slug to update.", "example": "GMAIL_SEND_EMAIL", "name": "tool_slug", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "toolkit_slug": { "type": "string", "minLength": 1, "description": "Toolkit slug that owns this tool permission. Use this to group and query connected-account permissions by app/toolkit, for example `gmail` or `slack`." }, "risk_group": { "type": "string", "enum": [ "read", "write", "destructive" ] }, "state": { "type": "string", "enum": [ "always_allow", "always_deny", "ask_once", "ask_always" ] }, "source": { "type": "string", "enum": [ "initial_connect", "settings", "elicitation", "migration" ], "default": "settings" }, "permission_config_version": { "type": "string", "minLength": 1 } }, "required": [ "toolkit_slug", "risk_group", "state" ] } } } }, "responses": { "200": { "description": "Connected account tool permission updated successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "permission": { "type": "object", "properties": { "id": { "type": "string" }, "connected_account_id": { "type": "string" }, "tool_slug": { "type": "string" }, "toolkit_slug": { "type": "string", "description": "Normalized toolkit slug that owns this tool permission. Use this to group permissions by app/toolkit, for example `gmail` or `slack`." }, "risk_group": { "type": "string", "enum": [ "read", "write", "destructive" ] }, "state": { "type": "string", "enum": [ "always_allow", "always_deny", "ask_once", "ask_always" ] }, "source": { "type": "string", "enum": [ "initial_connect", "settings", "elicitation", "migration" ] }, "permission_config_version": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "connected_account_id", "tool_slug", "toolkit_slug", "risk_group", "state", "source", "permission_config_version", "created_at", "updated_at" ] } }, "required": [ "permission" ] } } } }, "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": "Connected account not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-api-version": "3.1" } }, "/api/v3.1/consumer/permissions/resolve": { "post": { "summary": "Resolve consumer tool-router permissions", "description": "Resolves durable connected-account tool permissions into the landed tool-router experimental.permissions config so consumer flows can pass it directly when creating a tool-router session. In addition to existing auth methods, server-side callers may use admin auth with org_member_id/project_id/org_id query params to derive the project user context.", "tags": [ "Consumer" ], "operationId": "postConsumerPermissionsResolve", "security": [ { "ApiKeyAuth": [] }, { "UserApiKeyAuth": [] }, { "admin": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid", "description": "Org member/user UUID used with admin auth." }, "required": false, "description": "Org member/user UUID used with admin auth.", "name": "org_member_id", "in": "query" }, { "schema": { "type": "string", "format": "projectId", "description": "Project nano ID used with admin auth." }, "required": false, "description": "Project nano ID used with admin auth.", "name": "project_id", "in": "query" }, { "schema": { "type": "string", "format": "orgId", "description": "Org nano ID used with admin auth." }, "required": false, "description": "Org nano ID used with admin auth.", "name": "org_id", "in": "query" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "connected_account_ids": { "type": "array", "items": { "type": "string", "format": "connectedAccountId" }, "description": "Connected account nano IDs to include in resolution." }, "connected_accounts": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string", "format": "connectedAccountId" }, "minItems": 1 }, "description": "Optional toolkit_slug -> connected account nano ID array map. Values are flattened and merged with connected_account_ids." }, "default": { "type": "string", "enum": [ "allow_all", "ask_every_call", "ask_once_per_session" ], "description": "Optional default mode to include in the resolved tool-router permissions config.", "x-experimental": true } } } } } }, "responses": { "200": { "description": "Consumer permissions resolved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "experimental": { "type": "object", "properties": { "permissions": { "type": "object", "properties": { "default": { "type": "string", "enum": [ "allow_all", "ask_every_call", "ask_once_per_session" ], "description": "Default elicitation behavior when no override matches. `allow_all` runs every tool without prompting; `ask_every_call` prompts on each invocation; `ask_once_per_session` prompts once and remembers the answer for the rest of the session." }, "overrides": { "type": "object", "additionalProperties": { "type": "string", "enum": [ "always_allow", "always_deny", "ask_once", "ask_always" ] }, "description": "Per-tool overrides keyed by `${toolSlug}:${connectedAccountId ?? \"__none__\"}`, plus account-wide overrides keyed by `*:${connectedAccountId ?? \"__none__\"}`. Exact tool overrides take precedence over account-wide overrides. `always_allow` skips the prompt and runs the tool; `always_deny` blocks the tool; `ask_once` prompts once per session (allow/deny) and remembers; `ask_always` prompts on every call with allow-once/allow-session/deny, ignoring any cached session allow. Overrides take precedence over `default`." } }, "required": [ "default" ] } }, "required": [ "permissions" ] } }, "required": [ "experimental" ] } } } }, "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": "Connected account not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-api-version": "3.1" } }, "/api/v3.1/logs/tool_execution": { "post": { "summary": "Search and retrieve tool execution logs", "description": "Search and retrieve tool execution logs with filtering, pagination, and time range support.", "tags": [ "Logs" ], "operationId": "postLogsToolExecution", "security": [ { "ApiKeyAuth": [] }, { "UserApiKeyAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "limit": { "type": "number", "minimum": 1, "maximum": 100, "default": 20 }, "cursor": { "type": "string", "nullable": true }, "filters": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "enum": [ "tool_slug", "toolkit_slug", "connected_account_id", "auth_config_id", "status", "user_id", "session_id", "sandbox_id", "request_id", "log_id" ] }, "operator": { "type": "string", "enum": [ "==", "!=", "contains", "not_contains" ] }, "value": { "type": "string" } }, "required": [ "field", "operator", "value" ] }, "default": [] }, "time_range": { "type": "object", "properties": { "from": { "type": "number", "description": "Start time in epoch milliseconds" }, "to": { "type": "number", "description": "End time in epoch milliseconds" } }, "required": [ "from", "to" ] } } } } } }, "responses": { "200": { "description": "Successfully retrieved tool logs", "content": { "application/json": { "schema": { "type": "object", "properties": { "logs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp" }, "type": { "type": "string", "description": "Log event type, e.g. tool.execution, trigger.message, connected_account.created" }, "status": { "type": "string", "enum": [ "success", "failed" ] }, "level": { "type": "string", "enum": [ "info", "error", "warn" ] }, "message": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": {} }, "metrics": { "type": "object", "additionalProperties": {} }, "parent": { "type": "object", "nullable": true, "properties": { "log_id": { "type": "string" }, "tool_slug": { "type": "string" } }, "required": [ "log_id", "tool_slug" ] } }, "required": [ "id", "timestamp", "type", "status", "level", "metadata", "metrics", "parent" ] } }, "next_cursor": { "type": "string", "nullable": true } }, "required": [ "logs", "next_cursor" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-api-version": "3.1" } }, "/api/v3.1/logs/tool_execution/{id}": { "get": { "summary": "Get log details by ID", "description": "Retrieve detailed log information by log ID.", "tags": [ "Logs" ], "operationId": "getLogsToolExecutionById", "security": [ { "ApiKeyAuth": [] }, { "UserApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "The log ID" }, "required": true, "description": "The log ID", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Successfully retrieved log details", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp" }, "type": { "type": "string", "description": "Log event type, e.g. tool.execution, trigger.message, connected_account.created" }, "status": { "type": "string", "enum": [ "success", "failed" ] }, "level": { "type": "string", "enum": [ "info", "error", "warn" ] }, "message": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": {} }, "metrics": { "type": "object", "additionalProperties": {} }, "parent": { "type": "object", "nullable": true, "properties": { "log_id": { "type": "string" }, "tool_slug": { "type": "string" } }, "required": [ "log_id", "tool_slug" ] }, "timings": { "type": "object", "properties": { "start_time": { "type": "number", "description": "Epoch milliseconds" }, "end_time": { "type": "number", "description": "Epoch milliseconds" } }, "required": [ "start_time", "end_time" ] }, "context": { "type": "object", "properties": { "session_id": { "type": "string" }, "trace_id": { "type": "string" }, "request_id": { "type": "string" } } }, "source": { "type": "object", "properties": { "host": { "type": "string" }, "framework": { "type": "string" }, "language": { "type": "string" } } }, "data": { "type": "object", "additionalProperties": {} } }, "required": [ "id", "timestamp", "type", "status", "level", "metadata", "metrics", "parent", "context", "source", "data" ] } } } }, "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": "Log not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-api-version": "3.1" } }, "/api/v3.1/tools": { "get": { "summary": "List available tools", "description": "Retrieve a paginated list of available tools with comprehensive filtering, sorting and search capabilities. Use query parameters to narrow down results by toolkit, tags, or search terms.", "tags": [ "Tools" ], "operationId": "getTools", "security": [ { "ApiKeyAuth": [] }, { "UserApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": false, "description": "The slug of the toolkit to filter by", "in": "query", "name": "toolkit_slug" }, { "schema": { "type": "string" }, "required": false, "description": "Comma-separated list of specific tool slugs to retrieve (overrides other filters)", "in": "query", "name": "tool_slugs" }, { "schema": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "required": false, "description": "Comma-separated list of auth config IDs to filter tools by", "in": "query", "name": "auth_config_ids" }, { "schema": { "type": "string", "enum": [ "true", "false" ] }, "required": false, "description": "Filter to only show important/featured tools (set to \"true\" to enable)", "in": "query", "name": "important" }, { "schema": { "type": "array", "items": { "type": "string" } }, "required": false, "description": "Filter tools by one or more tags (can be specified multiple times)", "in": "query", "name": "tags" }, { "schema": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "Filter tools by one or more scopes (can be specified multiple times)" }, "required": false, "description": "Array of scopes to filter tools by)", "name": "scopes", "in": "query" }, { "schema": { "type": "string" }, "required": false, "description": "Full-text search query to filter tools by name, slug, or description. Applied as a soft filter on top of other filters.", "in": "query", "name": "query" }, { "schema": { "type": "string" }, "required": false, "description": "Deprecated: use \"query\" instead. Free-text search query to find tools by name, description, or functionality.", "in": "query", "name": "search", "deprecated": true }, { "schema": { "type": "boolean", "default": true }, "required": false, "description": "Include deprecated tools in the response", "in": "query", "name": "include_deprecated" }, { "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 } } }, { "schema": { "type": "number", "nullable": true }, "required": false, "description": "Number of items per page, max allowed is 1000", "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" } ], "responses": { "200": { "description": "Successfully retrieved tools list with pagination information", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolsPaginated" } } } }, "400": { "description": "Bad request - Invalid query parameters", "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 - User does not have permission to access tools", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found - The requested resource was not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests - Rate limit exceeded", "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" } } } } }, "x-api-version": "3.1" } }, "/api/v3.1/tools/enum": { "get": { "summary": "Get tool enum list", "description": "Retrieve a list of all available tool enumeration values (tool slugs) from latest version of each toolkit. This endpoint returns a comma-separated string of tool slugs that can be used in other API calls.", "tags": [ "Tools" ], "operationId": "getToolsEnum", "security": [ { "ApiKeyAuth": [] }, { "UserApiKeyAuth": [] } ], "responses": { "200": { "description": "Successfully retrieved tool enum list", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string" }, "description": "JSON string containing all tool enum values from latest version of each toolkit" } } } }, "400": { "description": "Bad request - Invalid request parameters", "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 - User does not have permission to access tool enums", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found - Tool enum list not found", "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" } } } } }, "x-api-version": "3.1" } }, "/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": "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" } } } } }, "x-api-version": "3.1" } }, "/api/v3.1/tools/execute/{tool_slug}": { "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.", "tags": [ "Tools" ], "operationId": "postToolsExecuteByToolSlug", "security": [ { "ApiKeyAuth": [] }, { "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": { "schema": { "type": "object", "properties": { "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" ] } }, "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" } ] } }, "custom_connection_data": { "description": "Custom connection data for tools that support custom connection data", "example": { "authScheme": "OAUTH2", "toolkitSlug": "github", "val": { "access_token": "secret-token" } }, "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" }, "extra_token_data": { "type": "object", "additionalProperties": {} }, "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 }, "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": "Successfully executed action 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", "example": { "session_id": "session-12345", "expires_at": "2023-01-01T13:00:00Z" }, "type": "object" }, "log_id": { "type": "string", "description": "Unique identifier for the execution log (useful for debugging and support)", "example": "log_abc123def456" } }, "required": [ "data", "error", "successful" ] } } } }, "400": { "description": "Bad request - Invalid request parameters, missing required arguments, or conflicting parameters", "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 execute this tool or access the requested resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "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", "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": "Rate limit exceeded - Too many requests to the tool or underlying API", "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", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/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": { "$ref": "#/components/schemas/Error" } } } } }, "x-api-version": "3.1" } }, "/api/v3.1/tools/execute/{tool_slug}/input": { "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.", "tags": [ "Tools" ], "operationId": "postToolsExecuteByToolSlugInput", "security": [ { "ApiKeyAuth": [] }, { "UserApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "description": "The tool slug to generate inputs for", "name": "tool_slug", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "text": { "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" }, "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." }, "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": [ "text" ] } } } }, "responses": { "200": { "description": "Successfully generated structured inputs for the action based on natural language description", "content": { "application/json": { "schema": { "type": "object", "properties": { "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" } } }, "error": { "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" } } } } } }, "400": { "description": "Bad request - Invalid input parameters or insufficient description to generate tool arguments", "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 - 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": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error - AI processing failed or other server error occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-api-version": "3.1" } }, "/api/v3.1/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.", "tags": [ "Tools" ], "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" }, "extra_token_data": { "type": "object", "additionalProperties": {} }, "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" } } } } }, "x-api-version": "3.1" } }, "/api/v3.1/tools/scopes/required": { "post": { "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": [ "Tools" ], "operationId": "postToolsScopesRequired", "security": [ { "ApiKeyAuth": [] }, { "UserApiKeyAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "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_FETCH_EMAILS", "GMAIL_SEND_EMAIL" ] }, "version": { "type": "string", "description": "Toolkit version to resolve scopes against for the requested toolkit. Defaults to the pinned HTTP version when omitted.", "example": "latest" } }, "required": [ "tools" ] } } } }, "responses": { "200": { "description": "Successfully retrieved scopes for the specified tools", "content": { "application/json": { "schema": { "type": "object", "properties": { "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" ] }, "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": [ "scopes_required", "per_tool_requirements" ] } } } }, "400": { "description": "Bad request - Invalid body parameters or tools from different toolkits", "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 - One or more tools could not be resolved for the requested version", "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" } } } } }, "x-api-version": "3.1" } }, "/api/v3.1/org/clanker/create_claim": { "post": { "summary": "Create a clanker-claim slug", "description": "Mints a four-word claim slug (no email sent) tied to the org's clanker and restricted to the given human email. The human redeems it via POST /api/v3.1/org/clanker/redeem_claim while authenticated. On redeem, the human joins the org and is recorded as the humanOwner of the clanker. Called by external services (e.g. agents.composio.dev) using an org API key.", "tags": [ "Invite Codes" ], "operationId": "postOrgClankerCreateClaim", "security": [ { "OrgApiKeyAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "human_email": { "type": "string", "format": "email", "description": "Email of the human who will claim the clanker" } }, "required": [ "human_email" ] } } } }, "responses": { "200": { "description": "Clanker claim invite created and emailed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "claim_slug": { "type": "string", "description": "Four-word hyphen-separated slug (e.g. \"red-castle-amber-pine\") the human types into /redeem_claim. Valid for 7 days, restricted to the provided email." }, "expires_at": { "type": "string", "format": "date-time", "description": "ISO timestamp when this claim slug expires." } }, "required": [ "claim_slug", "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" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Org has no clanker to claim.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict. The org's clanker has already been claimed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-api-version": "3.1" } }, "/api/v3.1/connected_accounts/{nanoid}/revoke": { "post": { "summary": "Revoke a connected account at the provider", "description": "Best-effort upstream revocation. On success, the connection transitions to REVOKED. Returns 400 when the toolkit does not support programmatic revocation, 409 when the connection is not in a revokable state, 500 when every upstream dispatch fails.", "tags": [ "Connected Accounts" ], "operationId": "postConnectedAccountsByNanoidRevoke", "security": [ { "ApiKeyAuth": [] }, { "UserApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "format": "connectedAccountId" }, "required": true, "description": "The unique identifier of the connected account", "example": "ca_1a2b3c4d5e6f", "name": "nanoid", "in": "path" } ], "responses": { "200": { "description": "Connection revoked. `revoked_tokens` reports which subjects were killed at the provider on this call; an empty array indicates the connection was already revoked.", "content": { "application/json": { "schema": { "type": "object", "properties": { "revoked_tokens": { "type": "array", "items": { "type": "string", "enum": [ "access_token", "refresh_token" ] }, "description": "Tokens revoked at the provider on this call. Empty array means the connection was already revoked (no upstream dispatch)." }, "connected_account": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier of the connected account" }, "status": { "type": "string", "enum": [ "INITIALIZING", "INITIATED", "ACTIVE", "FAILED", "EXPIRED", "INACTIVE", "REVOKED" ], "description": "The connection status after this call (REVOKED on success)." } }, "required": [ "id", "status" ] } }, "required": [ "revoked_tokens", "connected_account" ], "description": "Result of revoking a connected account at the upstream provider.", "example": { "revoked_tokens": [ "access_token", "refresh_token" ], "connected_account": { "id": "ca_1a2b3c4d5e6f", "status": "REVOKED" } } } } } }, "400": { "description": "Bad request - non-OAUTH2 auth scheme or toolkit lacks a revoke configuration.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized - Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden - Insufficient permissions to revoke this connected account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found - Connected account does not exist, was deleted, or its parent auth config was removed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict - Connection is in a state that cannot be revoked (only ACTIVE / already-REVOKED are accepted).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error - DB failure, data integrity violation, or every upstream dispatch failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-api-version": "3.1" } }, "/api/v3.1/tool_router/session": { "post": { "summary": "Create a new tool router session", "description": "Creates a new session for the tool router feature. This endpoint initializes a new session with specified toolkits and their authentication configurations. The session provides an isolated environment for testing and managing tool routing logic with scoped MCP server access.", "tags": [ "Tool Router" ], "operationId": "postToolRouterSession", "security": [ { "ApiKeyAuth": [] }, { "UserApiKeyAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "user_id": { "type": "string", "minLength": 1, "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": { "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_1a2b3c4d5e6f", "slack": "ac_7g8h9i0j1k2l" } }, "connected_accounts": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string", "format": "connectedAccountId" }, "minItems": 1 }, "description": "The connected accounts to use for the session, as an array of nano-IDs per toolkit. This overrides the default behaviour and pins specific connected accounts when toolkits are executed. Each account must exist (not deleted or disabled) and belong to the same `user_id` as the session. Multi-account sessions can pin multiple; non-multi-account sessions are capped at length 1." }, "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" ] } }, "disable": { "type": "array", "items": { "type": "string", "enum": [ "readOnlyHint", "destructiveHint", "idempotentHint", "openWorldHint" ] } } } } ], "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. Allows you to enable, disable, or filter by tags for specific tools within each toolkit. Every slug passed in `enable` / `disable` must be a valid Composio tool slug for that toolkit — invalid or typo'd slugs fail session creation with a clear error listing which ones didn't match.", "example": { "gmail": { "enable": [ "GMAIL_SEND_EMAIL", "GMAIL_FETCH_EMAILS" ] }, "slack": { "disable": [ "SLACK_ADD_EMOJI" ] }, "slackbot": { "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" ] } }, "disable": { "type": "array", "items": { "type": "string", "enum": [ "readOnlyHint", "destructiveHint", "idempotentHint", "openWorldHint" ] } } } } ], "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 }, "sandbox_size": { "type": "string", "enum": [ "standard", "medium", "large", "xlarge" ], "default": "standard", "description": "Sandbox compute tier: standard (1 vCPU / 1 GB), medium (2 vCPU / 2 GB), large (4 vCPU / 4 GB), xlarge (8 vCPU / 8 GB). Defaults to standard.", "example": "standard" } }, "default": { "enable": true, "enable_proxy_execution": true }, "additionalProperties": false, "description": "Configuration for workbench behavior" }, "multi_account": { "type": "object", "properties": { "enable": { "type": "boolean", "description": "When true, enables multi-account mode for this session. When not set, falls back to org/project-level configuration.", "example": true }, "max_accounts_per_toolkit": { "type": "integer", "minimum": 2, "maximum": 10, "description": "Maximum number of connected accounts allowed per toolkit. Must be between 2 and 10.", "example": 5 }, "require_explicit_selection": { "type": "boolean", "description": "When true, the agent must explicitly select which account to use. When false (default), the first/default account is used automatically.", "example": false } }, "additionalProperties": false, "description": "Configure multi-account behavior. When enabled, users can connect multiple accounts per toolkit." }, "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" }, "preload": { "type": "boolean", "description": "SDK hint for direct custom-tool exposure. Not stored in session config; echoed in create/attach responses for inline custom definitions." }, "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__ (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." }, "preload": { "type": "boolean", "description": "SDK hint for direct custom-tool exposure. Not stored in session config; echoed in create/attach responses for inline custom definitions." } }, "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_ (standalone) or LOCAL__ (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)" }, "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" }, "preload": { "type": "boolean", "description": "SDK hint for direct custom-tool exposure. Not stored in session config; echoed in create/attach responses for inline custom definitions." } }, "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." }, "permissions": { "type": "object", "properties": { "default": { "type": "string", "enum": [ "allow_all", "ask_every_call", "ask_once_per_session" ], "description": "Default elicitation behavior when no override matches. `allow_all` runs every tool without prompting; `ask_every_call` prompts on each invocation; `ask_once_per_session` prompts once and remembers the answer for the rest of the session." }, "overrides": { "type": "object", "additionalProperties": { "type": "string", "enum": [ "always_allow", "always_deny", "ask_once", "ask_always" ] }, "description": "Per-tool overrides keyed by `${toolSlug}:${connectedAccountId ?? \"__none__\"}`, plus account-wide overrides keyed by `*:${connectedAccountId ?? \"__none__\"}`. Exact tool overrides take precedence over account-wide overrides. `always_allow` skips the prompt and runs the tool; `always_deny` blocks the tool; `ask_once` prompts once per session (allow/deny) and remembers; `ask_always` prompts on every call with allow-once/allow-session/deny, ignoring any cached session allow. Overrides take precedence over `default`." } }, "required": [ "default" ], "description": "Per-tool elicitation permission config. Default behavior + per-tool always_allow/always_deny overrides. Mutation via PATCH." }, "link_url_overwrite": { "type": "string", "format": "uri", "description": "Experimental base URL override for connection link redirects created from this tool-router session. When set, link creation returns `${link_url_overwrite}/link/{link_token}` instead of the default Composio Connect base URL. Use only when your integration needs links to open through a custom Connect host.", "x-experimental": true } }, "description": "Experimental features - not stable, may be modified or removed in future versions.", "x-experimental": true }, "preload": { "type": "object", "properties": { "tools": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "string" } ], "description": "Explicit tool slugs to preload, or \"all\" to dynamically expose all current and future app tools allowed by the positive session filters. \"all\" is capped at 1000 tools and is not supported without a positive allowlist.", "example": "all" } }, "additionalProperties": false, "description": "Preload configuration. Use an explicit list for frequently used tool slugs, or \"all\" to dynamically expose every app tool allowed by positive toolkits/tools/tags filters." }, "search": { "type": "object", "properties": { "enable": { "type": "boolean", "default": true } }, "default": { "enable": true }, "additionalProperties": false }, "execute": { "type": "object", "properties": { "enable_multi_execute": { "type": "boolean", "default": true } }, "default": { "enable_multi_execute": true }, "additionalProperties": false } }, "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_1a2b3c4d5e6f", "slack": "ac_7g8h9i0j1k2l" } } }, "Session with connected account overrides": { "value": { "user_id": "user_123456789", "toolkits": { "enable": [ "gmail", "slack" ] }, "connected_accounts": { "gmail": "ca_1a2b3c4d5e6f", "slack": "ca_7g8h9i0j1k2l" } } }, "Session with comprehensive configuration": { "value": { "user_id": "user_123456789", "toolkits": { "enable": [ "gmail", "slack", "github" ] }, "auth_configs": { "gmail": "ac_1a2b3c4d5e6f", "slack": "ac_7g8h9i0j1k2l" }, "connected_accounts": { "github": "ca_3m4n5o6p7q8r" }, "manage_connections": { "enable": true, "callback_url": "https://your-app.com/auth/callback" }, "tools": { "gmail": { "enable": [ "GMAIL_SEND_EMAIL", "GMAIL_FETCH_EMAILS" ] }, "slack": { "disable": [ "SLACK_ADD_EMOJI" ] }, "slackbot": { "tags": [ "destructiveHint" ] } }, "tags": [ "destructiveHint", "idempotentHint" ], "workbench": { "enable_proxy_execution": true, "auto_offload_threshold": 10000 } } }, "Session with disabled toolkits and global tags": { "value": { "user_id": "user_123456789", "toolkits": { "disable": [ "gmail" ] }, "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_1a2b3c4d5e6f" }, "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_1a2b3c4d5e6f/mcp" } }, "required": [ "type", "url" ] }, "tool_router_tools": { "type": "array", "items": { "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" }, "description": "Auth config 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." } }, "description": "Manage connections configuration" }, "tools": { "type": "object", "additionalProperties": { "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 }, { "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 } ] }, "description": "Tool-level configuration per toolkit" }, "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" } }, "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" }, "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." }, "sandbox_size": { "type": "string", "enum": [ "standard", "medium", "large", "xlarge" ], "description": "Sandbox compute tier: standard (1 vCPU / 1 GB), medium (2 vCPU / 2 GB), large (4 vCPU / 4 GB), xlarge (8 vCPU / 8 GB). Defaults to standard." } }, "default": { "enable": true, "proxy_execution_enabled": true }, "description": "Workbench configuration" }, "multi_account": { "type": "object", "properties": { "enable": { "type": "boolean", "description": "When true, enables multi-account mode for this session. When not set, falls back to org/project-level configuration." }, "max_accounts_per_toolkit": { "type": "integer", "description": "Maximum number of connected accounts allowed per toolkit. Defaults to 5 when multi-account is enabled." }, "require_explicit_selection": { "type": "boolean", "description": "When true, require explicit account selection when multiple accounts are connected. When false (default), use the first/default account." } }, "description": "Multi-account configuration for this session." }, "preload": { "type": "object", "properties": { "tools": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "string", "enum": [ "all" ] } ], "description": "Explicit preloaded tool slugs, or \"all\" when the session dynamically exposes all app tools allowed by its filters." } }, "required": [ "tools" ], "additionalProperties": false, "description": "Preload configuration. Explicit slugs are returned as an array; dynamic preload is returned as \"all\"." }, "connected_accounts": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string", "format": "connectedAccountId" }, "minItems": 1 }, "description": "Per-toolkit connected account overrides (array of nano-IDs). Multi-account sessions can pin more than one account per toolkit; otherwise length is 1." }, "search": { "type": "object", "properties": { "enable": { "type": "boolean", "default": true } }, "description": "Search helper configuration" }, "execute": { "type": "object", "properties": { "enable_multi_execute": { "type": "boolean", "default": true } }, "description": "Execute helper configuration" } }, "required": [ "user_id", "preload", "search", "execute" ], "description": "The configuration used to create this session" }, "config_version": { "type": "integer", "description": "Monotonic version of the config. Incremented on each PATCH. Use for optimistic concurrency control." }, "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" } }, "description": "Experimental features including the generated system prompt. Only returned on session creation, not on GET.", "x-experimental": true }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "PRELOAD_TOOLS_HIGH_CONTEXT_USAGE" ], "description": "Stable machine code identifying the advisory. Safe to switch on in client code.", "example": "PRELOAD_TOOLS_HIGH_CONTEXT_USAGE" }, "message": { "type": "string", "description": "Human-readable description of the advisory. Suitable for logging or surfacing to end users.", "example": "Session preloads 25 tools; each preloaded tool adds to the agent context window. Consider keeping the list at or under ~20 tools." } }, "required": [ "code", "message" ] }, "default": [], "description": "Advisory list — the session exists and is usable, but the listed issues may warrant attention.", "example": [ { "code": "PRELOAD_TOOLS_HIGH_CONTEXT_USAGE", "message": "Session preloads 25 tools; each preloaded tool adds to the agent context window. Consider keeping the list at or under ~20 tools." } ] } }, "required": [ "session_id", "mcp", "tool_router_tools", "config", "config_version" ] } } } }, "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" } } } }, "408": { "description": "Request timeout. The session creation took too long to complete.", "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" } } } } }, "x-api-version": "3.1" } }, "/api/v3.1/tool_router/session/{session_id}": { "get": { "summary": "Get a tool router session by ID (v3.1)", "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_1a2b3c4d5e6f" }, "required": true, "description": "The unique identifier of the tool router session", "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_1a2b3c4d5e6f" }, "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_1a2b3c4d5e6f/mcp" } }, "required": [ "type", "url" ] }, "tool_router_tools": { "type": "array", "items": { "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" }, "description": "Auth config 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." } }, "description": "Manage connections configuration" }, "tools": { "type": "object", "additionalProperties": { "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 }, { "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 } ] }, "description": "Tool-level configuration per toolkit" }, "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" } }, "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" }, "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." }, "sandbox_size": { "type": "string", "enum": [ "standard", "medium", "large", "xlarge" ], "description": "Sandbox compute tier: standard (1 vCPU / 1 GB), medium (2 vCPU / 2 GB), large (4 vCPU / 4 GB), xlarge (8 vCPU / 8 GB). Defaults to standard." } }, "default": { "enable": true, "proxy_execution_enabled": true }, "description": "Workbench configuration" }, "multi_account": { "type": "object", "properties": { "enable": { "type": "boolean", "description": "When true, enables multi-account mode for this session. When not set, falls back to org/project-level configuration." }, "max_accounts_per_toolkit": { "type": "integer", "description": "Maximum number of connected accounts allowed per toolkit. Defaults to 5 when multi-account is enabled." }, "require_explicit_selection": { "type": "boolean", "description": "When true, require explicit account selection when multiple accounts are connected. When false (default), use the first/default account." } }, "description": "Multi-account configuration for this session." }, "preload": { "type": "object", "properties": { "tools": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "string", "enum": [ "all" ] } ], "description": "Explicit preloaded tool slugs, or \"all\" when the session dynamically exposes all app tools allowed by its filters." } }, "required": [ "tools" ], "additionalProperties": false, "description": "Preload configuration. Explicit slugs are returned as an array; dynamic preload is returned as \"all\"." }, "connected_accounts": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string", "format": "connectedAccountId" }, "minItems": 1 }, "description": "Per-toolkit connected account overrides (array of nano-IDs). Multi-account sessions can pin more than one account per toolkit; otherwise length is 1." }, "search": { "type": "object", "properties": { "enable": { "type": "boolean", "default": true } }, "description": "Search helper configuration" }, "execute": { "type": "object", "properties": { "enable_multi_execute": { "type": "boolean", "default": true } }, "description": "Execute helper configuration" } }, "required": [ "user_id", "preload", "search", "execute" ], "description": "The configuration used to create this session" }, "config_version": { "type": "integer", "description": "Monotonic version of the config. Incremented on each PATCH. Use for optimistic concurrency control." }, "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" } }, "description": "Experimental features", "x-experimental": true }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "PRELOAD_TOOLS_HIGH_CONTEXT_USAGE" ], "description": "Stable machine code identifying the advisory. Safe to switch on in client code.", "example": "PRELOAD_TOOLS_HIGH_CONTEXT_USAGE" }, "message": { "type": "string", "description": "Human-readable description of the advisory. Suitable for logging or surfacing to end users.", "example": "Session preloads 25 tools; each preloaded tool adds to the agent context window. Consider keeping the list at or under ~20 tools." } }, "required": [ "code", "message" ] }, "default": [], "description": "Advisory list — the session exists and is usable, but the listed issues may warrant attention.", "example": [ { "code": "PRELOAD_TOOLS_HIGH_CONTEXT_USAGE", "message": "Session preloads 25 tools; each preloaded tool adds to the agent context window. Consider keeping the list at or under ~20 tools." } ] } }, "required": [ "session_id", "mcp", "tool_router_tools", "config", "config_version" ] } } } }, "400": { "description": "Bad request. This may occur if the session_id format is invalid, please pass this in trs_ prefix format", "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" } } } }, "404": { "description": "Not found. The session with the provided ID does not exist or has been deleted.", "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" } } } } }, "x-api-version": "3.1" }, "patch": { "summary": "Patch a tool router session config (v3.1)", "description": "Partially updates the configuration of an existing tool router session. Only the fields provided in the request body will be updated. Uses optimistic concurrency control to prevent lost updates. The previous config is stored in config history.", "tags": [ "Tool Router" ], "operationId": "patchToolRouterSessionBySessionId", "security": [ { "ApiKeyAuth": [] }, { "UserApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "format": "toolRouterSessionId", "description": "The unique identifier of the tool router session", "example": "trs_1a2b3c4d5e6f" }, "required": true, "description": "The unique identifier of the tool router session", "name": "session_id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "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_1a2b3c4d5e6f", "slack": "ac_7g8h9i0j1k2l" } }, "connected_accounts": { "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string", "format": "connectedAccountId" }, "minItems": 1 }, "description": "The connected accounts to use for the session, as an array of nano-IDs per toolkit. This overrides the default behaviour and pins specific connected accounts when toolkits are executed. Each account must exist (not deleted or disabled) and belong to the same `user_id` as the session. Multi-account sessions can pin multiple; non-multi-account sessions are capped at length 1." }, "manage_connections": { "type": "object", "nullable": true, "properties": { "enable": { "type": "boolean", "nullable": 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, "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, "description": "Enable the \"remove\" action in COMPOSIO_MANAGE_CONNECTIONS to allow deleting connected accounts. Default true." } }, "additionalProperties": false }, "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" ] } }, "disable": { "type": "array", "items": { "type": "string", "enum": [ "readOnlyHint", "destructiveHint", "idempotentHint", "openWorldHint" ] } } } } ], "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. Allows you to enable, disable, or filter by tags for specific tools within each toolkit. Every slug passed in `enable` / `disable` must be a valid Composio tool slug for that toolkit — invalid or typo'd slugs fail session creation with a clear error listing which ones didn't match.", "example": { "gmail": { "enable": [ "GMAIL_SEND_EMAIL", "GMAIL_FETCH_EMAILS" ] }, "slack": { "disable": [ "SLACK_ADD_EMOJI" ] }, "slackbot": { "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" ] } }, "disable": { "type": "array", "items": { "type": "string", "enum": [ "readOnlyHint", "destructiveHint", "idempotentHint", "openWorldHint" ] } } } } ], "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", "nullable": true, "properties": { "enable": { "type": "boolean", "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", "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 }, "sandbox_size": { "type": "string", "enum": [ "standard", "medium", "large", "xlarge" ], "description": "Sandbox compute tier: standard (1 vCPU / 1 GB), medium (2 vCPU / 2 GB), large (4 vCPU / 4 GB), xlarge (8 vCPU / 8 GB). Patching this value recreates the sandbox on next access — sandbox FS state is lost, but /mnt/files/ R2 mount persists.", "example": "large" } }, "additionalProperties": false }, "multi_account": { "type": "object", "nullable": true, "properties": { "enable": { "type": "boolean", "description": "When true, enables multi-account mode for this session. When not set, falls back to org/project-level configuration.", "example": true }, "max_accounts_per_toolkit": { "type": "integer", "minimum": 2, "maximum": 10, "description": "Maximum number of connected accounts allowed per toolkit. Must be between 2 and 10.", "example": 5 }, "require_explicit_selection": { "type": "boolean", "description": "When true, the agent must explicitly select which account to use. When false (default), the first/default account is used automatically.", "example": false } }, "additionalProperties": false }, "preload": { "type": "object", "properties": { "tools": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "string" } ], "description": "Explicit tool slugs to preload, or \"all\" to dynamically expose all current and future app tools allowed by the positive session filters. \"all\" is capped at 1000 tools and is not supported without a positive allowlist.", "example": "all" } }, "additionalProperties": false, "description": "Preload configuration. Use an explicit list for frequently used tool slugs, or \"all\" to dynamically expose every app tool allowed by positive toolkits/tools/tags filters." }, "search": { "type": "object", "properties": { "enable": { "type": "boolean", "default": true } }, "additionalProperties": false }, "execute": { "type": "object", "properties": { "enable_multi_execute": { "type": "boolean", "default": true } }, "additionalProperties": false }, "experimental": { "type": "object", "nullable": true, "properties": { "permissions": { "type": "object", "properties": { "default": { "type": "string", "enum": [ "allow_all", "ask_every_call", "ask_once_per_session" ], "description": "Default elicitation behavior when no override matches. `allow_all` runs every tool without prompting; `ask_every_call` prompts on each invocation; `ask_once_per_session` prompts once and remembers the answer for the rest of the session." }, "overrides": { "type": "object", "additionalProperties": { "type": "string", "enum": [ "always_allow", "always_deny", "ask_once", "ask_always" ] }, "description": "Per-tool overrides keyed by `${toolSlug}:${connectedAccountId ?? \"__none__\"}`, plus account-wide overrides keyed by `*:${connectedAccountId ?? \"__none__\"}`. Exact tool overrides take precedence over account-wide overrides. `always_allow` skips the prompt and runs the tool; `always_deny` blocks the tool; `ask_once` prompts once per session (allow/deny) and remembers; `ask_always` prompts on every call with allow-once/allow-session/deny, ignoring any cached session allow. Overrides take precedence over `default`." } }, "required": [ "default" ], "description": "Per-tool elicitation permission config. Replaces the stored block when provided." }, "link_url_overwrite": { "type": "string", "format": "uri", "description": "Experimental base URL override for connection link redirects created from this tool-router session. When set, link creation returns `${link_url_overwrite}/link/{link_token}` instead of the default Composio Connect base URL. Use only when your integration needs links to open through a custom Connect host.", "x-experimental": true } }, "additionalProperties": false } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Session config successfully patched.", "content": { "application/json": { "schema": { "type": "object", "properties": { "session_id": { "type": "string", "format": "toolRouterSessionId", "description": "The identifier of the session", "example": "trs_1a2b3c4d5e6f" }, "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_1a2b3c4d5e6f/mcp" } }, "required": [ "type", "url" ] }, "tool_router_tools": { "type": "array", "items": { "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" }, "description": "Auth config 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." } }, "description": "Manage connections configuration" }, "tools": { "type": "object", "additionalProperties": { "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 }, { "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 } ] }, "description": "Tool-level configuration per toolkit" }, "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" } }, "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" }, "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." }, "sandbox_size": { "type": "string", "enum": [ "standard", "medium", "large", "xlarge" ], "description": "Sandbox compute tier: standard (1 vCPU / 1 GB), medium (2 vCPU / 2 GB), large (4 vCPU / 4 GB), xlarge (8 vCPU / 8 GB). Defaults to standard." } }, "default": { "enable": true, "proxy_execution_enabled": true }, "description": "Workbench configuration" }, "multi_account": { "type": "object", "properties": { "enable": { "type": "boolean", "description": "When true, enables multi-account mode for this session. When not set, falls back to org/project-level configuration." }, "max_accounts_per_toolkit": { "type": "integer", "description": "Maximum number of connected accounts allowed per toolkit. Defaults to 5 when multi-account is enabled." }, "require_explicit_selection": { "type": "boolean", "description": "When true, require explicit account selection when multiple accounts are connected. When false (default), use the first/default account." } }, "description": "Multi-account configuration for this session." }, "preload": { "type": "object", "properties": { "tools": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "string", "enum": [ "all" ] } ], "description": "Explicit preloaded tool slugs, or \"all\" when the session dynamically exposes all app tools allowed by its filters." } }, "required": [ "tools" ], "additionalProperties": false, "description": "Preload configuration. Explicit slugs are returned as an array; dynamic preload is returned as \"all\"." }, "connected_accounts": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string", "format": "connectedAccountId" }, "minItems": 1 }, "description": "Per-toolkit connected account overrides (array of nano-IDs). Multi-account sessions can pin more than one account per toolkit; otherwise length is 1." }, "search": { "type": "object", "properties": { "enable": { "type": "boolean", "default": true } }, "description": "Search helper configuration" }, "execute": { "type": "object", "properties": { "enable_multi_execute": { "type": "boolean", "default": true } }, "description": "Execute helper configuration" } }, "required": [ "user_id", "preload", "search", "execute" ], "description": "The configuration used to create this session" }, "config_version": { "type": "integer", "description": "Monotonic version of the config. Incremented on each PATCH. Use for optimistic concurrency control." }, "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" } }, "description": "Experimental features", "x-experimental": true }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "PRELOAD_TOOLS_HIGH_CONTEXT_USAGE" ], "description": "Stable machine code identifying the advisory. Safe to switch on in client code.", "example": "PRELOAD_TOOLS_HIGH_CONTEXT_USAGE" }, "message": { "type": "string", "description": "Human-readable description of the advisory. Suitable for logging or surfacing to end users.", "example": "Session preloads 25 tools; each preloaded tool adds to the agent context window. Consider keeping the list at or under ~20 tools." } }, "required": [ "code", "message" ] }, "default": [], "description": "Advisory list — the session exists and is usable, but the listed issues may warrant attention.", "example": [ { "code": "PRELOAD_TOOLS_HIGH_CONTEXT_USAGE", "message": "Session preloads 25 tools; each preloaded tool adds to the agent context window. Consider keeping the list at or under ~20 tools." } ] } }, "required": [ "session_id", "mcp", "tool_router_tools", "config", "config_version" ] } } } }, "400": { "description": "Bad request. Invalid config values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Session not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "408": { "description": "Request timeout while validating patch.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Config version conflict. Re-fetch the session and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-api-version": "3.1" } }, "/api/v3.1/tool_router/session/{session_id}/attach": { "post": { "summary": "Attach to an existing tool router session (v3.1)", "description": "Fetch an existing tool router session by ID.", "tags": [ "Tool Router" ], "operationId": "postToolRouterSessionBySessionIdAttach", "security": [ { "ApiKeyAuth": [] }, { "UserApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "format": "toolRouterSessionId", "description": "The unique identifier of the tool router session", "example": "trs_1a2b3c4d5e6f" }, "required": true, "description": "The unique identifier of the tool router session", "name": "session_id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "experimental": { "type": "object", "properties": { "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" }, "preload": { "type": "boolean", "description": "SDK hint for direct custom-tool exposure. Not stored in session config; echoed in create/attach responses for inline custom definitions." }, "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__ (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." }, "preload": { "type": "boolean", "description": "SDK hint for direct custom-tool exposure. Not stored in session config; echoed in create/attach responses for inline custom definitions." } }, "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_ (standalone) or LOCAL__ (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)" }, "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" }, "preload": { "type": "boolean", "description": "SDK hint for direct custom-tool exposure. Not stored in session config; echoed in create/attach responses for inline custom definitions." } }, "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": "Inline custom tools and toolkits for this request. v3.1 sessions do not persist customs — pass them on every request that needs them." } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Session successfully attached. Returns the session payload.", "content": { "application/json": { "schema": { "type": "object", "properties": { "session_id": { "type": "string", "format": "toolRouterSessionId", "description": "The identifier of the session", "example": "trs_1a2b3c4d5e6f" }, "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_1a2b3c4d5e6f/mcp" } }, "required": [ "type", "url" ] }, "tool_router_tools": { "type": "array", "items": { "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" }, "description": "Auth config 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." } }, "description": "Manage connections configuration" }, "tools": { "type": "object", "additionalProperties": { "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 }, { "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 } ] }, "description": "Tool-level configuration per toolkit" }, "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" } }, "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" }, "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." }, "sandbox_size": { "type": "string", "enum": [ "standard", "medium", "large", "xlarge" ], "description": "Sandbox compute tier: standard (1 vCPU / 1 GB), medium (2 vCPU / 2 GB), large (4 vCPU / 4 GB), xlarge (8 vCPU / 8 GB). Defaults to standard." } }, "default": { "enable": true, "proxy_execution_enabled": true }, "description": "Workbench configuration" }, "multi_account": { "type": "object", "properties": { "enable": { "type": "boolean", "description": "When true, enables multi-account mode for this session. When not set, falls back to org/project-level configuration." }, "max_accounts_per_toolkit": { "type": "integer", "description": "Maximum number of connected accounts allowed per toolkit. Defaults to 5 when multi-account is enabled." }, "require_explicit_selection": { "type": "boolean", "description": "When true, require explicit account selection when multiple accounts are connected. When false (default), use the first/default account." } }, "description": "Multi-account configuration for this session." }, "preload": { "type": "object", "properties": { "tools": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "string", "enum": [ "all" ] } ], "description": "Explicit preloaded tool slugs, or \"all\" when the session dynamically exposes all app tools allowed by its filters." } }, "required": [ "tools" ], "additionalProperties": false, "description": "Preload configuration. Explicit slugs are returned as an array; dynamic preload is returned as \"all\"." }, "connected_accounts": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string", "format": "connectedAccountId" }, "minItems": 1 }, "description": "Per-toolkit connected account overrides (array of nano-IDs). Multi-account sessions can pin more than one account per toolkit; otherwise length is 1." }, "search": { "type": "object", "properties": { "enable": { "type": "boolean", "default": true } }, "description": "Search helper configuration" }, "execute": { "type": "object", "properties": { "enable_multi_execute": { "type": "boolean", "default": true } }, "description": "Execute helper configuration" } }, "required": [ "user_id", "preload", "search", "execute" ], "description": "The configuration used to create this session" }, "config_version": { "type": "integer", "description": "Monotonic version of the config. Incremented on each PATCH. Use for optimistic concurrency control." }, "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" } }, "description": "Experimental features", "x-experimental": true }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "PRELOAD_TOOLS_HIGH_CONTEXT_USAGE" ], "description": "Stable machine code identifying the advisory. Safe to switch on in client code.", "example": "PRELOAD_TOOLS_HIGH_CONTEXT_USAGE" }, "message": { "type": "string", "description": "Human-readable description of the advisory. Suitable for logging or surfacing to end users.", "example": "Session preloads 25 tools; each preloaded tool adds to the agent context window. Consider keeping the list at or under ~20 tools." } }, "required": [ "code", "message" ] }, "default": [], "description": "Advisory list — the session exists and is usable, but the listed issues may warrant attention.", "example": [ { "code": "PRELOAD_TOOLS_HIGH_CONTEXT_USAGE", "message": "Session preloads 25 tools; each preloaded tool adds to the agent context window. Consider keeping the list at or under ~20 tools." } ] } }, "required": [ "session_id", "mcp", "tool_router_tools", "config", "config_version" ] } } } }, "400": { "description": "Bad request. Custom tool validation failed (slug collision, invalid extends_toolkit, schema invalid, etc).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden. Tool Router V2 is not enabled for your account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Session not found or has been deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-api-version": "3.1" } }, "/api/v3.1/tool_router/session/{session_id}/config_history": { "get": { "summary": "List a tool router session config history", "description": "Returns the session config history ordered by version DESC (newest first). The live (current) config appears once, on the first page only, with `is_current: true`; archived versions have `is_current: false`.", "tags": [ "Tool Router" ], "operationId": "getToolRouterSessionBySessionIdConfigHistory", "security": [ { "ApiKeyAuth": [] }, { "UserApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "format": "toolRouterSessionId", "description": "The unique identifier of the tool router session", "example": "trs_1a2b3c4d5e6f" }, "required": true, "description": "The unique identifier of the tool router session", "name": "session_id", "in": "path" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "required": false, "description": "Number of items per page, max allowed is 100", "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" } ], "responses": { "200": { "description": "Config history successfully retrieved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolRouterSessionV31ConfigHistoryListResponse" } } } }, "400": { "description": "Bad request. Invalid pagination cursor or session_id format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Session not found or has been deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-api-version": "3.1" } }, "/api/v3.1/tool_router/session/{session_id}/search": { "post": { "summary": "Search for tools using a query", "description": "Search for tools matching a use case query within an existing tool router session.", "tags": [ "Tool Router" ], "operationId": "postToolRouterSessionBySessionIdSearch", "security": [ { "ApiKeyAuth": [] }, { "UserApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "format": "toolRouterSessionId", "description": "Tool router session ID (trs_*)", "example": "trs_LX9uJKBinWWr" }, "required": true, "description": "Tool router session ID (trs_*)", "name": "session_id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "queries": { "type": "array", "items": { "type": "object", "properties": { "use_case": { "type": "string", "minLength": 1, "maxLength": 1024, "description": "The task or use case to search tools for. Provide a detailed description to get the best results. Max 1024 characters.", "example": "Send an email to john@example.com with a summary of my last 5 slack messages" }, "known_fields": { "type": "string", "maxLength": 500, "description": "Known field hints as key:value pairs (e.g., \"channel_name:general, user_email:john@example.com\"). Max 500 characters.", "example": "channel_name:general" } }, "required": [ "use_case" ] }, "minItems": 1, "maxItems": 7, "description": "List of search queries to execute in parallel.", "example": [ { "use_case": "Send a slack message to a channel" } ] }, "model": { "type": "string", "description": "Optional model hint for search/planning behavior (e.g., \"gpt-4o\").", "example": "gpt-4o" }, "experimental": { "type": "object", "properties": { "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" }, "preload": { "type": "boolean", "description": "SDK hint for direct custom-tool exposure. Not stored in session config; echoed in create/attach responses for inline custom definitions." }, "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__ (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." }, "preload": { "type": "boolean", "description": "SDK hint for direct custom-tool exposure. Not stored in session config; echoed in create/attach responses for inline custom definitions." } }, "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_ (standalone) or LOCAL__ (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)" }, "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" }, "preload": { "type": "boolean", "description": "SDK hint for direct custom-tool exposure. Not stored in session config; echoed in create/attach responses for inline custom definitions." } }, "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": "Inline custom tools and toolkits for this request. v3.1 sessions do not persist customs — pass them on every request that needs them." } }, "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:
\"" }, "results": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "number", "description": "1-based index of the query in the request" }, "use_case": { "type": "string", "description": "The use case that was searched" }, "execution_guidance": { "type": "string", "description": "Guidance message about the search results, particularly when a cached plan is available" }, "difficulty": { "type": "string", "description": "Task difficulty assessment (e.g., \"easy - Simple single-tool operation with known parameters\")" }, "recommended_plan_steps": { "type": "array", "items": { "type": "string" }, "description": "Workflow steps from cached plan (only present when cached plan is available)" }, "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" } }, "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" }, "toolkits": { "type": "array", "items": { "type": "string" }, "description": "List of unique toolkit slugs used by tools in this query" }, "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", "additionalProperties": { "type": "array", "items": { "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": { "type": "string", "description": "The toolkit slug identifier (e.g., \"gmail\", \"slack\")" }, "description": { "type": "string", "description": "Description of what the toolkit does and its capabilities" }, "has_active_connection": { "type": "boolean", "description": "Whether an active connection exists for this toolkit" }, "connection_details": { "type": "object", "additionalProperties": {}, "description": "Connection details including auth config and connected account IDs. Only present when has_active_connection is true." }, "current_user_info": { "type": "object", "additionalProperties": {}, "description": "Information about the currently connected user (email, name, etc.)" }, "account_type": { "type": "string", "enum": [ "PRIVATE", "SHARED" ], "description": "Sharing model for the connected account when has_active_connection is true. PRIVATE is owner-only; SHARED is reachable only when explicitly pinned to the session." }, "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" }, "account_type": { "type": "string", "enum": [ "PRIVATE", "SHARED" ], "description": "Sharing model for this connected account. PRIVATE is owner-only; SHARED is reachable from a tool-router session only when explicitly pinned." } }, "required": [ "id", "status", "created_at", "is_default" ] }, "description": "List of connected accounts for this toolkit. Present when multi-account is enabled." }, "account_selection": { "type": "string", "enum": [ "required" ], "description": "When \"required\", the agent must specify which account to use. Present only when multiple accounts exist." }, "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" }, "tool_slug": { "type": "string", "description": "The slug of the tool" }, "description": { "type": "string", "description": "Description of the tool" }, "input_schema": { "type": "object", "additionalProperties": {}, "description": "Input schema for the tool (only present when hasFullSchema is true)" }, "output_schema": { "type": "object", "additionalProperties": {}, "description": "Output/response schema for the tool. Only included when include_output_schemas is true." }, "hasFullSchema": { "type": "boolean", "description": "Whether the full input_schema is included in this response" }, "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": [ "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" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-api-version": "3.1" } }, "/api/v3.1/tool_router/session/{session_id}/tools": { "get": { "summary": "List tools with schemas for a tool router session (v3.1)", "description": "Returns tools available in a tool router session with complete schemas. Results are paginated; use `next_cursor` to fetch the next page.", "tags": [ "Tool Router" ], "operationId": "getToolRouterSessionBySessionIdTools", "security": [ { "ApiKeyAuth": [] }, { "UserApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "format": "toolRouterSessionId", "description": "Tool router session ID" }, "required": true, "description": "Tool router session ID", "name": "session_id", "in": "path" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 500 }, "required": false, "description": "Number of items per page, max allowed is 500", "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" } ], "responses": { "200": { "description": "Successfully retrieved paginated tools with their complete schemas.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolsPaginated" } } } }, "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 not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-api-version": "3.1" } }, "/api/v3.1/tool_router/session/{session_id}/execute": { "post": { "summary": "Execute a tool within a tool router session", "description": "Execute a tool (meta or app) within an existing tool router session.", "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. Supports both meta tools and app tools exposed by the session.", "example": "GITHUB_CREATE_AN_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 for direct tool execution. 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. Meta/helper tools either ignore this top-level field or define their own account-selection fields, for example COMPOSIO_MULTI_EXECUTE_TOOL.tools[].account.", "example": "coup_hurricane_dal_analytical" }, "enable_auto_workbench_offload": { "type": "boolean", "description": "When true, direct non-meta tool execution may return a workbench offload preview if the response exceeds the configured threshold and the session workbench is enabled. When omitted or false, direct tool execution returns the normal inline response. Meta/helper tools are unaffected, and COMPOSIO_MULTI_EXECUTE_TOOL uses session.workbench configuration for its own batch-level offload behavior.", "example": true }, "experimental": { "type": "object", "properties": { "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" }, "preload": { "type": "boolean", "description": "SDK hint for direct custom-tool exposure. Not stored in session config; echoed in create/attach responses for inline custom definitions." }, "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__ (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." }, "preload": { "type": "boolean", "description": "SDK hint for direct custom-tool exposure. Not stored in session config; echoed in create/attach responses for inline custom definitions." } }, "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_ (standalone) or LOCAL__ (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)" }, "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" }, "preload": { "type": "boolean", "description": "SDK hint for direct custom-tool exposure. Not stored in session config; echoed in create/attach responses for inline custom definitions." } }, "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": "Inline custom tools and toolkits for this request. v3.1 sessions do not persist customs — pass them on every request that needs them." } }, "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" } }, "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" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-api-version": "3.1" } }, "/api/v3.1/tool_router/session/{session_id}/execute_meta": { "post": { "summary": "Execute a meta tool within a tool router session", "description": "Execute a Composio meta tool (COMPOSIO_*) within an existing 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" ], "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 } }, "experimental": { "type": "object", "properties": { "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" }, "preload": { "type": "boolean", "description": "SDK hint for direct custom-tool exposure. Not stored in session config; echoed in create/attach responses for inline custom definitions." }, "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__ (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." }, "preload": { "type": "boolean", "description": "SDK hint for direct custom-tool exposure. Not stored in session config; echoed in create/attach responses for inline custom definitions." } }, "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_ (standalone) or LOCAL__ (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)" }, "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" }, "preload": { "type": "boolean", "description": "SDK hint for direct custom-tool exposure. Not stored in session config; echoed in create/attach responses for inline custom definitions." } }, "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": "Inline custom tools and toolkits for this request. v3.1 sessions do not persist customs — pass them on every request that needs them." } }, "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" } }, "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" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-api-version": "3.1" } }, "/api/v3.1/org/usage/summary": { "post": { "summary": "Org usage summary", "description": "Aggregated metering usage for the authenticated organization. By default includes all projects; use `filters.project_id` to restrict to one or more projects (must belong to the org). Values are summed from raw metering events grouped by `entity_type`.", "tags": [ "Organization" ], "operationId": "postOrgUsageSummary", "security": [ { "OrgApiKeyAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "from": { "type": "number", "description": "Inclusive range start (Unix epoch milliseconds). Defaults to 30 days before `to`." }, "to": { "type": "number", "description": "Exclusive range end (Unix epoch milliseconds). Defaults to now." }, "entity_types": { "type": "array", "items": { "type": "string" }, "description": "Filter to these metering entity types. Omit for all types." }, "filters": { "type": "object", "properties": { "user_id": { "type": "array", "nullable": true, "items": { "type": "string", "minLength": 1 }, "description": "Filter to events matching these external end-user IDs. OR logic within the array." }, "session_id": { "type": "array", "nullable": true, "items": { "type": "string", "minLength": 1 }, "description": "Filter to events matching these session IDs. OR logic within the array." }, "project_id": { "type": "array", "nullable": true, "items": { "type": "string", "format": "projectId" }, "description": "Restrict aggregates to one or more projects (must belong to the authenticated organization). OR logic within the array. Omit for org-wide totals." } } } } } } } }, "responses": { "200": { "description": "Usage aggregates for the organization.", "content": { "application/json": { "schema": { "type": "object", "properties": { "entities": { "type": "object", "additionalProperties": { "type": "object", "properties": { "unit": { "type": "string" }, "total_quantity": { "type": "string" }, "event_count": { "type": "integer", "minimum": 0 } }, "required": [ "unit", "total_quantity", "event_count" ] } } }, "required": [ "entities" ] } } } }, "400": { "description": "Invalid time range, entity_types, or query parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown project_id or project not in this organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Failed to load usage from analytics store or feature configuration.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-api-version": "3.1" } }, "/api/v3.1/org/usage/{entity_type}": { "post": { "summary": "Org usage breakdown", "description": "Grouped metering usage breakdown for the authenticated organization. Groups results by a single dimension or column key. By default includes all projects; use `filters.project_id` to restrict.", "tags": [ "Organization" ], "operationId": "postOrgUsageByEntityType", "security": [ { "OrgApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Metering entity type to break down (e.g. `tool_calls`, `sessions`)." }, "required": true, "description": "Metering entity type to break down (e.g. `tool_calls`, `sessions`).", "name": "entity_type", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "from": { "type": "number", "description": "Inclusive range start (Unix epoch milliseconds). Defaults to 30 days before `to`." }, "to": { "type": "number", "description": "Exclusive range end (Unix epoch milliseconds). Defaults to now." }, "group_by": { "type": "string", "description": "Dimension or column to group results by. Defaults to `tool_slug` for tool_calls and `user_id` for sessions." }, "order_by": { "type": "string", "enum": [ "key", "total_quantity", "event_count" ], "description": "Field to order groups by. Defaults to `total_quantity`." }, "order_direction": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort direction. Defaults to `desc`." }, "limit": { "type": "integer", "minimum": 1, "maximum": 1000, "description": "Maximum number of groups to return. Defaults to 100, max 1000." }, "filters": { "type": "object", "properties": { "user_id": { "type": "array", "nullable": true, "items": { "type": "string", "minLength": 1 }, "description": "Filter to events matching these external end-user IDs. OR logic within the array." }, "session_id": { "type": "array", "nullable": true, "items": { "type": "string", "minLength": 1 }, "description": "Filter to events matching these session IDs. OR logic within the array." }, "project_id": { "type": "array", "nullable": true, "items": { "type": "string", "format": "projectId" }, "description": "Restrict aggregates to one or more projects (must belong to the authenticated organization). OR logic within the array. Omit for org-wide totals." } } } } } } } }, "responses": { "200": { "description": "Usage breakdown for the organization.", "content": { "application/json": { "schema": { "type": "object", "properties": { "entity_type": { "type": "string" }, "unit": { "type": "string" }, "total_quantity": { "type": "string" }, "event_count": { "type": "integer", "minimum": 0 }, "groups": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "total_quantity": { "type": "string" }, "event_count": { "type": "integer", "minimum": 0 } }, "required": [ "key", "total_quantity", "event_count" ] } } }, "required": [ "entity_type", "unit", "total_quantity", "event_count", "groups" ] } } } }, "400": { "description": "Invalid entity_type, group_by, time range, or query parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown project_id or project not in this organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Failed to load usage from analytics store or feature configuration.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-api-version": "3.1" } }, "/api/v3.1/project/usage/summary": { "post": { "summary": "Project usage summary", "description": "Aggregated metering usage for the authenticated project only. Values are summed from raw metering events grouped by `entity_type`.", "tags": [ "Projects" ], "operationId": "postProjectUsageSummary", "security": [ { "ApiKeyAuth": [] }, { "UserApiKeyAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "from": { "type": "number", "description": "Inclusive range start (Unix epoch milliseconds). Defaults to 30 days before `to`." }, "to": { "type": "number", "description": "Exclusive range end (Unix epoch milliseconds). Defaults to now." }, "entity_types": { "type": "array", "items": { "type": "string" }, "description": "Filter to these metering entity types. Omit for all types." }, "filters": { "type": "object", "properties": { "user_id": { "type": "array", "nullable": true, "items": { "type": "string", "minLength": 1 }, "description": "Filter to events matching these external end-user IDs. OR logic within the array." }, "session_id": { "type": "array", "nullable": true, "items": { "type": "string", "minLength": 1 }, "description": "Filter to events matching these session IDs. OR logic within the array." } } } } } } } }, "responses": { "200": { "description": "Usage aggregates for the project.", "content": { "application/json": { "schema": { "type": "object", "properties": { "entities": { "type": "object", "additionalProperties": { "type": "object", "properties": { "unit": { "type": "string" }, "total_quantity": { "type": "string" }, "event_count": { "type": "integer", "minimum": 0 } }, "required": [ "unit", "total_quantity", "event_count" ] } } }, "required": [ "entities" ] } } } }, "400": { "description": "Invalid time range, entity_types, or query parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Project not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Failed to load usage from analytics store or feature configuration.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-api-version": "3.1" } }, "/api/v3.1/project/usage/{entity_type}": { "post": { "summary": "Project usage breakdown", "description": "Grouped metering usage breakdown for the authenticated project. Groups results by a single dimension or column key.", "tags": [ "Projects" ], "operationId": "postProjectUsageByEntityType", "security": [ { "ApiKeyAuth": [] }, { "UserApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Metering entity type to break down (e.g. `tool_calls`, `sessions`)." }, "required": true, "description": "Metering entity type to break down (e.g. `tool_calls`, `sessions`).", "name": "entity_type", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "from": { "type": "number", "description": "Inclusive range start (Unix epoch milliseconds). Defaults to 30 days before `to`." }, "to": { "type": "number", "description": "Exclusive range end (Unix epoch milliseconds). Defaults to now." }, "group_by": { "type": "string", "description": "Dimension or column to group results by. Defaults to `tool_slug` for tool_calls and `user_id` for sessions." }, "order_by": { "type": "string", "enum": [ "key", "total_quantity", "event_count" ], "description": "Field to order groups by. Defaults to `total_quantity`." }, "order_direction": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort direction. Defaults to `desc`." }, "limit": { "type": "integer", "minimum": 1, "maximum": 1000, "description": "Maximum number of groups to return. Defaults to 100, max 1000." }, "filters": { "type": "object", "properties": { "user_id": { "type": "array", "nullable": true, "items": { "type": "string", "minLength": 1 }, "description": "Filter to events matching these external end-user IDs. OR logic within the array." }, "session_id": { "type": "array", "nullable": true, "items": { "type": "string", "minLength": 1 }, "description": "Filter to events matching these session IDs. OR logic within the array." } } } } } } } }, "responses": { "200": { "description": "Usage breakdown for the project.", "content": { "application/json": { "schema": { "type": "object", "properties": { "entity_type": { "type": "string" }, "unit": { "type": "string" }, "total_quantity": { "type": "string" }, "event_count": { "type": "integer", "minimum": 0 }, "groups": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "total_quantity": { "type": "string" }, "event_count": { "type": "integer", "minimum": 0 } }, "required": [ "key", "total_quantity", "event_count" ] } } }, "required": [ "entity_type", "unit", "total_quantity", "event_count", "groups" ] } } } }, "400": { "description": "Invalid entity_type, group_by, time range, or query parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Project not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Failed to load usage from analytics store or feature configuration.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-api-version": "3.1" } }, "/api/v3.1/auth/session/info": { "get": { "summary": "Get current user session information", "description": "Retrieves detailed information about the current authenticated user session, including project details, organization membership, and API key information if applicable. This endpoint is useful for verifying authentication status and retrieving contextual information about the authenticated user and their access privileges.", "tags": [ "Authentication" ], "operationId": "getAuthSessionInfo", "security": [ { "ApiKeyAuth": [] }, { "UserApiKeyAuth": [] } ], "responses": { "200": { "description": "Session is valid and active. Returns detailed information about the authenticated user, their project, and organization.", "content": { "application/json": { "schema": { "type": "object", "properties": { "project": { "type": "object", "nullable": true, "properties": { "auto_id": { "type": "number", "description": "Internal auto-incrementing ID for the project", "example": 12345 }, "id": { "type": "string", "description": "UUID identifier for the project", "example": "550e8400-e29b-41d4-a716-446655440000" }, "org_id": { "type": "string", "description": "Organization UUID that this project belongs to", "example": "550e8400-e29b-41d4-a716-446655440001" }, "name": { "type": "string", "description": "User-defined name for the project", "example": "Production API" }, "email": { "type": "string", "description": "Email address used for project notifications", "example": "project-123@composio.dev" }, "nano_id": { "type": "string", "format": "projectId", "description": "Short, URL-friendly unique identifier for the project", "example": "pr_1a2b3c4d5e6f" }, "created_at": { "type": "string", "description": "Date and time when the project was created", "example": "2023-05-16T14:30:00.000Z" }, "updated_at": { "type": "string", "description": "Date and time when the project was last modified", "example": "2023-05-18T09:15:30.000Z" }, "webhook_url": { "type": "string", "nullable": true, "description": "Endpoint URL for trigger webhook notifications", "example": "https://example.com/webhook" }, "event_webhook_url": { "type": "string", "nullable": true, "description": "Endpoint URL for event webhook notifications", "example": "https://example.com/events" }, "webhook_secret": { "type": "string", "nullable": true, "description": "Secret used to verify webhook signatures", "example": "whsec_a1b2c3d4e5f6g7h8i9j0" }, "triggers_enabled": { "type": "boolean", "description": "Flag indicating if triggers are enabled for this project", "example": true }, "last_subscribed_at": { "type": "string", "nullable": true, "description": "Date and time when the project last subscribed to updates", "example": "2023-05-17T10:00:00.000Z" }, "deleted": { "type": "boolean", "description": "Flag indicating if the project has been deleted", "example": false }, "is_new_webhook": { "type": "boolean", "description": "Deprecated: Please refer to webhook_version instead. True indicates if the webhook configuration is using the previous new format (V2). False indicates the oldest format (V1)", "example": true, "deprecated": true }, "webhook_version": { "type": "string", "enum": [ "V1", "V2", "V3" ], "description": "Version of the webhook configuration", "example": "V2" }, "org": { "type": "object", "properties": { "id": { "type": "string", "format": "orgId", "description": "Short, URL-friendly unique identifier for the organization", "example": "ok_1a2b3c4d5e6f" }, "name": { "type": "string", "description": "User-defined name for the organization", "example": "Acme Corp" }, "plan": { "type": "string", "description": "Current subscription plan level", "example": "BUSINESS" } }, "required": [ "id", "name", "plan" ], "description": "Organization details" } }, "required": [ "auto_id", "id", "org_id", "name", "email", "nano_id", "created_at", "updated_at", "webhook_url", "event_webhook_url", "webhook_secret", "triggers_enabled", "last_subscribed_at", "deleted", "is_new_webhook", "webhook_version", "org" ], "description": "Details of the current active project (null if accessing with org-level credentials)" }, "api_key": { "type": "object", "nullable": true, "properties": { "auto_id": { "type": "number", "description": "Internal auto-incrementing ID for the API key", "example": 7890 }, "id": { "type": "string", "description": "UUID identifier for the API key", "example": "550e8400-e29b-41d4-a716-446655440003" }, "name": { "type": "string", "description": "User-defined name for the API key", "example": "Development Key" }, "project_id": { "type": "string", "format": "projectId", "description": "Short, URL-friendly unique identifier for the associated project", "example": "pr_1a2b3c4d5e6f" }, "org_member_id": { "type": "string", "description": "UUID identifier for the organization member who owns this API key", "example": "550e8400-e29b-41d4-a716-446655440002" }, "created_at": { "type": "string", "description": "Date and time when the API key was created", "example": "2023-05-01T10:00:00.000Z" }, "updated_at": { "type": "string", "description": "Date and time when the API key was last modified", "example": "2023-05-01T10:00:00.000Z" }, "deleted_at": { "type": "string", "nullable": true, "description": "Date and time when the API key was deleted (if applicable)" }, "key": { "type": "string", "description": "The actual API key value (usually only shown once during creation)", "example": "ak_a1b2c3d4e5f6g7h8i9j0" }, "deleted": { "type": "boolean", "description": "Flag indicating if the API key has been deleted", "example": false } }, "required": [ "auto_id", "id", "name", "project_id", "org_member_id", "created_at", "updated_at", "deleted_at", "key", "deleted" ], "description": "Details of the API key used for authentication (null if using session auth)" }, "org_member": { "type": "object", "properties": { "id": { "type": "string", "description": "UUID identifier for the organization member", "example": "550e8400-e29b-41d4-a716-446655440002" }, "email": { "type": "string", "description": "Email address of the authenticated user", "example": "user@example.com" }, "name": { "type": "string", "description": "Display name of the authenticated user", "example": "John Doe" }, "role": { "type": "string", "description": "Access role of the authenticated user within the organization", "example": "admin" }, "metadata": { "type": "object", "properties": { "createdInBetterAuth": { "type": "boolean", "description": "Whether the user was created via Better Auth (dashboard signup)." }, "prefers_old_dashboard": { "type": "boolean", "description": "If true, the user will be redirected to the legacy dashboard at platform.composio.dev." }, "onboarding_platform": { "type": "string", "enum": [ "consumer", "developer" ], "description": "Platform the user onboarded on." }, "seen_flow_consumer": { "type": "boolean", "description": "True once the user has completed the consumer onboarding flow." }, "seen_flow_developer": { "type": "boolean", "description": "True once the user has completed the developer onboarding flow." }, "seen_flow_cli": { "type": "boolean", "description": "True once the user has completed the CLI onboarding flow." }, "seen_connect_announcement": { "type": "boolean", "description": "True once the user has dismissed the Composio For You announcement modal in the developer dashboard." } }, "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "boolean" }, { "type": "number" } ] }, "description": "User metadata (JSONB). Typed keys are shown; additional keys pass through unchanged." } }, "required": [ "id", "email", "name", "role", "metadata" ], "description": "Information about the authenticated user", "example": { "id": "550e8400-e29b-41d4-a716-446655440002", "email": "user@example.com", "name": "John Doe", "role": "admin", "metadata": { "prefers_old_dashboard": false } } } }, "required": [ "project", "api_key", "org_member" ], "description": "Response containing user session information" } } } }, "400": { "description": "Bad request. The request format may be invalid or missing required parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized. Authentication is required or the provided credentials are invalid or expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden. The authenticated user does not have permission to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. The requested project, organization, or member resource could not be found.", "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" } } } } }, "x-api-version": "3.1" } }, "/api/v3.1/auth_configs": { "post": { "summary": "Create new authentication configuration", "description": "Creates a new auth config for a toolkit, allowing you to use your own OAuth credentials or API keys instead of Composio-managed authentication. This is required when you want to use custom OAuth apps (bring your own client ID/secret) or configure specific authentication parameters for a toolkit.", "tags": [ "Auth Configs" ], "operationId": "postAuthConfigs", "security": [ { "ApiKeyAuth": [] }, { "UserApiKeyAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "toolkit": { "type": "object", "properties": { "slug": { "type": "string", "description": "Toolkit slug to create auth config for" } }, "required": [ "slug" ] }, "auth_config": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "use_composio_managed_auth" ] }, "name": { "type": "string", "description": "The name of the integration" }, "credentials": { "type": "object", "properties": { "scopes": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "user_scopes": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] } }, "default": {} }, "tool_access_config": { "type": "object", "properties": { "tools_for_connected_account_creation": { "type": "array", "items": { "type": "string" }, "default": [], "description": "Tools used to generate the minimum required scopes for the auth config (only valid for OAuth). If passed, this will update the scopes." } } }, "restrict_to_following_tools": { "type": "array", "items": { "type": "string" }, "default": [], "description": "Use tool_access_config instead. This field will be deprecated in the future.", "deprecated": true }, "shared_credentials": { "type": "object", "additionalProperties": {}, "description": "[EXPERIMENTAL] Shared credentials that will be inherited by all connected accounts using this auth config", "x-experimental": true }, "is_enabled_for_tool_router": { "type": "boolean", "description": "Whether this auth config is enabled for tool router" } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "use_custom_auth" ] }, "name": { "type": "string", "description": "The name of the integration" }, "authScheme": { "type": "string", "enum": [ "OAUTH2", "OAUTH1", "API_KEY", "BASIC", "BILLCOM_AUTH", "BEARER_TOKEN", "GOOGLE_SERVICE_ACCOUNT", "NO_AUTH", "BASIC_WITH_JWT", "CALCOM_AUTH", "SERVICE_ACCOUNT", "SAML", "DCR_OAUTH", "S2S_OAUTH2" ] }, "credentials": { "type": "object", "properties": { "scopes": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "user_scopes": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] } }, "default": {} }, "proxy_config": { "type": "object", "nullable": true, "properties": { "proxy_url": { "type": "string", "format": "uri", "description": "The url of the auth proxy" }, "proxy_auth_key": { "type": "string", "description": "The auth key for the auth proxy" } }, "required": [ "proxy_url" ] }, "restrict_to_following_tools": { "type": "array", "items": { "type": "string" }, "default": [], "description": "Use tool_access_config instead. This field will be deprecated in the future.", "deprecated": true }, "tool_access_config": { "type": "object", "properties": { "tools_for_connected_account_creation": { "type": "array", "items": { "type": "string" }, "default": [], "description": "Tools used to generate the minimum required scopes for the auth config (only valid for OAuth). If passed, this will update the scopes." } } }, "shared_credentials": { "type": "object", "additionalProperties": {}, "description": "[EXPERIMENTAL] Shared credentials that will be inherited by all connected accounts using this auth config", "x-experimental": true }, "is_enabled_for_tool_router": { "type": "boolean", "description": "Whether this auth config is enabled for tool router" } }, "required": [ "type", "authScheme" ] } ], "default": { "type": "use_composio_managed_auth", "credentials": {}, "restrict_to_following_tools": [] } } }, "required": [ "toolkit" ] } } } }, "responses": { "201": { "description": "Successfully created auth config", "content": { "application/json": { "schema": { "type": "object", "properties": { "toolkit": { "type": "object", "properties": { "slug": { "type": "string", "description": "The unique key of the toolkit" } }, "required": [ "slug" ] }, "auth_config": { "type": "object", "properties": { "id": { "type": "string", "format": "authConfigId", "description": "The auth config id of the toolkit (must be a valid auth config id)" }, "auth_scheme": { "type": "string", "description": "The authentication mode of the toolkit" }, "is_composio_managed": { "type": "boolean", "description": "Whether the auth config is managed by Composio" }, "restrict_to_following_tools": { "type": "array", "items": { "type": "string" }, "default": [], "description": "The tools that the user can use with the auth config" } }, "required": [ "id", "auth_scheme", "is_composio_managed" ] } }, "required": [ "toolkit", "auth_config" ] } } } }, "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": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-api-version": "3.1" }, "get": { "summary": "List authentication configurations with optional filters", "description": "Retrieves all auth configs for your project. Auth configs define how users authenticate with external services (OAuth, API keys, etc.). Use filters to find configs for specific toolkits or to distinguish between Composio-managed and custom configurations.", "tags": [ "Auth Configs" ], "operationId": "getAuthConfigs", "security": [ { "ApiKeyAuth": [] }, { "UserApiKeyAuth": [] } ], "parameters": [ { "schema": { "anyOf": [ { "type": "string" }, { "type": "boolean" } ], "description": "Whether to filter by composio managed auth configs" }, "required": false, "description": "Whether to filter by composio managed auth configs", "name": "is_composio_managed", "in": "query" }, { "schema": { "type": "string" }, "required": false, "description": "Comma-separated list of toolkit slugs to filter auth configs by", "in": "query", "name": "toolkit_slug" }, { "schema": { "type": "string", "description": "DEPRECATED: This parameter will be removed in a future version. Please use toolkit_slug instead.", "deprecated": true }, "required": false, "description": "The app id to filter by", "name": "deprecated_app_id", "in": "query" }, { "schema": { "type": "string", "description": "DEPRECATED: This parameter will be removed in a future version.", "deprecated": true }, "required": false, "name": "deprecated_status", "in": "query" }, { "schema": { "type": "boolean", "nullable": true, "default": false, "description": "Show disabled auth configs" }, "required": false, "description": "Show disabled auth configs", "name": "show_disabled", "in": "query" }, { "schema": { "type": "string", "description": "Search auth configs by name or id" }, "required": false, "description": "Search auth configs by name or id", "name": "search", "in": "query" }, { "schema": { "type": "number", "nullable": true }, "required": false, "description": "Number of items per page, max allowed is 1000", "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" } ], "responses": { "200": { "description": "Successfully fetched auth configs", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "authConfigId", "description": "The unique ID of the authentication configuration" }, "uuid": { "type": "string", "description": "The UUID of the authentication configuration (for backward compatibility)" }, "type": { "type": "string", "enum": [ "default", "custom" ], "description": "The type of the authentication configuration (custom or default)" }, "toolkit": { "type": "object", "properties": { "slug": { "type": "string", "description": "The unique identifier of the integration app" }, "logo": { "type": "string", "description": "The URL to the integration app's logo image" }, "auth_guide_url": { "type": "string", "nullable": true, "description": "URL to a guide page with authentication setup instructions" }, "auth_hint_url": { "type": "string", "nullable": true, "description": "URL to a page where users can obtain or configure credentials" } }, "required": [ "slug", "logo" ], "description": "Information about the associated integration" }, "name": { "type": "string", "description": "The display name of the authentication configuration" }, "auth_scheme": { "type": "string", "enum": [ "OAUTH2", "OAUTH1", "API_KEY", "BASIC", "BILLCOM_AUTH", "BEARER_TOKEN", "GOOGLE_SERVICE_ACCOUNT", "NO_AUTH", "BASIC_WITH_JWT", "CALCOM_AUTH", "SERVICE_ACCOUNT", "SAML", "DCR_OAUTH", "S2S_OAUTH2" ], "description": "The authentication scheme used (e.g., OAuth2, API Key, etc.)" }, "is_composio_managed": { "type": "boolean", "description": "Whether this authentication configuration is managed by Composio or the user" }, "credentials": { "type": "object", "additionalProperties": {}, "description": "The authentication credentials (tokens, keys, etc.) - may be partially hidden for security" }, "proxy_config": { "type": "object", "nullable": true, "properties": { "proxy_url": { "type": "string", "format": "uri", "description": "The url of the auth proxy" }, "proxy_auth_key": { "type": "string", "description": "The auth key for the auth proxy" } }, "required": [ "proxy_url" ] }, "status": { "type": "string", "enum": [ "ENABLED", "DISABLED" ], "description": "Current status of the authentication configuration" }, "created_by": { "type": "string", "description": "The identifier of the user who created the auth config" }, "created_at": { "type": "string", "description": "ISO 8601 date-time when the auth config was created" }, "last_updated_at": { "type": "string", "description": "ISO 8601 date-time when the auth config was last updated" }, "no_of_connections": { "type": "number", "description": "The number of active connections using this auth config" }, "expected_input_fields": { "type": "array", "items": { "nullable": true, "type": "object" }, "description": "Fields expected during connection initialization" }, "restrict_to_following_tools": { "type": "array", "items": { "type": "string" }, "description": "Use tool_access_config instead. This field will be deprecated in the future.", "deprecated": true }, "tool_access_config": { "type": "object", "properties": { "tools_for_connected_account_creation": { "type": "array", "items": { "type": "string" }, "default": [], "description": "Tools used to generate the minimum required scopes for the auth config (only valid for OAuth). If passed, this will update the scopes." }, "tools_available_for_execution": { "type": "array", "items": { "type": "string" }, "default": [], "description": "The actions that the user can perform on the auth config. If passed, this will update the actions that the user can perform on the auth config." } } }, "shared_credentials": { "type": "object", "additionalProperties": {}, "description": "[EXPERIMENTAL] Shared credentials that will be inherited by all connected accounts using this auth config", "x-experimental": true }, "is_enabled_for_tool_router": { "type": "boolean", "description": "Whether this auth config is enabled for tool router" }, "deprecated_params": { "type": "object", "properties": { "default_connector_id": { "type": "string", "nullable": true, "description": "Deprecated: Default connector ID" }, "member_uuid": { "type": "string", "description": "Deprecated: Member UUID" }, "toolkit_id": { "type": "string", "description": "Deprecated: Toolkit ID" }, "expected_input_fields": { "type": "array", "items": { "type": "object", "additionalProperties": {} }, "description": "Deprecated: Fields expected during connection initialization" } }, "required": [ "default_connector_id" ], "description": "DEPRECATED: This parameter will be removed in a future version.", "deprecated": true } }, "required": [ "id", "uuid", "type", "toolkit", "name", "status", "no_of_connections", "tool_access_config" ] } }, "next_cursor": { "type": "string", "nullable": true }, "total_pages": { "type": "number" }, "current_page": { "type": "number" }, "total_items": { "type": "number" } }, "required": [ "items", "total_pages", "current_page", "total_items" ] } } } }, "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": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-api-version": "3.1" } }, "/api/v3.1/auth_configs/{nanoid}": { "get": { "summary": "Get single authentication configuration by ID", "description": "Retrieves detailed information about a specific authentication configuration using its unique identifier.", "tags": [ "Auth Configs" ], "operationId": "getAuthConfigsByNanoid", "security": [ { "ApiKeyAuth": [] }, { "UserApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "format": "authConfigId", "description": "The unique identifier of the authentication configuration to retrieve" }, "required": true, "description": "The unique identifier of the authentication configuration to retrieve", "name": "nanoid", "in": "path" } ], "responses": { "200": { "description": "Successfully fetched auth config", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "authConfigId", "description": "The unique ID of the authentication configuration" }, "uuid": { "type": "string", "description": "The UUID of the authentication configuration (for backward compatibility)" }, "type": { "type": "string", "enum": [ "default", "custom" ], "description": "The type of the authentication configuration (custom or default)" }, "toolkit": { "type": "object", "properties": { "slug": { "type": "string", "description": "The unique identifier of the integration app" }, "logo": { "type": "string", "description": "The URL to the integration app's logo image" }, "auth_guide_url": { "type": "string", "nullable": true, "description": "URL to a guide page with authentication setup instructions" }, "auth_hint_url": { "type": "string", "nullable": true, "description": "URL to a page where users can obtain or configure credentials" } }, "required": [ "slug", "logo" ], "description": "Information about the associated integration" }, "name": { "type": "string", "description": "The display name of the authentication configuration" }, "auth_scheme": { "type": "string", "enum": [ "OAUTH2", "OAUTH1", "API_KEY", "BASIC", "BILLCOM_AUTH", "BEARER_TOKEN", "GOOGLE_SERVICE_ACCOUNT", "NO_AUTH", "BASIC_WITH_JWT", "CALCOM_AUTH", "SERVICE_ACCOUNT", "SAML", "DCR_OAUTH", "S2S_OAUTH2" ], "description": "The authentication scheme used (e.g., OAuth2, API Key, etc.)" }, "is_composio_managed": { "type": "boolean", "description": "Whether this authentication configuration is managed by Composio or the user" }, "credentials": { "type": "object", "additionalProperties": {}, "description": "The authentication credentials (tokens, keys, etc.) - may be partially hidden for security" }, "proxy_config": { "type": "object", "nullable": true, "properties": { "proxy_url": { "type": "string", "format": "uri", "description": "The url of the auth proxy" }, "proxy_auth_key": { "type": "string", "description": "The auth key for the auth proxy" } }, "required": [ "proxy_url" ] }, "status": { "type": "string", "enum": [ "ENABLED", "DISABLED" ], "description": "Current status of the authentication configuration" }, "created_by": { "type": "string", "description": "The identifier of the user who created the auth config" }, "created_at": { "type": "string", "description": "ISO 8601 date-time when the auth config was created" }, "last_updated_at": { "type": "string", "description": "ISO 8601 date-time when the auth config was last updated" }, "no_of_connections": { "type": "number", "description": "The number of active connections using this auth config" }, "expected_input_fields": { "type": "array", "items": { "nullable": true, "type": "object" }, "description": "Fields expected during connection initialization" }, "restrict_to_following_tools": { "type": "array", "items": { "type": "string" }, "description": "Use tool_access_config instead. This field will be deprecated in the future.", "deprecated": true }, "tool_access_config": { "type": "object", "properties": { "tools_for_connected_account_creation": { "type": "array", "items": { "type": "string" }, "default": [], "description": "Tools used to generate the minimum required scopes for the auth config (only valid for OAuth). If passed, this will update the scopes." }, "tools_available_for_execution": { "type": "array", "items": { "type": "string" }, "default": [], "description": "The actions that the user can perform on the auth config. If passed, this will update the actions that the user can perform on the auth config." } } }, "shared_credentials": { "type": "object", "additionalProperties": {}, "description": "[EXPERIMENTAL] Shared credentials that will be inherited by all connected accounts using this auth config", "x-experimental": true }, "is_enabled_for_tool_router": { "type": "boolean", "description": "Whether this auth config is enabled for tool router" }, "deprecated_params": { "type": "object", "properties": { "default_connector_id": { "type": "string", "nullable": true, "description": "Deprecated: Default connector ID" }, "member_uuid": { "type": "string", "description": "Deprecated: Member UUID" }, "toolkit_id": { "type": "string", "description": "Deprecated: Toolkit ID" }, "expected_input_fields": { "type": "array", "items": { "type": "object", "additionalProperties": {} }, "description": "Deprecated: Fields expected during connection initialization" } }, "required": [ "default_connector_id" ], "description": "DEPRECATED: This parameter will be removed in a future version.", "deprecated": true } }, "required": [ "id", "uuid", "type", "toolkit", "name", "status", "no_of_connections", "tool_access_config" ] } } } }, "400": { "description": "Bad request - Invalid auth config ID format", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized - Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found - Auth configuration 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" } } } } }, "x-api-version": "3.1" }, "patch": { "summary": "Update an authentication configuration", "description": "Modifies an existing authentication configuration with new credentials or other settings. Only specified fields will be updated.", "tags": [ "Auth Configs" ], "operationId": "patchAuthConfigsByNanoid", "security": [ { "ApiKeyAuth": [] }, { "UserApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "format": "authConfigId", "description": "The unique identifier of the authentication configuration to update" }, "required": true, "description": "The unique identifier of the authentication configuration to update", "name": "nanoid", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "custom" ] }, "name": { "type": "string", "minLength": 1, "description": "The display name of the authentication configuration" }, "credentials": { "type": "object", "properties": { "scopes": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "user_scopes": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] } } }, "proxy_config": { "type": "object", "nullable": true, "properties": { "proxy_url": { "type": "string", "format": "uri", "description": "The url of the auth proxy" }, "proxy_auth_key": { "type": "string", "description": "The auth key for the auth proxy" } }, "required": [ "proxy_url" ] }, "restrict_to_following_tools": { "type": "array", "items": { "type": "string" }, "description": "Use tool_access_config instead. This field will be deprecated in the future.", "deprecated": true }, "tool_access_config": { "type": "object", "properties": { "tools_for_connected_account_creation": { "type": "array", "items": { "type": "string" }, "description": "Tools used to generate the minimum required scopes for the auth config (only valid for OAuth). If passed, this will update the scopes." }, "tools_available_for_execution": { "type": "array", "items": { "type": "string" }, "description": "The actions that the user can perform on the auth config. If passed, this will update the actions that the user can perform on the auth config." } } }, "shared_credentials": { "type": "object", "additionalProperties": {}, "description": "Shared credentials that will be inherited by connected accounts. For eg: this can be used to share the API key for a tool with all connected accounts using this auth config." }, "is_enabled_for_tool_router": { "type": "boolean", "description": "Whether this auth config is enabled for tool router" } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "default" ] }, "name": { "type": "string", "minLength": 1, "description": "The display name of the authentication configuration" }, "scopes": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "user_scopes": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "restrict_to_following_tools": { "type": "array", "items": { "type": "string" }, "description": "Use tool_access_config instead. This field will be deprecated in the future.", "deprecated": true }, "tool_access_config": { "type": "object", "properties": { "tools_for_connected_account_creation": { "type": "array", "items": { "type": "string" }, "description": "Tools used to generate the minimum required scopes for the auth config (only valid for OAuth). If passed, this will update the scopes." }, "tools_available_for_execution": { "type": "array", "items": { "type": "string" }, "description": "The actions that the user can perform on the auth config. If passed, this will update the actions that the user can perform on the auth config." } } }, "shared_credentials": { "type": "object", "additionalProperties": {}, "description": "Shared credentials that will be inherited by connected accounts. For eg: this can be used to share the API key for a tool with all connected accounts using this auth config." }, "is_enabled_for_tool_router": { "type": "boolean", "description": "Whether this auth config is enabled for tool router" } }, "required": [ "type" ] } ] }, "examples": { "standardUpdate": { "summary": "Standard credential update", "value": { "auth_config": { "credentials": { "api_key": "YOUR_NEW_API_KEY", "client_secret": "YOUR_NEW_CLIENT_SECRET" }, "restrict_to_following_tools": [ "GMAIL_SEND_EMAIL", "GMAIL_FETCH_EMAILS" ] } } } } } } }, "responses": { "200": { "description": "Successfully updated auth config", "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "400": { "description": "Bad request - Invalid input or credentials format", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized - Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found - Auth configuration 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" } } } } }, "x-api-version": "3.1" }, "delete": { "summary": "Delete an authentication configuration", "description": "Soft-deletes an authentication configuration by marking it as deleted in the database. This operation cannot be undone.", "tags": [ "Auth Configs" ], "operationId": "deleteAuthConfigsByNanoid", "security": [ { "ApiKeyAuth": [] }, { "UserApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "format": "authConfigId", "description": "The unique identifier of the authentication configuration to delete" }, "required": true, "description": "The unique identifier of the authentication configuration to delete", "name": "nanoid", "in": "path" } ], "responses": { "200": { "description": "Successfully deleted auth config", "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "400": { "description": "Bad request - Invalid auth config ID format", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized - Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Auth config not found - The specified configuration does not exist or was already deleted", "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "500": { "description": "Internal server error - Something went wrong on the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-api-version": "3.1" } }, "/api/v3.1/auth_configs/{nanoid}/{status}": { "patch": { "summary": "Enable or disable an authentication configuration", "description": "Updates the status of an authentication configuration to either enabled or disabled. Disabled configurations cannot be used for new connections.", "tags": [ "Auth Configs" ], "operationId": "patchAuthConfigsByNanoidByStatus", "security": [ { "ApiKeyAuth": [] }, { "UserApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "format": "authConfigId", "description": "The unique identifier of the authentication configuration to update" }, "required": true, "description": "The unique identifier of the authentication configuration to update", "name": "nanoid", "in": "path" }, { "schema": { "type": "string", "enum": [ "ENABLED", "DISABLED" ], "description": "The new status to set for the auth configuration" }, "required": true, "description": "The new status to set for the auth configuration", "name": "status", "in": "path" } ], "responses": { "200": { "description": "Successfully updated auth config status", "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "400": { "description": "Bad request - Invalid auth config ID or status value", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized - Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found - Auth configuration 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" } } } } }, "x-api-version": "3.1" } }, "/api/v3.1/connected_accounts": { "get": { "summary": "List connected accounts with optional filters", "description": "Retrieves all connected accounts for your project. Connected accounts represent authenticated user connections to external services (e.g., a user's Gmail account, Slack workspace). Filter by toolkit, status, user ID, or auth config to find specific connections.", "tags": [ "Connected Accounts" ], "operationId": "getConnectedAccounts", "security": [ { "ApiKeyAuth": [] }, { "UserApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "The toolkit slugs of the connected accounts" }, "required": false, "description": "The toolkit slugs of the connected accounts", "name": "toolkit_slugs", "in": "query" }, { "schema": { "type": "array", "nullable": true, "items": { "type": "string", "enum": [ "INITIALIZING", "INITIATED", "ACTIVE", "FAILED", "EXPIRED", "INACTIVE", "REVOKED" ] }, "description": "The status of the connected account" }, "required": false, "description": "The status of the connected account", "name": "statuses", "in": "query" }, { "schema": { "type": "string", "nullable": true, "description": "The cursor to paginate through the connected accounts" }, "required": false, "description": "The cursor to paginate through the connected accounts", "name": "cursor", "in": "query" }, { "schema": { "type": "number", "nullable": true, "description": "The limit of the connected accounts to return" }, "required": false, "description": "The limit of the connected accounts to return", "name": "limit", "in": "query" }, { "schema": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "The user ids of the connected accounts" }, "required": false, "description": "The user ids of the connected accounts", "name": "user_ids", "in": "query" }, { "schema": { "type": "array", "nullable": true, "items": { "type": "string", "format": "authConfigId" }, "description": "The auth config ids of the connected accounts" }, "required": false, "description": "The auth config ids of the connected accounts", "name": "auth_config_ids", "in": "query" }, { "schema": { "type": "array", "nullable": true, "items": { "type": "string", "format": "connectedAccountId" }, "description": "The connected account ids to filter by" }, "required": false, "description": "The connected account ids to filter by", "name": "connected_account_ids", "in": "query" }, { "schema": { "type": "string", "enum": [ "created_at", "updated_at" ], "default": "created_at", "description": "The order by of the connected accounts" }, "required": false, "description": "The order by of the connected accounts", "name": "order_by", "in": "query" }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc", "description": "The order direction of the connected accounts" }, "required": false, "description": "The order direction of the connected accounts", "name": "order_direction", "in": "query" }, { "schema": { "type": "string", "enum": [ "PRIVATE", "SHARED", "ALL" ], "description": "[Experimental] Filter by sharing model. Default (omitted) returns PRIVATE only — shared accounts must be requested explicitly. Pass SHARED for only shared accounts, or ALL for PRIVATE + SHARED.", "x-experimental": true }, "required": false, "description": "[Experimental] Filter by sharing model. Default (omitted) returns PRIVATE only — shared accounts must be requested explicitly. Pass SHARED for only shared accounts, or ALL for PRIVATE + SHARED.", "name": "account_type", "in": "query" } ], "responses": { "200": { "description": "Successfully retrieved connected accounts", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "toolkit": { "type": "object", "properties": { "slug": { "type": "string", "description": "The slug of the toolkit" } }, "required": [ "slug" ] }, "auth_config": { "type": "object", "properties": { "id": { "type": "string", "format": "authConfigId", "description": "The id of the auth config" }, "auth_scheme": { "type": "string", "enum": [ "OAUTH2", "OAUTH1", "API_KEY", "BASIC", "BILLCOM_AUTH", "BEARER_TOKEN", "GOOGLE_SERVICE_ACCOUNT", "NO_AUTH", "BASIC_WITH_JWT", "CALCOM_AUTH", "SERVICE_ACCOUNT", "SAML", "DCR_OAUTH", "S2S_OAUTH2" ], "description": "the authScheme is part of the connection state use it there", "deprecated": true }, "is_composio_managed": { "type": "boolean", "description": "Whether the auth config is managed by Composio" }, "is_disabled": { "type": "boolean", "description": "Whether the auth config is disabled" }, "deprecated": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "The uuid of the auth config" } }, "required": [ "uuid" ], "deprecated": true } }, "required": [ "id", "auth_scheme", "is_composio_managed", "is_disabled" ] }, "id": { "type": "string", "format": "connectedAccountId", "description": "The id of the connection" }, "word_id": { "type": "string", "nullable": true, "description": "A short, token-friendly identifier for multi-account disambiguation, typically toolkit-prefixed with 1-2 words (e.g., \"gmail_red-castle\")" }, "alias": { "type": "string", "nullable": true, "description": "A user-defined alias for the connected account" }, "user_id": { "type": "string", "description": "This is deprecated, we will not be providing userId from this api anymore, you will only be able to read via userId not get it back", "deprecated": true }, "status": { "type": "string", "enum": [ "INITIALIZING", "INITIATED", "ACTIVE", "FAILED", "EXPIRED", "INACTIVE", "REVOKED" ], "description": "The status of the connection" }, "experimental": { "type": "object", "properties": { "account_type": { "type": "string", "enum": [ "PRIVATE", "SHARED" ], "description": "Sharing model for this connected account. PRIVATE is usable only by the owning user_id. SHARED is reachable from a tool-router session only when explicitly pinned in the session config.", "x-experimental": true }, "acl_config_for_shared": { "type": "object", "properties": { "allow_all_users": { "type": "boolean" }, "allowed_user_ids": { "type": "array", "items": { "type": "string" } }, "not_allowed_user_ids": { "type": "array", "items": { "type": "string" } } }, "required": [ "allow_all_users", "allowed_user_ids", "not_allowed_user_ids" ], "description": "Access control for SHARED connections. Visible only to the connection creator and project/org API key callers; non-creator cookie callers receive the response without this block.", "x-experimental": true } }, "required": [ "account_type" ], "description": "Experimental features - not stable, may be modified or removed in future versions.", "x-experimental": true }, "created_at": { "type": "string", "description": "The created at of the connection" }, "updated_at": { "type": "string", "description": "The updated at of the connection" }, "state": { "description": "The state of the connection", "type": "object", "properties": { "authScheme": { "type": "string", "enum": [ "OAUTH1", "OAUTH2", "API_KEY", "BASIC", "BEARER_TOKEN", "GOOGLE_SERVICE_ACCOUNT", "NO_AUTH", "CALCOM_AUTH", "BILLCOM_AUTH", "BASIC_WITH_JWT", "SERVICE_ACCOUNT", "SAML", "DCR_OAUTH", "S2S_OAUTH2" ] }, "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" }, "status": { "type": "string", "enum": [ "INITIALIZING", "INITIATED", "ACTIVE", "FAILED", "EXPIRED", "INACTIVE" ] }, "oauth_token": { "type": "string" }, "authUri": { "type": "string" }, "oauth_token_secret": { "type": "string" }, "redirectUrl": { "type": "string" }, "callbackUrl": { "type": "string" }, "oauth_verifier": { "type": "string" }, "consumer_key": { "type": "string" }, "callback_url": { "type": "string" }, "error": { "type": "string" }, "error_description": { "type": "string" }, "expired_at": { "type": "string" } }, "required": [ "status" ], "additionalProperties": true } }, "required": [ "authScheme", "val" ], "additionalProperties": true }, "data": { "type": "object", "additionalProperties": {}, "description": "This is deprecated, use `state` instead", "deprecated": true }, "status_reason": { "type": "string", "nullable": true, "description": "The reason the connection status changed. Possible reasons: Connection initiation did not complete within 10 minutes, Permanent auth error during token refresh, Max auth failures reached, OAuth callback failed during token exchange, Connection status updated by user, Auth config is disabled, Revoked via user-initiated revoke endpoint, Revoked via admin tool, Revoked as part of connection delete" }, "is_disabled": { "type": "boolean", "description": "Whether the connection is disabled" }, "test_request_endpoint": { "type": "string", "description": "The endpoint to make test request for verification" }, "deprecated": { "type": "object", "properties": { "labels": { "type": "array", "items": { "type": "string" }, "description": "The labels of the connection" }, "uuid": { "type": "string", "format": "uuid", "description": "The uuid of the connection" } }, "required": [ "labels", "uuid" ], "deprecated": true } }, "required": [ "toolkit", "auth_config", "id", "word_id", "alias", "user_id", "status", "created_at", "updated_at", "state", "data", "status_reason", "is_disabled" ] } }, "next_cursor": { "type": "string", "nullable": true }, "total_pages": { "type": "number" }, "current_page": { "type": "number" }, "total_items": { "type": "number" } }, "required": [ "items", "total_pages", "current_page", "total_items" ] } } } }, "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": "Not found", "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" } } } } }, "x-api-version": "3.1" }, "post": { "summary": "Create a new connected account", "description": "Initiates a new connection to an external service for a user. For OAuth-based toolkits, this returns a redirect URL to complete authentication. For API key-based toolkits, provide the credentials directly in the request body. Use the `user_id` field to associate the connection with a specific user in your system.\n\n**Deprecated for Composio-managed OAuth:** For Composio-managed auth configs on OAuth1, OAuth2, or DCR_OAUTH schemes, this endpoint is being retired and will start returning `400 BadRequest` on **2026-05-08** for new organizations and **2026-07-03** for all remaining organizations. Migrate those calls to `POST /api/v3/connected_accounts/link`. Custom auth configs and non-OAuth schemes (API key, bearer, basic) continue to be supported here. Responses on the retiring path carry a `Deprecation` header (RFC 9745) and a `Sunset` header (RFC 8594) for client-side detection.", "tags": [ "Connected Accounts" ], "operationId": "postConnectedAccounts", "security": [ { "ApiKeyAuth": [] }, { "UserApiKeyAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "auth_config": { "type": "object", "properties": { "id": { "type": "string", "format": "authConfigId", "description": "The auth config id of the app (must be a valid auth config id)" } }, "required": [ "id" ] }, "connection": { "type": "object", "properties": { "state": { "description": "The state of the connected account", "type": "object", "properties": { "authScheme": { "type": "string", "enum": [ "OAUTH1", "OAUTH2", "API_KEY", "BASIC", "BEARER_TOKEN", "GOOGLE_SERVICE_ACCOUNT", "NO_AUTH", "CALCOM_AUTH", "BILLCOM_AUTH", "BASIC_WITH_JWT", "SERVICE_ACCOUNT", "SAML", "DCR_OAUTH", "S2S_OAUTH2" ] }, "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" }, "status": { "type": "string", "enum": [ "INITIALIZING", "INITIATED", "ACTIVE", "FAILED", "EXPIRED", "INACTIVE" ] }, "oauth_token": { "type": "string" }, "authUri": { "type": "string" }, "oauth_token_secret": { "type": "string" }, "redirectUrl": { "type": "string" }, "callbackUrl": { "type": "string" }, "oauth_verifier": { "type": "string" }, "consumer_key": { "type": "string" }, "callback_url": { "type": "string" }, "error": { "type": "string" }, "error_description": { "type": "string" }, "expired_at": { "type": "string" } }, "required": [ "status" ], "additionalProperties": true } }, "required": [ "authScheme", "val" ], "additionalProperties": true }, "data": { "type": "object", "additionalProperties": {}, "description": "DEPRECATED: This parameter will be removed in a future version. Please use state instead.", "deprecated": true }, "user_id": { "type": "string", "default": "default", "description": "The user id of the connected account" }, "alias": { "type": "string", "description": "A human-readable alias for this connected account. Must be unique per entity and toolkit within the project." }, "callback_url": { "type": "string", "format": "uri", "description": "The URL to redirect to after connection completion" }, "redirect_uri": { "type": "string", "format": "uri", "description": "DEPRECATED: This parameter will be removed in a future version. Please use callback_url instead.", "deprecated": true }, "deprecated_is_v1_rerouted": { "type": "boolean", "default": false, "description": "DEPRECATED: This parameter will be removed in a future version.", "deprecated": true }, "experimental": { "type": "object", "properties": { "account_type": { "type": "string", "enum": [ "PRIVATE", "SHARED" ], "description": "Sharing model for this connected account. PRIVATE (default) is usable only by the owning user_id. SHARED is reachable from a tool-router session ONLY when explicitly pinned in the session config — at most one SHARED connection per toolkit per session. Sessions never use a SHARED connection implicitly.", "x-experimental": true }, "acl_config_for_shared": { "type": "object", "properties": { "allow_all_users": { "type": "boolean", "description": "Wildcard \"any user_id in the project\" allow toggle. Only valid on SHARED connections." }, "allowed_user_ids": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 256 }, "maxItems": 1000, "description": "Explicit allow list of user_ids who can use this SHARED connection." }, "not_allowed_user_ids": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 256 }, "maxItems": 1000, "description": "Explicit deny list. Wins on conflict with allow_all_users and allowed_user_ids." } }, "description": "Access control for SHARED connections. Resolution rule (only fires when caller != creator): user in not_allowed_user_ids → DENY; allow_all_users=true → ALLOW; user in allowed_user_ids → ALLOW; else DENY. Default state (omitted or {}) is deny-by-default — only the creator can use.", "x-experimental": true } }, "description": "Experimental features - not stable, may be modified or removed in future versions.", "x-experimental": true } } }, "validate_credentials": { "type": "boolean", "default": false, "description": "[EXPERIMENTAL] Whether to validate the provided credentials, validates only for API Key Auth scheme", "x-experimental": true } }, "required": [ "auth_config", "connection" ] } } } }, "responses": { "201": { "description": "Successfully created connected account", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "connectedAccountId", "description": "The id of the connected account" }, "connectionData": { "description": "The connection data of the connected account", "type": "object", "properties": { "authScheme": { "type": "string", "enum": [ "OAUTH1", "OAUTH2", "API_KEY", "BASIC", "BEARER_TOKEN", "GOOGLE_SERVICE_ACCOUNT", "NO_AUTH", "CALCOM_AUTH", "BILLCOM_AUTH", "BASIC_WITH_JWT", "SERVICE_ACCOUNT", "SAML", "DCR_OAUTH", "S2S_OAUTH2" ] }, "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" }, "status": { "type": "string", "enum": [ "INITIALIZING", "INITIATED", "ACTIVE", "FAILED", "EXPIRED", "INACTIVE" ] }, "oauth_token": { "type": "string" }, "authUri": { "type": "string" }, "oauth_token_secret": { "type": "string" }, "redirectUrl": { "type": "string" }, "callbackUrl": { "type": "string" }, "oauth_verifier": { "type": "string" }, "consumer_key": { "type": "string" }, "callback_url": { "type": "string" }, "error": { "type": "string" }, "error_description": { "type": "string" }, "expired_at": { "type": "string" } }, "required": [ "status" ], "additionalProperties": true } }, "required": [ "authScheme", "val" ], "additionalProperties": true }, "status": { "type": "string", "enum": [ "INITIALIZING", "INITIATED", "ACTIVE", "FAILED", "EXPIRED", "INACTIVE", "REVOKED" ], "description": "DEPRECATED: This field will be removed in a future version", "deprecated": true }, "redirect_url": { "type": "string", "nullable": true, "description": "DEPRECATED: This field will be removed in a future version", "deprecated": true }, "redirect_uri": { "type": "string", "nullable": true, "description": "DEPRECATED: This field will be removed in a future version", "deprecated": true }, "deprecated": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "The uuid of the connected account" }, "authConfigUuid": { "type": "string", "format": "uuid", "description": "The uuid of the auth config" } }, "required": [ "uuid", "authConfigUuid" ], "description": "DEPRECATED: This field will be removed in a future version. Please use id and auth_config.id instead.", "deprecated": true }, "experimental": { "type": "object", "properties": { "account_type": { "type": "string", "enum": [ "PRIVATE", "SHARED" ], "description": "Sharing model for this connected account. PRIVATE is usable only by the owning user_id. SHARED is reachable from a tool-router session only when explicitly pinned in the session config.", "x-experimental": true }, "acl_config_for_shared": { "type": "object", "properties": { "allow_all_users": { "type": "boolean" }, "allowed_user_ids": { "type": "array", "items": { "type": "string" } }, "not_allowed_user_ids": { "type": "array", "items": { "type": "string" } } }, "required": [ "allow_all_users", "allowed_user_ids", "not_allowed_user_ids" ], "description": "Access control for SHARED connections. Visible only to the connection creator and project/org API key callers; non-creator cookie callers receive the response without this block.", "x-experimental": true } }, "required": [ "account_type" ], "description": "Experimental features - not stable, may be modified or removed in future versions.", "x-experimental": true } }, "required": [ "id", "connectionData", "status", "redirect_url", "redirect_uri", "deprecated" ] } } } }, "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": "Not found", "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" } } } } }, "x-api-version": "3.1" } }, "/api/v3.1/connected_accounts/{nanoid}": { "get": { "summary": "Get connected account details by ID", "description": "Retrieves comprehensive details of a connected account, including authentication configuration, connection status, and all parameters needed for API requests.", "tags": [ "Connected Accounts" ], "operationId": "getConnectedAccountsByNanoid", "security": [ { "ApiKeyAuth": [] }, { "UserApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "format": "connectedAccountId" }, "required": true, "description": "The unique identifier (nanoid) of the connected account", "example": "ca_1a2b3c4d5e6f", "name": "nanoid", "in": "path" } ], "responses": { "200": { "description": "Successfully retrieved connected account details with all authentication parameters and connection status", "content": { "application/json": { "schema": { "type": "object", "properties": { "toolkit": { "type": "object", "properties": { "slug": { "type": "string", "description": "The slug of the toolkit" } }, "required": [ "slug" ] }, "auth_config": { "type": "object", "properties": { "id": { "type": "string", "format": "authConfigId", "description": "The id of the auth config" }, "auth_scheme": { "type": "string", "enum": [ "OAUTH2", "OAUTH1", "API_KEY", "BASIC", "BILLCOM_AUTH", "BEARER_TOKEN", "GOOGLE_SERVICE_ACCOUNT", "NO_AUTH", "BASIC_WITH_JWT", "CALCOM_AUTH", "SERVICE_ACCOUNT", "SAML", "DCR_OAUTH", "S2S_OAUTH2" ], "description": "the authScheme is part of the connection state use it there", "deprecated": true }, "is_composio_managed": { "type": "boolean", "description": "Whether the auth config is managed by Composio" }, "is_disabled": { "type": "boolean", "description": "Whether the auth config is disabled" }, "deprecated": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "The uuid of the auth config" } }, "required": [ "uuid" ], "deprecated": true } }, "required": [ "id", "auth_scheme", "is_composio_managed", "is_disabled" ] }, "id": { "type": "string", "format": "connectedAccountId", "description": "The id of the connection" }, "word_id": { "type": "string", "nullable": true, "description": "A short, token-friendly identifier for multi-account disambiguation, typically toolkit-prefixed with 1-2 words (e.g., \"gmail_red-castle\")" }, "alias": { "type": "string", "nullable": true, "description": "A user-defined alias for the connected account" }, "user_id": { "type": "string", "description": "This is deprecated, we will not be providing userId from this api anymore, you will only be able to read via userId not get it back", "deprecated": true }, "status": { "type": "string", "enum": [ "INITIALIZING", "INITIATED", "ACTIVE", "FAILED", "EXPIRED", "INACTIVE", "REVOKED" ], "description": "The status of the connection" }, "experimental": { "type": "object", "properties": { "account_type": { "type": "string", "enum": [ "PRIVATE", "SHARED" ], "description": "Sharing model for this connected account. PRIVATE is usable only by the owning user_id. SHARED is reachable from a tool-router session only when explicitly pinned in the session config.", "x-experimental": true }, "acl_config_for_shared": { "type": "object", "properties": { "allow_all_users": { "type": "boolean" }, "allowed_user_ids": { "type": "array", "items": { "type": "string" } }, "not_allowed_user_ids": { "type": "array", "items": { "type": "string" } } }, "required": [ "allow_all_users", "allowed_user_ids", "not_allowed_user_ids" ], "description": "Access control for SHARED connections. Visible only to the connection creator and project/org API key callers; non-creator cookie callers receive the response without this block.", "x-experimental": true } }, "required": [ "account_type" ], "description": "Experimental features - not stable, may be modified or removed in future versions.", "x-experimental": true }, "created_at": { "type": "string", "description": "The created at of the connection" }, "updated_at": { "type": "string", "description": "The updated at of the connection" }, "state": { "description": "The state of the connection", "type": "object", "properties": { "authScheme": { "type": "string", "enum": [ "OAUTH1", "OAUTH2", "API_KEY", "BASIC", "BEARER_TOKEN", "GOOGLE_SERVICE_ACCOUNT", "NO_AUTH", "CALCOM_AUTH", "BILLCOM_AUTH", "BASIC_WITH_JWT", "SERVICE_ACCOUNT", "SAML", "DCR_OAUTH", "S2S_OAUTH2" ] }, "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" }, "status": { "type": "string", "enum": [ "INITIALIZING", "INITIATED", "ACTIVE", "FAILED", "EXPIRED", "INACTIVE" ] }, "oauth_token": { "type": "string" }, "authUri": { "type": "string" }, "oauth_token_secret": { "type": "string" }, "redirectUrl": { "type": "string" }, "callbackUrl": { "type": "string" }, "oauth_verifier": { "type": "string" }, "consumer_key": { "type": "string" }, "callback_url": { "type": "string" }, "error": { "type": "string" }, "error_description": { "type": "string" }, "expired_at": { "type": "string" } }, "required": [ "status" ], "additionalProperties": true } }, "required": [ "authScheme", "val" ], "additionalProperties": true }, "data": { "type": "object", "additionalProperties": {}, "description": "This is deprecated, use `state` instead", "deprecated": true }, "status_reason": { "type": "string", "nullable": true, "description": "The reason the connection status changed. Possible reasons: Connection initiation did not complete within 10 minutes, Permanent auth error during token refresh, Max auth failures reached, OAuth callback failed during token exchange, Connection status updated by user, Auth config is disabled, Revoked via user-initiated revoke endpoint, Revoked via admin tool, Revoked as part of connection delete" }, "is_disabled": { "type": "boolean", "description": "Whether the connection is disabled" }, "test_request_endpoint": { "type": "string", "description": "The endpoint to make test request for verification" }, "deprecated": { "type": "object", "properties": { "labels": { "type": "array", "items": { "type": "string" }, "description": "The labels of the connection" }, "uuid": { "type": "string", "format": "uuid", "description": "The uuid of the connection" } }, "required": [ "labels", "uuid" ], "deprecated": true }, "params": { "type": "object", "additionalProperties": {}, "description": "The initialization data of the connection, including configuration parameters", "deprecated": true } }, "required": [ "toolkit", "auth_config", "id", "word_id", "alias", "user_id", "status", "created_at", "updated_at", "state", "data", "status_reason", "is_disabled", "params" ] } } } }, "400": { "description": "Bad request - Invalid nanoid format or other validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized - Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden - Insufficient permissions to access this connected account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found - Connected account does not exist or was deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error - Failed to retrieve connected account details", "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" } } } } }, "x-api-version": "3.1" }, "delete": { "summary": "Delete a connected account", "description": "Soft-deletes a connected account by marking it as deleted in the database. This prevents the account from being used for API calls but preserves the record for audit purposes.", "tags": [ "Connected Accounts" ], "operationId": "deleteConnectedAccountsByNanoid", "security": [ { "ApiKeyAuth": [] }, { "UserApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "format": "connectedAccountId" }, "required": true, "description": "The unique identifier (nanoid) of the connected account", "example": "ca_1a2b3c4d5e6f", "name": "nanoid", "in": "path" } ], "responses": { "200": { "description": "Successfully deleted the connected account. The account is marked as deleted but retained in the database for historical purposes.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Indicates whether the connected account was successfully deleted" } }, "required": [ "success" ], "description": "Response returned after successfully deleting a connected account", "example": { "success": true } } } } }, "400": { "description": "Bad request - Invalid nanoid format or other validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized - Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden - Insufficient permissions to delete this connected account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Connected account not found - The specified account does not exist or has already been deleted", "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "500": { "description": "Internal server error - Failed to delete the connected account due to a server-side issue", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-api-version": "3.1" }, "patch": { "summary": "Update a connected account", "description": "Update a connected account. Supports updating the alias and/or credentials. Only specified fields will be updated. Set a credential field to null to remove it. Alias must be unique within the same project, entity, and toolkit scope.", "tags": [ "Connected Accounts" ], "operationId": "patchConnectedAccountsByNanoid", "security": [ { "ApiKeyAuth": [] }, { "UserApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "format": "connectedAccountId" }, "required": true, "description": "The unique identifier (nanoid) of the connected account", "example": "ca_1a2b3c4d5e6f", "name": "nanoid", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchConnectedAccountBody" }, "examples": { "credentials": { "summary": "Update credentials", "value": { "connection": { "state": { "authScheme": "BEARER_TOKEN", "val": { "token": "new_access_token" } } } } }, "alias": { "summary": "Update alias", "value": { "alias": "work-gmail" } } } } } }, "responses": { "200": { "description": "Successfully updated connected account", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the update was successful" }, "id": { "type": "string", "format": "connectedAccountId", "description": "The unique identifier of the updated connected account" }, "status": { "type": "string", "description": "The current status of the connected account after the update (ACTIVE, EXPIRED, INACTIVE, etc.)" } }, "required": [ "success", "id", "status" ], "example": { "success": true, "id": "ca_1a2b3c4d5e6f", "status": "ACTIVE" } } } } }, "400": { "description": "Bad request - Invalid nanoid, duplicate alias, or invalid credential values", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized - Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden - Insufficient permissions to update this connected account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found - Connected account does not exist or was deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error - Failed to update connected account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-api-version": "3.1" } }, "/api/v3.1/connected_accounts/{nanoId}/status": { "patch": { "summary": "Enable or disable a connected account", "description": "Updates the status of a connected account to either enabled (active) or disabled (inactive). Disabled accounts cannot be used for API calls but remain in the database.", "tags": [ "Connected Accounts" ], "operationId": "patchConnectedAccountsByNanoIdStatus", "security": [ { "ApiKeyAuth": [] }, { "UserApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "format": "connectedAccountId" }, "required": true, "description": "The unique identifier of the connected account", "example": "ca_1a2b3c4d5e6f", "name": "nanoId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Set to true to enable the account or false to disable it" } }, "required": [ "enabled" ], "example": { "enabled": true } } } } }, "responses": { "200": { "description": "Successfully updated the connected account status. If enabled=true, the account status is set to ACTIVE; if enabled=false, the status is set to INACTIVE.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Indicates whether the connected account status was successfully updated" } }, "required": [ "success" ], "description": "Response returned after successfully updating a connected account status", "example": { "success": true } } } } }, "400": { "description": "Bad request - Invalid nanoid format or invalid request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized - Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden - Insufficient permissions to update this connected account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Connected account not found - The specified account does not exist or has been deleted", "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "500": { "description": "Internal server error - Failed to update the connected account status due to a server-side issue", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-api-version": "3.1" } }, "/api/v3.1/connected_accounts/{nanoid}/refresh": { "post": { "summary": "Refresh authentication for a connected account", "description": "Initiates a new authentication flow for a connected account when credentials have expired or become invalid. This may generate a new authentication URL for OAuth flows or refresh tokens for other auth schemes.", "tags": [ "Connected Accounts" ], "operationId": "postConnectedAccountsByNanoidRefresh", "security": [ { "ApiKeyAuth": [] }, { "UserApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "format": "connectedAccountId" }, "required": true, "description": "The unique identifier of the connected account", "example": "ca_1a2b3c4d5e6f", "name": "nanoid", "in": "path" }, { "schema": { "type": "string", "format": "uri" }, "required": false, "name": "redirect_url", "in": "query" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "redirect_url": { "type": "string", "format": "uri" }, "validate_credentials": { "type": "boolean", "default": false, "description": "[EXPERIMENTAL] Whether to validate the provided credentials, validates only for API Key Auth scheme", "x-experimental": true } } } } } }, "responses": { "200": { "description": "Successfully refreshed the connected account authentication. For OAuth flows, a new redirect URL is provided.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier of the connected account" }, "status": { "type": "string", "enum": [ "INITIALIZING", "INITIATED", "ACTIVE", "FAILED", "EXPIRED", "INACTIVE", "REVOKED" ], "description": "The current status of the connected account (e.g., active, pending, failed)" }, "redirect_url": { "type": "string", "nullable": true, "description": "The URL to which the user should be redirected to complete the authentication process (null for auth schemes that do not require redirection)" } }, "required": [ "id", "status", "redirect_url" ], "description": "Response schema for a refreshed connected account authentication", "example": { "id": "ca_1a2b3c4d5e6f", "status": "ACTIVE", "redirect_url": "https://app.example.com/oauth/callback" } } } } }, "400": { "description": "Bad request - Invalid nanoid format or the account cannot be refreshed in its current state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized - Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden - Insufficient permissions to refresh this connected account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found - Connected account does not exist or was deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict - The connection cannot be refreshed because of a permanent attribute (e.g. its auth scheme does not support refresh, such as API_KEY or BEARER_TOKEN)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Unprocessable entity - The connection is in an invalid state for refresh (e.g. connection-data validation failed, or the stored connection status is incompatible with reinitiation)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error - Failed to refresh the connected account authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-api-version": "3.1" } }, "/api/v3.1/connected_accounts/link": { "post": { "summary": "Create a new auth link session", "description": "Creates a new authentication link session that users can use to connect their accounts", "tags": [ "Connected Accounts" ], "operationId": "postConnectedAccountsLink", "security": [ { "ApiKeyAuth": [] }, { "UserApiKeyAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "auth_config_id": { "type": "string", "format": "authConfigId", "description": "The auth config id to create a link for" }, "user_id": { "type": "string", "minLength": 1, "description": "The user id to create a link for" }, "alias": { "type": "string", "description": "A human-readable alias for this connected account. Must be unique per entity and toolkit within the project." }, "callback_url": { "type": "string", "description": "The callback url to create a link for" }, "connection_data": { "description": "Optional data to pre-fill connection fields with default values", "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" }, "oauth_token": { "type": "string" }, "authUri": { "type": "string" }, "oauth_token_secret": { "type": "string" }, "redirectUrl": { "type": "string" }, "callbackUrl": { "type": "string" }, "oauth_verifier": { "type": "string" }, "consumer_key": { "type": "string" }, "callback_url": { "type": "string" }, "error": { "type": "string" }, "error_description": { "type": "string" }, "expired_at": { "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" }, "code_verifier": { "type": "string" }, "finalRedirectUri": { "type": "string" }, "webhook_signature": { "type": "string" }, "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" } ] }, "authed_user": { "type": "object", "properties": { "access_token": { "type": "string" }, "scope": { "type": "string" } }, "description": "for slack user scopes" }, "extra_token_data": { "type": "object", "additionalProperties": {} }, "revoked_at": { "type": "string" }, "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" }, "composio_link_redirect_url": { "type": "string" }, "credentials_json": { "type": "string" }, "sessionId": { "type": "string" }, "devKey": { "type": "string" }, "application_id": { "type": "string" }, "installation_id": { "type": "string" }, "private_key": { "type": "string" }, "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" }, "expires_at": { "type": "string" } }, "additionalProperties": true }, "experimental": { "type": "object", "properties": { "account_type": { "type": "string", "enum": [ "PRIVATE", "SHARED" ], "description": "Sharing model for this connected account. PRIVATE (default) is usable only by the owning user_id. SHARED is reachable from a tool-router session ONLY when explicitly pinned in the session config — at most one SHARED connection per toolkit per session. Sessions never use a SHARED connection implicitly.", "x-experimental": true }, "acl_config_for_shared": { "type": "object", "properties": { "allow_all_users": { "type": "boolean", "description": "Wildcard \"any user_id in the project\" allow toggle. Only valid on SHARED connections." }, "allowed_user_ids": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 256 }, "maxItems": 1000, "description": "Explicit allow list of user_ids who can use this SHARED connection." }, "not_allowed_user_ids": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 256 }, "maxItems": 1000, "description": "Explicit deny list. Wins on conflict with allow_all_users and allowed_user_ids." } }, "description": "Access control for SHARED connections. Resolution rule (only fires when caller != creator): user in not_allowed_user_ids → DENY; allow_all_users=true → ALLOW; user in allowed_user_ids → ALLOW; else DENY. Default state (omitted or {}) is deny-by-default — only the creator can use.", "x-experimental": true } }, "description": "Experimental features - not stable, may be modified or removed in future versions.", "x-experimental": true } }, "required": [ "auth_config_id", "user_id" ] } } } }, "responses": { "201": { "description": "Successfully created auth link", "content": { "application/json": { "schema": { "type": "object", "properties": { "link_token": { "type": "string", "description": "The generated link token for the auth session" }, "redirect_url": { "type": "string", "description": "The redirect URI to send users to for authentication" }, "expires_at": { "type": "string", "description": "ISO timestamp when the link expires" }, "connected_account_id": { "type": "string", "format": "connectedAccountId", "description": "The connected account ID that was created" }, "experimental": { "type": "object", "properties": { "account_type": { "type": "string", "enum": [ "PRIVATE", "SHARED" ], "description": "Sharing model for this connected account. PRIVATE is usable only by the owning user_id. SHARED is reachable from a tool-router session only when explicitly pinned in the session config.", "x-experimental": true }, "acl_config_for_shared": { "type": "object", "properties": { "allow_all_users": { "type": "boolean" }, "allowed_user_ids": { "type": "array", "items": { "type": "string" } }, "not_allowed_user_ids": { "type": "array", "items": { "type": "string" } } }, "required": [ "allow_all_users", "allowed_user_ids", "not_allowed_user_ids" ], "description": "Access control for SHARED connections. Visible only to the connection creator and project/org API key callers; non-creator cookie callers receive the response without this block.", "x-experimental": true } }, "required": [ "account_type" ], "description": "Experimental features - not stable, may be modified or removed in future versions.", "x-experimental": true } }, "required": [ "link_token", "redirect_url", "expires_at", "connected_account_id" ] } } } }, "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": "Auth config not found", "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" } } } } }, "x-api-version": "3.1" } }, "/api/v3.1/org/project/config": { "get": { "summary": "Get project configuration", "description": "Retrieves the current project configuration including 2FA settings.", "tags": [ "Projects" ], "operationId": "getOrgProjectConfig", "security": [ { "ApiKeyAuth": [] }, { "UserApiKeyAuth": [] } ], "responses": { "200": { "description": "Project configuration retrieved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "is_2FA_enabled": { "type": "boolean" }, "logo_url": { "type": "string" }, "display_name": { "type": "string" }, "mask_secret_keys_in_connected_account": { "type": "boolean" }, "log_visibility_setting": { "type": "string", "enum": [ "show_all", "dont_store_data" ] }, "require_mcp_api_key": { "type": "boolean" }, "is_composio_link_enabled_for_managed_auth": { "type": "boolean", "description": "Whether to enable composio link for managed authentication. This key will be deprecated in the future. Please don't use this key." }, "signed_url_file_expiry_in_seconds": { "type": "number", "minimum": 1, "maximum": 86400 } }, "required": [ "is_2FA_enabled", "mask_secret_keys_in_connected_account", "log_visibility_setting" ] } } } }, "400": { "description": "Bad request. The project configuration data may be invalid.", "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" } } } }, "404": { "description": "Project not found. The specified project does not exist or has been deleted.", "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" } } } } }, "x-api-version": "3.1" }, "patch": { "summary": "Update project configuration", "description": "Updates the project configuration settings.", "tags": [ "Projects" ], "operationId": "patchOrgProjectConfig", "security": [ { "ApiKeyAuth": [] }, { "UserApiKeyAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "is_2FA_enabled": { "type": "boolean" }, "logo_url": { "type": "string" }, "display_name": { "type": "string" }, "mask_secret_keys_in_connected_account": { "type": "boolean" }, "log_visibility_setting": { "type": "string", "enum": [ "show_all", "dont_store_data" ] }, "require_mcp_api_key": { "type": "boolean" }, "is_composio_link_enabled_for_managed_auth": { "type": "boolean", "description": "Whether to enable composio link for managed authentication. This key will be deprecated in the future. Please don't use this key." }, "signed_url_file_expiry_in_seconds": { "type": "number", "minimum": 1, "maximum": 86400 } } }, "examples": { "Enable 2FA": { "value": { "is_2FA_enabled": true } }, "Disable 2FA": { "value": { "is_2FA_enabled": false } } } } } }, "responses": { "200": { "description": "Project configuration updated successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "is_2FA_enabled": { "type": "boolean" }, "logo_url": { "type": "string" }, "display_name": { "type": "string" }, "mask_secret_keys_in_connected_account": { "type": "boolean" }, "log_visibility_setting": { "type": "string", "enum": [ "show_all", "dont_store_data" ] }, "require_mcp_api_key": { "type": "boolean" }, "is_composio_link_enabled_for_managed_auth": { "type": "boolean", "description": "Whether to enable composio link for managed authentication. This key will be deprecated in the future. Please don't use this key." }, "signed_url_file_expiry_in_seconds": { "type": "number", "minimum": 1, "maximum": 86400 } }, "required": [ "is_2FA_enabled", "mask_secret_keys_in_connected_account", "log_visibility_setting" ] } } } }, "400": { "description": "Bad request. The configuration data may be invalid or missing.", "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" } } } }, "404": { "description": "Project not found. The specified project does not exist or has been deleted.", "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" } } } } }, "x-api-version": "3.1" } }, "/api/v3.1/org/owner/project/new": { "post": { "summary": "Create a new project", "description": "Creates a new project within the authenticated user's organization using the specified name. Projects are isolated environments within your organization, each with their own API keys, webhook configurations, and resources. Use this endpoint to create additional projects for different environments (e.g., development, staging, production) or for separate applications.", "tags": [ "Projects" ], "operationId": "postOrgOwnerProjectNew", "security": [ { "OrgApiKeyAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 3, "maxLength": 75, "pattern": "^[a-zA-Z0-9_-]+$", "description": "A unique name for your project that follows the required format rules", "example": "my-awesome-project" }, "should_create_api_key": { "type": "boolean", "default": false, "description": "Whether to create an API key for the project. If true, the API key will be created and returned in the response.", "example": false }, "config": { "type": "object", "properties": { "is_2FA_enabled": { "type": "boolean" }, "logo_url": { "type": "string" }, "display_name": { "type": "string" }, "mask_secret_keys_in_connected_account": { "type": "boolean" }, "log_visibility_setting": { "type": "string", "enum": [ "show_all", "dont_store_data" ] }, "require_mcp_api_key": { "type": "boolean" }, "is_composio_link_enabled_for_managed_auth": { "type": "boolean", "description": "Whether to enable composio link for managed authentication. This key will be deprecated in the future. Please don't use this key." }, "signed_url_file_expiry_in_seconds": { "type": "number", "minimum": 1, "maximum": 86400 } }, "required": [ "is_2FA_enabled", "mask_secret_keys_in_connected_account", "log_visibility_setting" ], "description": "Configuration for the project" } }, "required": [ "name" ] }, "examples": { "Simple project": { "value": { "name": "my_production_api" } } } } } }, "responses": { "200": { "description": "Project successfully created. Returns the complete project object with generated IDs, webhook secrets, and configuration.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "projectId", "description": "Unique identifier for the project", "example": "pr_1a2b3c4d5e6f" }, "name": { "type": "string", "description": "Name of the project", "example": "My Awesome Project" }, "api_key": { "type": "string", "nullable": true, "description": "API key for the project", "example": "ak_a1b2c3d4e5f6g7h8i9j0" } }, "required": [ "id", "api_key" ] } } } }, "400": { "description": "Bad request. This may occur if the project name format is invalid, too short, or contains invalid characters.", "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" } } } }, "500": { "description": "Internal server error. An unexpected error occurred while processing the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-api-version": "3.1" } }, "/api/v3.1/org/owner/project/list": { "get": { "summary": "List all projects", "description": "Retrieves all projects belonging to the authenticated organization. Projects are returned in descending order of creation date (newest first). This endpoint is useful for displaying project selection in dashboards or for integrations that need to list all available projects.", "tags": [ "Projects" ], "operationId": "getOrgOwnerProjectList", "security": [ { "OrgApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "number", "nullable": true }, "required": false, "description": "Number of items per page, max allowed is 1000", "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" } ], "responses": { "200": { "description": "Projects retrieved successfully with pagination. Returns an array of projects with pagination info.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "projectId", "description": "Unique identifier for the project", "example": "pr_1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "orgId", "description": "Identifier of the organization that owns this project", "example": "ok_1a2b3c4d5e6f" }, "name": { "type": "string", "description": "Name of the project", "example": "My Awesome Project" }, "email": { "type": "string", "description": "Email address associated with the project", "example": "project-123@composio.dev" }, "created_at": { "type": "string", "description": "ISO timestamp when the project was created", "example": "2023-05-16T14:30:00.000Z" }, "updated_at": { "type": "string", "description": "ISO timestamp when the project was last updated", "example": "2023-05-18T09:15:30.000Z" }, "webhook_url": { "type": "string", "nullable": true, "format": "uri", "description": "DEPRECATED: Use GET /api/v3/webhook_subscriptions instead. Legacy project-level webhook URL.", "example": "https://example.com/webhook", "deprecated": true }, "event_webhook_url": { "type": "string", "nullable": true, "format": "uri", "description": "DEPRECATED: No longer used.", "example": "https://example.com/events", "deprecated": true }, "webhook_secret": { "type": "string", "nullable": true, "description": "DEPRECATED: Use GET /api/v3/webhook_subscriptions instead. Legacy project-level webhook secret.", "example": "whsec_abcdef123456789", "deprecated": true }, "triggers_enabled": { "type": "boolean", "description": "Whether triggers are enabled for this project", "example": true }, "last_subscribed_at": { "type": "string", "nullable": true, "format": "date-time", "description": "ISO timestamp when the project last subscribed to updates", "example": "2023-05-17T10:00:00.000Z" }, "is_new_webhook": { "type": "boolean", "description": "Deprecated: Please refer to webhook_version instead. True indicates if the webhook configuration is using the previous new format (V2). False indicates the oldest format (V1)", "example": true, "deprecated": true }, "webhook_version": { "type": "string", "enum": [ "V1", "V2", "V3" ], "description": "Payload format version for Pusher real-time events only. For webhook configuration, use GET /api/v3/webhook_subscriptions.", "example": "V2" }, "deleted": { "type": "boolean", "description": "Whether this project has been soft-deleted", "example": false } }, "required": [ "id", "org_id", "name", "email", "created_at", "updated_at", "webhook_url", "event_webhook_url", "webhook_secret", "webhook_version", "deleted" ] } }, "next_cursor": { "type": "string", "nullable": true }, "total_pages": { "type": "number" }, "current_page": { "type": "number" }, "total_items": { "type": "number" } }, "required": [ "data", "total_pages", "current_page", "total_items" ] } } } }, "400": { "description": "Bad request. This may occur if there are invalid query parameters or the request is 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" } } } }, "500": { "description": "Internal server error. An unexpected error occurred while processing the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-api-version": "3.1" } }, "/api/v3.1/org/owner/project/{nano_id}": { "get": { "summary": "Get project details by ID With Org Api key", "description": "Retrieves detailed information about a specific project using its unique identifier. This endpoint provides complete project configuration including webhook URLs, creation and update timestamps, and webhook secrets. Use this endpoint to inspect project settings or verify project configuration.", "tags": [ "Projects" ], "operationId": "getOrgOwnerProjectByNanoId", "security": [ { "OrgApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "format": "projectId", "description": "Unique identifier (Nano ID) of the project to retrieve", "example": "pr_1a2b3c4d5e6f" }, "required": true, "description": "Unique identifier (Nano ID) of the project to retrieve", "name": "nano_id", "in": "path" } ], "responses": { "200": { "description": "Project retrieved successfully. Returns a complete project object with all configuration details and associated API keys.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "projectId", "description": "Unique identifier for the project", "example": "pr_1a2b3c4d5e6f" }, "org_id": { "type": "string", "format": "orgId", "description": "Identifier of the organization that owns this project", "example": "ok_1a2b3c4d5e6f" }, "name": { "type": "string", "description": "Name of the project", "example": "My Awesome Project" }, "email": { "type": "string", "description": "Email address associated with the project", "example": "project-123@composio.dev" }, "created_at": { "type": "string", "description": "ISO timestamp when the project was created", "example": "2023-05-16T14:30:00.000Z" }, "updated_at": { "type": "string", "description": "ISO timestamp when the project was last updated", "example": "2023-05-18T09:15:30.000Z" }, "webhook_url": { "type": "string", "nullable": true, "format": "uri", "description": "DEPRECATED: Use GET /api/v3/webhook_subscriptions instead. Legacy project-level webhook URL.", "example": "https://example.com/webhook", "deprecated": true }, "event_webhook_url": { "type": "string", "nullable": true, "format": "uri", "description": "DEPRECATED: No longer used.", "example": "https://example.com/events", "deprecated": true }, "webhook_secret": { "type": "string", "nullable": true, "description": "DEPRECATED: Use GET /api/v3/webhook_subscriptions instead. Legacy project-level webhook secret.", "example": "whsec_abcdef123456789", "deprecated": true }, "triggers_enabled": { "type": "boolean", "description": "Whether triggers are enabled for this project", "example": true }, "last_subscribed_at": { "type": "string", "nullable": true, "format": "date-time", "description": "ISO timestamp when the project last subscribed to updates", "example": "2023-05-17T10:00:00.000Z" }, "is_new_webhook": { "type": "boolean", "description": "Deprecated: Please refer to webhook_version instead. True indicates if the webhook configuration is using the previous new format (V2). False indicates the oldest format (V1)", "example": true, "deprecated": true }, "webhook_version": { "type": "string", "enum": [ "V1", "V2", "V3" ], "description": "Payload format version for Pusher real-time events only. For webhook configuration, use GET /api/v3/webhook_subscriptions.", "example": "V2" }, "deleted": { "type": "boolean", "description": "Whether this project has been soft-deleted", "example": false }, "api_keys": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the API key", "example": "01H4DKRF5SMP7NQCA3BWT0JYB6" }, "name": { "type": "string", "description": "User-defined name for the API key", "example": "Production Server Key" }, "key": { "type": "string", "description": "The actual API key value used for authentication", "example": "ak_a1b2c3d4e5f6g7h8i9j0" }, "created_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the API key was created", "example": "2023-07-15T14:30:00.000Z" } }, "required": [ "id", "name", "key", "created_at" ] }, "description": "Array of API keys for the project, including their properties" } }, "required": [ "id", "org_id", "name", "email", "created_at", "updated_at", "webhook_url", "event_webhook_url", "webhook_secret", "webhook_version", "deleted", "api_keys" ] } } } }, "400": { "description": "Bad request. This may occur if the project ID format is invalid.", "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" } } } }, "404": { "description": "Not found. The specified project does not exist or you do not have access to it.", "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" } } } } }, "x-api-version": "3.1" }, "delete": { "summary": "Delete a project", "description": "Soft-deletes a project within the organization by its unique identifier. When a project is deleted, it is marked as deleted but not immediately removed from the database. This operation affects all resources associated with the project including API keys, webhook configurations, and connected services. This action cannot be undone through the API.", "tags": [ "Projects" ], "operationId": "deleteOrgOwnerProjectByNanoId", "security": [ { "OrgApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "format": "projectId", "description": "Unique identifier (Nano ID) of the project to delete", "example": "pr_1a2b3c4d5e6f" }, "required": true, "description": "Unique identifier (Nano ID) of the project to delete", "name": "nano_id", "in": "path" } ], "responses": { "200": { "description": "Project successfully deleted. The project has been marked as deleted in the system.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ], "description": "Status indicating successful deletion", "example": "success" } }, "required": [ "status" ], "description": "Response indicating successful project deletion" } } } }, "400": { "description": "Bad request. The project ID may be invalid or in an incorrect format.", "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. You do not have permission to delete this project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. The specified project does not exist or has already been deleted.", "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" } } } } }, "x-api-version": "3.1" } }, "/api/v3.1/org/owner/project/{nano_id}/regenerate_api_key": { "post": { "summary": "Delete and generate new API key for project", "description": "Generates a new API key for the specified project, invalidating any existing API keys for that project. This operation creates a fresh API key with a new random name and key value. All existing API keys for this project will be marked as deleted.", "tags": [ "Projects" ], "operationId": "postOrgOwnerProjectByNanoIdRegenerateApiKey", "security": [ { "OrgApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "format": "projectId", "description": "Unique identifier (Nano ID) of the project to regenerate API key for", "example": "pr_1a2b3c4d5e6f" }, "required": true, "description": "Unique identifier (Nano ID) of the project to regenerate API key for", "name": "nano_id", "in": "path" } ], "responses": { "200": { "description": "API key regenerated successfully. Returns the new API key details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "api_key": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the API key", "example": "01H4DKRF5SMP7NQCA3BWT0JYB6" }, "name": { "type": "string", "description": "Name of the API key", "example": "epic_avatar" }, "key": { "type": "string", "description": "The newly generated API key value", "example": "ak_a1b2c3d4e5f6g7h8i9j0" }, "created_at": { "type": "string", "description": "ISO timestamp when the API key was created", "example": "2023-05-16T14:30:00.000Z" } }, "required": [ "id", "name", "key", "created_at" ], "description": "The newly generated API key for this project" }, "message": { "type": "string", "description": "Success message", "example": "API key regenerated successfully" } }, "required": [ "api_key", "message" ] } } } }, "400": { "description": "Bad request. The project ID may be invalid or in an incorrect format.", "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" } } } }, "404": { "description": "Not found. The specified project does not exist or you do not have access to it.", "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" } } } } }, "x-api-version": "3.1" } }, "/api/v3.1/webhook_subscriptions": { "post": { "summary": "Create webhook subscription", "description": "Creates a webhook subscription for the authenticated project. Only one subscription is allowed per project. The signing secret is returned in subscription responses.", "tags": [ "Webhook Subscriptions" ], "operationId": "postWebhookSubscriptions", "security": [ { "ApiKeyAuth": [] }, { "UserApiKeyAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "webhook_url": { "type": "string", "maxLength": 2048, "format": "uri", "description": "HTTPS URL to receive webhook events" }, "enabled_events": { "type": "array", "items": { "type": "string" }, "minItems": 1, "description": "Array of event types to subscribe to" }, "version": { "type": "string", "enum": [ "V1", "V2", "V3" ], "default": "V3", "description": "Webhook payload version" } }, "required": [ "webhook_url", "enabled_events" ] } } } }, "responses": { "201": { "description": "Webhook subscription created", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "webhookSubscriptionId", "description": "Unique subscription ID" }, "webhook_url": { "type": "string", "description": "Webhook destination URL" }, "version": { "type": "string", "enum": [ "V1", "V2", "V3" ], "description": "Webhook payload version" }, "enabled_events": { "type": "array", "items": { "type": "string" }, "description": "Subscribed event types" }, "secret": { "type": "string", "description": "Signing secret for HMAC verification" }, "created_at": { "type": "string", "description": "ISO 8601 timestamp" }, "updated_at": { "type": "string", "description": "ISO 8601 timestamp" } }, "required": [ "id", "webhook_url", "version", "enabled_events", "secret", "created_at", "updated_at" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Subscription already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-api-version": "3.1" }, "get": { "summary": "List webhook subscriptions", "description": "Lists all webhook subscriptions for the authenticated project with pagination. Currently limited to one subscription per project.", "tags": [ "Webhook Subscriptions" ], "operationId": "getWebhookSubscriptions", "security": [ { "ApiKeyAuth": [] }, { "UserApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "number", "nullable": true }, "required": false, "description": "Number of items per page, max allowed is 1000", "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" } ], "responses": { "200": { "description": "Webhook subscriptions retrieved", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "webhookSubscriptionId", "description": "Unique subscription ID" }, "webhook_url": { "type": "string", "description": "Webhook destination URL" }, "version": { "type": "string", "enum": [ "V1", "V2", "V3" ], "description": "Webhook payload version" }, "enabled_events": { "type": "array", "items": { "type": "string" }, "description": "Subscribed event types" }, "secret": { "type": "string", "description": "Signing secret for HMAC verification" }, "created_at": { "type": "string", "description": "ISO 8601 timestamp" }, "updated_at": { "type": "string", "description": "ISO 8601 timestamp" } }, "required": [ "id", "webhook_url", "version", "enabled_events", "secret", "created_at", "updated_at" ] } }, "next_cursor": { "type": "string", "nullable": true }, "total_pages": { "type": "number" }, "current_page": { "type": "number" }, "total_items": { "type": "number" } }, "required": [ "items", "total_pages", "current_page", "total_items" ] } } } }, "400": { "description": "Invalid pagination", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-api-version": "3.1" } }, "/api/v3.1/webhook_subscriptions/{id}": { "get": { "summary": "Get webhook subscription", "description": "Retrieves a webhook subscription by ID.", "tags": [ "Webhook Subscriptions" ], "operationId": "getWebhookSubscriptionsById", "security": [ { "ApiKeyAuth": [] }, { "UserApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "format": "webhookSubscriptionId", "description": "Webhook subscription ID" }, "required": true, "description": "Webhook subscription ID", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Webhook subscription retrieved", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "webhookSubscriptionId", "description": "Unique subscription ID" }, "webhook_url": { "type": "string", "description": "Webhook destination URL" }, "version": { "type": "string", "enum": [ "V1", "V2", "V3" ], "description": "Webhook payload version" }, "enabled_events": { "type": "array", "items": { "type": "string" }, "description": "Subscribed event types" }, "secret": { "type": "string", "description": "Signing secret for HMAC verification" }, "created_at": { "type": "string", "description": "ISO 8601 timestamp" }, "updated_at": { "type": "string", "description": "ISO 8601 timestamp" } }, "required": [ "id", "webhook_url", "version", "enabled_events", "secret", "created_at", "updated_at" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Subscription not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-api-version": "3.1" }, "patch": { "summary": "Update webhook subscription", "description": "Updates a webhook subscription. At least one field must be provided.", "tags": [ "Webhook Subscriptions" ], "operationId": "patchWebhookSubscriptionsById", "security": [ { "ApiKeyAuth": [] }, { "UserApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "format": "webhookSubscriptionId", "description": "Webhook subscription ID" }, "required": true, "description": "Webhook subscription ID", "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "webhook_url": { "type": "string", "maxLength": 2048, "format": "uri", "description": "HTTPS URL to receive webhook events" }, "enabled_events": { "type": "array", "items": { "type": "string" }, "minItems": 1, "description": "Array of event types to subscribe to" }, "version": { "type": "string", "enum": [ "V1", "V2", "V3" ], "description": "Webhook payload version" } } } } } }, "responses": { "200": { "description": "Webhook subscription updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "webhookSubscriptionId", "description": "Unique subscription ID" }, "webhook_url": { "type": "string", "description": "Webhook destination URL" }, "version": { "type": "string", "enum": [ "V1", "V2", "V3" ], "description": "Webhook payload version" }, "enabled_events": { "type": "array", "items": { "type": "string" }, "description": "Subscribed event types" }, "secret": { "type": "string", "description": "Signing secret for HMAC verification" }, "created_at": { "type": "string", "description": "ISO 8601 timestamp" }, "updated_at": { "type": "string", "description": "ISO 8601 timestamp" } }, "required": [ "id", "webhook_url", "version", "enabled_events", "secret", "created_at", "updated_at" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Subscription not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-api-version": "3.1" }, "delete": { "summary": "Delete webhook subscription", "description": "Permanently deletes a webhook subscription. This action cannot be undone.", "tags": [ "Webhook Subscriptions" ], "operationId": "deleteWebhookSubscriptionsById", "security": [ { "ApiKeyAuth": [] }, { "UserApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "format": "webhookSubscriptionId", "description": "Webhook subscription ID" }, "required": true, "description": "Webhook subscription ID", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Webhook subscription deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Subscription not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-api-version": "3.1" } }, "/api/v3.1/webhook_subscriptions/{id}/rotate_secret": { "post": { "summary": "Rotate webhook secret", "description": "Generates a new signing secret for the webhook subscription.", "tags": [ "Webhook Subscriptions" ], "operationId": "postWebhookSubscriptionsByIdRotateSecret", "security": [ { "ApiKeyAuth": [] }, { "UserApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "format": "webhookSubscriptionId", "description": "Webhook subscription ID" }, "required": true, "description": "Webhook subscription ID", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Webhook secret rotated", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "webhookSubscriptionId", "description": "Subscription ID" }, "secret": { "type": "string", "description": "New signing secret" } }, "required": [ "id", "secret" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Subscription not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-api-version": "3.1" } }, "/api/v3.1/webhook_subscriptions/event_types": { "get": { "summary": "List available event types", "description": "Returns all event types that can be subscribed to, along with their supported webhook versions.", "tags": [ "Webhook Subscriptions" ], "operationId": "getWebhookSubscriptionsEventTypes", "security": [ { "ApiKeyAuth": [] }, { "UserApiKeyAuth": [] } ], "responses": { "200": { "description": "Event types retrieved", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "event_type": { "type": "string", "description": "Event type identifier" }, "description": { "type": "string", "description": "Human-readable description of the event" }, "supported_versions": { "type": "array", "items": { "type": "string", "enum": [ "V1", "V2", "V3" ] }, "description": "Webhook versions that support this event" } }, "required": [ "event_type", "description", "supported_versions" ] } } }, "required": [ "items" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-api-version": "3.1" } }, "/api/v3.1/webhook_endpoints": { "post": { "summary": "Create webhook endpoint", "description": "Creates a shared webhook endpoint for a toolkit + OAuth app + project. Returns the webhook URL that the customer registers in their app dashboard. Idempotent — returns existing endpoint if one already exists for this toolkit + client_id + project.", "tags": [ "Webhook Endpoints" ], "operationId": "postWebhookEndpoints", "security": [ { "ApiKeyAuth": [] }, { "UserApiKeyAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "toolkit_slug": { "type": "string", "minLength": 1, "description": "Toolkit identifier (e.g., slack, discord)" }, "client_id": { "type": "string", "minLength": 1, "description": "OAuth app client ID — identifies which app this endpoint is for" } }, "required": [ "toolkit_slug", "client_id" ] } } } }, "responses": { "200": { "description": "Existing webhook endpoint returned", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Webhook endpoint nano ID" }, "toolkit_slug": { "type": "string", "description": "Toolkit this endpoint is for" }, "client_id": { "type": "string", "nullable": true, "description": "OAuth app client ID" }, "webhook_url": { "type": "string", "description": "The webhook URL to register with the provider" }, "data": { "type": "object", "nullable": true, "additionalProperties": { "type": "string" }, "description": "Configured fields with secret values masked" }, "created_at": { "type": "string", "description": "ISO 8601 timestamp" } }, "required": [ "id", "toolkit_slug", "client_id", "webhook_url", "data", "created_at" ] } } } }, "201": { "description": "Webhook endpoint created", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Webhook endpoint nano ID" }, "toolkit_slug": { "type": "string", "description": "Toolkit this endpoint is for" }, "client_id": { "type": "string", "nullable": true, "description": "OAuth app client ID" }, "webhook_url": { "type": "string", "description": "The webhook URL to register with the provider" }, "data": { "type": "object", "nullable": true, "additionalProperties": { "type": "string" }, "description": "Configured fields with secret values masked" }, "created_at": { "type": "string", "description": "ISO 8601 timestamp" } }, "required": [ "id", "toolkit_slug", "client_id", "webhook_url", "data", "created_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": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-api-version": "3.1" }, "get": { "summary": "List webhook endpoints", "description": "Lists webhook endpoints for the authenticated project, optionally filtered by toolkit.", "tags": [ "Webhook Endpoints" ], "operationId": "getWebhookEndpoints", "security": [ { "ApiKeyAuth": [] }, { "UserApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Filter by toolkit slug" }, "required": false, "description": "Filter by toolkit slug", "name": "toolkit_slug", "in": "query" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Webhook endpoint nano ID" }, "toolkit_slug": { "type": "string", "description": "Toolkit this endpoint is for" }, "client_id": { "type": "string", "nullable": true, "description": "OAuth app client ID" } }, "required": [ "id", "toolkit_slug", "client_id" ] } } }, "required": [ "items" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-api-version": "3.1" } }, "/api/v3.1/webhook_endpoints/{nano_id}": { "get": { "summary": "Get webhook endpoint", "description": "Retrieves a single webhook endpoint. Secret values are redacted. Use GET /webhook_endpoints/schema to discover field definitions.", "tags": [ "Webhook Endpoints" ], "operationId": "getWebhookEndpointsByNanoId", "security": [ { "ApiKeyAuth": [] }, { "UserApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Webhook endpoint nano ID (e.g., we_abc123)" }, "required": true, "description": "Webhook endpoint nano ID (e.g., we_abc123)", "name": "nano_id", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Webhook endpoint nano ID" }, "toolkit_slug": { "type": "string", "description": "Toolkit this endpoint is for" }, "client_id": { "type": "string", "nullable": true, "description": "OAuth app client ID" }, "webhook_url": { "type": "string", "description": "The webhook URL to register with the provider" }, "data": { "type": "object", "nullable": true, "additionalProperties": { "type": "string" }, "description": "Configured fields with secret values masked" }, "created_at": { "type": "string", "description": "ISO 8601 timestamp" } }, "required": [ "id", "toolkit_slug", "client_id", "webhook_url", "data", "created_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": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-api-version": "3.1" }, "post": { "summary": "Put webhook endpoint configuration", "description": "Full replacement of webhook endpoint configuration. All required setup fields must be provided. Use PATCH to update individual fields.", "tags": [ "Webhook Endpoints" ], "operationId": "postWebhookEndpointsByNanoId", "security": [ { "ApiKeyAuth": [] }, { "UserApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Webhook endpoint nano ID (e.g., we_abc123)" }, "required": true, "description": "Webhook endpoint nano ID (e.g., we_abc123)", "name": "nano_id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Key-value pairs for ALL required setup_fields. Unlike PATCH, all required fields must be provided — this is initial configuration." } }, "required": [ "data" ] } } } }, "responses": { "200": { "description": "Configured", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Webhook endpoint nano ID" }, "toolkit_slug": { "type": "string", "description": "Toolkit this endpoint is for" }, "client_id": { "type": "string", "nullable": true, "description": "OAuth app client ID" }, "webhook_url": { "type": "string", "description": "The webhook URL to register with the provider" }, "data": { "type": "object", "nullable": true, "additionalProperties": { "type": "string" }, "description": "Configured fields with secret values masked" }, "created_at": { "type": "string", "description": "ISO 8601 timestamp" } }, "required": [ "id", "toolkit_slug", "client_id", "webhook_url", "data", "created_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": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-api-version": "3.1" }, "patch": { "summary": "Update webhook endpoint configuration", "description": "Updates app-specific secrets and credentials. Uses merge semantics — only included fields are updated; omitted fields are preserved. Can be called on active endpoints (e.g., to rotate a signing secret).", "tags": [ "Webhook Endpoints" ], "operationId": "patchWebhookEndpointsByNanoId", "security": [ { "ApiKeyAuth": [] }, { "UserApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Webhook endpoint nano ID (e.g., we_abc123)" }, "required": true, "description": "Webhook endpoint nano ID (e.g., we_abc123)", "name": "nano_id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Key-value pairs matching the toolkit's setup_fields. Only include fields you want to update — omitted fields are preserved." } }, "required": [ "data" ] } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Webhook endpoint nano ID" }, "toolkit_slug": { "type": "string", "description": "Toolkit this endpoint is for" }, "client_id": { "type": "string", "nullable": true, "description": "OAuth app client ID" }, "webhook_url": { "type": "string", "description": "The webhook URL to register with the provider" }, "data": { "type": "object", "nullable": true, "additionalProperties": { "type": "string" }, "description": "Configured fields with secret values masked" }, "created_at": { "type": "string", "description": "ISO 8601 timestamp" } }, "required": [ "id", "toolkit_slug", "client_id", "webhook_url", "data", "created_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": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-api-version": "3.1" } }, "/api/v3.1/toolkits": { "get": { "summary": "List available toolkits", "description": "Retrieves a comprehensive list of toolkits of their latest versions that are available to the authenticated project. Toolkits represent integration points with external services and applications, each containing a collection of tools and triggers. This endpoint supports filtering by category and management type, as well as different sorting options.", "tags": [ "Toolkits" ], "operationId": "getToolkits", "security": [ { "ApiKeyAuth": [] }, { "UserApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Category ID or name to filter toolkits by", "example": "productivity" }, "required": false, "description": "Filter toolkits by category", "name": "category", "in": "query" }, { "schema": { "type": "string", "enum": [ "composio", "all", "project" ], "description": "Entity responsible for managing the toolkits" }, "required": false, "description": "Filter toolkits by who manages them", "name": "managed_by", "in": "query" }, { "schema": { "type": "string", "enum": [ "usage", "alphabetically" ], "description": "Determines how toolkits should be sorted in the response" }, "required": false, "description": "Sort order for returned toolkits", "name": "sort_by", "in": "query" }, { "schema": { "type": "boolean", "nullable": true, "default": false, "description": "Include deprecated toolkits in the response", "example": true }, "required": false, "description": "Include deprecated toolkits in the response", "name": "include_deprecated", "in": "query" }, { "schema": { "type": "string", "description": "Search query to filter toolkits by name, slug, or description (minimum 3 characters)", "example": "gmail" }, "required": false, "description": "Search query to filter toolkits by name, slug, or description", "name": "search", "in": "query" }, { "schema": { "type": "number", "nullable": true }, "required": false, "description": "Number of items per page, max allowed is 1000", "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" } ], "responses": { "200": { "description": "Toolkits retrieved successfully. Returns a paginated list of available toolkits with detailed metadata.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "slug": { "type": "string", "description": "URL-friendly unique identifier for the toolkit", "example": "github" }, "name": { "type": "string", "description": "Human-readable name of the toolkit", "example": "GitHub" }, "auth_schemes": { "type": "array", "items": { "type": "string" }, "description": "List of authentication methods supported by this toolkit", "example": [ "oauth2", "api_key" ] }, "composio_managed_auth_schemes": { "type": "array", "items": { "type": "string" }, "description": "List of authentication methods that Composio manages for this toolkit", "example": [ "oauth2" ] }, "is_local_toolkit": { "type": "boolean", "description": "DEPRECATED: This field is no longer meaningful and will always return false. It was previously used to indicate if a toolkit is specific to the current project.", "deprecated": true, "example": false }, "no_auth": { "type": "boolean", "description": "When true, this toolkit can be used without authentication", "example": false }, "auth_guide_url": { "type": "string", "nullable": true, "description": "URL to a guide page with authentication setup instructions for this toolkit", "example": "https://composio.dev/auth/github" }, "deprecated": { "$ref": "#/components/schemas/DeprecatedToolkitInfo" }, "meta": { "type": "object", "properties": { "created_at": { "type": "string", "description": "Creation date and time of the toolkit", "example": "2023-01-15T09:30:00.000Z" }, "updated_at": { "type": "string", "description": "Last modification date and time of the toolkit", "example": "2023-05-20T14:45:00.000Z" }, "description": { "type": "string", "description": "Human-readable description explaining the toolkit's purpose and functionality", "example": "Integrate with GitHub repositories, issues, pull requests, and more." }, "logo": { "type": "string", "description": "Image URL for the toolkit's branding", "example": "https://assets.composio.dev/logos/github.png" }, "app_url": { "type": "string", "nullable": true, "description": "Link to the toolkit's main application or service website", "example": "https://github.com" }, "categories": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Category identifier", "example": "developer-tools" }, "name": { "type": "string", "description": "Human-readable category name", "example": "Developer Tools" } }, "required": [ "id", "name" ] }, "description": "List of categories associated with this toolkit", "example": [ { "id": "developer-tools", "name": "Developer Tools" }, { "id": "productivity", "name": "Productivity" } ] }, "triggers_count": { "type": "number", "description": "Count of available triggers in this toolkit", "example": 5 }, "tools_count": { "type": "number", "description": "Count of available tools in this toolkit", "example": 12 }, "version": { "type": "string", "description": "Version of the toolkit", "example": "20250905_00" } }, "required": [ "created_at", "updated_at", "description", "logo", "categories", "triggers_count", "tools_count", "version" ], "description": "Additional metadata about the toolkit" } }, "required": [ "slug", "name", "is_local_toolkit", "deprecated", "meta" ], "description": "Detailed information about a toolkit" } }, "next_cursor": { "type": "string", "nullable": true }, "total_pages": { "type": "number" }, "current_page": { "type": "number" }, "total_items": { "type": "number" } }, "required": [ "items", "total_pages", "current_page", "total_items" ] } } } }, "400": { "description": "Bad request. The query parameters may be invalid or in an incorrect format.", "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" } } } }, "404": { "description": "Not found. The toolkits you are looking for do not exist.", "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" } } } } }, "x-api-version": "3.1" } }, "/api/v3.1/toolkits/categories": { "get": { "summary": "List toolkit categories", "description": "Retrieves a comprehensive list of all available toolkit categories from their latest versions. These categories can be used to filter toolkits by type or purpose when using the toolkit listing endpoint. Categories help organize toolkits into logical groups based on their functionality or industry focus.", "tags": [ "Toolkits" ], "operationId": "getToolkitsCategories", "security": [ { "ApiKeyAuth": [] }, { "UserApiKeyAuth": [] } ], "responses": { "200": { "description": "Successfully retrieved a paginated list of all available toolkit categories with their identifiers and display names.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Display name of the toolkit category", "example": "Developer Tools" }, "id": { "type": "string", "description": "URL-friendly unique identifier for the category, used for filtering toolkits", "example": "developer-tools" } }, "required": [ "name", "id" ], "description": "Information about a single toolkit category" } }, "next_cursor": { "type": "string", "nullable": true }, "total_pages": { "type": "number" }, "current_page": { "type": "number" }, "total_items": { "type": "number" } }, "required": [ "items", "total_pages", "current_page", "total_items" ] } } } }, "400": { "description": "Bad request. The request may be invalid or in an incorrect format.", "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" } } } }, "404": { "description": "Not found. The requested resource was not found.", "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" } } } } }, "x-api-version": "3.1" } }, "/api/v3.1/toolkits/{slug}": { "get": { "summary": "Get toolkit by slug", "description": "Retrieves comprehensive information about a specific toolkit using its unique slug identifier. This endpoint provides detailed metadata, authentication configuration options, and feature counts for the requested toolkit.", "tags": [ "Toolkits" ], "operationId": "getToolkitsBySlug", "security": [ { "ApiKeyAuth": [] }, { "UserApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "The unique slug identifier of the toolkit to retrieve", "example": "github" }, "required": true, "description": "Toolkit slug identifier", "name": "slug", "in": "path" }, { "schema": { "type": "string", "default": "latest", "description": "Version of the toolkit", "example": "20250905_00" }, "required": false, "description": "Version of the toolkit", "name": "version", "in": "query" } ], "responses": { "200": { "description": "Successfully retrieved detailed information about the requested toolkit, including authentication options, metadata, and feature counts.", "content": { "application/json": { "schema": { "type": "object", "properties": { "slug": { "type": "string", "description": "URL-friendly unique identifier for the toolkit", "example": "github" }, "name": { "type": "string", "description": "Human-readable name of the toolkit", "example": "GitHub" }, "enabled": { "type": "boolean", "description": "Indicates if this toolkit is currently enabled and available for use", "example": true }, "composio_managed_auth_schemes": { "type": "array", "items": { "type": "string" }, "description": "List of authentication methods that Composio manages for this toolkit", "example": [ "oauth2" ] }, "is_local_toolkit": { "type": "boolean", "description": "DEPRECATED: This field is no longer meaningful and will always return false. It was previously used to indicate if a toolkit is specific to the current project.", "deprecated": true, "example": false }, "auth_config_details": { "type": "array", "items": { "type": "object", "properties": { "mode": { "type": "string", "description": "The type of authentication mode (e.g., oauth2, basic_auth, api_key)", "example": "oauth2" }, "fields": { "type": "object", "properties": { "auth_config_creation": { "type": "object", "properties": { "required": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "displayName": { "type": "string" }, "default": { "type": "string", "nullable": true }, "type": { "type": "string" }, "description": { "type": "string" }, "required": { "type": "boolean" }, "is_secret": { "type": "boolean" }, "legacy_template_name": { "type": "string" }, "advanced": { "type": "boolean" } }, "required": [ "name", "displayName", "type", "description", "required" ] } }, "optional": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "displayName": { "type": "string" }, "default": { "type": "string", "nullable": true }, "type": { "type": "string" }, "description": { "type": "string" }, "required": { "type": "boolean" }, "is_secret": { "type": "boolean" }, "legacy_template_name": { "type": "string" }, "advanced": { "type": "boolean" } }, "required": [ "name", "displayName", "type", "description", "required" ] } } }, "required": [ "required", "optional" ], "description": "Form fields needed when creating an authentication configuration" }, "connected_account_initiation": { "type": "object", "properties": { "required": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "displayName": { "type": "string" }, "default": { "type": "string", "nullable": true }, "type": { "type": "string" }, "description": { "type": "string" }, "required": { "type": "boolean" }, "is_secret": { "type": "boolean" }, "legacy_template_name": { "type": "string" }, "advanced": { "type": "boolean" } }, "required": [ "name", "displayName", "type", "description", "required" ] } }, "optional": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "displayName": { "type": "string" }, "default": { "type": "string", "nullable": true }, "type": { "type": "string" }, "description": { "type": "string" }, "required": { "type": "boolean" }, "is_secret": { "type": "boolean" }, "legacy_template_name": { "type": "string" }, "advanced": { "type": "boolean" } }, "required": [ "name", "displayName", "type", "description", "required" ] } } }, "required": [ "required", "optional" ], "description": "Form fields needed when connecting a user account with this authentication method" } }, "required": [ "auth_config_creation", "connected_account_initiation" ], "description": "Field groups required for different authentication stages" }, "proxy": { "type": "object", "properties": { "base_url": { "type": "string", "description": "URL to which authentication requests will be proxied", "example": "https://auth.example.com/proxy" } }, "required": [ "base_url" ], "description": "Configuration for proxying authentication requests to external services" }, "name": { "type": "string", "description": "Display name for this authentication method", "example": "OAuth 2.0" }, "auth_hint_url": { "type": "string", "nullable": true, "description": "URL to a page where users can obtain or configure credentials for this authentication method", "example": "https://github.com/settings/tokens" }, "deprecated_auth_provider_details": { "type": "object", "properties": { "authorization_url": { "type": "string" }, "token_url": { "type": "string" } }, "description": "Authentication URL fields for OAuth 2.0 and OAuth 1.0. We don't recommend using this field for authentication and might break post Aug 31 2025.", "deprecated": true } }, "required": [ "mode", "fields", "name" ], "description": "Detailed configuration for an authentication method" }, "description": "Complete authentication configuration details for each supported auth method" }, "auth_guide_url": { "type": "string", "nullable": true, "description": "URL to a guide page with authentication setup instructions for this toolkit", "example": "https://composio.dev/auth/github" }, "base_url": { "type": "string", "description": "If evaluation of base URL needs some connection info (like shopify), please create the connection and get the base URL from there", "example": "https://api.github.com" }, "meta": { "type": "object", "properties": { "created_at": { "type": "string", "description": "Creation date and time of the toolkit", "example": "2023-01-15T09:30:00.000Z" }, "updated_at": { "type": "string", "description": "Last modification date and time of the toolkit", "example": "2023-05-20T14:45:00.000Z" }, "description": { "type": "string", "description": "Human-readable description explaining the toolkit's purpose and functionality", "example": "Integrate with GitHub repositories, issues, pull requests, and more." }, "logo": { "type": "string", "description": "Image URL for the toolkit's branding", "example": "https://assets.composio.dev/logos/github.png" }, "app_url": { "type": "string", "nullable": true, "description": "Link to the toolkit's main application or service website", "example": "https://github.com" }, "categories": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Human-readable category name", "example": "Developer Tools" }, "slug": { "type": "string", "description": "URL-friendly identifier for the category", "example": "developer-tools" } }, "required": [ "name", "slug" ] }, "description": "List of categories associated with this toolkit", "example": [ { "name": "Developer Tools", "slug": "developer-tools" }, { "name": "Productivity", "slug": "productivity" } ] }, "triggers_count": { "type": "number", "description": "Count of available triggers in this toolkit", "example": 5 }, "tools_count": { "type": "number", "description": "Count of available tools in this toolkit", "example": 12 }, "version": { "type": "string", "description": "Version of the toolkit", "example": "20250905_00" }, "available_versions": { "type": "array", "items": { "type": "string" }, "description": "Available versions of the toolkit", "example": [ "20250905_00", "20250906_00" ] } }, "required": [ "created_at", "updated_at", "description", "logo", "categories", "triggers_count", "tools_count", "version", "available_versions" ], "description": "Comprehensive metadata for the toolkit including dates, descriptions, and statistics" }, "get_current_user_endpoint": { "type": "string", "description": "Endpoint to get the current user" }, "get_current_user_endpoint_method": { "type": "string", "description": "HTTP method to use when calling the get current user endpoint (e.g., GET, POST)", "example": "GET" }, "deprecated": { "type": "object", "properties": { "toolkitId": { "type": "string" }, "getCurrentUserEndpoint": { "type": "string" }, "rawProxyInfoByAuthSchemes": { "type": "array", "items": { "type": "object", "additionalProperties": {} } } }, "required": [ "toolkitId", "rawProxyInfoByAuthSchemes" ] } }, "required": [ "slug", "name", "enabled", "is_local_toolkit", "meta", "deprecated" ], "description": "Detailed information about a single toolkit" } } } }, "400": { "description": "Bad request. The toolkit slug may be invalid or in an incorrect format.", "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" } } } }, "404": { "description": "Not found. The requested toolkit does not exist or is not accessible to the authenticated project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error. An unexpect ed error occurred while processing the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-api-version": "3.1" } }, "/api/v3.1/toolkits/multi": { "post": { "summary": "Fetch multiple toolkits", "description": "Retrieves a comprehensive list of toolkits of their latest versions that are available to the authenticated project. Toolkits represent integration points with external services and applications, each containing a collection of tools and triggers. This endpoint supports filtering by category and management type, as well as different sorting options. You can optionally specify a list of toolkit slugs to fetch specific toolkits.", "tags": [ "Toolkits" ], "operationId": "postToolkitsMulti", "security": [ { "ApiKeyAuth": [] }, { "UserApiKeyAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "toolkits": { "type": "array", "items": { "type": "string" }, "description": "Array of toolkit slug identifiers to retrieve", "example": [ "github", "slack", "gmail" ] }, "category": { "type": "string", "description": "Category ID or name to filter toolkits by", "example": "productivity" }, "managed_by": { "type": "string", "enum": [ "composio", "all", "project" ], "description": "Entity responsible for managing the toolkits" }, "sort_by": { "type": "string", "enum": [ "usage", "alphabetically" ], "description": "Determines how toolkits should be sorted in the response" }, "limit": { "type": "number", "nullable": true }, "cursor": { "type": "string" } }, "description": "Body parameters for filtering and sorting toolkits" } } } }, "responses": { "200": { "description": "Toolkits retrieved successfully. Returns a paginated list of available toolkits with detailed metadata.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "slug": { "type": "string", "description": "URL-friendly unique identifier for the toolkit", "example": "github" }, "name": { "type": "string", "description": "Human-readable name of the toolkit", "example": "GitHub" }, "auth_schemes": { "type": "array", "items": { "type": "string" }, "description": "List of authentication methods supported by this toolkit", "example": [ "oauth2", "api_key" ] }, "composio_managed_auth_schemes": { "type": "array", "items": { "type": "string" }, "description": "List of authentication methods that Composio manages for this toolkit", "example": [ "oauth2" ] }, "is_local_toolkit": { "type": "boolean", "description": "DEPRECATED: This field is no longer meaningful and will always return false. It was previously used to indicate if a toolkit is specific to the current project.", "deprecated": true, "example": false }, "no_auth": { "type": "boolean", "description": "When true, this toolkit can be used without authentication", "example": false }, "auth_guide_url": { "type": "string", "nullable": true, "description": "URL to a guide page with authentication setup instructions for this toolkit", "example": "https://composio.dev/auth/github" }, "deprecated": { "$ref": "#/components/schemas/DeprecatedToolkitInfo" }, "meta": { "type": "object", "properties": { "created_at": { "type": "string", "description": "Creation date and time of the toolkit", "example": "2023-01-15T09:30:00.000Z" }, "updated_at": { "type": "string", "description": "Last modification date and time of the toolkit", "example": "2023-05-20T14:45:00.000Z" }, "description": { "type": "string", "description": "Human-readable description explaining the toolkit's purpose and functionality", "example": "Integrate with GitHub repositories, issues, pull requests, and more." }, "logo": { "type": "string", "description": "Image URL for the toolkit's branding", "example": "https://assets.composio.dev/logos/github.png" }, "app_url": { "type": "string", "nullable": true, "description": "Link to the toolkit's main application or service website", "example": "https://github.com" }, "categories": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Category identifier", "example": "developer-tools" }, "name": { "type": "string", "description": "Human-readable category name", "example": "Developer Tools" } }, "required": [ "id", "name" ] }, "description": "List of categories associated with this toolkit", "example": [ { "id": "developer-tools", "name": "Developer Tools" }, { "id": "productivity", "name": "Productivity" } ] }, "triggers_count": { "type": "number", "description": "Count of available triggers in this toolkit", "example": 5 }, "tools_count": { "type": "number", "description": "Count of available tools in this toolkit", "example": 12 }, "version": { "type": "string", "description": "Version of the toolkit", "example": "20250905_00" } }, "required": [ "created_at", "updated_at", "description", "logo", "categories", "triggers_count", "tools_count", "version" ], "description": "Additional metadata about the toolkit" } }, "required": [ "slug", "name", "is_local_toolkit", "deprecated", "meta" ], "description": "Detailed information about a toolkit" } }, "next_cursor": { "type": "string", "nullable": true }, "total_pages": { "type": "number" }, "current_page": { "type": "number" }, "total_items": { "type": "number" } }, "required": [ "items", "total_pages", "current_page", "total_items" ] } } } }, "400": { "description": "Bad request. The query parameters may be invalid or in an incorrect format.", "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" } } } }, "404": { "description": "Not found. The toolkits you are looking for do not exist.", "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" } } } } }, "x-api-version": "3.1" } }, "/api/v3.1/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" } } } }, "409": { "description": "Conflict", "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" } } } } }, "x-api-version": "3.1" } }, "/api/v3.1/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", "security": [ { "ApiKeyAuth": [] }, { "UserApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "Array of user IDs to filter triggers by" }, "required": false, "description": "Array of user IDs to filter triggers by", "name": "user_ids", "in": "query" }, { "schema": { "type": "array", "nullable": true, "items": { "type": "string", "format": "connectedAccountId" }, "description": "Array of connected account IDs to filter triggers by" }, "required": false, "description": "Array of connected account IDs to filter triggers by", "name": "connected_account_ids", "in": "query" }, { "schema": { "type": "array", "nullable": true, "items": { "type": "string", "format": "authConfigId" }, "description": "Array of auth config IDs to filter triggers by" }, "required": false, "description": "Array of auth config IDs to filter triggers by", "name": "auth_config_ids", "in": "query" }, { "schema": { "type": "array", "nullable": true, "items": { "type": "string", "format": "triggerInstanceId" }, "description": "Array of trigger IDs to filter triggers by" }, "required": false, "description": "Array of trigger IDs to filter triggers by", "name": "trigger_ids", "in": "query" }, { "schema": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "Array of trigger names to filter triggers by. Case-insensitive (internally normalized to uppercase)." }, "required": false, "description": "Array of trigger names to filter triggers by. Case-insensitive (internally normalized to uppercase).", "name": "trigger_names", "in": "query" }, { "schema": { "type": "array", "nullable": true, "items": { "type": "string", "format": "connectedAccountId" } }, "required": false, "description": "DEPRECATED: This parameter will be removed in a future version. Please use connected_account_ids instead.", "deprecated": true, "name": "connectedAccountIds", "in": "query" }, { "schema": { "type": "array", "nullable": true, "items": { "type": "string", "format": "authConfigId" } }, "required": false, "description": "DEPRECATED: This parameter will be removed in a future version. Please use auth_config_ids instead.", "deprecated": true, "name": "authConfigIds", "in": "query" }, { "schema": { "type": "array", "nullable": true, "items": { "type": "string", "format": "triggerInstanceId" } }, "required": false, "description": "DEPRECATED: This parameter will be removed in a future version. Please use trigger_ids instead.", "deprecated": true, "name": "triggerIds", "in": "query" }, { "schema": { "type": "boolean", "nullable": true, "default": false, "description": "When set to true, includes disabled triggers in the response." }, "required": false, "description": "When set to true, includes disabled triggers in the response.", "name": "show_disabled", "in": "query" }, { "schema": { "type": "array", "nullable": true, "items": { "type": "string" } }, "required": false, "description": "DEPRECATED: This parameter will be removed in a future version. Please use trigger_names instead.", "deprecated": true, "name": "triggerNames", "in": "query" }, { "schema": { "type": "boolean", "nullable": true, "default": false, "description": "DEPRECATED: Use show_disabled instead" }, "required": false, "description": "DEPRECATED: This parameter will be removed in a future version. Please use show_disabled instead.", "deprecated": true, "name": "showDisabled", "in": "query" }, { "schema": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "Array of connected account UUIDs to filter triggers by" }, "required": false, "description": "DEPRECATED: This parameter will be removed in a future version. Please use connected_account_ids instead.", "deprecated": true, "name": "deprecatedConnectedAccountUuids", "in": "query" }, { "schema": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "Array of auth config UUIDs to filter triggers by" }, "required": false, "description": "DEPRECATED: This parameter will be removed in a future version. Please use auth_config_ids instead.", "deprecated": true, "name": "deprecatedAuthConfigUuids", "in": "query" }, { "schema": { "type": "number", "nullable": true }, "required": false, "description": "Number of items per page, max allowed is 1000", "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" } ], "responses": { "200": { "description": "Successfully retrieved active trigger instances", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "description": "Unique identifier of the trigger instance" }, "id": { "type": "string", "format": "triggerInstanceId", "description": "Nano ID of the trigger instance" }, "connected_account_id": { "type": "string", "description": "ID of the connected account this trigger is associated with" }, "trigger_name": { "type": "string", "description": "Name of the trigger" }, "connected_account_uuid": { "type": "string", "description": "UUID of the connected account this trigger is associated with" }, "user_id": { "type": "string", "description": "ID of the user this trigger is associated with" }, "trigger_data": { "type": "string", "description": "Additional data associated with the trigger instance" }, "version": { "type": "string", "description": "Version of the trigger instance" }, "trigger_config": { "type": "object", "additionalProperties": {}, "description": "Configuration for the trigger" }, "state": { "type": "object", "additionalProperties": {}, "description": "DEPRECATED: This field exposes internal state and will be removed in a future version.", "deprecated": true }, "updated_at": { "type": "string", "description": "ISO 8601 timestamp when the trigger instance was updated" }, "disabled_at": { "type": "string", "nullable": true, "description": "ISO 8601 timestamp when the trigger instance was disabled, if applicable" }, "disabledAt": { "type": "string", "nullable": true, "description": "DEPRECATED: This parameter will be removed in a future version. Please use disabled_at instead.", "deprecated": true }, "connectedAccountId": { "type": "string", "description": "DEPRECATED: This parameter will be removed in a future version. Please use connected_account_id instead.", "deprecated": true }, "triggerName": { "type": "string", "description": "DEPRECATED: This parameter will be removed in a future version. Please use trigger_name instead.", "deprecated": true }, "updatedAt": { "type": "string", "description": "DEPRECATED: This parameter will be removed in a future version. Please use updated_at 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 }, "deprecated": { "type": "object", "properties": { "createdAt": { "type": "string", "description": "Deprecated created_at for the trigger instance" } }, "required": [ "createdAt" ], "description": "Deprecated fields for the trigger instance" } }, "required": [ "id", "connected_account_id", "trigger_name", "connected_account_uuid", "user_id", "version", "trigger_config", "state", "updated_at", "disabled_at", "disabledAt", "connectedAccountId", "triggerName", "updatedAt", "triggerConfig" ] } }, "next_cursor": { "type": "string", "nullable": true }, "total_pages": { "type": "number" }, "current_page": { "type": "number" }, "total_items": { "type": "number" } }, "required": [ "items", "total_pages", "current_page", "total_items" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-api-version": "3.1" } }, "/api/v3.1/trigger_instances/manage/{triggerId}": { "delete": { "summary": "Delete a trigger", "description": "Permanently deletes a trigger instance. This stops the trigger from listening for events and removes it from your project. Use the PATCH endpoint with status \"disable\" if you want to temporarily pause a trigger instead.", "tags": [ "Triggers" ], "operationId": "deleteTriggerInstancesManageByTriggerId", "security": [ { "ApiKeyAuth": [] }, { "UserApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "format": "triggerInstanceId", "description": "The ID of the trigger instance to delete" }, "required": true, "description": "The ID of the trigger instance to delete", "name": "triggerId", "in": "path" } ], "responses": { "200": { "description": "Successfully deleted the trigger instance", "content": { "application/json": { "schema": { "type": "object", "properties": { "trigger_id": { "type": "string", "format": "triggerInstanceId", "description": "The ID of the deleted trigger instance" } }, "required": [ "trigger_id" ] } } } }, "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" } } } }, "409": { "description": "Trigger instance already deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Trigger instance already gone", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-api-version": "3.1" }, "patch": { "summary": "Enable or disable a trigger", "description": "Updates the status of a trigger instance to enable or disable it. Disabling a trigger pauses event listening without deleting the trigger configuration. Re-enabling restores the trigger to its active state. Use this for temporary maintenance or to control trigger execution.", "tags": [ "Triggers" ], "operationId": "patchTriggerInstancesManageByTriggerId", "security": [ { "ApiKeyAuth": [] }, { "UserApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "format": "triggerInstanceId", "description": "The ID of the trigger instance to update" }, "required": true, "description": "The ID of the trigger instance to update", "name": "triggerId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "enable", "disable" ] } }, "required": [ "status" ] } } } }, "responses": { "200": { "description": "Successfully updated trigger status", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "success" ], "description": "Status of the operation" } }, "required": [ "status" ] } } } }, "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" } } } }, "409": { "description": "Trigger instance already enabled/disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Trigger instance already gone", "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" } } } } }, "x-api-version": "3.1" } }, "/api/v3.1/triggers_types/list/enum": { "get": { "summary": "List trigger type enums", "description": "Retrieves a list of all available trigger type enum values that can be used across the API from latest versions of the toolkit only", "tags": [ "Triggers" ], "operationId": "getTriggersTypesListEnum", "security": [ { "ApiKeyAuth": [] }, { "UserApiKeyAuth": [] } ], "responses": { "200": { "description": "Successfully retrieved trigger enum list", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string" }, "description": "JSON string containing all trigger enum values" } } } }, "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": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-api-version": "3.1" } }, "/api/v3.1/triggers_types/{slug}": { "get": { "summary": "Get trigger type by slug", "description": "Retrieve detailed information about a specific trigger type using its slug identifier", "tags": [ "Triggers" ], "operationId": "getTriggersTypesBySlug", "security": [ { "ApiKeyAuth": [] }, { "UserApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "The unique slug identifier for the trigger type. Case-insensitive (internally normalized to uppercase).", "example": "SLACK_RECEIVE_MESSAGE" }, "required": true, "description": "The unique slug identifier for the trigger type. Case-insensitive (internally normalized to uppercase).", "name": "slug", "in": "path" }, { "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 latest)", "value": null } } } ], "responses": { "200": { "description": "Successfully retrieved trigger type", "content": { "application/json": { "schema": { "type": "object", "properties": { "slug": { "type": "string", "description": "Unique identifier for the trigger type", "example": "SLACK_RECEIVE_MESSAGE" }, "name": { "type": "string", "description": "Human-readable name of the trigger", "example": "New Message in Slack Channel" }, "description": { "type": "string", "description": "Detailed description of what the trigger does", "example": "Triggers when a new message is posted to a Slack channel" }, "instructions": { "type": "string", "description": "Step-by-step instructions on how to set up and use this trigger" }, "type": { "type": "string", "enum": [ "webhook", "poll" ], "description": "The trigger mechanism - either webhook (event-based) or poll (scheduled check)", "example": "webhook" }, "toolkit": { "type": "object", "properties": { "slug": { "type": "string", "description": "Unique identifier for the parent toolkit", "example": "slack" }, "name": { "type": "string", "description": "Deprecated: Use slug instead", "example": "Slack" }, "logo": { "type": "string", "description": "Logo of the toolkit", "example": "https://example.com/logo.png" } }, "required": [ "slug", "name", "logo" ], "description": "Information about the toolkit that provides this trigger" }, "config": { "type": "object", "additionalProperties": {}, "description": "Configuration schema required to set up this trigger", "example": { "channel_id": { "type": "string", "required": true }, "message_type": { "type": "enum", "options": [ "all", "direct", "channel" ] } } }, "payload": { "type": "object", "additionalProperties": {}, "description": "Schema of the data payload this trigger will deliver when it fires", "example": { "message": { "type": "string" }, "sender": { "type": "object", "properties": { "id": "string", "name": "string" } }, "timestamp": { "type": "number" } } }, "version": { "type": "string", "description": "Version of the trigger type", "example": "20250930_00" }, "requires_webhook_endpoint_setup": { "type": "boolean", "default": false, "description": "True when the developer must register a Composio-issued webhook URL with the upstream provider (e.g. Slack Event Subscriptions, Notion integration webhooks). See the webhook_endpoint API for the setup.", "example": false } }, "required": [ "slug", "name", "description", "instructions", "type", "toolkit", "config", "payload", "version" ] } } } }, "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": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-api-version": "3.1" } }, "/api/v3.1/triggers_types": { "get": { "summary": "List trigger types", "description": "Retrieve a list of available trigger types with optional filtering by toolkit. Results are paginated and can be filtered by toolkit.", "tags": [ "Triggers" ], "operationId": "getTriggersTypes", "security": [ { "ApiKeyAuth": [] }, { "UserApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "Array of toolkit slugs to filter triggers by", "example": [ "slack", "github" ] }, "required": false, "description": "Array of toolkit slugs to filter triggers by", "name": "toolkit_slugs", "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 latest)", "value": null } } }, { "schema": { "type": "number", "nullable": true }, "required": false, "description": "Number of items per page, max allowed is 1000", "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" } ], "responses": { "200": { "description": "Successfully retrieved triggers", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "slug": { "type": "string", "description": "Unique identifier for the trigger type", "example": "SLACK_RECEIVE_MESSAGE" }, "name": { "type": "string", "description": "Human-readable name of the trigger", "example": "New Message in Slack Channel" }, "description": { "type": "string", "description": "Detailed description of what the trigger does", "example": "Triggers when a new message is posted to a Slack channel" }, "instructions": { "type": "string", "description": "Step-by-step instructions on how to set up and use this trigger" }, "type": { "type": "string", "enum": [ "webhook", "poll" ], "description": "The trigger mechanism - either webhook (event-based) or poll (scheduled check)", "example": "webhook" }, "toolkit": { "type": "object", "properties": { "slug": { "type": "string", "description": "Unique identifier for the parent toolkit", "example": "slack" }, "name": { "type": "string", "description": "Deprecated: Use slug instead", "example": "Slack" }, "logo": { "type": "string", "description": "Logo of the toolkit", "example": "https://example.com/logo.png" } }, "required": [ "slug", "name", "logo" ], "description": "Information about the toolkit that provides this trigger" }, "config": { "type": "object", "additionalProperties": {}, "description": "Configuration schema required to set up this trigger", "example": { "channel_id": { "type": "string", "required": true }, "message_type": { "type": "enum", "options": [ "all", "direct", "channel" ] } } }, "payload": { "type": "object", "additionalProperties": {}, "description": "Schema of the data payload this trigger will deliver when it fires", "example": { "message": { "type": "string" }, "sender": { "type": "object", "properties": { "id": "string", "name": "string" } }, "timestamp": { "type": "number" } } }, "version": { "type": "string", "description": "Version of the trigger type", "example": "20250930_00" }, "requires_webhook_endpoint_setup": { "type": "boolean", "default": false, "description": "True when the developer must register a Composio-issued webhook URL with the upstream provider (e.g. Slack Event Subscriptions, Notion integration webhooks). See the webhook_endpoint API for the setup.", "example": false } }, "required": [ "slug", "name", "description", "instructions", "type", "toolkit", "config", "payload", "version" ] } }, "next_cursor": { "type": "string", "nullable": true }, "total_pages": { "type": "number" }, "current_page": { "type": "number" }, "total_items": { "type": "number" } }, "required": [ "items", "total_pages", "current_page", "total_items" ] } } } }, "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": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-api-version": "3.1" } }, "/api/v3.1/mcp/servers": { "get": { "summary": "List MCP servers with optional filters and pagination", "description": "Retrieves a paginated list of MCP servers associated with the authenticated project. Results can be filtered by name, toolkit, or authentication configuration ID. MCP servers are used to provide Model Control Protocol integration points for connecting AI assistants to your applications and services.", "tags": [ "MCP" ], "operationId": "getMcpServers", "security": [ { "ApiKeyAuth": [] }, { "UserApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Name substring to filter servers by", "example": "github" }, "required": false, "description": "Filter MCP servers by name (case-insensitive partial match)", "name": "name", "in": "query" }, { "schema": { "type": "string" }, "required": false, "description": "Comma-separated list of toolkit slugs to filter servers by", "in": "query", "name": "toolkits" }, { "schema": { "type": "string" }, "required": false, "description": "Comma-separated list of auth config IDs to filter servers by", "in": "query", "name": "auth_config_ids" }, { "schema": { "type": "string", "enum": [ "created_at", "updated_at" ], "default": "updated_at", "description": "Field to use for ordering the results", "example": "updated_at" }, "required": false, "description": "Field to order results by", "name": "order_by", "in": "query" }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc", "description": "Sort direction (ascending or descending)", "example": "desc" }, "required": false, "description": "Direction of ordering", "name": "order_direction", "in": "query" }, { "schema": { "type": "number", "nullable": true, "default": 1, "description": "Page number to retrieve", "example": 1 }, "required": false, "description": "Page number for pagination (1-based)", "name": "page_no", "in": "query" }, { "schema": { "type": "number", "nullable": true, "default": 10, "description": "Number of servers to return per page", "example": 10 }, "required": false, "description": "Number of items per page (default: 10)", "name": "limit", "in": "query" } ], "responses": { "200": { "description": "Successfully retrieved MCP servers. Returns a paginated list of server configurations including connection details and command instructions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "UUID of the MCP server instance", "example": "550e8400-e29b-41d4-a716-446655440000" }, "name": { "type": "string", "description": "User-defined descriptive name for this MCP server", "example": "GitHub Integration Server" }, "auth_config_ids": { "type": "array", "items": { "type": "string" }, "description": "ID references to the auth configurations used by this server", "example": [ "ac_1a2b3c4d5e6f", "ac_7g8h9i0j1k2l" ] }, "allowed_tools": { "type": "array", "items": { "type": "string" }, "description": "Array of tool slugs that this MCP server is allowed to use", "example": [ "GITHUB_CREATE_AN_ISSUE", "GITHUB_GET_A_REPOSITORY", "GITHUB_LIST_PULL_REQUESTS" ] }, "mcp_url": { "type": "string", "description": "[DEPRECATED] Please use the URL with user_id or connected_account_id query param", "deprecated": true, "example": "https://backend.composio.dev/v3/mcp/550e8400-e29b-41d4-a716-446655440000?user_id=john" }, "toolkits": { "type": "array", "items": { "type": "string" }, "description": "Array of toolkit slugs that this MCP server is allowed to use", "example": [ "github", "jira", "slack" ] }, "toolkit_icons": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Object mapping each toolkit slug to its icon/logo URL for display purposes", "example": { "github": "https://assets.composio.dev/logos/github.png", "jira": "https://assets.composio.dev/logos/jira.png", "slack": "https://assets.composio.dev/logos/slack.png" } }, "commands": { "type": "object", "properties": { "cursor": { "type": "string", "description": "Command line instruction for Cursor client setup", "deprecated": true, "example": "npx @composio/mcp@latest setup \"https://backend.composio.dev/v3/mcp/550e8400-e29b-41d4-a716-446655440000?user_id=john\" --client cursor" }, "claude": { "type": "string", "description": "Command line instruction for Claude client setup", "deprecated": true, "example": "npx @composio/mcp@latest setup \"https://backend.composio.dev/v3/mcp/550e8400-e29b-41d4-a716-446655440000?user_id=john\" --client claude" }, "windsurf": { "type": "string", "description": "Command line instruction for Windsurf client setup", "deprecated": true, "example": "npx @composio/mcp@latest setup \"https://backend.composio.dev/v3/mcp/550e8400-e29b-41d4-a716-446655440000?user_id=john\" --client windsurf" } }, "required": [ "cursor", "claude", "windsurf" ], "description": "Set of command line instructions for connecting various clients to this MCP server", "deprecated": true }, "updated_at": { "type": "string", "description": "Date and time when this server configuration was last modified", "example": "2023-06-15T14:30:00.000Z" }, "created_at": { "type": "string", "description": "Date and time when this server was initially created", "example": "2023-06-10T09:15:00.000Z" }, "server_instance_count": { "type": "number", "description": "Total count of active user instances connected to this server", "example": 5 }, "managed_auth_via_composio": { "type": "boolean", "description": "Whether the MCP server is managed by Composio", "example": true } }, "required": [ "id", "name", "auth_config_ids", "allowed_tools", "mcp_url", "toolkits", "toolkit_icons", "commands", "updated_at", "created_at", "server_instance_count", "managed_auth_via_composio" ], "description": "MCP server configuration and connection details" }, "description": "Array of MCP server configurations", "example": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "GitHub Integration Server", "auth_config_ids": [ "ac_1a2b3c4d5e6f", "ac_7g8h9i0j1k2l" ], "allowed_tools": [ "GITHUB_CREATE_AN_ISSUE", "GITHUB_GET_A_REPOSITORY" ], "mcp_url": "https://backend.composio.dev/v3/mcp/550e8400-e29b-41d4-a716-446655440000?user_id=john", "commands": { "cursor": "npx @composio/mcp@latest setup \"https://backend.composio.dev/v3/mcp/550e8400-e29b-41d4-a716-446655440000?user_id=john\" --client cursor", "claude": "npx @composio/mcp@latest setup \"https://backend.composio.dev/v3/mcp/550e8400-e29b-41d4-a716-446655440000?user_id=john\" --client claude", "windsurf": "npx @composio/mcp@latest setup \"https://backend.composio.dev/v3/mcp/550e8400-e29b-41d4-a716-446655440000?user_id=john\" --client windsurf" }, "toolkits": [ "github", "jira", "slack" ], "toolkit_icons": { "github": "https://assets.composio.dev/logos/github.png", "jira": "https://assets.composio.dev/logos/jira.png", "slack": "https://assets.composio.dev/logos/slack.png" }, "updated_at": "2023-06-15T14:30:00.000Z", "created_at": "2023-06-10T09:15:00.000Z", "server_instance_count": 5, "managed_auth_via_composio": true } ] }, "total_pages": { "type": "number", "description": "Total number of pages in the paginated response", "example": 5 }, "current_page": { "type": "number", "description": "Current page number being returned", "example": 1 } }, "required": [ "items", "total_pages", "current_page" ], "description": "Paginated response containing MCP servers" } } } }, "400": { "description": "Bad request. The query parameters may be invalid or in an incorrect format.", "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 authenticated user does not have permission to view MCP servers for this project.", "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" } } } } }, "x-api-version": "3.1" }, "post": { "summary": "Create a new MCP server", "description": "Creates a new Model Control Protocol (MCP) server instance for the authenticated project. An MCP server provides a connection point for AI assistants to access your applications and services. The server is configured with specific authentication and tool permissions that determine what actions the connected assistants can perform.", "tags": [ "MCP" ], "operationId": "postMcpServers", "security": [ { "ApiKeyAuth": [] }, { "UserApiKeyAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 4, "maxLength": 30, "pattern": "^[a-zA-Z0-9- ]+$", "description": "Human-readable name to identify this MCP server instance (4-30 characters, alphanumeric, spaces, and hyphens only)", "example": "Production GitHub Integration" }, "auth_config_ids": { "type": "array", "items": { "type": "string" }, "description": "ID references to existing authentication configurations", "example": [ "ac_1a2b3c4d5e6f", "ac_7g8h9i0j1k2l" ] }, "no_auth_apps": { "type": "array", "items": { "type": "string" }, "description": "List of NO_AUTH apps to enable for this MCP server", "example": [ "exa", "codeinterpreter", "composio", "composio_search" ] }, "allowed_tools": { "type": "array", "items": { "type": "string" }, "default": [], "description": "List of tool slugs that should be allowed for this server. If not provided, all available tools for the authentication configuration will be enabled.", "example": [ "GITHUB_CREATE_AN_ISSUE", "GITHUB_GET_A_REPOSITORY", "GITHUB_LIST_PULL_REQUESTS" ] }, "managed_auth_via_composio": { "type": "boolean", "description": "Whether the MCP server is managed by Composio" } }, "required": [ "name", "auth_config_ids" ], "description": "Request parameters for creating a new MCP server with specific authentication configuration" }, "examples": { "Basic MCP Server": { "value": { "name": "GitHub Integration Server", "auth_config_ids": [ "ac_1a2b3c4d5e6f" ] } }, "Server with Limited Tools": { "value": { "name": "GitHub Issues Only", "auth_config_ids": [ "ac_1a2b3c4d5e6f" ], "allowed_tools": [ "GMAIL_ADD_LABEL_TO_EMAIL" ] } }, "Server with Expiration": { "value": { "name": "Temporary Integration Server", "auth_config_ids": [ "ac_1a2b3c4d5e6f" ] } } } } } }, "responses": { "201": { "description": "MCP server created successfully. Returns the complete server configuration including connection details and command instructions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "UUID of the MCP server instance", "example": "550e8400-e29b-41d4-a716-446655440000" }, "name": { "type": "string", "description": "User-defined descriptive name for this MCP server", "example": "GitHub Integration Server" }, "auth_config_ids": { "type": "array", "items": { "type": "string" }, "description": "ID references to the auth configurations used by this server", "example": [ "ac_1a2b3c4d5e6f", "ac_7g8h9i0j1k2l" ] }, "allowed_tools": { "type": "array", "items": { "type": "string" }, "description": "Array of tool slugs that this MCP server is allowed to use", "example": [ "GITHUB_CREATE_AN_ISSUE", "GITHUB_GET_A_REPOSITORY", "GITHUB_LIST_PULL_REQUESTS" ] }, "mcp_url": { "type": "string", "description": "[DEPRECATED] Please use the URL with user_id or connected_account_id query param", "deprecated": true, "example": "https://backend.composio.dev/v3/mcp/550e8400-e29b-41d4-a716-446655440000?user_id=john" }, "toolkits": { "type": "array", "items": { "type": "string" }, "description": "Array of toolkit slugs that this MCP server is allowed to use", "example": [ "github", "jira", "slack" ] }, "toolkit_icons": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Object mapping each toolkit slug to its icon/logo URL for display purposes", "example": { "github": "https://assets.composio.dev/logos/github.png", "jira": "https://assets.composio.dev/logos/jira.png", "slack": "https://assets.composio.dev/logos/slack.png" } }, "commands": { "type": "object", "properties": { "cursor": { "type": "string", "description": "Command line instruction for Cursor client setup", "deprecated": true, "example": "npx @composio/mcp@latest setup \"https://backend.composio.dev/v3/mcp/550e8400-e29b-41d4-a716-446655440000?user_id=john\" --client cursor" }, "claude": { "type": "string", "description": "Command line instruction for Claude client setup", "deprecated": true, "example": "npx @composio/mcp@latest setup \"https://backend.composio.dev/v3/mcp/550e8400-e29b-41d4-a716-446655440000?user_id=john\" --client claude" }, "windsurf": { "type": "string", "description": "Command line instruction for Windsurf client setup", "deprecated": true, "example": "npx @composio/mcp@latest setup \"https://backend.composio.dev/v3/mcp/550e8400-e29b-41d4-a716-446655440000?user_id=john\" --client windsurf" } }, "required": [ "cursor", "claude", "windsurf" ], "description": "Set of command line instructions for connecting various clients to this MCP server", "deprecated": true }, "updated_at": { "type": "string", "description": "Date and time when this server configuration was last modified", "example": "2023-06-15T14:30:00.000Z" }, "created_at": { "type": "string", "description": "Date and time when this server was initially created", "example": "2023-06-10T09:15:00.000Z" }, "server_instance_count": { "type": "number", "description": "Total count of active user instances connected to this server", "example": 5 }, "managed_auth_via_composio": { "type": "boolean", "description": "Whether the MCP server is managed by Composio", "example": true } }, "required": [ "id", "name", "auth_config_ids", "allowed_tools", "mcp_url", "toolkits", "toolkit_icons", "commands", "updated_at", "created_at", "server_instance_count", "managed_auth_via_composio" ], "description": "MCP server configuration and connection details" } } } }, "400": { "description": "Bad request. The request body may be invalid, missing required parameters, or the auth_config_id may not exist.", "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 authenticated user does not have permission to create MCP servers for this project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not Found. The specified auth_config_id does not exist or is not accessible to the authenticated user.", "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" } } } } }, "x-api-version": "3.1" } }, "/api/v3.1/mcp/servers/custom": { "post": { "summary": "Create a new custom MCP server with multiple apps", "description": "Creates a new Model Control Protocol (MCP) server instance that can integrate with multiple applications or toolkits simultaneously. This endpoint allows you to create a server that can access tools from different applications, making it suitable for complex workflows that span multiple services.", "tags": [ "MCP" ], "operationId": "postMcpServersCustom", "security": [ { "ApiKeyAuth": [] }, { "UserApiKeyAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 4, "maxLength": 30, "pattern": "^[a-zA-Z0-9- ]+$", "description": "Human-readable name to identify this custom MCP server (4-30 characters, alphanumeric, spaces, and hyphens only)", "example": "Multi App Integration Server" }, "auth_config_ids": { "type": "array", "items": { "type": "string" }, "description": "ID references to existing authentication configurations", "example": [ "ac_1a2b3c4d5e6f", "ac_7g8h9i0j1k2l" ] }, "toolkits": { "type": "array", "items": { "type": "string" }, "description": "List of application/toolkit identifiers to enable for this server", "example": [ "github", "jira", "slack" ] }, "allowed_tools": { "type": "array", "items": { "type": "string" }, "description": "Tool identifiers to enable that aren't part of standard toolkits", "example": [ "GITHUB_CREATE_AN_ISSUE", "SLACK_SEND_MESSAGE" ] }, "custom_tools": { "type": "array", "items": { "type": "string" }, "description": "DEPRECATED: Use allowed_tools instead. Tool identifiers to enable that aren't part of standard toolkits", "example": [ "GITHUB_CREATE_AN_ISSUE", "SLACK_SEND_MESSAGE" ] }, "managed_auth_via_composio": { "type": "boolean", "description": "Whether to manage authentication via Composio" } }, "required": [ "name" ], "description": "Parameters for creating a new custom MCP server with multiple applications" }, "examples": { "Basic Multi-App Server": { "value": { "name": "Development Integration Server", "toolkits": [ "github", "jira" ] } }, "Advanced Multi-App Server": { "value": { "name": "Complete Workflow Integration", "toolkits": [ "github", "jira", "slack" ], "custom_tools": [ "SLACK_SEND_MESSAGE" ] } } } } } }, "responses": { "201": { "description": "Custom MCP server created successfully. Returns the complete server configuration including connection details and command instructions for all specified applications.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the newly created custom MCP server", "example": "550e8400-e29b-41d4-a716-446655440000" }, "name": { "type": "string", "description": "Human-readable name of the custom MCP server", "example": "Multi-App Integration Server" }, "auth_config_ids": { "type": "array", "items": { "type": "string" }, "description": "ID references to the auth configurations used by this server", "example": [ "ac_1a2b3c4d5e6f", "ac_7g8h9i0j1k2l" ] }, "allowed_tools": { "type": "array", "items": { "type": "string" }, "description": "List of tool identifiers that are enabled for this server", "example": [ "GITHUB_CREATE_AN_ISSUE", "JIRA_GET_ISSUE", "SLACK_SEND_MESSAGE", "GMAIL_SEND_EMAIL" ] }, "mcp_url": { "type": "string", "description": "URL endpoint for establishing connection to this MCP server", "example": "https://backend.composio.dev/v3/mcp/550e8410-e29b-41d4-a716-446655440000?user_id=john" }, "commands": { "type": "object", "properties": { "cursor": { "type": "string", "description": "Command line instruction for Cursor client setup", "example": "npx @composio/mcp@latest setup \"https://backend.composio.dev/v3/mcp/550e8410-e29b-41d4-a716-446655440000?user_id=john\" --client cursor" }, "claude": { "type": "string", "description": "Command line instruction for Claude client setup", "example": "npx @composio/mcp@latest setup \"https://backend.composio.dev/v3/mcp/550e8410-e29b-41d4-a716-446655440000?user_id=john\" --client claude" }, "windsurf": { "type": "string", "description": "Command line instruction for Windsurf client setup", "example": "npx @composio/mcp@latest setup \"https://backend.composio.dev/v3/mcp/550e8410-e29b-41d4-a716-446655440000?user_id=john\" --client windsurf" } }, "required": [ "cursor", "claude", "windsurf" ], "description": "Set of command line instructions for connecting various clients to this MCP server" } }, "required": [ "id", "name", "auth_config_ids", "allowed_tools", "mcp_url", "commands" ], "description": "Response for a successfully created custom MCP server with multiple applications" } } } }, "400": { "description": "Bad request. The request body may be invalid, missing required parameters, or contain invalid toolkit identifiers.", "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 authenticated user does not have permission to create MCP servers for this project.", "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" } } } } }, "x-api-version": "3.1" } }, "/api/v3.1/mcp/servers/generate": { "post": { "summary": "Generate MCP URL with custom parameters", "description": "Generates a Model Control Protocol (MCP) URL for an existing server with custom query parameters. The URL includes user-specific parameters and configuration flags that control the behavior of the MCP connection.", "tags": [ "MCP" ], "operationId": "postMcpServersGenerate", "security": [ { "ApiKeyAuth": [] }, { "UserApiKeyAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "mcp_server_id": { "type": "string", "description": "Unique identifier of the MCP server to generate URL for", "example": "550e8400-e29b-41d4-a716-446655440000" }, "managed_auth_by_composio": { "type": "boolean", "default": false, "description": "Flag indicating if Composio manages authentication", "example": true }, "user_ids": { "type": "array", "items": { "type": "string" }, "description": "List of user identifiers for whom the URL is generated", "example": [ "user_123456", "user_789012" ] }, "connected_account_ids": { "type": "array", "items": { "type": "string" }, "description": "List of connected account identifiers", "example": [ "ca_1a2b3c4d5e6f", "ca_7g8h9i0j1k2l", "ca_3m4n5o6p7q8r" ] } }, "required": [ "mcp_server_id" ], "description": "Request parameters for generating an MCP URL" }, "examples": { "Basic URL Generation": { "value": { "mcp_server_id": "550e8400-e29b-41d4-a716-446655440000", "user_ids": [ "user_123456" ], "connected_account_ids": [ "ca_1a2b3c4d5e6f", "ca_7g8h9i0j1k2l" ] } }, "Managed Auth Configuration": { "value": { "mcp_server_id": "550e8400-e29b-41d4-a716-446655440000", "user_ids": [ "user_123456", "user_789012" ], "connected_account_ids": [ "ca_1a2b3c4d5e6f", "ca_7g8h9i0j1k2l", "ca_3m4n5o6p7q8r" ] } } } } } }, "responses": { "200": { "description": "Successfully generated MCP URL. Returns the complete URL with all specified query parameters.", "content": { "application/json": { "schema": { "type": "object", "properties": { "mcp_url": { "type": "string", "description": "Base MCP URL without any query parameters", "example": "https://mcp.composio.dev/composio/server/550e8400-e29b-41d4-a716-446655440000" }, "connected_account_urls": { "type": "array", "items": { "type": "string" }, "description": "List of URLs generated for each connected account ID", "example": [ "https://mcp.composio.dev/composio/server/550e8400-e29b-41d4-a716-446655440000?include_composio_helper_actions=true&connected_account_ids=ca_1a2b3c4d5e6f&user_id=user_123456,user_789012", "https://mcp.composio.dev/composio/server/550e8400-e29b-41d4-a716-446655440000?include_composio_helper_actions=true&connected_account_ids=ca_7g8h9i0j1k2l&user_id=user_123456,user_789012" ] }, "user_ids_url": { "type": "array", "items": { "type": "string" }, "description": "List of URLs generated for each user ID", "example": [ "https://mcp.composio.dev/composio/server/550e8400-e29b-41d4-a716-446655440000?include_composio_helper_actions=true&connected_account_ids=ca_1a2b3c4d5e6f,ca_7g8h9i0j1k2l&user_id=user_123456", "https://mcp.composio.dev/composio/server/550e8400-e29b-41d4-a716-446655440000?include_composio_helper_actions=true&connected_account_ids=ca_1a2b3c4d5e6f,ca_7g8h9i0j1k2l&user_id=user_789012" ] } }, "required": [ "mcp_url", "connected_account_urls", "user_ids_url" ], "description": "Response containing the generated MCP URLs" } } } }, "400": { "description": "Bad request. The request body may be invalid or missing required parameters.", "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 authenticated user does not have permission to access this MCP server.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "MCP server not found. No server with the specified ID exists or it has been deleted.", "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" } } } } }, "x-api-version": "3.1" } }, "/api/v3.1/mcp/{id}": { "get": { "summary": "Get MCP server details by ID", "description": "Retrieves detailed configuration information for a specific Model Control Protocol (MCP) server. The returned data includes connection details, associated applications, enabled tools, and authentication configuration.", "tags": [ "MCP" ], "operationId": "getMcpById", "security": [ { "ApiKeyAuth": [] }, { "UserApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Unique identifier of the MCP server to retrieve, update, or delete", "example": "550e8400-e29b-41d4-a716-446655440000" }, "required": true, "description": "The ID of the MCP server", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Successfully retrieved MCP server. Returns the complete server configuration including connection details, authentication settings, and available tools.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "UUID of the MCP server instance", "example": "550e8400-e29b-41d4-a716-446655440000" }, "name": { "type": "string", "description": "User-defined descriptive name for this MCP server", "example": "GitHub Integration Server" }, "auth_config_ids": { "type": "array", "items": { "type": "string" }, "description": "ID references to the auth configurations used by this server", "example": [ "ac_1a2b3c4d5e6f", "ac_7g8h9i0j1k2l" ] }, "allowed_tools": { "type": "array", "items": { "type": "string" }, "description": "Array of tool slugs that this MCP server is allowed to use", "example": [ "GITHUB_CREATE_AN_ISSUE", "GITHUB_GET_A_REPOSITORY", "GITHUB_LIST_PULL_REQUESTS" ] }, "mcp_url": { "type": "string", "description": "[DEPRECATED] Please use the URL with user_id or connected_account_id query param", "deprecated": true, "example": "https://backend.composio.dev/v3/mcp/550e8400-e29b-41d4-a716-446655440000?user_id=john" }, "toolkits": { "type": "array", "items": { "type": "string" }, "description": "Array of toolkit slugs that this MCP server is allowed to use", "example": [ "github", "jira", "slack" ] }, "toolkit_icons": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Object mapping each toolkit slug to its icon/logo URL for display purposes", "example": { "github": "https://assets.composio.dev/logos/github.png", "jira": "https://assets.composio.dev/logos/jira.png", "slack": "https://assets.composio.dev/logos/slack.png" } }, "commands": { "type": "object", "properties": { "cursor": { "type": "string", "description": "Command line instruction for Cursor client setup", "deprecated": true, "example": "npx @composio/mcp@latest setup \"https://backend.composio.dev/v3/mcp/550e8400-e29b-41d4-a716-446655440000?user_id=john\" --client cursor" }, "claude": { "type": "string", "description": "Command line instruction for Claude client setup", "deprecated": true, "example": "npx @composio/mcp@latest setup \"https://backend.composio.dev/v3/mcp/550e8400-e29b-41d4-a716-446655440000?user_id=john\" --client claude" }, "windsurf": { "type": "string", "description": "Command line instruction for Windsurf client setup", "deprecated": true, "example": "npx @composio/mcp@latest setup \"https://backend.composio.dev/v3/mcp/550e8400-e29b-41d4-a716-446655440000?user_id=john\" --client windsurf" } }, "required": [ "cursor", "claude", "windsurf" ], "description": "Set of command line instructions for connecting various clients to this MCP server", "deprecated": true }, "updated_at": { "type": "string", "description": "Date and time when this server configuration was last modified", "example": "2023-06-15T14:30:00.000Z" }, "created_at": { "type": "string", "description": "Date and time when this server was initially created", "example": "2023-06-10T09:15:00.000Z" }, "server_instance_count": { "type": "number", "description": "Total count of active user instances connected to this server", "example": 5 }, "managed_auth_via_composio": { "type": "boolean", "description": "Whether the MCP server is managed by Composio", "example": true }, "deleted": { "type": "boolean", "description": "Whether the MCP server is deleted" } }, "required": [ "id", "name", "auth_config_ids", "allowed_tools", "mcp_url", "toolkits", "toolkit_icons", "commands", "updated_at", "created_at", "server_instance_count", "managed_auth_via_composio", "deleted" ], "description": "MCP server configuration and connection details" } } } }, "400": { "description": "Bad request. The server ID parameter may be invalid or in an incorrect format.", "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 authenticated user does not have permission to view this MCP server.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "MCP server not found. No server with the specified ID exists or it has been deleted.", "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" } } } } }, "x-api-version": "3.1" }, "patch": { "summary": "Update MCP server configuration", "description": "Updates the configuration of an existing Model Control Protocol (MCP) server. You can modify the server name, associated applications, and enabled tools. Only the fields included in the request will be updated.", "tags": [ "MCP" ], "operationId": "patchMcpById", "security": [ { "ApiKeyAuth": [] }, { "UserApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Unique identifier of the MCP server to retrieve, update, or delete", "example": "550e8400-e29b-41d4-a716-446655440000" }, "required": true, "description": "The ID of the MCP server", "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Human-readable name to identify this MCP server instance (4-30 characters, alphanumeric, spaces, and hyphens only)", "example": "Production GitHub Integration" }, "toolkits": { "type": "array", "items": { "type": "string" }, "description": "List of toolkit slugs this server should be configured to work with.", "example": [ "gmail", "notion" ] }, "allowed_tools": { "type": "array", "items": { "type": "string" }, "description": "List of action identifiers that should be enabled for this server", "example": [ "GMAIL_ADD_LABEL_TO_EMAIL" ] }, "managed_auth_via_composio": { "type": "boolean", "description": "Whether the MCP server is managed by Composio", "example": true }, "auth_config_ids": { "type": "array", "items": { "type": "string" }, "description": "List of auth config IDs to use for this MCP server.", "example": [ "ac_1a2b3c4d5e6f", "ac_7g8h9i0j1k2l" ] } }, "description": "Parameters for updating an existing MCP server configuration" }, "examples": { "Update Server Name": { "value": { "name": "Updated GitHub Integration Server" } }, "Update Single Auth Config": { "value": { "auth_config_ids": [ "ac_1a2b3c4d5e6f" ], "toolkits": [ "gmail" ], "allowed_tools": [ "GMAIL_ADD_LABEL_TO_EMAIL" ] } }, "Update Multiple Auth Configs": { "value": { "auth_config_ids": [ "ac_1a2b3c4d5e6f", "ac_7g8h9i0j1k2l" ], "toolkits": [ "gmail", "notion" ], "allowed_tools": [ "GMAIL_ADD_LABEL_TO_EMAIL", "NOTION_CREATE_NOTION_PAGE" ] } }, "Update Toolkits Only": { "value": { "toolkits": [ "gmail", "notion" ] } }, "Full Update": { "value": { "name": "Production Multi-App MCP Server", "auth_config_ids": [ "ac_1a2b3c4d5e6f", "ac_7g8h9i0j1k2l" ], "toolkits": [ "gmail", "notion" ], "allowed_tools": [ "GMAIL_ADD_LABEL_TO_EMAIL", "NOTION_CREATE_NOTION_PAGE" ] } } } } } }, "responses": { "200": { "description": "Successfully updated MCP server. Returns the complete updated server configuration including connection details, authentication settings, and available tools.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "UUID of the MCP server instance", "example": "550e8400-e29b-41d4-a716-446655440000" }, "name": { "type": "string", "description": "User-defined descriptive name for this MCP server", "example": "GitHub Integration Server" }, "auth_config_ids": { "type": "array", "items": { "type": "string" }, "description": "ID references to the auth configurations used by this server", "example": [ "ac_1a2b3c4d5e6f", "ac_7g8h9i0j1k2l" ] }, "allowed_tools": { "type": "array", "items": { "type": "string" }, "description": "Array of tool slugs that this MCP server is allowed to use", "example": [ "GITHUB_CREATE_AN_ISSUE", "GITHUB_GET_A_REPOSITORY", "GITHUB_LIST_PULL_REQUESTS" ] }, "mcp_url": { "type": "string", "description": "[DEPRECATED] Please use the URL with user_id or connected_account_id query param", "deprecated": true, "example": "https://backend.composio.dev/v3/mcp/550e8400-e29b-41d4-a716-446655440000?user_id=john" }, "toolkits": { "type": "array", "items": { "type": "string" }, "description": "Array of toolkit slugs that this MCP server is allowed to use", "example": [ "github", "jira", "slack" ] }, "toolkit_icons": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Object mapping each toolkit slug to its icon/logo URL for display purposes", "example": { "github": "https://assets.composio.dev/logos/github.png", "jira": "https://assets.composio.dev/logos/jira.png", "slack": "https://assets.composio.dev/logos/slack.png" } }, "commands": { "type": "object", "properties": { "cursor": { "type": "string", "description": "Command line instruction for Cursor client setup", "deprecated": true, "example": "npx @composio/mcp@latest setup \"https://backend.composio.dev/v3/mcp/550e8400-e29b-41d4-a716-446655440000?user_id=john\" --client cursor" }, "claude": { "type": "string", "description": "Command line instruction for Claude client setup", "deprecated": true, "example": "npx @composio/mcp@latest setup \"https://backend.composio.dev/v3/mcp/550e8400-e29b-41d4-a716-446655440000?user_id=john\" --client claude" }, "windsurf": { "type": "string", "description": "Command line instruction for Windsurf client setup", "deprecated": true, "example": "npx @composio/mcp@latest setup \"https://backend.composio.dev/v3/mcp/550e8400-e29b-41d4-a716-446655440000?user_id=john\" --client windsurf" } }, "required": [ "cursor", "claude", "windsurf" ], "description": "Set of command line instructions for connecting various clients to this MCP server", "deprecated": true }, "updated_at": { "type": "string", "description": "Date and time when this server configuration was last modified", "example": "2023-06-15T14:30:00.000Z" }, "created_at": { "type": "string", "description": "Date and time when this server was initially created", "example": "2023-06-10T09:15:00.000Z" }, "server_instance_count": { "type": "number", "description": "Total count of active user instances connected to this server", "example": 5 }, "managed_auth_via_composio": { "type": "boolean", "description": "Whether the MCP server is managed by Composio", "example": true }, "deleted": { "type": "boolean", "description": "Whether the MCP server is deleted" } }, "required": [ "id", "name", "auth_config_ids", "allowed_tools", "mcp_url", "toolkits", "toolkit_icons", "commands", "updated_at", "created_at", "server_instance_count", "managed_auth_via_composio", "deleted" ], "description": "MCP server configuration and connection details" } } } }, "400": { "description": "Bad request. The request parameters may be invalid or in an incorrect format.", "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 authenticated user does not have permission to update this MCP server.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "MCP server not found. No server with the specified ID exists or it has been deleted.", "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" } } } } }, "x-api-version": "3.1" }, "delete": { "summary": "Delete an MCP server", "description": "Performs a soft delete on a Model Control Protocol (MCP) server, making it unavailable for future use. This operation is reversible in the database but cannot be undone through the API. Any applications or services connected to this server will lose access after deletion.", "tags": [ "MCP" ], "operationId": "deleteMcpById", "security": [ { "ApiKeyAuth": [] }, { "UserApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Unique identifier of the MCP server to retrieve, update, or delete", "example": "550e8400-e29b-41d4-a716-446655440000" }, "required": true, "description": "The ID of the MCP server", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Successfully deleted MCP server. The server has been soft-deleted and is no longer available for use.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the MCP server to retrieve, update, or delete", "example": "550e8400-e29b-41d4-a716-446655440000" }, "deleted": { "type": "boolean", "description": "Indicates whether the MCP server was successfully deleted", "example": true } }, "required": [ "id", "deleted" ], "description": "Response indicating the success of the delete operation" } } } }, "400": { "description": "Bad request. The server ID parameter may be invalid or in an incorrect format.", "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 authenticated user does not have permission to delete this MCP server.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "MCP server not found. No server with the specified ID exists or it has already been deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "500": { "description": "Internal server error. An unexpected error occurred while processing the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-api-version": "3.1" } }, "/api/v3.1/mcp/app/{appKey}": { "get": { "summary": "List MCP servers for a specific app", "description": "Retrieves a paginated list of Model Control Protocol (MCP) servers that are configured for a specific application or toolkit. This endpoint allows you to find all MCP server instances that have access to a particular application, such as GitHub, Slack, or Jira.", "tags": [ "MCP" ], "operationId": "getMcpAppByAppKey", "security": [ { "ApiKeyAuth": [] }, { "UserApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Toolkit or application slug identifier to filter MCP servers by", "example": "github" }, "required": true, "description": "The key of the app to find MCP servers for", "name": "appKey", "in": "path" }, { "schema": { "type": "string", "description": "Name substring to filter servers by", "example": "github" }, "required": false, "description": "Filter MCP servers by name (case-insensitive partial match)", "name": "name", "in": "query" }, { "schema": { "type": "string" }, "required": false, "description": "Comma-separated list of toolkit slugs to filter servers by", "in": "query", "name": "toolkits" }, { "schema": { "type": "string" }, "required": false, "description": "Comma-separated list of auth config IDs to filter servers by", "in": "query", "name": "auth_config_ids" }, { "schema": { "type": "string", "enum": [ "created_at", "updated_at" ], "default": "updated_at", "description": "Field to use for ordering the results", "example": "updated_at" }, "required": false, "description": "Field to order results by", "name": "order_by", "in": "query" }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc", "description": "Sort direction (ascending or descending)", "example": "desc" }, "required": false, "description": "Direction of ordering", "name": "order_direction", "in": "query" }, { "schema": { "type": "number", "nullable": true, "default": 1, "description": "Page number to retrieve", "example": 1 }, "required": false, "description": "Page number for pagination (1-based)", "name": "page_no", "in": "query" }, { "schema": { "type": "number", "nullable": true, "default": 10, "description": "Number of servers to return per page", "example": 10 }, "required": false, "description": "Number of items per page (default: 10)", "name": "limit", "in": "query" } ], "responses": { "200": { "description": "Successfully retrieved MCP servers for the specified application. Returns a paginated list of server configurations including connection details and command instructions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "UUID of the MCP server instance", "example": "550e8400-e29b-41d4-a716-446655440000" }, "name": { "type": "string", "description": "User-defined descriptive name for this MCP server", "example": "GitHub Integration Server" }, "auth_config_ids": { "type": "array", "items": { "type": "string" }, "description": "ID references to the auth configurations used by this server", "example": [ "ac_1a2b3c4d5e6f", "ac_7g8h9i0j1k2l" ] }, "allowed_tools": { "type": "array", "items": { "type": "string" }, "description": "Array of tool slugs that this MCP server is allowed to use", "example": [ "GITHUB_CREATE_AN_ISSUE", "GITHUB_GET_A_REPOSITORY", "GITHUB_LIST_PULL_REQUESTS" ] }, "mcp_url": { "type": "string", "description": "[DEPRECATED] Please use the URL with user_id or connected_account_id query param", "deprecated": true, "example": "https://backend.composio.dev/v3/mcp/550e8400-e29b-41d4-a716-446655440000?user_id=john" }, "toolkits": { "type": "array", "items": { "type": "string" }, "description": "Array of toolkit slugs that this MCP server is allowed to use", "example": [ "github", "jira", "slack" ] }, "toolkit_icons": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Object mapping each toolkit slug to its icon/logo URL for display purposes", "example": { "github": "https://assets.composio.dev/logos/github.png", "jira": "https://assets.composio.dev/logos/jira.png", "slack": "https://assets.composio.dev/logos/slack.png" } }, "commands": { "type": "object", "properties": { "cursor": { "type": "string", "description": "Command line instruction for Cursor client setup", "deprecated": true, "example": "npx @composio/mcp@latest setup \"https://backend.composio.dev/v3/mcp/550e8400-e29b-41d4-a716-446655440000?user_id=john\" --client cursor" }, "claude": { "type": "string", "description": "Command line instruction for Claude client setup", "deprecated": true, "example": "npx @composio/mcp@latest setup \"https://backend.composio.dev/v3/mcp/550e8400-e29b-41d4-a716-446655440000?user_id=john\" --client claude" }, "windsurf": { "type": "string", "description": "Command line instruction for Windsurf client setup", "deprecated": true, "example": "npx @composio/mcp@latest setup \"https://backend.composio.dev/v3/mcp/550e8400-e29b-41d4-a716-446655440000?user_id=john\" --client windsurf" } }, "required": [ "cursor", "claude", "windsurf" ], "description": "Set of command line instructions for connecting various clients to this MCP server", "deprecated": true }, "updated_at": { "type": "string", "description": "Date and time when this server configuration was last modified", "example": "2023-06-15T14:30:00.000Z" }, "created_at": { "type": "string", "description": "Date and time when this server was initially created", "example": "2023-06-10T09:15:00.000Z" }, "server_instance_count": { "type": "number", "description": "Total count of active user instances connected to this server", "example": 5 }, "managed_auth_via_composio": { "type": "boolean", "description": "Whether the MCP server is managed by Composio", "example": true } }, "required": [ "id", "name", "auth_config_ids", "allowed_tools", "mcp_url", "toolkits", "toolkit_icons", "commands", "updated_at", "created_at", "server_instance_count", "managed_auth_via_composio" ], "description": "MCP server configuration and connection details" }, "description": "Array of MCP server configurations", "example": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "GitHub Integration Server", "auth_config_ids": [ "ac_1a2b3c4d5e6f", "ac_7g8h9i0j1k2l" ], "allowed_tools": [ "GITHUB_CREATE_AN_ISSUE", "GITHUB_GET_A_REPOSITORY" ], "mcp_url": "https://backend.composio.dev/v3/mcp/550e8400-e29b-41d4-a716-446655440000?user_id=john", "commands": { "cursor": "npx @composio/mcp@latest setup \"https://backend.composio.dev/v3/mcp/550e8400-e29b-41d4-a716-446655440000?user_id=john\" --client cursor", "claude": "npx @composio/mcp@latest setup \"https://backend.composio.dev/v3/mcp/550e8400-e29b-41d4-a716-446655440000?user_id=john\" --client claude", "windsurf": "npx @composio/mcp@latest setup \"https://backend.composio.dev/v3/mcp/550e8400-e29b-41d4-a716-446655440000?user_id=john\" --client windsurf" }, "toolkits": [ "github", "jira", "slack" ], "toolkit_icons": { "github": "https://assets.composio.dev/logos/github.png", "jira": "https://assets.composio.dev/logos/jira.png", "slack": "https://assets.composio.dev/logos/slack.png" }, "updated_at": "2023-06-15T14:30:00.000Z", "created_at": "2023-06-10T09:15:00.000Z", "server_instance_count": 5, "managed_auth_via_composio": true } ] }, "total_pages": { "type": "number", "description": "Total number of pages in the paginated response", "example": 5 }, "current_page": { "type": "number", "description": "Current page number being returned", "example": 1 } }, "required": [ "items", "total_pages", "current_page" ], "description": "Paginated response containing MCP servers" } } } }, "400": { "description": "Bad request. The query parameters may be invalid or in an incorrect format.", "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 authenticated user does not have permission to view MCP servers for this application.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Application not found. No application with the specified key exists.", "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" } } } } }, "x-api-version": "3.1" } }, "/api/v3.1/mcp/servers/{serverId}/instances": { "get": { "summary": "List all instances for an MCP server", "description": "Retrieves a paginated list of user instances (user IDs) associated with a specific Model Control Protocol (MCP) server. This endpoint supports pagination to handle servers with many instances.", "tags": [ "MCP" ], "operationId": "getMcpServersByServerIdInstances", "security": [ { "ApiKeyAuth": [] }, { "UserApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "UUID of the MCP server to list instances for", "example": "550e8400-e29b-41d4-a716-446655440000" }, "required": true, "description": "The ID of the MCP server", "name": "serverId", "in": "path" }, { "schema": { "type": "number", "nullable": true, "default": 1, "description": "Page number to retrieve", "example": 1 }, "required": false, "description": "Page number for pagination (1-based)", "name": "page_no", "in": "query" }, { "schema": { "type": "number", "nullable": true, "default": 20, "description": "Number of instances to return per page", "example": 20 }, "required": false, "description": "Number of items per page (default: 20)", "name": "limit", "in": "query" }, { "schema": { "type": "string", "description": "Filter instances by user ID or instance ID (partial match)", "example": "user_123" }, "required": false, "description": "Search instances by user ID/instance ID", "name": "search", "in": "query" }, { "schema": { "type": "string", "enum": [ "created_at", "updated_at" ], "default": "updated_at", "description": "Field to use for ordering the results", "example": "updated_at" }, "required": false, "description": "Field to order results by", "name": "order_by", "in": "query" }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc", "description": "Sort direction (ascending or descending)", "example": "desc" }, "required": false, "description": "Direction of ordering", "name": "order_direction", "in": "query" } ], "responses": { "200": { "description": "Successfully retrieved MCP server instances. Returns the list of user IDs associated with this server.", "content": { "application/json": { "schema": { "type": "object", "properties": { "instances": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "UUID of the instance record", "example": "550e8400-e29b-41d4-a716-446655440000" }, "instance_id": { "type": "string", "description": "The instance identifier (same as the user_id)", "example": "user_123456" }, "mcp_server_id": { "type": "string", "description": "UUID of the parent MCP server", "example": "660e8400-e29b-41d4-a716-446655440001" }, "created_at": { "type": "string", "description": "Date and time when this instance was created", "example": "2023-06-10T09:15:00.000Z" }, "updated_at": { "type": "string", "description": "Date and time when this instance was last modified", "example": "2023-06-15T14:30:00.000Z" } }, "required": [ "id", "instance_id", "mcp_server_id", "created_at", "updated_at" ], "description": "MCP server instance details" }, "description": "List of instance objects associated with this MCP server for the current page", "example": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "instance_id": "user_123456", "mcp_server_id": "660e8400-e29b-41d4-a716-446655440001", "created_at": "2023-06-10T09:15:00.000Z", "updated_at": "2023-06-15T14:30:00.000Z" } ] }, "server_id": { "type": "string", "description": "UUID of the MCP server", "example": "550e8400-e29b-41d4-a716-446655440000" }, "server_name": { "type": "string", "description": "Name of the MCP server", "example": "Production GitHub Integration" }, "total_pages": { "type": "number", "description": "Total number of pages in the paginated response", "example": 3 }, "current_page": { "type": "number", "description": "Current page number being returned", "example": 1 } }, "required": [ "instances", "server_id", "server_name", "total_pages", "current_page" ], "description": "Paginated list of instances for an MCP server" } } } }, "400": { "description": "Bad request. The server ID parameter may be invalid.", "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" } } } }, "404": { "description": "MCP server not found. No server with the specified ID exists.", "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" } } } } }, "x-api-version": "3.1" }, "post": { "summary": "Create a new MCP server instance", "description": "Creates a new instance for a Model Control Protocol (MCP) server. This endpoint validates that the user has connected accounts for all auth configurations associated with the MCP server before creating the instance.", "tags": [ "MCP" ], "operationId": "postMcpServersByServerIdInstances", "security": [ { "ApiKeyAuth": [] }, { "UserApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "UUID of the MCP server to create an instance for", "example": "550e8400-e29b-41d4-a716-446655440000" }, "required": true, "description": "The ID of the MCP server", "name": "serverId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "user_id": { "type": "string", "minLength": 1, "description": "The user ID (entity ID) that will be used as both the user identifier and instance ID", "example": "user_123456" } }, "required": [ "user_id" ], "description": "Parameters for creating a new MCP server instance" }, "examples": { "Create Instance": { "value": { "user_id": "user_123456" } } } } } }, "responses": { "201": { "description": "Successfully created MCP server instance. Returns the created instance details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "UUID of the instance record", "example": "550e8400-e29b-41d4-a716-446655440000" }, "instance_id": { "type": "string", "description": "The instance identifier (same as the user_id)", "example": "user_123456" }, "mcp_server_id": { "type": "string", "description": "UUID of the parent MCP server", "example": "660e8400-e29b-41d4-a716-446655440001" }, "created_at": { "type": "string", "description": "Date and time when this instance was created", "example": "2023-06-10T09:15:00.000Z" }, "updated_at": { "type": "string", "description": "Date and time when this instance was last modified", "example": "2023-06-15T14:30:00.000Z" } }, "required": [ "id", "instance_id", "mcp_server_id", "created_at", "updated_at" ], "description": "MCP server instance details" } } } }, "400": { "description": "Bad request. The request parameters may be invalid or the instance ID already exists.", "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 does not have connected accounts for all required auth configurations.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "MCP server not found. No server with the specified ID exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict. An instance with this ID already exists for the server.", "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" } } } } }, "x-api-version": "3.1" } }, "/api/v3.1/mcp/servers/{serverId}/instances/{instanceId}": { "delete": { "summary": "Delete an MCP server instance and associated connected accounts", "description": "Removes a user instance from the MCP server and deletes all connected accounts for that user that are associated with the auth configurations of this specific MCP server. Connected accounts for other auth configurations are not affected.", "tags": [ "MCP" ], "operationId": "deleteMcpServersByServerIdInstancesByInstanceId", "security": [ { "ApiKeyAuth": [] }, { "UserApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "UUID of the MCP server", "example": "550e8400-e29b-41d4-a716-446655440000" }, "required": true, "description": "The ID of the MCP server", "name": "serverId", "in": "path" }, { "schema": { "type": "string", "description": "The user ID to remove from this server", "example": "user_123456" }, "required": true, "description": "The instance ID (user ID) to delete", "name": "instanceId", "in": "path" } ], "responses": { "200": { "description": "Successfully deleted MCP server instance and associated connected accounts.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "deleted_connected_accounts": { "type": "number" } }, "required": [ "message", "deleted_connected_accounts" ] } } } }, "400": { "description": "Bad request. The request parameters may be invalid.", "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" } } } }, "404": { "description": "MCP server or instance not found.", "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" } } } } }, "x-api-version": "3.1" } }, "/api/v3.1/files/list": { "get": { "summary": "List files with optional app and action filters", "description": "Retrieves a list of files associated with the authenticated project. Results can be filtered by toolkit and tool slugs.", "tags": [ "Files" ], "operationId": "getFilesList", "security": [ { "ApiKeyAuth": [] }, { "UserApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Filter files by app slug. Example: \"file-converter\"" }, "required": false, "description": "Filter files by app slug. Example: \"file-converter\"", "name": "toolkit_slug", "in": "query" }, { "schema": { "type": "string", "description": "Filter files by action slug. Example: \"convert-to-pdf\"" }, "required": false, "description": "Filter files by action slug. Example: \"convert-to-pdf\"", "name": "tool_slug", "in": "query" }, { "schema": { "type": "number", "nullable": true }, "required": false, "description": "Number of items per page, max allowed is 1000", "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" } ], "responses": { "200": { "description": "Successfully retrieved files", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "toolkit_slug": { "type": "string", "description": "Slug of the app where this file belongs to. Example: \"file-converter\"" }, "tool_slug": { "type": "string", "description": "Slug of the action where this file belongs to. Example: \"convert-to-pdf\"" }, "filename": { "type": "string", "description": "Name of the original file. Example: \"document.docx\"" }, "mimetype": { "type": "string", "description": "Mime type of the original file. Example: \"application/vnd.openxmlformats-officedocument.wordprocessingml.document\"" }, "md5": { "type": "string", "description": "MD5 hash of the file for integrity verification. Example: \"d41d8cd98f00b204e9800998ecf8427e\"" } }, "required": [ "toolkit_slug", "tool_slug", "filename", "mimetype", "md5" ] } }, "next_cursor": { "type": "string", "nullable": true }, "total_pages": { "type": "number" }, "current_page": { "type": "number" }, "total_items": { "type": "number" } }, "required": [ "items", "total_pages", "current_page", "total_items" ] } } } }, "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": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-api-version": "3.1" } }, "/api/v3.1/files/upload/request": { "post": { "summary": "Create presigned URL for request file upload to S3", "description": "Generates a presigned URL for uploading a file to S3. This endpoint handles deduplication by checking if a file with the same MD5 hash already exists.", "tags": [ "Files" ], "operationId": "postFilesUploadRequest", "security": [ { "ApiKeyAuth": [] }, { "UserApiKeyAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "toolkit_slug": { "type": "string", "description": "Slug of the app where this file belongs to. Example: \"gmail\", \"slack\", \"github\"" }, "tool_slug": { "type": "string", "description": "Slug of the action where this file belongs to. Example: \"GMAIL_SEND_EMAIL\", \"SLACK_UPLOAD_FILE\"" }, "filename": { "type": "string", "description": "Name of the original file. Example: \"quarterly_report.pdf\"" }, "mimetype": { "type": "string", "description": "Mime type of the original file. Example: \"application/pdf\", \"image/png\"" }, "md5": { "type": "string", "description": "MD5 hash of the file for deduplication and integrity verification. Example: \"a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6\"" } }, "required": [ "toolkit_slug", "tool_slug", "filename", "mimetype", "md5" ] }, "examples": { "Gmail Email Attachment": { "value": { "toolkit_slug": "gmail", "tool_slug": "GMAIL_SEND_EMAIL", "filename": "quarterly_report.pdf", "mimetype": "application/pdf", "md5": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6" } }, "Slack File Upload": { "value": { "toolkit_slug": "slack", "tool_slug": "SLACK_SEND_MESSAGE", "filename": "meeting_notes.docx", "mimetype": "application/vnd.openxmlformats-officedocument.wordprocessingml.document", "md5": "b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7" } }, "GitHub Issue Screenshot": { "value": { "toolkit_slug": "github", "tool_slug": "GITHUB_CREATE_AN_ISSUE", "filename": "bug_screenshot.png", "mimetype": "image/png", "md5": "c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8" } }, "Notion Page Image": { "value": { "toolkit_slug": "notion", "tool_slug": "NOTION_ADD_PAGE_CONTENT", "filename": "diagram.svg", "mimetype": "image/svg+xml", "md5": "d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9" } }, "Jira Attachment": { "value": { "toolkit_slug": "jira", "tool_slug": "JIRA_ADD_ATTACHMENT_TO_ISSUE", "filename": "error_logs.txt", "mimetype": "text/plain", "md5": "e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0" } } } } } }, "responses": { "200": { "description": "Successfully created upload URL for request file", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the request file. Example: \"req_file_9mZn4qR8sXwT\"" }, "key": { "type": "string", "description": "Object storage upload location. Example: \"projects/pr_1a2b3c4d5e6f/requests/slack/SLACK_UPLOAD_FILE/document_9mZn4q.docx\"" }, "new_presigned_url": { "type": "string", "description": "Presigned URL for upload. Example: \"https://storage.composio.dev/projects/pr_1a2b3c4d5e6f/requests/slack/document_9mZn4q.docx?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=3600...\"" }, "newPresignedUrl": { "type": "string", "description": "[DEPRECATED] Use new_presigned_url instead. Presigned URL for upload. Example: \"https://storage.composio.dev/projects/pr_1a2b3c4d5e6f/requests/slack/document_9mZn4q.docx?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=3600...\"", "deprecated": true }, "type": { "type": "string", "enum": [ "new" ], "description": "[DEPRECATED] Indicates this is a new file that needs to be uploaded", "deprecated": true }, "metadata": { "type": "object", "properties": { "storage_backend": { "type": "string", "enum": [ "s3", "azure_blob_storage" ], "description": "Storage backend used for the file. If this is azure, use `x-ms-blob-type` header to set the blob type to `BlockBlob` while uploading the file" } }, "required": [ "storage_backend" ] } }, "required": [ "id", "key", "new_presigned_url", "newPresignedUrl", "type", "metadata" ] } } } }, "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" } } } }, "410": { "description": "Gone", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too Many Requests", "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" } } } } }, "x-api-version": "3.1" } }, "/api/v3.1/migration/get-nanoid": { "get": { "summary": "Get NanoId from UUID", "description": "Convert a legacy UUID to its corresponding NanoId for migration purposes. This endpoint facilitates the transition from UUID-based identifiers to the more compact NanoId format used in the v3 API.", "tags": [ "Migration" ], "operationId": "getMigrationGetNanoid", "security": [ { "ApiKeyAuth": [] }, { "UserApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000" }, "required": true, "description": "The legacy UUID that needs to be converted to a NanoId", "name": "uuid", "in": "query" }, { "schema": { "type": "string", "enum": [ "CONNECTED_ACCOUNT", "AUTH_CONFIG", "TRIGGER_INSTANCE" ], "example": "CONNECTED_ACCOUNT" }, "required": true, "description": "The type of resource that the UUID belongs to", "name": "type", "in": "query" }, { "schema": { "type": "string", "description": "Your Composio API key used for authentication", "example": "sk_123456789abcdef" }, "required": true, "name": "x-api-key", "in": "header" } ], "responses": { "200": { "description": "Successfully retrieved NanoId for the given UUID", "content": { "application/json": { "schema": { "type": "object", "properties": { "nanoid": { "type": "string", "minLength": 10, "maxLength": 10, "description": "The NanoId corresponding to the provided UUID. This is the new identifier that should be used in place of the legacy UUID.", "example": "XqXrPalt3v" } }, "required": [ "nanoid" ] } } } }, "400": { "description": "Bad Request - Invalid UUID or resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not Found - The UUID does not correspond to any resource of the specified type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Gone - The UUID does not correspond to any resource of the specified type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error - An unexpected error occurred during processing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-api-version": "3.1" } }, "/api/v3.1/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.", "tags": [ "Tool Router" ], "operationId": "postToolRouterSessionBySessionIdLink", "security": [ { "ApiKeyAuth": [] }, { "UserApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "format": "toolRouterSessionId", "description": "The session ID returned when creating the session", "example": "trs_LX9uJKBinWWr" }, "required": true, "description": "The unique identifier of the tool router session", "name": "session_id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "toolkit": { "type": "string", "minLength": 1, "description": "The unique slug identifier of the toolkit to connect", "example": "github" }, "alias": { "type": "string", "description": "A human-readable alias for this connected account. Must be unique per entity and toolkit within the project." }, "callback_url": { "type": "string", "format": "uri", "description": "URL where users will be redirected after completing auth", "example": "https://myapp.com/callback" }, "experimental": { "type": "object", "properties": { "account_type": { "type": "string", "enum": [ "PRIVATE", "SHARED" ], "description": "Sharing model for this connected account. PRIVATE (default) is usable only by the owning user_id. SHARED is reachable from a tool-router session ONLY when explicitly pinned in the session config — at most one SHARED connection per toolkit per session. Sessions never use a SHARED connection implicitly.", "x-experimental": true }, "acl_config_for_shared": { "type": "object", "properties": { "allow_all_users": { "type": "boolean", "description": "Wildcard \"any user_id in the project\" allow toggle. Only valid on SHARED connections." }, "allowed_user_ids": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 256 }, "maxItems": 1000, "description": "Explicit allow list of user_ids who can use this SHARED connection." }, "not_allowed_user_ids": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 256 }, "maxItems": 1000, "description": "Explicit deny list. Wins on conflict with allow_all_users and allowed_user_ids." } }, "description": "Access control for SHARED connections. Resolution rule (only fires when caller != creator): user in not_allowed_user_ids → DENY; allow_all_users=true → ALLOW; user in allowed_user_ids → ALLOW; else DENY. Default state (omitted or {}) is deny-by-default — only the creator can use.", "x-experimental": true } }, "description": "Experimental features - not stable, may be modified or removed in future versions.", "x-experimental": true } }, "required": [ "toolkit" ] } } } }, "responses": { "201": { "description": "Successfully created link session. Returns link token, redirect URL, and connected account ID.", "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" }, "experimental": { "type": "object", "properties": { "account_type": { "type": "string", "enum": [ "PRIVATE", "SHARED" ], "description": "Sharing model for this connected account. PRIVATE is usable only by the owning user_id. SHARED is reachable from a tool-router session only when explicitly pinned in the session config.", "x-experimental": true }, "acl_config_for_shared": { "type": "object", "properties": { "allow_all_users": { "type": "boolean" }, "allowed_user_ids": { "type": "array", "items": { "type": "string" } }, "not_allowed_user_ids": { "type": "array", "items": { "type": "string" } } }, "required": [ "allow_all_users", "allowed_user_ids", "not_allowed_user_ids" ], "description": "Access control for SHARED connections. Visible only to the connection creator and project/org API key callers; non-creator cookie callers receive the response without this block.", "x-experimental": true } }, "required": [ "account_type" ], "description": "Experimental features - not stable, may be modified or removed in future versions.", "x-experimental": true } }, "required": [ "link_token", "redirect_url", "connected_account_id" ] } } } }, "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.", "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 session does not belong to the authenticated user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. The session does not exist, toolkit not found, or no auth config exists for the toolkit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error. An unexpected error occurred while creating the link session.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-api-version": "3.1" } }, "/api/v3.1/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": "postToolRouterSessionBySessionIdProxyExecute", "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": { "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": { "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": { "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" }, "extra_token_data": { "type": "object", "additionalProperties": {} }, "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": [ "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" }, "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" } } }, "required": [ "status" ] } } } }, "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" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Bad gateway", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-api-version": "3.1" } }, "/api/v3.1/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_1a2b3c4d5e6f" }, "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": { "$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 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": { "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" } } } } }, "x-api-version": "3.1" } }, "/api/v3.1/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_1a2b3c4d5e6f" }, "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": "Files listed successfully", "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" ] }, "description": "List of files in the mount" }, "next_cursor": { "type": "string", "description": "Cursor for the next page of results. If absent, there are no more pages." } }, "required": [ "items" ] } } } }, "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": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-api-version": "3.1" } }, "/api/v3.1/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_1a2b3c4d5e6f" }, "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": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-api-version": "3.1" } }, "/api/v3.1/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": "postToolRouterSessionBySessionIdMountsByMountIdUploadUrl", "security": [ { "ApiKeyAuth": [] }, { "UserApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "format": "toolRouterSessionId", "description": "The unique identifier of the tool router session", "example": "trs_1a2b3c4d5e6f" }, "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": "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": { "201": { "description": "Upload URL created successfully", "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)" }, "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", "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": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-api-version": "3.1" } }, "/api/v3.1/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": "postToolRouterSessionBySessionIdMountsByMountIdDelete", "security": [ { "ApiKeyAuth": [] }, { "UserApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "format": "toolRouterSessionId", "description": "The unique identifier of the tool router session", "example": "trs_1a2b3c4d5e6f" }, "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": { "200": { "description": "File deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "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": [ "mount_relative_path", "sandbox_mount_prefix" ] } } } }, "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": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-api-version": "3.1" } }, "/api/v3.1/toolkits/changelog": { "get": { "summary": "Get toolkits changelog", "description": "Retrieves the last 10 versions changelog for all toolkits. This endpoint provides version history and changelog information for each toolkit.", "tags": [ "Toolkits" ], "operationId": "getToolkitsChangelog", "security": [ { "ApiKeyAuth": [] }, { "UserApiKeyAuth": [] } ], "responses": { "200": { "description": "Toolkits changelog retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "slug": { "type": "string", "description": "Toolkit slug" }, "name": { "type": "string", "description": "Toolkit name" }, "display_name": { "type": "string", "description": "Toolkit display name" }, "versions": { "type": "array", "items": { "type": "object", "properties": { "version": { "type": "string", "description": "Version identifier" }, "changelog": { "type": "string", "description": "Changelog for this version" } }, "required": [ "version", "changelog" ] }, "description": "Array of version changelogs" } }, "required": [ "slug", "name", "display_name", "versions" ] }, "description": "List of toolkits with their changelogs" } }, "required": [ "items" ] } } } }, "400": { "description": "Bad request - invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized - authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found - the toolkits you are looking for do not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-api-version": "3.1" } } } }