> ## 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 — marketplace endpoints

> REST API reference for the Kataven marketplace — browse and install pre-built agent templates.

Browse and install pre-built agent templates. Wrapped by the [Python SDK](/sdks/python/marketplace) and [Node SDK](/sdks/node/marketplace).

## Endpoints at a glance

| Method | Path                                                                                    | Summary                                       |
| ------ | --------------------------------------------------------------------------------------- | --------------------------------------------- |
| `GET`  | [`/api/v1/marketplace/agents`](#get-api-v1-marketplace-agents)                          | List marketplace agent templates              |
| `GET`  | [`/api/v1/marketplace/agents/{id}`](#get-api-v1-marketplace-agents-id)                  | Get a marketplace agent template              |
| `POST` | [`/api/v1/marketplace/agents/{id}/install`](#post-api-v1-marketplace-agents-id-install) | Install a marketplace template as a new agent |
| `GET`  | [`/api/v1/marketplace/categories`](#get-api-v1-marketplace-categories)                  | List marketplace categories                   |

## Reference

### `GET /api/v1/marketplace/agents`

List marketplace agent templates

**Parameters**

| Name       | In    | Type      | Required | Description                          |
| ---------- | ----- | --------- | -------- | ------------------------------------ |
| `category` | query | `string`  | No       | Filter by category                   |
| `search`   | query | `string`  | No       | Substring search on 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.ListMarketplaceAgentsResponse`](#schemas) |
| `400` | Missing X-Account-ID header | `string`                                             |
| `500` | Database error              | `string`                                             |

**Example**

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

### `GET /api/v1/marketplace/agents/{id}`

Get a marketplace agent template

Returns the full template — system prompt, voice config, attached tools and playbooks.

**Parameters**

| Name | In   | Type     | Required | Description              |
| ---- | ---- | -------- | -------- | ------------------------ |
| `id` | path | `string` | Yes      | Agent template id (uuid) |

**Responses**

| Code  | Description     | Body                                |
| ----- | --------------- | ----------------------------------- |
| `200` | OK              | [`handlers.AgentVersion`](#schemas) |
| `404` | Agent not found | `string`                            |
| `500` | Database error  | `string`                            |

**Example**

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

### `POST /api/v1/marketplace/agents/{id}/install`

Install a marketplace template as a new agent

Creates a new agent in the caller's account from the template, copying its prompts, voice config, attached playbooks and FAQs. Optionally renames it.

**Parameters**

| Name | In   | Type     | Required | Description              |
| ---- | ---- | -------- | -------- | ------------------------ |
| `id` | path | `string` | Yes      | Agent template id (uuid) |

**Request body** (`application/json`)

Schema: `handlers.InstallTemplateRequest`. Server-set fields (`id`, `created_at`, `updated_at`, …) are ignored if supplied; only the user-settable fields are shown below.

| Field  | Type     | Description                |
| ------ | -------- | -------------------------- |
| `name` | `string` | e.g. `Front Desk (custom)` |

**Responses**

| Code  | Description     | Body     |
| ----- | --------------- | -------- |
| `200` | OK              | `object` |
| `404` | Agent not found | `string` |
| `500` | Database error  | `string` |

**Example**

<CodeGroup>
  ```bash curl theme={null}
  curl https://api.kataven.ai/v1/marketplace/agents/agent_01HZ2N.../install \
    -X POST \
    -H "Authorization: Bearer $KATAVEN_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "name": "Front Desk (custom)"
  }'
  ```
</CodeGroup>

### `GET /api/v1/marketplace/categories`

List marketplace categories

Returns the set of category labels that have at least one published marketplace template, with counts.

**Responses**

| Code  | Description    | Body     |
| ----- | -------------- | -------- |
| `200` | OK             | `object` |
| `500` | Database error | `string` |

**Example**

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