Environments let you maintain separate configurations for the same routes and secrets across stages like production, staging, and development. Each environment can override a route’s target URL, injected headers, rate limits, and more.
Every tenant starts with a default production environment. You can create additional environments based on your subscription plan.
List Environments
Returns all environments for your tenant (not paginated — returns the full list).
Response
{
"data": [
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"name": "production",
"display_name": "Production",
"description": "Live production environment",
"color": "#22c55e",
"is_default": true,
"created_at": "2026-01-01T00:00:00.000Z"
},
{
"id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"name": "staging",
"display_name": "Staging",
"description": "Pre-production testing",
"color": "#f59e0b",
"is_default": false,
"created_at": "2026-01-15T10:00:00.000Z"
}
],
"meta": { "request_id": "550e8400-e29b-41d4-a716-446655440000" }
}
curl https://api.knoxcall.com/v1/environments \
-H "Authorization: Bearer tk_live_abc123..."
Create Environment
Creates a new environment.
Request Body
| Field | Type | Required | Description |
|---|
name | string | Yes | Machine-friendly name. Must match ^[a-z0-9_-]+$ (lowercase alphanumeric, hyphens, underscores) |
display_name | string | No | Human-friendly display name |
description | string | No | Description of the environment |
color | string | No | Hex color code for the UI (defaults to #6366f1) |
is_default | boolean | No | Whether this is the default environment (defaults to false) |
Response
Returns the created environment object.
curl -X POST https://api.knoxcall.com/v1/environments \
-H "Authorization: Bearer tk_live_abc123..." \
-H "Content-Type: application/json" \
-d '{
"name": "staging",
"display_name": "Staging",
"description": "Pre-production testing",
"color": "#f59e0b"
}'
Errors
| Status | Type | Description |
|---|
| 400 | validation_error | Invalid name format or missing required field |
| 403 | plan_limit | Environments not available on your plan, or environment limit reached |
| 409 | conflict | An environment with this name already exists |
Update Environment
PATCH /v1/environments/:id
Path Parameters
| Parameter | Type | Description |
|---|
id | uuid | The environment ID |
Request Body
All fields are optional. Only provided fields will be updated.
| Field | Type | Description |
|---|
name | string | Machine-friendly name (must match ^[a-z0-9_-]+$) |
display_name | string | Human-friendly display name |
description | string | Description |
color | string | Hex color code |
is_default | boolean | Set as default environment |
Response
Returns the updated environment object.
Errors
| Status | Type | Description |
|---|
| 400 | validation_error | Invalid name format |
| 404 | not_found | Environment not found |
| 409 | conflict | An environment with this name already exists |
Delete Environment
DELETE /v1/environments/:id
Path Parameters
| Parameter | Type | Description |
|---|
id | uuid | The environment ID |
Response
{
"data": { "deleted": true },
"meta": { "request_id": "550e8400-e29b-41d4-a716-446655440000" }
}
Errors
| Status | Type | Description |
|---|
| 400 | validation_error | Cannot delete the default environment |
| 404 | not_found | Environment not found |
| 409 | in_use | Environment is used by one or more route configurations |
