Skip to main content

​
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, use your route’s unique proxy URL (e.g., https://proxy.knoxcall.com/v1/your-route-slug).

​
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:
MethodHeaderExample
Bearer tokenAuthorizationAuthorization: Bearer tk_live_abc123...
API key headerx-api-keyx-api-key: tk_live_abc123...
curl https://api.knoxcall.com/v1/routes \
  -H "Authorization: Bearer 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": "rt_8f3a1b2c",
    "name": "Payment Gateway",
    "slug": "payment-gateway",
    "method": "POST",
    "target_url": "https://api.stripe.com/v1/charges",
    "created_at": "2026-01-15T09:30:00Z"
  },
  "meta": {
    "request_id": "req_a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}

​
Successful Response (List)

{
  "data": [
    {
      "id": "rt_8f3a1b2c",
      "name": "Payment Gateway",
      "slug": "payment-gateway"
    },
    {
      "id": "rt_9d4e2f3a",
      "name": "User Service",
      "slug": "user-service"
    }
  ],
  "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:
ParameterDefaultMaxDescription
page1—Page number to retrieve
per_page20100Number of items per page
sortcreated_at—Field to sort by
orderdesc—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:
HeaderDescription
X-RateLimit-LimitMaximum requests allowed in the current window
X-RateLimit-RemainingRequests remaining in the current window
Retry-AfterSeconds 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 TypeHTTP StatusDescription
authentication_required401No API key was provided in the request
invalid_api_key401The API key is invalid, revoked, or expired
wrong_key_type403A test key was used against production, or vice versa
subscription_inactive403The tenant’s subscription is paused, cancelled, or past due
rate_limit_exceeded429Too many requests — back off and retry
validation_error400The request body or parameters failed validation
not_found404The requested resource does not exist
conflict409A resource with the same unique identifier already exists
in_use409The resource cannot be deleted because other resources depend on it
plan_limit403The tenant has reached a limit imposed by their current plan
internal_error500An 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..."

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

​
Delete a client

curl -X DELETE https://api.knoxcall.com/v1/clients/cl_7x9m2k4p \
  -H "Authorization: Bearer tk_live_abc123..."

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