> ## Documentation Index
> Fetch the complete documentation index at: https://docs.knoxcall.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Gateways (v1)
> List, create, read, update, and archive AI Gateways over the public /v1 Management API.
# Gateways
A **gateway** is the top-level container for AI agents. It carries an optional daily/monthly USD budget that applies across its agents. These endpoints are the public `/v1` control-plane equivalent of the dashboard gateway pages — see the [control-plane overview](/api-reference/ai-gateway/control-plane-overview) for authentication, the response envelope, and error types.
Base path: `https://api.knoxcall.com/v1/ai-gateway/gateways`
## The gateway object
| Field | Type | Description |
| -------------------- | --------------------- | --------------------------------------------------------------------- |
| `id` | string (uuid) | Gateway identifier. |
| `tenant_id` | string (uuid) | Owning tenant. |
| `name` | string | Display name. |
| `slug` | string | URL-safe handle, unique per tenant. Set at creation and not editable. |
| `description` | string \| null | Free-text description. |
| `budget_daily_usd` | string \| null | Daily spend cap in USD (numeric, returned as a string). |
| `budget_monthly_usd` | string \| null | Monthly spend cap in USD. |
| `status` | string | One of `active`, `paused`, `archived`. |
| `paused_reason` | string \| null | Set when the gateway is paused. |
| `created_at` | string (ISO 8601) | Creation timestamp. |
| `updated_at` | string (ISO 8601) | Last-update timestamp. |
| `created_by` | string (uuid) \| null | API key / actor that created it. |
## List gateways
```http theme={"dark"}
GET /v1/ai-gateway/gateways
```
Returns your tenant's gateways, paginated (`page`, `per_page`). Requires the `read` capability on `ai_gateway`.
```bash cURL theme={"dark"}
curl "https://api.knoxcall.com/v1/ai-gateway/gateways?page=1&per_page=20" \
-H "Authorization: Bearer tk_live_abc123..."
```
```python Python theme={"dark"}
import requests
resp = requests.get(
"https://api.knoxcall.com/v1/ai-gateway/gateways",
headers={"Authorization": "Bearer tk_live_abc123..."},
params={"page": 1, "per_page": 20},
)
gateways = resp.json()["data"]
```
```javascript Node.js theme={"dark"}
const resp = await fetch(
"https://api.knoxcall.com/v1/ai-gateway/gateways?page=1&per_page=20",
{ headers: { Authorization: "Bearer tk_live_abc123..." } }
);
const { data: gateways } = await resp.json();
```
**Response**
```json theme={"dark"}
{
"data": [
{
"id": "3f2a1c4e-8b9d-4e7a-9f1c-2d6e5a8b3c10",
"tenant_id": "9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d",
"name": "Production",
"slug": "production",
"description": null,
"budget_daily_usd": "50.00",
"budget_monthly_usd": "1000.00",
"status": "active",
"paused_reason": null,
"created_at": "2026-05-01T00:00:00.000Z",
"updated_at": "2026-05-01T00:00:00.000Z",
"created_by": "1b2c3d4e-5f6a-7b8c-9d0e-1f2a3b4c5d6e"
}
],
"meta": {
"total": 1,
"page": 1,
"per_page": 20,
"total_pages": 1,
"request_id": "0d5b2a9e-1f3c-4a7d-8e2b-6c9a1f4d7e35"
}
}
```
## Create a gateway
```http theme={"dark"}
POST /v1/ai-gateway/gateways
```
Requires the `write` capability on `ai_gateway`.
**Request body**
| Field | Type | Description |
| -------------------- | ------ | --------------------------------------------------------------------------------------------------------------- |
| `name` | string | **Required.** Display name. |
| `slug` | string | **Required.** 2–64 lowercase alphanumerics/hyphens; must start and end with an alphanumeric. Unique per tenant. |
| `description` | string | Optional. |
| `budget_daily_usd` | number | Optional daily spend cap. |
| `budget_monthly_usd` | number | Optional monthly spend cap. |
```bash cURL theme={"dark"}
curl -X POST https://api.knoxcall.com/v1/ai-gateway/gateways \
-H "Authorization: Bearer tk_live_abc123..." \
-H "Content-Type: application/json" \
-d '{
"name": "Production",
"slug": "production",
"description": "Production AI egress",
"budget_daily_usd": 50.00,
"budget_monthly_usd": 1000.00
}'
```
```python Python theme={"dark"}
import requests
resp = requests.post(
"https://api.knoxcall.com/v1/ai-gateway/gateways",
headers={"Authorization": "Bearer tk_live_abc123..."},
json={
"name": "Production",
"slug": "production",
"description": "Production AI egress",
"budget_daily_usd": 50.00,
"budget_monthly_usd": 1000.00,
},
)
gateway = resp.json()["data"]
```
**Response** — the created gateway wrapped in `{ data, meta }`:
```json theme={"dark"}
{
"data": {
"id": "3f2a1c4e-8b9d-4e7a-9f1c-2d6e5a8b3c10",
"tenant_id": "9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d",
"name": "Production",
"slug": "production",
"description": "Production AI egress",
"budget_daily_usd": "50.00",
"budget_monthly_usd": "1000.00",
"status": "active",
"paused_reason": null,
"created_at": "2026-07-06T12:00:00.000Z",
"updated_at": "2026-07-06T12:00:00.000Z",
"created_by": "1b2c3d4e-5f6a-7b8c-9d0e-1f2a3b4c5d6e"
},
"meta": {
"request_id": "0d5b2a9e-1f3c-4a7d-8e2b-6c9a1f4d7e35"
}
}
```
Missing `name` or `slug` returns `400 validation`; an invalid slug returns `422 invalid_slug`; a duplicate slug returns `409 conflict`.
## Get a gateway
```http theme={"dark"}
GET /v1/ai-gateway/gateways/{id}
```
Returns a single gateway. Requires the `read` capability. Returns `404 not_found` if the gateway does not belong to your tenant.
```bash theme={"dark"}
curl https://api.knoxcall.com/v1/ai-gateway/gateways/3f2a1c4e-8b9d-4e7a-9f1c-2d6e5a8b3c10 \
-H "Authorization: Bearer tk_live_abc123..."
```
## Update a gateway
```http theme={"dark"}
PATCH /v1/ai-gateway/gateways/{id}
```
Partial update — all fields optional. Requires the `write` capability. The `slug` cannot be changed.
**Request body**
| Field | Type | Description |
| -------------------- | ------ | ----------------- |
| `name` | string | New display name. |
| `description` | string | New description. |
| `budget_daily_usd` | number | New daily cap. |
| `budget_monthly_usd` | number | New monthly cap. |
```bash theme={"dark"}
curl -X PATCH https://api.knoxcall.com/v1/ai-gateway/gateways/3f2a1c4e-8b9d-4e7a-9f1c-2d6e5a8b3c10 \
-H "Authorization: Bearer tk_live_abc123..." \
-H "Content-Type: application/json" \
-d '{ "budget_daily_usd": 75.00 }'
```
The response is the updated gateway wrapped in `{ data, meta }`.
## Archive a gateway
```http theme={"dark"}
DELETE /v1/ai-gateway/gateways/{id}
```
Soft-deletes (archives) the gateway and returns its id and new status. Requires the `write` capability.
```bash theme={"dark"}
curl -X DELETE https://api.knoxcall.com/v1/ai-gateway/gateways/3f2a1c4e-8b9d-4e7a-9f1c-2d6e5a8b3c10 \
-H "Authorization: Bearer tk_live_abc123..."
```
**Response**
```json theme={"dark"}
{
"data": {
"id": "3f2a1c4e-8b9d-4e7a-9f1c-2d6e5a8b3c10",
"status": "archived"
},
"meta": {
"request_id": "0d5b2a9e-1f3c-4a7d-8e2b-6c9a1f4d7e35"
}
}
```
Archiving a gateway does not change the status of its agents. The data plane gates each request on the **agent's** status, so an agent that is still `active` keeps serving traffic. To stop traffic, [archive the agents directly](/api-reference/ai-gateway/agents#archive-an-agent).