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 live credentials — a minted kc_live_ OAuth token, or a production API key (tk_ / AKE prefixed).

Sandbox

https://sandbox.knoxcall.com/v1

Use test credentials (kc_test_ tokens or tk_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

Every request to the KnoxCall API must be authenticated. For new integrations we recommend one of the first-party SDKs — they handle OAuth 2.1 token minting, caching, refresh, and DPoP for you:

import { KnoxCall } from "@knoxcall/sdk";

const client = new KnoxCall(); // credentials from `knoxcall login` or KNOXCALL_CLIENT_ID / KNOXCALL_CLIENT_SECRET
const routes = await client.routes.list();

Calling the REST API directly, mint a short-lived OAuth 2.1 access token and pass it as a Bearer token. The curl examples on this page reuse $TOKEN from this mint:

# Mint a 1-hour OAuth token (client_credentials) — see /api-reference/authentication
TOKEN=$(curl -s -X POST https://api.knoxcall.com/oauth/token \
  -u "$KNOXCALL_CLIENT_ID:$KNOXCALL_CLIENT_SECRET" \
  -d "grant_type=client_credentials" | jq -r .access_token)

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

Long-lived API keys remain fully supported as a legacy alternative, passed in either header:

Method	Header	Example
Bearer token	`Authorization`	`Authorization: Bearer tk_live_abc123...`
API key header	`x-api-key`	`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 OAuth grant types, CLI login (knoxcall login), workload identity federation, key types, 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": "550e8400-e29b-41d4-a716-446655440000"
  }
}

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": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Error Response

Every error on /v1 returns the same canonical envelope — a single error object with a machine-readable type, a human-readable message, and a bare-UUID request_id:

{
  "error": {
    "type": "not_found",
    "message": "Route not found",
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

The request_id is a bare UUID (for example 550e8400-e29b-41d4-a716-446655440000) — it is not prefixed with req_. The same value is returned on every response (success or error) in the X-Request-Id header, so you can correlate a log line even when you never parsed the body. Quote it when contacting support and we can trace the exact request through our systems.

For the complete list of error types, how to branch on error.type, and correlation guidance, see the Errors reference.

Pagination

List endpoints support pagination via query parameters:

Parameter	Default	Max	Description
`page`	`1`	`floor(100000 / per_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 $TOKEN"

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": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Depth limit

Pagination is offset-based, and the server will not skip more than 100,000 rows. page is clamped to floor(100000 / per_page) + 1 — 1,001 pages at the maximum per_page of 100 — and total_pages is capped at the same value, so a loop that walks until page >= total_pages always terminates. meta.page is the effective page and always matches the rows you got back; if you ask for a deeper one you receive the last reachable page, not an error. meta.total keeps reporting the true row count, so when total is larger than total_pages × per_page you are past the depth limit. Narrow the result set with a filter — a date range, a status, a resource id — rather than paging further.

Rate Limiting

API requests are rate-limited per API key, enforced consistently across all API workers. When you exceed the limit you receive a 429 response with the rate_limit_exceeded error type. Rate-limit headers are returned on every response for which a limit is configured — not only on 429s — so you can track your remaining budget as you go:

Header	Description
`X-RateLimit-Limit`	Maximum requests allowed in the current window
`X-RateLimit-Remaining`	Requests remaining in the current window
`X-RateLimit-Reset`	Epoch seconds (UTC) at which the current window resets
`Retry-After`	Seconds to wait before retrying — sent 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.

See the Rate limits reference for backoff guidance and worked examples.

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
`forbidden`	403	The key is valid but lacks the role/scope required for this action (RBAC denial)
`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. Validation failures are always 400 — the only 422 on the API is idempotency_key_reuse (see Idempotency).

Mutating requests can also return idempotency errors — invalid_idempotency_key (400), request_in_progress (409), and idempotency_key_reuse (422). The complete type→status table, including these, lives in the Errors reference.

Quick Examples

List all routes

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

import os
import requests

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

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

Create a secret

curl -X POST https://api.knoxcall.com/v1/secrets \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "STRIPE_API_KEY",
    "value": "sk_live_..."
  }'

import os
import requests

resp = requests.post(
    "https://api.knoxcall.com/v1/secrets",
    headers={
        "Authorization": f"Bearer {os.environ['KNOXCALL_ACCESS_TOKEN']}",
        "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 ${process.env.KNOXCALL_ACCESS_TOKEN}`,
    "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 $TOKEN"

import os
import requests

resp = requests.delete(
    "https://api.knoxcall.com/v1/clients/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    headers={"Authorization": f"Bearer {os.environ['KNOXCALL_ACCESS_TOKEN']}"}
)
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 ${process.env.KNOXCALL_ACCESS_TOKEN}` }
});
const { data } = await resp.json();  // { deleted: true }

What’s Next?

Authentication

OAuth 2.1 + DPoP, CLI login, API key types, 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

Changelog

API Overview

API Overview

Introduction

Base URLs

Production

Sandbox

Authentication

Response Format

Successful Response (Single Resource)

Successful Response (List)

Error Response

Depth limit

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

​Depth limit

​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

Depth limit

Rate Limiting

Error Types

Quick Examples

List all routes

Create a secret

Delete a client

What’s Next?