> ## 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.

# Kataven Hub API — tools endpoints

> REST API reference for Kataven tools — built-in tool catalog, custom tools, paginated listing with filters.

Tools are functions an agent can call mid-conversation — built-in or custom Python. Wrapped by the [Python SDK](/sdks/python/tools) and [Node SDK](/sdks/node/tools).

## Endpoints at a glance

| Method   | Path                                            | Summary              |
| -------- | ----------------------------------------------- | -------------------- |
| `GET`    | [`/api/v1/tools`](#get-api-v1-tools)            | List tools           |
| `POST`   | [`/api/v1/tools`](#post-api-v1-tools)           | Create a custom tool |
| `GET`    | [`/api/v1/tools/{id}`](#get-api-v1-tools-id)    | Get a single tool    |
| `PUT`    | [`/api/v1/tools/{id}`](#put-api-v1-tools-id)    | Update a tool        |
| `DELETE` | [`/api/v1/tools/{id}`](#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`](#schemas) |
| `400` | Missing X-Account-ID header | `string`                                 |
| `500` | Database error              | `string`                                 |

**Example**

<CodeGroup>
  ```bash curl theme={null}
  curl https://api.kataven.ai/v1/tools \
    -H "Authorization: Bearer $KATAVEN_API_KEY"
  ```
</CodeGroup>

### `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**

<CodeGroup>
  ```bash curl theme={null}
  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"
    ]
  }'
  ```
</CodeGroup>

### `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`](#schemas) |
| `404` | Tool not found | `string`                    |
| `500` | Database error | `string`                    |

**Example**

<CodeGroup>
  ```bash curl theme={null}
  curl https://api.kataven.ai/v1/tools/agent_01HZ2N... \
    -H "Authorization: Bearer $KATAVEN_API_KEY"
  ```
</CodeGroup>

### `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**

<CodeGroup>
  ```bash curl theme={null}
  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"
    ]
  }'
  ```
</CodeGroup>

### `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**

<CodeGroup>
  ```bash curl theme={null}
  curl https://api.kataven.ai/v1/tools/agent_01HZ2N... \
    -X DELETE \
    -H "Authorization: Bearer $KATAVEN_API_KEY"
  ```
</CodeGroup>