API reference

Tools

Tools let an agent take action — call an API, run a built-in function, look something up. Create tool configurations, test them, and assign them to bots. Read endpoints need tools:read; everything that changes state needs tools:write.

Endpoints

Method & path	Ability	Notes
`GET /api/v1/tools`	`tools:read`	List (no pagination)
`GET /api/v1/tools/catalog`	`tools:read`	Available tool types + presets
`GET /api/v1/tools/bot?bot_id=`	`tools:read`	A bot's assigned tools (`bot_id` required)
`GET /api/v1/tools/{id}`	`tools:read`	Full tool object
`POST /api/v1/tools`	`tools:write`	Create → `{ id }`
`PUT /api/v1/tools/{id}`	`tools:write`	Update → message only
`DELETE /api/v1/tools/{id}`	`tools:write`
`POST /api/v1/tools/{id}/test`	`tools:write`	Run with sample parameters
`POST /api/v1/tools/assign`	`tools:write`	Replace a bot's assignment set
`POST /api/v1/tools/discover`	`tools:write`	AI setup from API docs (SSE; JSON via `Accept`)

The tool object

id, tenant_id, tool_type, name, description, optional preset_id, is_default, is_active, optional created_by, metadata, created_at, updated_at, configuration (object, returned decrypted with secrets removed), and secrets_set (array of field names that have a secret stored).

Secrets are write-only. Raw secret values are never returned — the response only lists which fields have a secret set (secrets_set). Send secret values inside configuration when you create or update a tool.

Create a tool

POST /api/v1/tools → { id }. Body: tool_type (required), name (required), description (required), configuration (required — validated against the type's schema), plus optional preset_id and metadata. Use GET /api/v1/tools/catalog to discover the available tool_type values, their config schemas, and presets.

Assign tools to a bot

POST /api/v1/tools/assign replaces a bot's full set of tool assignments.

{
  "bot_id": "b1f2c3d4-…",
  "assignments": [
    {
      "tool_type": "http_request",
      "tool_configuration_id": "t0a1b2c3-…",
      "tool_instructions": "Use this to look up an order.",
      "speak_during_execution": true,
      "speak_after_execution": true,
      "tool_error_handling_mode": "passthrough"
    }
  ]
}

tool_error_handling_mode is passthrough or hide; tool_configuration_id is needed for tools that carry credentials.

Test a tool

POST /api/v1/tools/{id}/test with { "parameters": { … } } runs the tool and returns { success, execution_time_ms, error?, result, resolved_request? } — handy for validating a configuration before assigning it.

Discover from API docs

POST /api/v1/tools/discover reads an API's documentation and drafts a tool configuration for you. It streams as SSE by default, or returns JSON with Accept: application/json.