Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.kataven.ai/llms.txt

Use this file to discover all available pages before exploring further.

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

MethodPathSummary
GET/api/v1/toolsList tools
POST/api/v1/toolsCreate 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
NameInTypeRequiredDescription
categoryquerystringNoFilter by category
typequerystringNoFilter by implementation_type (python, http)
searchquerystringNoSubstring search on name, display_name, description
limitqueryintegerNoPage size (1-100, default 10)
offsetqueryintegerNoPagination offset (default 0)
Responses
CodeDescriptionBody
200OKhandlers.ListToolsResponse
400Missing X-Account-ID headerstring
500Database errorstring
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.
FieldTypeDescription
categorystringe.g. ecommerce
descriptionstringe.g. Look up an order by its ID. Returns status, line items, shipping address, and tracking links if available.
implementation_codestringe.g. `def run(args, context):
return get_order(args[‘order_id’])`
implementation_configobject
implementation_typestringe.g. http
namestringe.g. lookup_order
schemaobject
tagsarray<string>e.g. ['orders', 'ecommerce']
Responses
CodeDescriptionBody
201Createdobject
400Invalid bodystring
500Database errorstring
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
NameInTypeRequiredDescription
idpathstringYesTool id (uuid) or snake_case name
Responses
CodeDescriptionBody
200OKhandlers.Tool
404Tool not foundstring
500Database errorstring
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
NameInTypeRequiredDescription
idpathstringYesTool 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.
FieldTypeDescription
descriptionstringe.g. Updated description after Q2 schema change.
implementation_codestring
implementation_configobject
schemaobject
tagsarray<string>e.g. ['orders', 'ecommerce', 'q2']
Responses
CodeDescriptionBody
200OKobject
400Invalid bodystring
404Tool not foundstring
500Database errorstring
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
NameInTypeRequiredDescription
idpathstringYesTool id
Responses
CodeDescriptionBody
200OKobject
403Cannot delete default toolstring
500Database errorstring
Example 
curl https://api.kataven.ai/v1/tools/agent_01HZ2N... \
  -X DELETE \
  -H "Authorization: Bearer $KATAVEN_API_KEY"