> ## Documentation Index
> Fetch the complete documentation index at: https://composio-preview.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Execute tool

> 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.



## OpenAPI

````yaml api-reference/openapi.json POST /api/v3.1/tools/execute/{tool_slug}
openapi: 3.1.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: Composio production API
security:
  - ApiKeyAuth: []
tags:
  - name: Authentication
    description: Authentication related endpoints
    x-group: Authentication
  - name: Auth Configs
    description: Authentication configuration management
    x-group: Auth Configs
  - name: Connected Accounts
    description: Connected account management
    x-group: Connected Accounts
  - name: Logs
    description: Logging and monitoring
    x-group: Logs
  - name: OpenAPI
    description: OpenAPI specification management
    x-group: OpenAPI
  - name: Organization
    description: Organization management
    x-group: Organization
  - name: API Keys
    description: API key management
    x-group: API Keys
  - name: Webhooks
    description: Webhook configuration
    x-group: Webhooks
  - name: Webhook Endpoints
    description: >-
      Per-OAuth-app webhook ingress endpoints. Inbound URLs the provider posts
      to, plus signing secret storage and verification.
    x-group: Webhook Endpoints
  - name: Webhook Subscriptions
    description: >-
      Webhook delivery subscriptions. Outbound URLs Composio posts trigger
      events to, plus signing secret rotation and event-type filters.
    x-group: Webhook Subscriptions
  - name: Team
    description: Team member management
    x-group: Team
  - name: Consumer Skills
    description: Organization-authored Skill management
    x-group: Consumer Skills
  - name: Toolkits
    description: Toolkit and tool management
    x-group: Toolkits
  - name: Tools
    description: Tool execution endpoints
    x-group: Tools
  - name: Triggers
    description: Trigger management and execution
    x-group: Triggers
  - name: Payments
    description: Payment and subscription management
    x-group: Payments
  - name: Billing
    description: Dashboard billing state — usage, subscription, contract (cookie-auth only)
    x-group: Billing
  - name: Compliance
    description: Organization compliance agreements and acceptance state
    x-group: Compliance
  - name: Files
    description: File management
    x-group: Files
  - name: MCP
    description: MCP server management
    x-group: MCP
  - name: MCP Partner
    description: MCP partner management
    x-group: MCP Partner
  - name: Stripe Projects
    description: Stripe Projects provisioning
    x-group: Stripe Projects
  - name: Tool Router
    description: (Labs) Tool router endpoints
    x-group: Sessions (Prev Tool Router)
  - name: Playground
    description: Dashboard playground chat
    x-group: Playground
  - name: Arena
    description: Arena conversations, messages and terms
    x-group: Arena
  - name: Projects
    description: Projects API endpoints.
    x-group: Projects
  - name: Organization Management
    description: Organization Management API endpoints.
    x-group: Organization Management
  - name: Webhook Events
    description: Events delivered by Composio to your registered webhook endpoints
    x-group: Webhook Events
paths:
  /api/v3.1/tools/execute/{tool_slug}:
    post:
      tags:
        - Tools
      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.
      operationId: postToolsExecuteByToolSlug
      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:
                  anyOf:
                    - type: string
                      enum:
                        - instant_account
                    - type: string
                      format: connectedAccountId
                  description: >-
                    Unique identifier for the connected account to use for
                    authentication. Pass `instant_account` to run the tool on
                    the Composio instant account for its toolkit, even when the
                    user has connected the toolkit themselves; the request fails
                    rather than falling back to another credential.
                  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 the latest published
                    version ("latest") when omitted.
                  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
                        displayName:
                          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
                            - 'null'
                        token_type:
                          type: string
                        refresh_token:
                          type:
                            - string
                            - 'null'
                        expires_in:
                          anyOf:
                            - type: number
                            - type: string
                            - type:
                                - object
                                - 'null'
                        scope:
                          anyOf:
                            - type: string
                            - type: array
                              items:
                                type: string
                            - type:
                                - object
                                - 'null'
                        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: {}
                  additionalProperties: true
                  required:
                    - authScheme
                    - toolkitSlug
                    - val
                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
                    - 'null'
                  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
                      - 'null'
                    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:
                    description: >-
                      Optional session information for tools that return session
                      context
                    example:
                      session_id: session-12345
                      expires_at: '2023-01-01T13:00:00Z'
                    type:
                      - object
                      - 'null'
                  log_id:
                    type: string
                    description: >-
                      Unique identifier for the execution log (useful for
                      debugging and support)
                    example: log_1a2b3c4d5e6f
                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'
        '402':
          description: >-
            Payment required - Wallet balance is exhausted; add credits to
            resume Instant tool calls or connect your account
          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'
      security:
        - ApiKeyAuth: []
        - UserApiKeyAuth: []
components:
  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
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        Your Composio project API key. Create or copy it from the Composio
        dashboard.
      x-default: your-project-api-key
    UserApiKeyAuth:
      type: apiKey
      in: header
      name: x-user-api-key
      description: Your Composio user API key for user-scoped endpoints.
      x-default: your-user-api-key

````