HTTP tools
See the HTTP tools guide for how a tool’s request is built.
Paths are relative to /api/workspaces/{workspaceId}.
| Method | Path | Does |
|---|---|---|
GET |
/tools/ |
List tools |
POST |
/tools/ |
Create a tool |
PATCH |
/tools/{toolId} |
Update |
DELETE |
/tools/{toolId} |
Delete |
Create a tool
Section titled “Create a tool”curl -X POST https://<host>/api/workspaces/{workspaceId}/tools/ \ -H "Authorization: Bearer $KATA_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "get_order", "description": "Look up an order by its id.", "method": "GET", "url": "https://api.example.com/orders/{orderId}", "parameters": [ { "name": "orderId", "type": "string", "description": "The order id", "required": true } ] }'| Field | Required | Notes |
|---|---|---|
name |
yes | |
url |
yes | May contain {placeholders} |
method |
no | GET (default), POST, PUT, PATCH, DELETE |
description |
no | Tells the bot when to use it |
parameters |
no | name, type (string / number / boolean), description, required |
access |
no | Role slug → none / read / write. See below |
Who may use a tool
Section titled “Who may use a tool”There is no per-bot attachment. Every bot gets every tool the role of the person
it works for may use. GET counts as read; every other method writes:
none— the role’s runs never see the tool.read—GETtools only. The default for every role but admin.write— every method. The default for admin.
The owner always has write. A run with no person behind it gets no tools.
GET /tools/ returns each tool’s access per role; PATCH changes only the
roles named:
curl -X PATCH https://<host>/api/workspaces/{workspaceId}/tools/{toolId} \ -H "Authorization: Bearer $KATA_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "access": { "admin": "write", "member": "none" } }'