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

GET /v1/ai-gateway/gateways

Returns your tenant’s gateways, paginated (page, per_page). Requires the read capability on ai_gateway.

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

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"]

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

{
  "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

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.

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
  }'

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 }:

{
  "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

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.

curl https://api.knoxcall.com/v1/ai-gateway/gateways/3f2a1c4e-8b9d-4e7a-9f1c-2d6e5a8b3c10 \
  -H "Authorization: Bearer tk_live_abc123..."

Update a gateway

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.

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

DELETE /v1/ai-gateway/gateways/{id}

Soft-deletes (archives) the gateway and returns its id and new status. Requires the write capability.

curl -X DELETE https://api.knoxcall.com/v1/ai-gateway/gateways/3f2a1c4e-8b9d-4e7a-9f1c-2d6e5a8b3c10 \
  -H "Authorization: Bearer tk_live_abc123..."

Response

{
  "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.

Overview

Routes

Secrets

Clients

Environments

API Keys

Webhooks

Ephemeral Proxy

AI Gateway

Audit Logs

Account

Tenant KMS

Secret Store Migrations

Gateways (v1)

Gateways

The gateway object

List gateways

Create a gateway

Get a gateway

Update a gateway

Archive a gateway

​Gateways

​The gateway object

​List gateways

​Create a gateway

​Get a gateway

​Update a gateway

​Archive a gateway

Gateways

The gateway object

List gateways

Create a gateway

Get a gateway

Update a gateway

Archive a gateway