Skip to content

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
Окно терминала
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

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 — GET tools 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" } }'