API Tool

Table of contents

Create custom tools that call HTTP APIs.

Overview

The API tool type lets you define custom tools that make HTTP requests to external APIs. This is useful for integrating agents with REST APIs, webhooks, or any HTTP-based service without writing code.

Note
When to Use
Integrating with REST APIs that don't have an MCP server
Simple HTTP operations (GET, POST)
Quick prototyping before building a full MCP server

Configuration

agents:
  assistant:
    model: openai/gpt-4o
    description: Assistant with API access
    instruction: You can look up 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 to get weather for
          required: ["city"]
          headers:
            Authorization: "Bearer ${env.WEATHER_API_KEY}"

Properties

The api toolset accepts the following toolset-level fields in addition to the api_config block:

Property	Type	Required	Description
`api_config`	object	✓	The HTTP tool definition. See the table below.
`timeout`	int	✗	HTTP client timeout in seconds (default: `30`). Applies to every call the generated tool makes.
`allow_private_ips`	boolean	✗	Opt in to dialling non-public IP addresses (loopback, RFC1918, link-local — including the cloud-metadata endpoint at `169.254.169.254` — multicast and the unspecified address). Set to `true` only when the configured endpoint legitimately targets internal services. See Reaching internal services.

`api_config`

Property	Type	Required	Description
`name`	string	✓	Tool name (how the agent references it)
`method`	string	✓	HTTP method: `GET` or `POST`
`endpoint`	string	✓	URL endpoint (supports `${param}` interpolation)
`instruction`	string	✗	Description shown to the agent
`args`	object	✗	Parameter definitions (JSON Schema properties)
`required`	array	✗	List of required parameter names
`headers`	object	✗	HTTP headers to include. Values support `${env.VAR}` and `${headers.NAME}` placeholders (the latter forwards a header from the caller's incoming request, useful when docker agent is itself exposed as an HTTP server).
`output_schema`	object	✗	JSON Schema for the response. Used by MCP / Code Mode consumers; tool responses are still returned to the model as raw strings.

HTTP Methods

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 (default 10)
      required: ["query"]

POST Requests

For POST requests, parameters are sent as JSON in the request body:

toolsets:
  - type: api
    api_config:
      name: create_task
      method: POST
      endpoint: "https://api.example.com/tasks"
      instruction: Create a new task
      args:
        title:
          type: string
          description: Task title
        description:
          type: string
          description: Task description
        priority:
          type: string
          enum: ["low", "medium", "high"]
          description: Task priority
      required: ["title"]
      headers:
        Content-Type: "application/json"
        Authorization: "Bearer ${env.API_TOKEN}"

URL Interpolation

Use ${param} syntax to insert parameter values into URLs:

endpoint: "https://api.example.com/users/${user_id}/posts/${post_id}"

Parameter values are inserted as strings by the template expansion. Add URL encoding in the template when needed (for example, ${encodeURIComponent(city)}).

Headers

Headers can include environment variables:

headers:
  Authorization: "Bearer ${env.API_KEY}"
  X-Custom-Header: "static-value"
  Content-Type: "application/json"

Output Schema

Optionally document the expected response format:

toolsets:
  - type: api
    api_config:
      name: get_user
      method: GET
      endpoint: "https://api.example.com/users/${id}"
      instruction: Get user details by ID
      args:
        id:
          type: string
          description: User ID
      required: ["id"]
      output_schema:
        type: object
        properties:
          id:
            type: string
          name:
            type: string
          email:
            type: string
          created_at:
            type: string

Example: GitHub API

agents:
  github_assistant:
    model: openai/gpt-4o
    description: Assistant that can query GitHub
    instruction: You can look up GitHub repositories and users.
    toolsets:
      - type: api
        api_config:
          name: get_repo
          method: GET
          endpoint: "https://api.github.com/repos/${owner}/${repo}"
          instruction: Get information about a GitHub repository
          args:
            owner:
              type: string
              description: Repository owner (user or org)
            repo:
              type: string
              description: Repository name
          required: ["owner", "repo"]
          headers:
            Accept: "application/vnd.github.v3+json"
            Authorization: "Bearer ${env.GITHUB_TOKEN}"

      - type: api
        api_config:
          name: get_user
          method: GET
          endpoint: "https://api.github.com/users/${username}"
          instruction: Get information about a GitHub user
          args:
            username:
              type: string
              description: GitHub username
          required: ["username"]
          headers:
            Accept: "application/vnd.github.v3+json"

Limitations

Only supports GET and POST methods
Response body is limited to 1MB
Default 30-second timeout per request (override with the timeout field)
Only HTTP and HTTPS URLs are supported
No support for file uploads or multipart forms
By default, requests to non-public IP ranges (loopback, RFC1918, link-local, the cloud-metadata endpoint, multicast, the unspecified address) are refused at dial time — even when DNS for an otherwise-public host resolves there. Set allow_private_ips: true to disable that check.

Reaching internal services

toolsets:
  - type: api
    timeout: 60
    allow_private_ips: true
    api_config:
      name: get_local_status
      method: GET
      endpoint: "http://localhost:8080/health"
      instruction: Check the local service health

Warning
SSRF
Setting allow_private_ips: true re-exposes the SSRF surface for this tool. Only enable it when the configured endpoint is a trusted internal service — a prompt-injected agent cannot redirect the call elsewhere because the endpoint is fixed in config, but redirects from the configured host can still reach unexpected places.

Tip
For Complex APIs
For APIs that need authentication flows, pagination, or complex request/response handling, consider using an MCP server instead. The API tool is best for simple, stateless HTTP operations.

Warning
Security
API keys and tokens in headers are visible in debug logs. Use environment variables (${env.VAR}) rather than hardcoding secrets in configuration files.

What can I help you with?

API Tool