Composio Tools API

openapi: 3.0.0
info:
  version: 3.0.0
  title: Composio Platform Account Management Tools API
  description: Tool execution endpoints
  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: Tools
  description: Tool execution endpoints
paths:
  /api/v3/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: []
      - CookieAuth: []
      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'
  /api/v3/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: []
      - CookieAuth: []
      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'
  /api/v3/tools/{tool_slug}:
    get:
      summary: Get tool by slug
      description: Retrieve detailed information about a specific tool using its slug identifier. This endpoint returns full metadata about a tool including input/output parameters, versions, and toolkit information.
      tags:
      - Tools
      operationId: getToolsByToolSlug
      security:
      - ApiKeyAuth: []
      - UserApiKeyAuth: []
      - CookieAuth: []
      parameters:
      - schema:
          type: string
        required: true
        description: The unique slug identifier of the tool
        name: tool_slug
        in: path
      - schema:
          type: string
        required: false
        description: Optional version of the tool to retrieve
        name: version
        in: query
      - schema:
          oneOf:
          - type: 'null'
          - type: string
          - type: object
            additionalProperties:
              type: string
            description: Object representation of parsed bracket notation
        required: false
        description: Toolkit version specification. Use "latest" for latest versions or bracket notation for specific versions per toolkit.
        in: query
        name: toolkit_versions
        examples:
          latest_version:
            summary: Latest version for all toolkits
            value: latest
          bracket_notation:
            summary: Specific versions using bracket notation
            value: 'Use: toolkit_versions[gmail]=20250930_00&toolkit_versions[slack]=20250929_00'
          null_value:
            summary: No version specified (uses 00000000_00)
            value: null
      responses:
        '200':
          description: Successfully retrieved tool details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Tool'
        '400':
          description: Bad request - Invalid tool slug format
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized - Authentication credentials are missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found - Tool with the specified slug does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error - Something went wrong on the server
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v3/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: []
      - CookieAuth: []
      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:
                        nullable: true
                      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:
                  oneOf:
                  - type: object
                    properties:
                      authScheme:
                        type: string
                        enum:
                        - 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
                          scope:
                            anyOf:
                            - type: string
                            - type: array
                              items:
                                type: string
                            - nullable: true
                          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:
                              nullable: true
                        required:
                        - access_token
                        additionalProperties:
                          nullable: true
                    required:
                    - authScheme
                    - toolkitSlug
                    - val
                  - type: object
                    properties:
                      authScheme:
                        type: string
                        enum:
                        - DCR_OAUTH
                      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
                          client_id:
                            type: string
                            description: Dynamically registered client ID
                          client_secret:
                            type: string
                            description: Dynamically registered client secret
                          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
                          scope:
                            anyOf:
                            - type: string
                            - type: array
                              items:
                                type: string
                            - nullable: true
                          client_id_issued_at:
                            type: number
                          client_secret_expires_at:
                            type: number
                        required:
                        - client_id
                        - access_token
                        additionalProperties:
                          nullable: true
                    required:
                    - authScheme
                    - toolkitSlug
                    - val
                  - type: object
                    properties:
                      authScheme:
                        type: string
                        enum:
                        - API_KEY
                      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
                          generic_api_key:
                            type: string
                          api_key:
                            type: string
                          bearer_token:
                            type: string
                          basic_encoded:
                            type: string
                        additionalProperties:
                          nullable: true
                    required:
                    - authScheme
                    - toolkitSlug
                    - val
                  - type: object
                    properties:
                      authScheme:
                        type: string
                        enum:
                        - BASIC_WITH_JWT
                      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
                          username:
                            type: string
                          password:
                            type: string
                        required:
                        - username
                        - password
                        additionalProperties:
                          nullable: true
                    required:
                    - authScheme
                    - toolkitSlug
                    - val
                  - type: object
                    properties:
                      authScheme:
                        type: string
                        enum:
                        - BASIC
                      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
                          username:
                            type: string
                          password:
                            type: string
                        required:
                        - username
                        additionalProperties:
                          nullable: true
                    required:
                    - authScheme
                    - toolkitSlug
                    - val
                  - type: object
                    properties:
                      authScheme:
                        type: string
                        enum:
                        - BEARER_TOKEN
                      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
      

# --- truncated at 32 KB (107 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/composio/refs/heads/main/openapi/composio-tools-api-openapi.yml