> ## Documentation Index
> Fetch the complete documentation index at: https://docs.knoxcall.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Overview

> Learn how to authenticate and interact with the KnoxCall Management API

# API Overview

## Introduction

The KnoxCall REST API gives you full programmatic control over your API gateway configuration. You can manage routes, secrets, clients, environments, webhooks, and API keys -- everything available in the dashboard, accessible through a clean, predictable interface.

All API endpoints return JSON and follow consistent conventions for authentication, pagination, error handling, and response structure.

<Note>
  This API is for **managing** your KnoxCall configuration. To call the routes you've configured, send traffic to your tenant proxy URL (e.g., `https://{your-slug}.knoxcall.com/{your-route}`, or `https://sandbox-{your-slug}.knoxcall.com/{your-route}` in sandbox).
</Note>

## Base URLs

<CardGroup cols={2}>
  <Card title="Production" icon="server">
    ```text theme={"dark"}
    https://api.knoxcall.com/v1
    ```

    Use production API keys (`tk_` or `AKE` prefixed) for live operations.
  </Card>

  <Card title="Sandbox" icon="flask">
    ```text theme={"dark"}
    https://sandbox.knoxcall.com/v1
    ```

    Use test keys only. Data is isolated from production.
  </Card>
</CardGroup>

<Warning>
  Sandbox and production environments are completely isolated. API keys, routes, secrets, and all other resources created in one environment are not accessible from the other.
</Warning>

## Authentication

All requests to the KnoxCall API must include an API key. You can pass it in one of two ways:

| Method         | Header          | Example                                   |
| -------------- | --------------- | ----------------------------------------- |
| Bearer token   | `Authorization` | `Authorization: Bearer tk_live_abc123...` |
| API key header | `x-api-key`     | `x-api-key: tk_live_abc123...`            |

<CodeGroup>
  ```bash Authorization Header theme={"dark"}
  curl https://api.knoxcall.com/v1/routes \
    -H "Authorization: Bearer tk_live_abc123..."
  ```

  ```bash x-api-key Header theme={"dark"}
  curl https://api.knoxcall.com/v1/routes \
    -H "x-api-key: tk_live_abc123..."
  ```
</CodeGroup>

API keys are scoped per tenant and can be created in the [KnoxCall Dashboard](https://knoxcall.com) or via the [API Keys endpoint](/api-reference/api-keys).

For detailed information on key types, key creation, and security best practices, see the [Authentication guide](/api-reference/authentication).

## Response Format

Every response from the KnoxCall API follows a consistent JSON structure.

### Successful Response (Single Resource)

```json theme={"dark"}
{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Payment Gateway",
    "target_base_url": "https://api.stripe.com/v1",
    "enabled": true,
    "created_at": "2026-01-15T09:30:00Z"
  },
  "meta": {
    "request_id": "req_a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}
```

### Successful Response (List)

```json theme={"dark"}
{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Payment Gateway",
      "enabled": true
    },
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "name": "User Service",
      "enabled": true
    }
  ],
  "meta": {
    "total": 100,
    "page": 1,
    "per_page": 20,
    "total_pages": 5,
    "request_id": "req_a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}
```

### Error Response

```json theme={"dark"}
{
  "error": {
    "type": "not_found",
    "message": "Route not found",
    "request_id": "req_a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}
```

<Note>
  Every response includes a `request_id`. Include this ID when contacting support -- it allows us to trace the exact request through our systems.
</Note>

## Pagination

List endpoints support pagination via query parameters:

| Parameter  | Default      | Max   | Description                 |
| ---------- | ------------ | ----- | --------------------------- |
| `page`     | `1`          | --    | Page number to retrieve     |
| `per_page` | `20`         | `100` | Number of items per page    |
| `sort`     | `created_at` | --    | Field to sort by            |
| `order`    | `desc`       | --    | Sort order: `asc` or `desc` |

```bash theme={"dark"}
curl "https://api.knoxcall.com/v1/routes?page=2&per_page=50&sort=name&order=asc" \
  -H "Authorization: Bearer tk_live_abc123..."
```

The response `meta` object contains the total count and page information so you can build pagination controls:

```json theme={"dark"}
{
  "meta": {
    "total": 237,
    "page": 2,
    "per_page": 50,
    "total_pages": 5,
    "request_id": "req_..."
  }
}
```

## Rate Limiting

API requests are rate-limited per API key. When you exceed the limit, you will receive a `429` status code.

Rate limit information is included in the response headers:

| Header                  | Description                                               |
| ----------------------- | --------------------------------------------------------- |
| `X-RateLimit-Limit`     | Maximum requests allowed in the current window            |
| `X-RateLimit-Remaining` | Requests remaining in the current window                  |
| `Retry-After`           | Seconds to wait before retrying (only on `429` responses) |

<Warning>
  If you receive a `429` response, back off and retry after the number of seconds indicated by the `Retry-After` header. Continuing to send requests during a rate limit will not reset the window.
</Warning>

## Error Types

All errors return a consistent structure with a `type` field that you can use for programmatic error handling.

| Error Type                | HTTP Status | Description                                                         |
| ------------------------- | ----------- | ------------------------------------------------------------------- |
| `authentication_required` | 401         | No API key was provided in the request                              |
| `invalid_api_key`         | 401         | The API key is invalid, revoked, or expired                         |
| `wrong_key_type`          | 403         | A test key was used against production, or vice versa               |
| `subscription_inactive`   | 403         | The tenant's subscription is paused, cancelled, or past due         |
| `rate_limit_exceeded`     | 429         | Too many requests -- back off and retry                             |
| `validation_error`        | 400         | The request body or parameters failed validation                    |
| `not_found`               | 404         | The requested resource does not exist                               |
| `conflict`                | 409         | A resource with the same unique identifier already exists           |
| `in_use`                  | 409         | The resource cannot be deleted because other resources depend on it |
| `plan_limit`              | 402 / 403   | The tenant has reached a limit imposed by their current plan        |
| `internal_error`          | 500         | An unexpected server error occurred -- contact support              |

<Note>
  For `validation_error` responses, the `message` field contains a human-readable description of which field failed validation and why.
</Note>

## Quick Examples

### List all routes

<CodeGroup>
  ```bash cURL theme={"dark"}
  curl https://api.knoxcall.com/v1/routes \
    -H "Authorization: Bearer tk_live_abc123..."
  ```

  ```python Python theme={"dark"}
  import requests

  resp = requests.get(
      "https://api.knoxcall.com/v1/routes",
      headers={"Authorization": "Bearer tk_live_abc123..."}
  )
  routes = resp.json()["data"]
  ```

  ```javascript Node.js theme={"dark"}
  const resp = await fetch("https://api.knoxcall.com/v1/routes", {
    headers: { Authorization: "Bearer tk_live_abc123..." }
  });
  const { data: routes } = await resp.json();
  ```
</CodeGroup>

### Create a secret

<CodeGroup>
  ```bash cURL theme={"dark"}
  curl -X POST https://api.knoxcall.com/v1/secrets \
    -H "Authorization: Bearer tk_live_abc123..." \
    -H "Content-Type: application/json" \
    -d '{
      "name": "STRIPE_API_KEY",
      "value": "sk_live_..."
    }'
  ```

  ```python Python theme={"dark"}
  import requests

  resp = requests.post(
      "https://api.knoxcall.com/v1/secrets",
      headers={
          "Authorization": "Bearer tk_live_abc123...",
          "Content-Type": "application/json"
      },
      json={
          "name": "STRIPE_API_KEY",
          "value": "sk_live_..."
      }
  )
  secret = resp.json()["data"]
  ```

  ```javascript Node.js theme={"dark"}
  const resp = await fetch("https://api.knoxcall.com/v1/secrets", {
    method: "POST",
    headers: {
      Authorization: "Bearer tk_live_abc123...",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      name: "STRIPE_API_KEY",
      value: "sk_live_..."
    })
  });
  const { data: secret } = await resp.json();
  ```
</CodeGroup>

### Delete a client

<CodeGroup>
  ```bash cURL theme={"dark"}
  curl -X DELETE https://api.knoxcall.com/v1/clients/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
    -H "Authorization: Bearer tk_live_abc123..."
  ```

  ```python Python theme={"dark"}
  import requests

  resp = requests.delete(
      "https://api.knoxcall.com/v1/clients/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      headers={"Authorization": "Bearer tk_live_abc123..."}
  )
  result = resp.json()["data"]  # {"deleted": true}
  ```

  ```javascript Node.js theme={"dark"}
  const resp = await fetch("https://api.knoxcall.com/v1/clients/a1b2c3d4-e5f6-7890-abcd-ef1234567890", {
    method: "DELETE",
    headers: { Authorization: "Bearer tk_live_abc123..." }
  });
  const { data } = await resp.json();  // { deleted: true }
  ```
</CodeGroup>

## What's Next?

<CardGroup cols={2}>
  <Card title="Authentication" icon="lock" href="/api-reference/authentication">
    Learn about API key types, creation, and security best practices.
  </Card>

  <Card title="Routes" icon="route" href="/api-reference/routes">
    Create and manage your API proxy routes.
  </Card>

  <Card title="Secrets" icon="key" href="/api-reference/secrets">
    Store and inject sensitive credentials into your routes.
  </Card>

  <Card title="Clients" icon="users" href="/api-reference/clients">
    Control who can access your routes with API clients.
  </Card>
</CardGroup>