API Reference

Gatekeeper API Reference

Complete reference for the Gatekeeper REST API. All endpoints are available at https://your-gatekeeper-host/v1 (or http://localhost:4000/v1 for local deployments).

Authentication

All requests require a Bearer token. Use your virtual key for application requests, or your master key for administrative operations (key management, usage queries).

curl http://localhost:4000/v1/chat/completions \
  -H "Authorization: Bearer sk-gk-myapp-xxxxxxxxxxxx"

Virtual keys (prefix sk-gk-) have scoped permissions and budget limits. Master keys (prefix sk-gk-master-) have full admin access.

/v1/chat/completions

OpenAI-compatible chat completions endpoint. Works with any OpenAI SDK — just change the base URL.

POST/v1/chat/completions

Create a chat completion. Compatible with the OpenAI Chat API format.

Parameter	Type	Required	Description
model	string	Yes	Model ID (e.g. gpt-4o, claude-3-5-sonnet-20241022)
messages	Message[]	Yes	Conversation history
stream	boolean	No	Enable SSE streaming
max_tokens	integer	No	Maximum tokens in response
temperature	number	No	Sampling temperature (0–2)

POST /v1/chat/completions

{
  "model": "gpt-4o",
  "messages": [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "What is 2+2?"}
  ],
  "stream": false
}

→ Response: standard OpenAI ChatCompletion object

/v1/messages

Anthropic-compatible Messages endpoint. Drop-in replacement for the Anthropic API — same format, same response shape. Works with the Anthropic Python and TypeScript SDKs.

POST/v1/messages

Create a message using the Anthropic Messages API format.

Parameter	Type	Required	Description
model	string	Yes	Anthropic model ID or alias
messages	Message[]	Yes	Conversation messages
max_tokens	integer	Yes	Maximum tokens in response
system	string	No	System prompt
stream	boolean	No	Enable streaming

This endpoint also accepts non-Anthropic models — Gatekeeper translates the Anthropic format to the appropriate provider format internally.

/v1/models

GET/v1/models

List all models available to your virtual key based on your team's allowlist.

GET /v1/models

{
  "data": [
    {
      "id": "gpt-4o",
      "object": "model",
      "provider": "openai",
      "context_length": 128000
    },
    {
      "id": "claude-3-5-sonnet-20241022",
      "object": "model",
      "provider": "anthropic",
      "context_length": 200000
    }
  ]
}

GET/v1/models/:id

Get details for a specific model.

Parameter	Type	Required	Description
id	string	Yes	Model ID

/v1/usage

GET/v1/usage

Query usage and cost data. Filter by time range, virtual key, model, or provider.

Parameter	Type	Required	Description
start_date	ISO 8601	No	Start of query range
end_date	ISO 8601	No	End of query range (defaults to now)
key_id	string	No	Filter by virtual key ID
model	string	No	Filter by model
provider	string	No	Filter by provider
group_by	string	No	Group by: day, key, model, provider

GET /v1/usage?start_date=2026-04-01&group_by=model

{
  "total_tokens": 4820000,
  "total_cost_usd": 48.20,
  "by_model": [
    {"model": "gpt-4o", "tokens": 2100000, "cost_usd": 21.00},
    {"model": "claude-3-5-sonnet-20241022", "tokens": 2720000, "cost_usd": 27.20}
  ]
}

/v1/keys

GET/v1/keys

List all virtual keys in your organization.

POST/v1/keys

Create a new virtual key.

Parameter	Type	Required	Description
name	string	Yes	Human-readable name
models	string[]	No	Allowed model IDs (default: all)
budget_limit	number	No	Monthly budget limit in USD
budget_period	string	No	daily \| weekly \| monthly (default: monthly)
expires_at	ISO 8601	No	Key expiry timestamp

DELETE/v1/keys/:id

Revoke a virtual key immediately. Active requests using this key will fail.

Parameter	Type	Required	Description
id	string	Yes	Key ID

PATCH/v1/keys/:id

Update key metadata: name, budget, model allowlist.

Parameter	Type	Required	Description
name	string	No	Rename the key
budget_limit	number	No	New budget limit
models	string[]	No	Updated model allowlist