API / Overview

Overview

Browse docs

--- title: "API Overview" description: "Aurora exposes OpenAI-compatible and Anthropic-compatible APIs, plus provider-native passthrough routes and a built-in admin API." icon: "book-open" ---

Base URL

All API endpoints are served under the gateway base URL. Default:

code

http://your-aurora-host

With BASE_PATH=/g:

code

http://your-aurora-host/g/v1/...
http://your-aurora-host/g/admin/api/v1/...
http://your-aurora-host/g/health

Authentication

Authenticate with a Bearer token:

http

Authorization: Bearer <AURORA_MASTER_KEY or managed API key>

Requests without authentication use the default tenant and no user path. Managed API keys carry metadata (tenant, user_path, rate limits, allowed models) for scoped access.

Endpoint Categories

Category	Base Path	Documentation
OpenAI-Compatible API	`/v1/...`	Chat, embeddings, models, files, batches
Anthropic-Compatible API	`/v1/messages`	Anthropic-format messages (opt-in)
Provider Passthrough	`/p/{provider}/...`	Any HTTP method, provider-native
Admin API	`/admin/api/v1/...`	Gateway management, usage, policies
Dashboard UI	`/admin/dashboard`	Visual admin interface
Health & Metrics	`/health`, `/metrics`	Monitoring endpoints
Swagger UI	`/swagger/...`	Interactive API docs (debug mode)

OpenAI-Compatible Endpoints

Method	Endpoint	Description
`POST`	`/v1/chat/completions`	Create a chat completion
`POST`	`/v1/completions`	Legacy text completion (OpenAI compatibility)
`POST`	`/v1/embeddings`	Create embeddings
`POST`	`/v1/rerank`	Rerank documents by relevance
`GET`	`/v1/models`	List available models
`POST`	`/v1/responses`	Create a response (Beta)
`GET`	`/v1/responses/{id}`	Retrieve a stored response
`DELETE`	`/v1/responses/{id}`	Delete a stored response
`GET`	`/v1/responses/{id}/input_items`	Get normalized input items
`POST`	`/v1/responses/{id}/cancel`	Cancel an in-progress response
`POST`	`/v1/responses/input_tokens`	Count input tokens via provider utility
`POST`	`/v1/responses/compact`	Compact response input via provider utility
`GET`	`/v1/files`	List uploaded files
`POST`	`/v1/files`	Upload a file
`GET`	`/v1/files/{id}`	Get file metadata
`DELETE`	`/v1/files/{id}`	Delete a file
`GET`	`/v1/files/{id}/content`	Download file content
`POST`	`/v1/batches`	Create a batch job
`GET`	`/v1/batches`	List batch jobs
`GET`	`/v1/batches/{id}`	Get batch status
`POST`	`/v1/batches/{id}/cancel`	Cancel a batch job
`GET`	`/v1/batches/{id}/results`	Get batch results

Anthropic-Compatible Endpoint

Method	Endpoint	Description
`POST`	`/v1/messages`	Anthropic-format messages (enable with `ENABLE_ANTHROPIC_INGRESS=true`)

The /v1/messages endpoint follows the Anthropic Messages API shape. Use it when client code uses the Anthropic SDK with base URL pointed at Aurora.

Passthrough Endpoints

Method	Path	Description
Any	`/p/{provider}/{endpoint}`	Proxy provider-native requests without translation

Supports GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS.

Other Endpoints

Method	Path	Description
`GET`	`/health`	Health check (unauthenticated)
`GET`	`/metrics`	Prometheus metrics (when `METRICS_ENABLED=true`)

Error Format

Aurora returns OpenAI-compatible error responses:

json

{
  "error": {
    "type": "invalid_request_error",
    "message": "description of the error",
    "code": "error_code"
  }
}

Common error types: invalid_request_error, authentication_error, rate_limit_error, edition_restricted.

OpenAPI Spec

The complete API specification is available as openapi.json for use with API clients, code generation, and documentation tools.

Endpoint Categories

Category	Base Path	Documentation
OpenAI-Compatible API	`/v1/...`	Chat, embeddings, models, files, batches
Anthropic-Compatible API	`/v1/messages`	Anthropic-format messages (opt-in)
Provider Passthrough	`/p/{provider}/...`	Any HTTP method, provider-native
Admin API	`/admin/api/v1/...`	Gateway management, usage, policies
Dashboard UI	`/admin/dashboard`	Visual admin interface
Health & Metrics	`/health`, `/metrics`	Monitoring endpoints
Swagger UI	`/swagger/...`	Interactive API docs (debug mode)

OpenAI-Compatible Endpoints

Method	Endpoint	Description
`POST`	`/v1/chat/completions`	Create a chat completion
`POST`	`/v1/completions`	Legacy text completion (OpenAI compatibility)
`POST`	`/v1/embeddings`	Create embeddings
`POST`	`/v1/rerank`	Rerank documents by relevance
`GET`	`/v1/models`	List available models
`POST`	`/v1/responses`	Create a response (Beta)
`GET`	`/v1/responses/{id}`	Retrieve a stored response
`DELETE`	`/v1/responses/{id}`	Delete a stored response
`GET`	`/v1/responses/{id}/input_items`	Get normalized input items
`POST`	`/v1/responses/{id}/cancel`	Cancel an in-progress response
`POST`	`/v1/responses/input_tokens`	Count input tokens via provider utility
`POST`	`/v1/responses/compact`	Compact response input via provider utility
`GET`	`/v1/files`	List uploaded files
`POST`	`/v1/files`	Upload a file
`GET`	`/v1/files/{id}`	Get file metadata
`DELETE`	`/v1/files/{id}`	Delete a file
`GET`	`/v1/files/{id}/content`	Download file content
`POST`	`/v1/batches`	Create a batch job
`GET`	`/v1/batches`	List batch jobs
`GET`	`/v1/batches/{id}`	Get batch status
`POST`	`/v1/batches/{id}/cancel`	Cancel a batch job
`GET`	`/v1/batches/{id}/results`	Get batch results

Method

Endpoint

Description

POST

/v1/messages

Anthropic-format messages (enable with ENABLE_ANTHROPIC_INGRESS=true)

Method

Path

Description

Any

/p/{provider}/{endpoint}

Proxy provider-native requests without translation

Method

Path

Description

GET

/health

Health check (unauthenticated)

GET

/metrics

Prometheus metrics (when METRICS_ENABLED=true)