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

> REST API reference for Kataven third-party integrations — Stripe, Shopify, Slack with encrypted credentials.

Third-party integrations bundle a set of tools + required credentials. Wrapped by the [Python SDK](/sdks/python/integrations) and [Node SDK](/sdks/node/integrations).

## Endpoints at a glance

| Method | Path                                                                            | Summary                       |
| ------ | ------------------------------------------------------------------------------- | ----------------------------- |
| `GET`  | [`/api/v1/integrations`](#get-api-v1-integrations)                              | List third-party integrations |
| `GET`  | [`/api/v1/integrations/{id}`](#get-api-v1-integrations-id)                      | Get a single integration      |
| `POST` | [`/api/v1/integrations/{id}/install`](#post-api-v1-integrations-id-install)     | Install an integration        |
| `POST` | [`/api/v1/integrations/{id}/uninstall`](#post-api-v1-integrations-id-uninstall) | Uninstall an integration      |
| `GET`  | [`/api/v1/mcp-connections`](#get-api-v1-mcp-connections)                        | List MCP connections (stub)   |
| `GET`  | [`/api/v1/native-tools`](#get-api-v1-native-tools)                              | List native tools (stub)      |

## Reference

### `GET /api/v1/integrations`

List third-party integrations

Returns the catalog of third-party integrations (Stripe, Shopify, ...) for this tenant. Includes per-category counts.

**Parameters**

| Name       | In    | Type     | Required | Description                                     |
| ---------- | ----- | -------- | -------- | ----------------------------------------------- |
| `category` | query | `string` | No       | Filter by category                              |
| `status`   | query | `string` | No       | Filter by install status (available, installed) |

**Responses**

| Code  | Description                 | Body     |
| ----- | --------------------------- | -------- |
| `200` | OK                          | `object` |
| `400` | Missing X-Account-ID header | `string` |
| `500` | Database error              | `string` |

**Example**

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

### `GET /api/v1/integrations/{id}`

Get a single integration

**Parameters**

| Name | In   | Type     | Required | Description                               |
| ---- | ---- | -------- | -------- | ----------------------------------------- |
| `id` | path | `string` | Yes      | Integration id (uuid) or snake\_case name |

**Responses**

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

**Example**

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

### `POST /api/v1/integrations/{id}/install`

Install an integration

Stores params (plaintext) and secrets (encrypted) supplied by the caller, then flips the integration row's status to 'installed'. Empty body installs without params.

**Parameters**

| Name | In   | Type     | Required | Description                   |
| ---- | ---- | -------- | -------- | ----------------------------- |
| `id` | path | `string` | Yes      | Integration id (uuid) or name |

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

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

| Field     | Type     | Description                                                      |
| --------- | -------- | ---------------------------------------------------------------- |
| `params`  | `object` | e.g. `{'api_version': '2024-09', 'region': 'us-east-1'}`         |
| `secrets` | `object` | e.g. `{'api_key': 'sk_live_...', 'webhook_secret': 'whsec_...'}` |

**Responses**

| Code  | Description                           | Body     |
| ----- | ------------------------------------- | -------- |
| `200` | OK                                    | `object` |
| `404` | Integration not found                 | `string` |
| `500` | Database error                        | `string` |
| `503` | Secret encryption service unavailable | `string` |

**Example**

<CodeGroup>
  ```bash curl theme={null}
  curl https://api.kataven.ai/v1/integrations/agent_01HZ2N.../install \
    -X POST \
    -H "Authorization: Bearer $KATAVEN_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "params": {
      "api_version": "2024-09",
      "region": "us-east-1"
    },
    "secrets": {
      "api_key": "sk_live_...",
      "webhook_secret": "whsec_..."
    }
  }'
  ```
</CodeGroup>

### `POST /api/v1/integrations/{id}/uninstall`

Uninstall an integration

Flips status back to 'available' and clears installed\_at. Stored params/secrets are NOT purged.

**Parameters**

| Name | In   | Type     | Required | Description                   |
| ---- | ---- | -------- | -------- | ----------------------------- |
| `id` | path | `string` | Yes      | Integration id (uuid) or name |

**Responses**

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

**Example**

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

### `GET /api/v1/mcp-connections`

List MCP connections (stub)

Returns an empty list — endpoint reserved for future use.

**Responses**

| Code  | Description                 | Body     |
| ----- | --------------------------- | -------- |
| `200` | OK                          | `object` |
| `400` | Missing X-Account-ID header | `string` |

**Example**

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

### `GET /api/v1/native-tools`

List native tools (stub)

Returns an empty list — endpoint reserved for future use.

**Responses**

| Code  | Description                 | Body     |
| ----- | --------------------------- | -------- |
| `200` | OK                          | `object` |
| `400` | Missing X-Account-ID header | `string` |

**Example**

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