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

# List available tools

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



## OpenAPI

````yaml api-reference/openapi.json GET /api/v3.1/tools
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:
    get:
      tags:
        - Tools
      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.
      operationId: getTools
      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: >-
            DEPRECATED: This parameter will be removed in a future version.
            Filter directly instead with tool_slugs and toolkit_slug, which
            accepts a comma-separated list of toolkits.
          in: query
          name: auth_config_ids
          deprecated: true
        - 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
              - 'null'
            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:
            type: boolean
            default: false
          required: false
          description: >-
            Whether to include published pricing within instant, when available.
            Defaults to false.
          in: query
          name: include_pricing
        - 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. Defaults to the
            latest published version ("latest") when omitted.
          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
              - 'null'
          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'
      security:
        - ApiKeyAuth: []
        - UserApiKeyAuth: []
components:
  schemas:
    ToolsPaginated:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Tool'
        next_cursor:
          type:
            - string
            - 'null'
        total_pages:
          type: number
        current_page:
          type: number
        total_items:
          type: number
      required:
        - items
        - total_pages
        - current_page
        - total_items
    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
        instant:
          $ref: '#/components/schemas/InstantAccount'
        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
            - 'null'
          properties:
            all_of:
              type: array
              items:
                anyOf:
                  - type: string
                  - type: object
                    properties:
                      any_of:
                        type: array
                        items:
                          anyOf:
                            - type: string
                            - type: object
                              properties:
                                all_of:
                                  type: array
                                  items:
                                    type: string
                                  minItems: 1
                                source:
                                  type: array
                                  items:
                                    type: string
                                    minLength: 1
                                  minItems: 1
                              required:
                                - all_of
                        minItems: 1
                      when:
                        type: object
                        additionalProperties:
                          type: array
                          items:
                            type: string
                          minItems: 1
                      source:
                        type: array
                        items:
                          type: string
                          minLength: 1
                        minItems: 1
                    required:
                      - any_of
            source:
              type: array
              items:
                type: string
                minLength: 1
              minItems: 1
          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
    InstantAccount:
      type: object
      properties:
        supported:
          type: boolean
          enum:
            - true
        price:
          $ref: '#/components/schemas/ToolPricing'
      required:
        - supported
      description: >-
        Present only when the tool supports an Instant account and its selected
        toolkit version is the latest. Missing for older toolkit versions or
        ineligible tools.
    ToolPricing:
      type: object
      properties:
        description:
          type: string
          description: Human-readable pricing description.
        discount:
          type:
            - string
            - 'null'
          description: Discount on top of provider charges.
      description: Published pricing for the tool
      additionalProperties: false
  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

````