Skip to main content
The Raven API is organized around REST. It accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes.

​
Base URL

http://localhost:4000

​
Two APIs, One Gateway

Raven has two distinct API surfaces:
APIBase PathAuthenticationPurpose
Proxy API/v1/Virtual key (Bearer token)Send LLM requests through the gateway
Management API/Session cookie or Bearer tokenManage providers, keys, guardrails, etc.

​
Proxy API

The proxy API handles AI requests. It is OpenAI-compatible: 
POST http://localhost:4000/v1/chat/completions
Authorization: Bearer rk_live_...

​
Management API

The management API handles resource configuration: 
GET http://localhost:4000/providers
Authorization: Bearer rk_live_...
X-Org-Id: org_abc123

​
Authentication

Two authentication methods are supported. See Authentication for full details.
MethodUsed ForHeader
Virtual keyProxy API and management APIAuthorization: Bearer rk_live_...
Session cookieDashboard (web app)Set automatically by the browser

​
Request Format

All requests should include: 
Content-Type: application/json
Authorization: Bearer <your-virtual-key>
For management API requests, include the organization ID: 
X-Org-Id: <your-organization-id>

​
Response Format

​
Success

Successful responses return JSON with the relevant data: 
{
  "id": "prov_abc123",
  "provider": "openai",
  "name": "Production OpenAI",
  "isEnabled": true,
  "createdAt": "2025-01-15T10:00:00Z"
}
List endpoints return arrays: 
[
  { "id": "prov_abc123", "provider": "openai", "name": "Production" },
  { "id": "prov_def456", "provider": "anthropic", "name": "Backup" }
]

​
Errors

Errors return a consistent structure: 
{
  "error": {
    "type": "validation_error",
    "message": "Provider name is required"
  }
}

​
HTTP Status Codes

CodeDescriptionCommon Causes
200SuccessRequest completed successfully
201CreatedResource created successfully
400Bad RequestInvalid input, missing required fields, unsupported model
401UnauthorizedMissing or invalid API key
402Payment RequiredBudget exceeded
403ForbiddenIP not in allowlist, insufficient permissions, data residency violation
404Not FoundResource does not exist
409ConflictResource already exists (e.g., duplicate domain)
413Payload Too LargeRequest body exceeds size limit
429Rate LimitedRate limit exceeded
500Internal Server ErrorUnexpected server error

​
Rate Limits

Rate limits are applied per virtual key. When exceeded, the API returns 429 Too Many Requests. See Rate Limiting for configuration details.

​
Versioning

The chat completions endpoint is versioned under /v1: 
POST /v1/chat/completions
Management API endpoints are unversioned: 
GET  /providers
POST /providers
GET  /keys
POST /keys

​
Request IDs

Every response includes an X-Request-ID header for tracing: 
X-Request-ID: req_abc123def456
Include this ID when contacting support about specific requests.

​
Raven-Specific Headers

Proxy responses include additional headers:
HeaderDescription
X-Raven-ProviderProvider that handled the request
X-Raven-ModelModel that was used
X-Raven-Latency-MsTotal request latency in milliseconds
X-Guardrail-WarningsGuardrail warnings, if any

​
BYOK (Bring Your Own Key)

You can provide your own provider API key for a request using the X-Provider-Key header: 
X-Provider-Key: sk-your-openai-key
When X-Provider-Key is present, that key is used instead of the organization’s stored provider key. All gateway features (logging, guardrails, rate limiting, budgets) still apply.

​
Next Steps

Authentication

Learn about auth methods and virtual keys.

Chat Completions

Send your first LLM request.