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.

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

Base URLs

Production

https://api.knoxcall.com/v1

Use production API keys (tk_ or AKE prefixed) for live operations.

Sandbox

https://sandbox.knoxcall.com/v1

Use test keys only. Data is isolated from production.

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.

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

curl https://api.knoxcall.com/v1/routes \
  -H "Authorization: Bearer tk_live_abc123..."

curl https://api.knoxcall.com/v1/routes \
  -H "x-api-key: tk_live_abc123..."

API keys are scoped per tenant and can be created in the KnoxCall Dashboard or via the API Keys endpoint. For detailed information on key types, key creation, and security best practices, see the Authentication guide.

Response Format

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

Successful Response (Single Resource)

{
  "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)

{
  "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

{
  "error": {
    "type": "not_found",
    "message": "Route not found",
    "request_id": "req_a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}

Every response includes a request_id. Include this ID when contacting support — it allows us to trace the exact request through our systems.

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`

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:

{
  "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)

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.

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

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

Quick Examples

List all routes

curl https://api.knoxcall.com/v1/routes \
  -H "Authorization: Bearer tk_live_abc123..."

import requests

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

const resp = await fetch("https://api.knoxcall.com/v1/routes", {
  headers: { Authorization: "Bearer tk_live_abc123..." }
});
const { data: routes } = await resp.json();

Create a secret

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_..."
  }'

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"]

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();

Delete a client

curl -X DELETE https://api.knoxcall.com/v1/clients/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer tk_live_abc123..."

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}

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 }

What’s Next?

Authentication

Learn about API key types, creation, and security best practices.

Routes

Create and manage your API proxy routes.

Secrets

Store and inject sensitive credentials into your routes.

Clients

Control who can access your routes with API clients.

Overview

Routes

Secrets

Clients

Environments

API Keys

Webhooks

Ephemeral Proxy

AI Gateway

Audit Logs

Account

Tenant KMS

Secret Store Migrations

API Overview

API Overview

Introduction

Base URLs

Production

Sandbox

Authentication

Response Format

Successful Response (Single Resource)

Successful Response (List)

Error Response

Rate Limiting

Error Types

Quick Examples

List all routes

Create a secret

Delete a client

What’s Next?

Authentication

Routes

Secrets

Clients

​API Overview

​Introduction

​Base URLs

Production

Sandbox

​Authentication

​Response Format

​Successful Response (Single Resource)

​Successful Response (List)

​Error Response

​Pagination

​Rate Limiting

​Error Types

​Quick Examples

​List all routes

​Create a secret

​Delete a client

​What’s Next?

Authentication

Routes

Secrets

Clients

API Overview

Introduction

Base URLs

Authentication

Response Format

Successful Response (Single Resource)

Successful Response (List)

Error Response

Pagination

Rate Limiting

Error Types

Quick Examples

List all routes

Create a secret

Delete a client

What’s Next?