Skip to main content
The API tool type lets you define custom tools that make HTTP requests to external APIs. Each tool you define gets a name, a description, typed parameters, and a URL template. The agent calls these tools by name without needing to construct the HTTP request itself. This is useful for integrating agents with REST APIs that don’t have an MCP server, and for quick prototyping before building a full MCP integration.

​
Configuration

agents:
  assistant:
    model: openai/gpt-4o
    description: Assistant with weather access
    instruction: You can look up current weather information.
    toolsets:
      - type: api
        api_config:
          name: get_weather
          method: GET
          endpoint: "https://api.weather.example/v1/current?city=${city}"
          instruction: Get current weather for a city
          args:
            city:
              type: string
              description: City name
          required: [city]
          headers:
            Authorization: "Bearer ${env.WEATHER_API_KEY}"

​
Properties

​
api_config.name
string
required
Tool name. This is how the agent refers to the tool in calls.
​
api_config.method
string
required
HTTP method. Supports GET and POST.
​
api_config.endpoint
string
required
The URL. Use ${param} to interpolate parameter values. For GET requests, parameters can be interpolated into the URL. For POST requests, parameters are sent as JSON in the request body.
​
api_config.instruction
string
Description shown to the model. A clear description helps the agent choose the right tool and use it correctly.
​
api_config.args
object
Parameter definitions as JSON Schema properties.
​
api_config.required
array
List of required parameter names.
​
api_config.headers
object
HTTP headers to include in every request. Use ${env.VAR} to reference environment variables.
​
api_config.output_schema
object
Optional JSON Schema describing the response structure. Useful for MCP and Code Mode consumers.

​
GET requests

For GET requests, parameters are interpolated into the URL: 
toolsets:
  - type: api
    api_config:
      name: search_users
      method: GET
      endpoint: "https://api.example.com/users?q=${query}&limit=${limit}"
      instruction: Search for users by name
      args:
        query:
          type: string
          description: Search query
        limit:
          type: integer
          description: Maximum results
      required: [query]

​
POST requests

For POST requests, parameters are sent as JSON in the request body: 
toolsets:
  - type: api
    api_config:
      name: create_issue
      method: POST
      endpoint: "https://api.example.com/issues"
      instruction: Create a new issue
      args:
        title:
          type: string
          description: Issue title
        priority:
          type: string
          enum: [low, medium, high]
          description: Issue priority
      required: [title]
      headers:
        Content-Type: "application/json"
        Authorization: "Bearer ${env.API_TOKEN}"

​
Multiple tools on one agent

Add multiple api toolset entries to give the agent access to several endpoints:
api-tool.yaml
agents:
  root:
    model: google/gemini-2.5-pro
    description: Chess.com daily puzzle agent
    instruction: |
      Call the daily-puzzle tool and print the puzzle.
      Do not solve it — only provide hints.
    toolsets:
      - type: api
        api_config:
          name: daily-puzzle
          method: GET
          endpoint: https://api.chess.com/pub/puzzle
          instruction: Get today's chess puzzle
          output_schema:
            type: object
            properties:
              title:
                type: string
              url:
                type: string
              fen:
                type: string
                description: Board state in FEN notation

​
Limitations

  • Only GET and POST are supported.
  • Response body is limited to 1 MB.
  • Request timeout is 30 seconds.
  • Only http:// and https:// URLs are supported.
  • File uploads and multipart forms are not supported.
API keys and tokens in headers are visible in debug logs. Always use ${env.VAR} to reference secrets from the environment rather than hardcoding them in configuration files.
For APIs that need OAuth flows, pagination, or complex request handling, use an MCP server instead. See MCP toolsets for details.

Fetch

Make arbitrary HTTP requests at runtime.

Script

Run shell scripts as named tools.

Tools overview

Compare all built-in toolsets.

Configuration

Full toolset configuration reference.

Build docs developers (and LLMs) love

Get started for freeTalk to us