Skip to content

Tools API

Define tools that assistants call at runtime — REST API requests, MCP servers, and rich content transforms.

Endpoints

Method	Path	Description
`GET`	`/api/v1/tools`	List tools
`POST`	`/api/v1/tools`	Create tool
`GET`	`/api/v1/tools/{id}`	Get tool
`PATCH`	`/api/v1/tools/{id}`	Update tool
`DELETE`	`/api/v1/tools/{id}`	Delete tool
`POST`	`/api/v1/tools/{id}/test`	Run test invocation

Requires API key or session auth.

Create API request tool

POST /api/v1/tools
Authorization: Bearer ch_live_xxx
Content-Type: application/json

{
  "name": "get_order_status",
  "description": "Look up an order by ID for the customer",
  "type": "api_request",
  "config": {
    "method": "GET",
    "url": "https://api.yourbusiness.com/orders/{order_id}",
    "credential_id": "cred_5hJ9kL2m",
    "path_params": {
      "order_id": { "type": "string", "required": true }
    },
    "result_transform": {
      "type": "product_card",
      "mapping": {
        "title": "$.product_name",
        "price": "$.total"
      }
    }
  },
  "strict_params": true
}

Create MCP tool

{
  "name": "inventory_lookup",
  "description": "Check warehouse stock via MCP",
  "type": "mcp",
  "config": {
    "transport": "sse",
    "url": "https://mcp.yourbusiness.com/sse",
    "credential_id": "cred_8nP1qR3s"
  }
}

Test tool

POST /api/v1/tools/tool_9aB2cD4e/test

{
  "parameters": {
    "order_id": "ORD-10482"
  }
}

Returns the raw API response, parsed parameters, and any rich content preview. Use this before attaching to a production assistant.

Tool types

Type	Description
`api_request`	HTTP call with stored credentials
`mcp`	Model Context Protocol server integration

Common errors

Status	Cause
`401` / `403` on test	Credential misconfigured or expired — see Tool 401/403
`422`	Invalid `result_transform` or missing required params