Kataven Hub API — tools endpoints

Tools are functions an agent can call mid-conversation — built-in or custom Python. Wrapped by the Python SDK and Node SDK.

Endpoints at a glance

Method	Path	Summary
`GET`	`/api/v1/tools`	List tools
`POST`	`/api/v1/tools`	Create a custom tool
`GET`	`/api/v1/tools/{id}`	Get a single tool
`PUT`	`/api/v1/tools/{id}`	Update a tool
`DELETE`	`/api/v1/tools/{id}`	Delete a custom tool

Reference

`GET /api/v1/tools`

List tools Returns the catalog of tools available in this account, paginated and filterable. Includes category counts for filter UIs. Parameters

Name	In	Type	Required	Description
`category`	query	`string`	No	Filter by category
`type`	query	`string`	No	Filter by implementation_type (python, http)
`search`	query	`string`	No	Substring search on name, display_name, description
`limit`	query	`integer`	No	Page size (1-100, default 10)
`offset`	query	`integer`	No	Pagination offset (default 0)

Responses

Code	Description	Body
`200`	OK	`handlers.ListToolsResponse`
`400`	Missing X-Account-ID header	`string`
`500`	Database error	`string`

Example

curl https://api.kataven.ai/v1/tools \
  -H "Authorization: Bearer $KATAVEN_API_KEY"

`POST /api/v1/tools`

Create a custom tool Request body (application/json) Schema: handlers.CreateToolRequest. Server-set fields (id, created_at, updated_at, …) are ignored if supplied; only the user-settable fields are shown below.

Field	Type	Description
`category`	`string`	e.g. `ecommerce`
`description`	`string`	e.g. `Look up an order by its ID. Returns status, line items, shipping address, and tracking links if available.`
`implementation_code`	`string`	e.g. `def run(args, context):
return get_order(args[‘order_id’])`
`implementation_config`	`object`
`implementation_type`	`string`	e.g. `http`
`name`	`string`	e.g. `lookup_order`
`schema`	`object`
`tags`	`array<string>`	e.g. `['orders', 'ecommerce']`

Responses

Code	Description	Body
`201`	Created	`object`
`400`	Invalid body	`string`
`500`	Database error	`string`

Example

curl https://api.kataven.ai/v1/tools \
  -X POST \
  -H "Authorization: Bearer $KATAVEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "category": "ecommerce",
  "description": "Look up an order by its ID. Returns status, line items, shipping address, and tracking links if available.",
  "implementation_code": "def run(args, context):\n    return get_order(args['order_id'])",
  "implementation_type": "http",
  "name": "lookup_order",
  "tags": [
    "orders",
    "ecommerce"
  ]
}'

`GET /api/v1/tools/{id}`

Get a single tool Looks up the tool by uuid or by snake_case name. Returns 404 if neither matches. Parameters

Name	In	Type	Required	Description
`id`	path	`string`	Yes	Tool id (uuid) or snake_case name

Responses

Code	Description	Body
`200`	OK	`handlers.Tool`
`404`	Tool not found	`string`
`500`	Database error	`string`

Example

curl https://api.kataven.ai/v1/tools/agent_01HZ2N... \
  -H "Authorization: Bearer $KATAVEN_API_KEY"

`PUT /api/v1/tools/{id}`

Update a tool Patches description / schema / implementation_config / implementation_code / tags. Default tools are flipped to modified_from_default=TRUE so re-seeds skip them. Parameters

Name	In	Type	Required	Description
`id`	path	`string`	Yes	Tool id

Request body (application/json) Schema: handlers.UpdateToolRequest. Server-set fields (id, created_at, updated_at, …) are ignored if supplied; only the user-settable fields are shown below.

Field	Type	Description
`description`	`string`	e.g. `Updated description after Q2 schema change.`
`implementation_code`	`string`
`implementation_config`	`object`
`schema`	`object`
`tags`	`array<string>`	e.g. `['orders', 'ecommerce', 'q2']`

Responses

Code	Description	Body
`200`	OK	`object`
`400`	Invalid body	`string`
`404`	Tool not found	`string`
`500`	Database error	`string`

Example

curl https://api.kataven.ai/v1/tools/agent_01HZ2N... \
  -X PUT \
  -H "Authorization: Bearer $KATAVEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "description": "Updated description after Q2 schema change.",
  "tags": [
    "orders",
    "ecommerce",
    "q2"
  ]
}'

`DELETE /api/v1/tools/{id}`

Delete a custom tool Default (seeded) tools cannot be deleted — only custom ones. Returns 403 if the tool is default. Parameters

Name	In	Type	Required	Description
`id`	path	`string`	Yes	Tool id

Responses

Code	Description	Body
`200`	OK	`object`
`403`	Cannot delete default tool	`string`
`500`	Database error	`string`

Example

curl https://api.kataven.ai/v1/tools/agent_01HZ2N... \
  -X DELETE \
  -H "Authorization: Bearer $KATAVEN_API_KEY"

Get started

Resources

Kataven Hub API — tools endpoints

Endpoints at a glance

Reference

`GET /api/v1/tools`

`POST /api/v1/tools`

`GET /api/v1/tools/{id}`

`PUT /api/v1/tools/{id}`

`DELETE /api/v1/tools/{id}`

​Endpoints at a glance

​Reference

​GET /api/v1/tools

​POST /api/v1/tools

​GET /api/v1/tools/{id}

​PUT /api/v1/tools/{id}

​DELETE /api/v1/tools/{id}

Endpoints at a glance

Reference

`GET /api/v1/tools`

`POST /api/v1/tools`

`GET /api/v1/tools/{id}`

`PUT /api/v1/tools/{id}`

`DELETE /api/v1/tools/{id}`