Routes - KnoxCall Docs

Routes are the core building block of KnoxCall. Each route defines a target upstream API that KnoxCall proxies requests to, along with configuration for secrets injection, rate limiting, request signing, and more.

These endpoints manage route configuration. To actually call a route you’ve configured, use your tenant’s unique proxy URL (e.g., https://{hash}.{slug}.knoxcall.com/your-route).

List Routes

GET /v1/routes

Returns a paginated list of all routes in your tenant.

Query Parameters

Parameter	Type	Default	Description
`page`	integer	`1`	Page number
`per_page`	integer	`20`	Items per page (max 100)
`sort`	string	`created_at`	Sort by: `created_at`, `name`, or `enabled`
`order`	string	`desc`	Sort direction: `asc` or `desc`
`enabled`	boolean	—	Filter by enabled status

Response

{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Payment Gateway",
      "target_base_url": "https://api.stripe.com/v1",
      "base_environment": "production",
      "enabled": true,
      "requires_clients": false,
      "collection_id": null,
      "created_at": "2026-01-15T09:30:00.000Z",
      "environment_override_count": 2,
      "require_signature": false,
      "rate_limit_enabled": true,
      "rate_limit_requests": 100,
      "rate_limit_window_sec": 60,
      "allowed_methods": ["GET", "POST"]
    }
  ],
  "meta": {
    "total": 24,
    "page": 1,
    "per_page": 20,
    "total_pages": 2,
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

curl "https://api.knoxcall.com/v1/routes?page=1&per_page=20" \
  -H "Authorization: Bearer tk_live_abc123..."

Get Route

GET /v1/routes/:id

Returns the full configuration for a single route, including injection rules, environment overrides, and payload structure.

Path Parameters

Parameter	Type	Description
`id`	uuid	The route ID

Response

{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Payment Gateway",
    "target_base_url": "https://api.stripe.com/v1",
    "base_environment": "production",
    "enabled": true,
    "requires_clients": false,
    "methods": null,
    "mtls_certificate_id": null,
    "collection_id": null,
    "created_at": "2026-01-15T09:30:00.000Z",
    "environment_override_count": 2,
    "payload_structure": null,
    "injection_rules": null,
    "ip_allowlist": null,
    "data_plane_node_id": null,
    "configured_environments": ["production", "staging"]
  },
  "meta": { "request_id": "550e8400-e29b-41d4-a716-446655440000" }
}

Errors

Status	Type	Description
404	`not_found`	Route not found

Create Route

POST /v1/routes

Creates a new route in your tenant.

Request Body

Field	Type	Required	Description
`name`	string	Yes	Display name for the route
`target_base_url`	string	Yes	The upstream API base URL to proxy requests to
`base_environment`	string	No	Default environment (defaults to `production`)
`inject_headers_json`	object	No	Headers to inject into proxied requests
`inject_body_json`	object	No	Body fields to inject into proxied requests
`injection_rules`	object[]	No	Advanced injection rules for secrets
`ip_allowlist`	string[]	No	IP addresses or CIDR ranges allowed to call this route
`method_configs`	object	No	Per-HTTP-method configuration overrides
`collection_id`	string	No	Assign to a collection

Response

Returns the created route object (same shape as Get Route).

curl -X POST https://api.knoxcall.com/v1/routes \
  -H "Authorization: Bearer tk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Payment Gateway",
    "target_base_url": "https://api.stripe.com/v1"
  }'

Errors

Status	Type	Description
400	`validation_error`	Missing required fields or invalid environment
403	`plan_limit`	Route limit reached for your subscription plan
409	`conflict`	A route with this name already exists

Update Route

PATCH /v1/routes/:id

Updates one or more fields on an existing route. Only include the fields you want to change.

Path Parameters

Parameter	Type	Description
`id`	uuid	The route ID

Request Body

All fields are optional. Only provided fields will be updated.

Field	Type	Description
`name`	string	Display name
`enabled`	boolean	Enable or disable the route
`requires_clients`	boolean	Whether requests must come from an authorized client
`target_base_url`	string	Upstream API base URL
`inject_headers_json`	object	Headers to inject
`inject_body_json`	object	Body fields to inject
`method_configs`	object	Per-HTTP-method configuration
`injection_rules`	object[]	Advanced injection rules
`require_signature`	boolean	Require request signature validation
`signature_tolerance_sec`	number	Signature timestamp tolerance in seconds
`rate_limit_enabled`	boolean	Enable rate limiting
`rate_limit_requests`	number	Max requests per window
`rate_limit_window_sec`	number	Rate limit window in seconds
`rate_limit_burst`	number	Burst allowance
`allowed_methods`	string[]	Restrict to specific HTTP methods
`http_method_restrictions_enabled`	boolean	Enable method restrictions
`egress_server_id`	string	Route through a specific egress/VPN server
`ip_allowlist`	string[]	Allowed IP addresses or CIDR ranges
`data_plane_node_id`	string	Assign to a specific data plane node

Response

Returns the updated route object.

Errors

Status	Type	Description
400	`validation_error`	No valid fields provided
404	`not_found`	Route not found

Delete Route

DELETE /v1/routes/:id

Permanently deletes a route and all of its environment overrides.

Path Parameters

Parameter	Type	Description
`id`	uuid	The route ID

Response

{
  "data": { "deleted": true },
  "meta": { "request_id": "550e8400-e29b-41d4-a716-446655440000" }
}

Errors

Status	Type	Description
404	`not_found`	Route not found

Get Route Logs

GET /v1/routes/:id/logs

Returns paginated request logs for a specific route, showing every proxied request with status, latency, and geographic data.

Path Parameters

Parameter	Type	Description
`id`	uuid	The route ID

Query Parameters

Parameter	Type	Default	Description
`page`	integer	`1`	Page number
`per_page`	integer	`20`	Items per page (max 100)

Response

{
  "data": [
    {
      "id": "log-uuid",
      "request_id": "req_a1b2c3d4",
      "ts": "2026-03-10T14:22:01.000Z",
      "src_ip": "203.0.113.42",
      "method": "POST",
      "path": "/v1/charges",
      "status_code": 200,
      "latency_ms": 187,
      "upstream_host": "api.stripe.com",
      "error": null,
      "environment": "production",
      "rate_limited": false,
      "signature_valid": true,
      "source_ip_country": "US",
      "source_ip_city": "San Francisco"
    }
  ],
  "meta": {
    "total": 1482,
    "page": 1,
    "per_page": 20,
    "total_pages": 75,
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Errors

Status	Type	Description
404	`not_found`	Route not found

List Route Environments

GET /v1/routes/:id/environments

Returns all environment-specific configuration overrides for a route.

Path Parameters

Parameter	Type	Description
`id`	uuid	The route ID

Response

[
  {
    "environment_name": "staging",
    "target_base_url": "https://api-staging.stripe.com/v1",
    "inject_headers_json": {},
    "inject_body_json": {},
    "require_signature": false,
    "signature_tolerance_sec": null,
    "rate_limit_enabled": false,
    "rate_limit_requests": null,
    "rate_limit_window_sec": null,
    "rate_limit_burst": null,
    "allowed_methods": null
  }
]

Errors

Status	Type	Description
404	`not_found`	Route not found

Set Route Environment Override

PUT /v1/routes/:id/environments/:env

Creates or replaces the environment-specific configuration for a route. This lets you point the same route at a different upstream URL, inject different headers, or apply different rate limits per environment.

Path Parameters

Parameter	Type	Description
`id`	uuid	The route ID
`env`	string	Environment name (e.g., `staging`, `development`)

Request Body

All fields are optional. Only provided fields will override the base route configuration for this environment.

Field	Type	Description
`target_base_url`	string	Override upstream URL
`inject_headers_json`	object	Override injected headers
`inject_body_json`	object	Override injected body fields
`require_signature`	boolean	Override signature requirement
`signature_tolerance_sec`	number	Override signature tolerance
`rate_limit_enabled`	boolean	Override rate limiting
`rate_limit_requests`	number	Override max requests
`rate_limit_window_sec`	number	Override window duration
`rate_limit_burst`	number	Override burst allowance
`allowed_methods`	string[]	Override allowed HTTP methods

Response

Returns the environment config object.

Errors

Status	Type	Description
400	`validation_error`	Invalid environment name
404	`not_found`	Route not found

Delete Route Environment Override

DELETE /v1/routes/:id/environments/:env

Removes the environment-specific override, reverting the route to its base configuration for that environment.

Path Parameters

Parameter	Type	Description
`id`	uuid	The route ID
`env`	string	Environment name

Response

{
  "deleted": true
}

Errors

Status	Type	Description
404	`not_found`	Route or environment config not found

API Overview

Endpoints

​List Routes

​Query Parameters

​Response

​Get Route

​Path Parameters

​Response

​Errors

​Create Route

​Request Body

​Response

​Errors

​Update Route

​Path Parameters

​Request Body

​Response

​Errors

​Delete Route

​Path Parameters

​Response

​Errors

​Get Route Logs

​Path Parameters

​Query Parameters

​Response

​Errors

​List Route Environments

​Path Parameters

​Response

​Errors

​Set Route Environment Override

​Path Parameters

​Request Body

​Response

​Errors

​Delete Route Environment Override

​Path Parameters

​Response

​Errors

List Routes

Query Parameters

Response

Get Route

Path Parameters

Response

Errors

Create Route

Request Body

Response

Errors

Update Route

Path Parameters

Request Body

Response

Errors

Delete Route

Path Parameters

Response

Errors

Get Route Logs

Path Parameters

Query Parameters

Response

Errors

List Route Environments

Path Parameters

Response

Errors

Set Route Environment Override

Path Parameters

Request Body

Response

Errors

Delete Route Environment Override

Path Parameters

Response

Errors