--- title: "Execute tool" method: POST path: "/api/v3.1/tools/execute/{tool_slug}" tags: ["Tools", "Execution"] --- # Execute tool `POST /api/v3.1/tools/execute/{tool_slug}` 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. ## Path parameters - `tool_slug` string, required ## Headers - `x-llm-gateway-headers` string — JSON object containing custom headers to pass to LLM providers (OpenAI, Bedrock, etc.) ## Request body - object - `connected_account_id` string — Unique identifier for the connected account to use for authentication - `entity_id` string — Deprecated: please use user_id instead. Entity identifier for multi-entity connected accounts (e.g. multiple repositories, organizations) - `user_id` string — User id for multi-user connected accounts (e.g. multiple users, organizations) - `version` string — Tool version to execute (defaults to "00000000_00" if not specified) - `custom_auth_params` object — Custom authentication parameters for tools that support parameterized authentication - `base_url` string — 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` object[] - `name` string, required — The name of the parameter. For example, 'x-api-key', 'Content-Type', etc. - `in` 'query' | 'header', required — The location of the parameter. Can be 'query' or 'header'. - `value` union, required — The value of the parameter. For example, '1234567890', 'application/json', etc. - string - number - `body` object — 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. - `custom_connection_data` union — Custom connection data for tools that support custom connection data - object - `authScheme` 'OAUTH2', required - `toolkitSlug` string, required - `val` object, required - `subdomain` string - `your-domain` string - `region` string - `shop` string - `account_url` string - `COMPANYDOMAIN` string - `extension` string - `form_api_base_url` string - `instanceEndpoint` string - `api_url` string - `borneo_dashboard_url` string - `proxy_username` string - `proxy_password` string - `domain` string - `version` string - `dc` string - `site_name` string - `instanceName` string - `account_id` string - `your_server` string - `server_location` string - `base_url` string - `state_prefix` string — The oauth2 state prefix for the connection - `long_redirect_url` boolean — Whether to return the redirect url without shortening - `access_token` string, required - `id_token` string - `token_type` string - `refresh_token` string, nullable - `expires_in` union - number - string - unknown - `scope` union - string - string[] - unknown - `webhook_signature` string - `authed_user` object — for slack user scopes - `access_token` string - `scope` string - `extra_token_data` object - object - `authScheme` 'DCR_OAUTH', required - `toolkitSlug` string, required - `val` object, required - `subdomain` string - `your-domain` string - `region` string - `shop` string - `account_url` string - `COMPANYDOMAIN` string - `extension` string - `form_api_base_url` string - `instanceEndpoint` string - `api_url` string - `borneo_dashboard_url` string - `proxy_username` string - `proxy_password` string - `domain` string - `version` string - `dc` string - `site_name` string - `instanceName` string - `account_id` string - `your_server` string - `server_location` string - `base_url` string - `state_prefix` string — The oauth2 state prefix for the connection - `long_redirect_url` boolean — Whether to return the redirect url without shortening - `client_id` string, required — Dynamically registered client ID - `client_secret` string — Dynamically registered client secret - `access_token` string, required - `id_token` string - `token_type` string - `refresh_token` string, nullable - `expires_in` union - number - string - unknown - `scope` union - string - string[] - unknown - `client_id_issued_at` number - `client_secret_expires_at` number - object - `authScheme` 'API_KEY', required - `toolkitSlug` string, required - `val` object, required - `subdomain` string - `your-domain` string - `region` string - `shop` string - `account_url` string - `COMPANYDOMAIN` string - `extension` string - `form_api_base_url` string - `instanceEndpoint` string - `api_url` string - `borneo_dashboard_url` string - `proxy_username` string - `proxy_password` string - `domain` string - `version` string - `dc` string - `site_name` string - `instanceName` string - `account_id` string - `your_server` string - `server_location` string - `base_url` string - `generic_api_key` string - `api_key` string - `bearer_token` string - `basic_encoded` string - object - `authScheme` 'BASIC_WITH_JWT', required - `toolkitSlug` string, required - `val` object, required - `subdomain` string - `your-domain` string - `region` string - `shop` string - `account_url` string - `COMPANYDOMAIN` string - `extension` string - `form_api_base_url` string - `instanceEndpoint` string - `api_url` string - `borneo_dashboard_url` string - `proxy_username` string - `proxy_password` string - `domain` string - `version` string - `dc` string - `site_name` string - `instanceName` string - `account_id` string - `your_server` string - `server_location` string - `base_url` string - `username` string, required - `password` string, required - object - `authScheme` 'BASIC', required - `toolkitSlug` string, required - `val` object, required - `subdomain` string - `your-domain` string - `region` string - `shop` string - `account_url` string - `COMPANYDOMAIN` string - `extension` string - `form_api_base_url` string - `instanceEndpoint` string - `api_url` string - `borneo_dashboard_url` string - `proxy_username` string - `proxy_password` string - `domain` string - `version` string - `dc` string - `site_name` string - `instanceName` string - `account_id` string - `your_server` string - `server_location` string - `base_url` string - `username` string, required - `password` string - object - `authScheme` 'BEARER_TOKEN', required - `toolkitSlug` string, required - `val` object, required - `subdomain` string - `your-domain` string - `region` string - `shop` string - `account_url` string - `COMPANYDOMAIN` string - `extension` string - `form_api_base_url` string - `instanceEndpoint` string - `api_url` string - `borneo_dashboard_url` string - `proxy_username` string - `proxy_password` string - `domain` string - `version` string - `dc` string - `site_name` string - `instanceName` string - `account_id` string - `your_server` string - `server_location` string - `base_url` string - `token` string, required - object - `authScheme` 'OAUTH1', required - `toolkitSlug` string, required - `val` object, required - `subdomain` string - `your-domain` string - `region` string - `shop` string - `account_url` string - `COMPANYDOMAIN` string - `extension` string - `form_api_base_url` string - `instanceEndpoint` string - `api_url` string - `borneo_dashboard_url` string - `proxy_username` string - `proxy_password` string - `domain` string - `version` string - `dc` string - `site_name` string - `instanceName` string - `account_id` string - `your_server` string - `server_location` string - `base_url` string - `oauth_token` string, required - `oauth_token_secret` string, required - `oauth_verifier` string - `consumer_key` string - `redirectUrl` string - `callback_url` string - object - `authScheme` 'NO_AUTH', required - `toolkitSlug` string, required - `val` object, required - `subdomain` string - `your-domain` string - `region` string - `shop` string - `account_url` string - `COMPANYDOMAIN` string - `extension` string - `form_api_base_url` string - `instanceEndpoint` string - `api_url` string - `borneo_dashboard_url` string - `proxy_username` string - `proxy_password` string - `domain` string - `version` string - `dc` string - `site_name` string - `instanceName` string - `account_id` string - `your_server` string - `server_location` string - `base_url` string - object - `authScheme` 'SERVICE_ACCOUNT', required - `toolkitSlug` string, required - `val` object, required - `subdomain` string - `your-domain` string - `region` string - `shop` string - `account_url` string - `COMPANYDOMAIN` string - `extension` string - `form_api_base_url` string - `instanceEndpoint` string - `api_url` string - `borneo_dashboard_url` string - `proxy_username` string - `proxy_password` string - `domain` string - `version` string - `dc` string - `site_name` string - `instanceName` string - `account_id` string - `your_server` string - `server_location` string - `base_url` string - `application_id` string, required - `installation_id` string, required - `private_key` string, required - object - `authScheme` 'GOOGLE_SERVICE_ACCOUNT', required - `toolkitSlug` string, required - `val` object, required - `subdomain` string - `your-domain` string - `region` string - `shop` string - `account_url` string - `COMPANYDOMAIN` string - `extension` string - `form_api_base_url` string - `instanceEndpoint` string - `api_url` string - `borneo_dashboard_url` string - `proxy_username` string - `proxy_password` string - `domain` string - `version` string - `dc` string - `site_name` string - `instanceName` string - `account_id` string - `your_server` string - `server_location` string - `base_url` string - `credentials_json` string, required - object - `authScheme` 'S2S_OAUTH2', required - `toolkitSlug` string, required - `val` object, required - `subdomain` string - `your-domain` string - `region` string - `shop` string - `account_url` string - `COMPANYDOMAIN` string - `extension` string - `form_api_base_url` string - `instanceEndpoint` string - `api_url` string - `borneo_dashboard_url` string - `proxy_username` string - `proxy_password` string - `domain` string - `version` string - `dc` string - `site_name` string - `instanceName` string - `account_id` string - `your_server` string - `server_location` string - `base_url` string - `access_token` string, required - `token_type` string - `client_id` string - `client_secret` string - `expires_in` union - number - string - unknown - `expires_at` string - `scope` union - string - string[] - unknown - `arguments` object — Key-value pairs of arguments required by the tool (mutually exclusive with text) - `text` string — Natural language description of the task to perform (mutually exclusive with arguments) - `allow_tracing` boolean, nullable — Deprecated. Enable debug tracing for tool execution (useful for debugging) ## Response `200` Successfully executed action and received response - object - `data` object, required — Tool execution output data that varies based on the specific tool - `error` string, nullable, required — Error message if the tool execution was not successful (null if successful) - `successful` boolean, required — Indicates if the tool execution was successful - `session_info` unknown - `log_id` string — Unique identifier for the execution log (useful for debugging and support) ## Other responses - `400` — Bad request - Invalid request parameters, missing required arguments, or conflicting parameters - `401` — Unauthorized - Authentication credentials are missing or invalid - `403` — Forbidden - Connected account does not have permission to execute this tool or access the requested resource - `404` — Not found - Tool or connected account not found - `408` — Request timeout - Tool execution exceeded the maximum allowed time - `410` — Gone - Tool has been deprecated and is no longer available - `413` — Payload too large - Request or response payload exceeds size limits - `422` — Unprocessable entity - Invalid state of the connected account - `429` — Rate limit exceeded - Too many requests to the tool or underlying API - `500` — Internal server error - Something went wrong on the server - `501` — Not implemented - `502` — Bad gateway - Error communicating with the tool provider API - `503` — Upstream service unavailable - Tool provider API is currently down or unavailable --- [API](https://skmtc.net/composiohq/apis/composio-platform-api-v3-1.md) · [All operations](https://skmtc.net/composiohq/apis/composio-platform-api-v3-1/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/composiohq/composio-platform-api-v3-1/revisions/4239836857f8/schema)