AutoGPT Tools API

openapi: 3.2.0
info:
  title: AutoGPT External Tools API
  description: External API for AutoGPT integrations
  version: '1.0'
servers:
- url: /external-api
tags:
- name: Tools
paths:
  /v1/tools/find-agent:
    post:
      tags:
      - Tools
      summary: Find Agent
      description: 'Search for agents in the marketplace based on capabilities and user needs.


        Args:

        request: Search query for finding agents


        Returns:

        List of matching agents or no results response'
      operationId: find_agent_v1_tools_find_agent_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FindAgentRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Find Agent V1 Tools Find Agent Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - APIKeyHeader: []
      - HTTPBearer: []
  /v1/tools/run-agent:
    post:
      tags:
      - Tools
      summary: Run Agent
      description: 'Run or schedule an agent from the marketplace.


        The endpoint automatically handles the setup flow:

        - Returns missing inputs if required fields are not provided

        - Returns missing credentials if user needs to configure them

        - Executes immediately if all requirements are met

        - Schedules execution if schedule_name and cron are provided


        For scheduled execution:

        - Cron format: "minute hour day month weekday"

        - Examples: "0 9 * * 1-5" (9am weekdays), "0 0 * * *" (daily at midnight)

        - Timezone: Use IANA timezone names like "America/New_York"


        Args:

        request: Agent slug, inputs, and optional schedule config


        Returns:

        - setup_requirements: If inputs or credentials are missing

        - execution_started: If agent was run or scheduled successfully

        - error: If something went wrong'
      operationId: run_agent_v1_tools_run_agent_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RunAgentRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Run Agent V1 Tools Run Agent Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - APIKeyHeader: []
      - HTTPBearer: []
components:
  schemas:
    RunAgentRequest:
      properties:
        username_agent_slug:
          type: string
          title: Username Agent Slug
          description: The marketplace agent slug (e.g., 'username/agent-name')
        inputs:
          additionalProperties: true
          type: object
          title: Inputs
          description: Dictionary of input values for the agent
        use_defaults:
          type: boolean
          title: Use Defaults
          description: Set to true to run with default values (user must confirm)
          default: false
        schedule_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Schedule Name
          description: Name for scheduled execution (triggers scheduling mode)
        cron:
          anyOf:
          - type: string
          - type: 'null'
          title: Cron
          description: 'Cron expression (5 fields: minute hour day month weekday)'
        timezone:
          type: string
          title: Timezone
          description: IANA timezone (e.g., 'America/New_York', 'UTC')
          default: UTC
      type: object
      required:
      - username_agent_slug
      title: RunAgentRequest
      description: 'Request to run or schedule an agent.


        The tool automatically handles the setup flow:

        - First call returns available inputs so user can decide what values to use

        - Returns missing credentials if user needs to configure them

        - Executes when inputs are provided OR use_defaults=true

        - Schedules execution if schedule_name and cron are provided'
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    FindAgentRequest:
      properties:
        query:
          type: string
          title: Query
          description: Search query for finding agents
      type: object
      required:
      - query
      title: FindAgentRequest
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key
    HTTPBearer:
      type: http
      scheme: bearer