API Reference Index
Use this page when you already know which kind of connection you need. The API reference is grouped by request handling, administration, MCP tools, and A2A agents. If you are new to GoRoute, begin with the overview before choosing an API.
GoRoute exposes these capabilities through HTTP, WebSocket, and gRPC interfaces. The catalog below lets you search routes and narrow them by API surface.
[!NOTE] All data plane, MCP, and A2A routes require a tenant-scoped Virtual API Key passed via
Authorization: Bearer sk-gw-....
All administrative control plane routes require the Master Admin Key passed viaAuthorization: Bearer $GATEWAY_MASTER_ADMIN_KEY.
Interactive Endpoint Catalog
Search and filter every HTTP and WebSocket route exposed by GoRoute AI Gateway across /v1/*, /openai/v1/*, /anthropic/v1/*, /mcp*, /a2a/v1/*, and /admin/v1/*. The interactive catalog documents 112 endpoints across 7 API surfaces, while the unified OpenAPI specification (gateway.openapi.yaml) covers 73 paths (24 /v1 + 49 /admin/v1) with automated parity enforced by cmd/specgen.
| Method | Path | Group | Auth | Summary |
|---|---|---|---|---|
| POST | /v1/chat/completions | Text & Chat | Virtual API Key | Unified OpenAI-compatible chat completions with streaming SSE, tool calling, reasoning, and FinOps headers. |
| POST | /v1/completions | Text & Chat | Virtual API Key | Legacy text completions endpoint with streaming support. |
| POST | /v1/embeddings | Embeddings & Rerank | Virtual API Key | Generate vector embeddings across OpenAI, Cohere, Gemini, Bedrock, Vertex, and dialect providers. |
| GET | /v1/models | Models | Virtual API Key | List models accessible to the authenticated virtual key or tenant. |
| POST | /v1/rerank | Embeddings & Rerank | Virtual API Key | Rerank candidate documents against a query (Cohere, Voyage, Jina, Together, Fireworks, Novita, NVIDIA). |
| POST | /v1/moderations | Safety & Tokens | Virtual API Key | Classify text inputs for policy and content safety violations. |
| POST | /v1/messages | Text & Chat | Virtual API Key | Anthropic Messages API ingress supporting Claude SDKs and extended thinking. |
| POST | /v1/messages/count_tokens | Safety & Tokens | Virtual API Key | Count input tokens using the Anthropic Messages token-counting schema. |
| POST | /v1/tokenize | Safety & Tokens | Virtual API Key | Pre-flight token count estimation for request payloads. |
| POST | /v1/audio/transcriptions | Audio | Virtual API Key | Speech-to-text transcription via multipart audio upload. |
| POST | /v1/audio/translations | Audio | Virtual API Key | Speech-to-English audio translation. |
| POST | /v1/audio/speech | Audio | Virtual API Key | Text-to-speech audio synthesis returning binary audio streams. |
| POST | /v1/images/generations | Images | Virtual API Key | Generate images from text prompts. |
| POST | /v1/images/edits | Images | Virtual API Key | Edit or inpaint an existing image with a prompt and optional mask. |
| POST | /v1/images/variations | Images | Virtual API Key | Create visual variations of an uploaded source image. |
| POST | /v1/files | Files | Virtual API Key | Upload a file for batch processing or assistants. |
| GET | /v1/files | Files | Virtual API Key | List uploaded files scoped to the tenant. |
| GET | /v1/files/{file_id} | Files | Virtual API Key | Retrieve metadata for a specific uploaded file. |
| GET | /v1/files/{file_id}/content | Files | Virtual API Key | Download the raw contents of an uploaded file. |
| DELETE | /v1/files/{file_id} | Files | Virtual API Key | Delete an uploaded file. |
| POST | /v1/batches | Batches | Virtual API Key | Create an asynchronous batch inference job. |
| GET | /v1/batches | Batches | Virtual API Key | List asynchronous batch jobs for the tenant. |
| GET | /v1/batches/{batch_id} | Batches | Virtual API Key | Inspect status and output file IDs for a batch job. |
| POST | /v1/batches/{batch_id}/cancel | Batches | Virtual API Key | Cancel an in-progress batch job. |
| POST | /v1/responses | Responses & Realtime | Virtual API Key | OpenAI Responses API for stateful multi-turn reasoning and tool execution. |
| WS | /v1/realtime | Responses & Realtime | Virtual API Key | Full-duplex WebSocket proxy for low-latency realtime audio and text sessions. |
| POST | /v1/guardrails/apply | Safety & Tokens | Virtual API Key | Evaluate input/output text or tool calls directly against Pipeline v2 guardrails. |
| POST | /openai/v1/responses | Responses & Realtime | Virtual API Key | Direct OpenAI-prefixed Responses API alias. |
| WS | /openai/v1/realtime | Responses & Realtime | Virtual API Key | Direct OpenAI-prefixed Realtime WebSocket alias. |
| POST | /anthropic/v1/messages | Anthropic Ingress | Virtual API Key | Native Anthropic Messages endpoint for Claude Code and Anthropic SDKs. |
| POST | /anthropic/v1/messages/count_tokens | Anthropic Ingress | Virtual API Key | Native Anthropic token-counting endpoint. |
| GET | /mcp/subscriptions/listen | MCP Hub | Virtual API Key | SSE stream for MCP resource and tool list change notifications. |
| POST | /mcp | MCP Hub | Virtual API Key | MCP Virtual Hub JSON-RPC endpoint aggregating tools across upstream servers. |
| POST | /mcp/{serverSlug} | MCP Hub | Virtual API Key | Scoped MCP JSON-RPC endpoint targeting a single registered MCP server. |
| POST | /mcp/toolsets/{toolsetSlug} | MCP Hub | Virtual API Key | Curated MCP toolset endpoint exposing an approved subset of tools. |
| GET | /mcp-rest/tools/list | MCP REST Bridge | Virtual API Key | Plain REST bridge listing available MCP tools without JSON-RPC framing. |
| POST | /mcp-rest/tools/call | MCP REST Bridge | Virtual API Key | Plain REST bridge invoking an MCP tool by name and arguments. |
| GET | /v1/goroute/mcp/registry | Progressive Discovery | Virtual API Key | Progressive tool catalog registry feed returning compact tool handles. |
| GET | /.well-known/agent-card.json | Discovery | Public | Signed gateway Agent Card JSON for A2A capability discovery. |
| POST | /a2a/v1/agents/{agentSlug}/ | Agent Messaging | Virtual API Key | Send an A2A message/task to a registered agent. |
| GET | /a2a/v1/agents/{agentSlug}/tasks | Tasks | Virtual API Key | List A2A tasks for the specified agent. |
| GET | /a2a/v1/agents/{agentSlug}/tasks/{taskID} | Tasks | Virtual API Key | Retrieve current state and artifacts of an A2A task. |
| POST | /a2a/v1/agents/{agentSlug}/tasks/{taskID}:cancel | Tasks | Virtual API Key | Cancel an active A2A task. |
| GET | /a2a/v1/agents/{agentSlug}/tasks/{taskID}:subscribe | Tasks | Virtual API Key | Subscribe-first SSE stream for live A2A task status and artifact updates. |
| POST | /a2a/v1/agents/{agentSlug}/tasks/{taskID}:subscribe | Tasks | Virtual API Key | POST variant for subscribing to an A2A task SSE stream. |
| POST | /admin/v1/organizations | Organizations & Policies | Master Admin Key | Create a new tenant organization. |
| GET | /admin/v1/organizations | Organizations & Policies | Master Admin Key | List all organizations. |
| POST | /admin/v1/organizations/{orgID}/subscriptions | Organizations & Policies | Master Admin Key | Set provider subscription access for an organization. |
| GET | /admin/v1/organizations/{orgID}/subscriptions | Organizations & Policies | Master Admin Key | Get provider subscriptions for an organization. |
| POST | /admin/v1/organizations/{orgID}/models | Organizations & Policies | Master Admin Key | Configure model allowlist/denylist policies for an organization. |
| GET | /admin/v1/organizations/{orgID}/models | Organizations & Policies | Master Admin Key | Retrieve model policies for an organization. |
| POST | /admin/v1/organizations/{orgID}/guardrails | Guardrails | Master Admin Key | Set input/output security guardrail policies for an organization. |
| GET | /admin/v1/organizations/{orgID}/guardrails | Guardrails | Master Admin Key | Get configured guardrail policies for an organization. |
| POST | /admin/v1/organizations/{orgID}/guardrails/simulate | Guardrails | Master Admin Key | Dry-run guardrail rules and Pipeline v2 drivers against a sample payload. |
| POST | /admin/v1/organizations/{orgID}/guardrail-definitions | Guardrails | Master Admin Key | Create a named guardrail definition backed by one of 19 drivers, Starlark, or webhooks. |
| GET | /admin/v1/organizations/{orgID}/guardrail-definitions | Guardrails | Master Admin Key | List named guardrail definitions configured for an organization. |
| GET | /admin/v1/guardrail-definitions/{guardrailID} | Guardrails | Master Admin Key | Retrieve a named guardrail definition by ID. |
| PUT | /admin/v1/guardrail-definitions/{guardrailID} | Guardrails | Master Admin Key | Replace configuration and credentials for a guardrail definition. |
| PATCH | /admin/v1/guardrail-definitions/{guardrailID} | Guardrails | Master Admin Key | Partially update a named guardrail definition. |
| DELETE | /admin/v1/guardrail-definitions/{guardrailID} | Guardrails | Master Admin Key | Delete a named guardrail definition. |
| POST | /admin/v1/guardrail-definitions/{guardrailID}/status | Guardrails | Master Admin Key | Enable or disable a named guardrail definition. |
| POST | /admin/v1/guardrail-bindings | Guardrails | Master Admin Key | Bind a guardrail definition to an Org, Team, VirtualKey, EndUser, ModelGroup, or Tag. |
| GET | /admin/v1/organizations/{orgID}/guardrail-bindings | Guardrails | Master Admin Key | List hierarchical guardrail bindings for an organization. |
| DELETE | /admin/v1/guardrail-bindings/{bindingID} | Guardrails | Master Admin Key | Remove a guardrail binding. |
| POST | /admin/v1/organizations/{orgID}/tool-policies | Guardrails | Master Admin Key | Create or update tool permission and cross-turn taint trust policies. |
| GET | /admin/v1/organizations/{orgID}/tool-policies | Guardrails | Master Admin Key | List tool trust policies configured for an organization. |
| DELETE | /admin/v1/organizations/{orgID}/tool-policies/{policyID} | Guardrails | Master Admin Key | Delete a tool trust policy. |
| GET | /admin/v1/organizations/{orgID}/guardrail-usage | Guardrails | Master Admin Key | Query micro-dollar guardrail usage rollups and evaluation counts. |
| POST | /admin/v1/teams | Teams & Users | Master Admin Key | Create a team within an organization. |
| GET | /admin/v1/teams | Teams & Users | Master Admin Key | List teams. |
| POST | /admin/v1/users | Teams & Users | Master Admin Key | Create a user. |
| GET | /admin/v1/users | Teams & Users | Master Admin Key | List users. |
| POST | /admin/v1/keys | Virtual Keys | Master Admin Key | Issue a scoped Virtual API Key (sk-gw-...) with rate and budget limits. |
| GET | /admin/v1/keys | Virtual Keys | Master Admin Key | List issued Virtual API Keys. |
| POST | /admin/v1/keys/{keyID}/revoke | Virtual Keys | Master Admin Key | Revoke a Virtual API Key. |
| DELETE | /admin/v1/keys/{keyID} | Virtual Keys | Master Admin Key | Delete/revoke a Virtual API Key. |
| POST | /admin/v1/credentials | Credentials Vault | Master Admin Key | Store an upstream provider credential encrypted with AES-256-GCM. |
| GET | /admin/v1/credentials | Credentials Vault | Master Admin Key | List stored provider credentials (secrets redacted). |
| POST | /admin/v1/credentials/validate | Credentials Vault | Master Admin Key | Preflight-validate a provider credential before storing. |
| POST | /admin/v1/credentials/{credID}/rotate | Credentials Vault | Master Admin Key | Rotate a stored provider credential. |
| POST | /admin/v1/credentials/{credID}/validate | Credentials Vault | Master Admin Key | Live-validate an existing stored credential against the upstream provider. |
| POST | /admin/v1/model-groups | Routing & Deployments | Master Admin Key | Create a logical model alias group with routing strategy. |
| GET | /admin/v1/model-groups | Routing & Deployments | Master Admin Key | List model groups. |
| POST | /admin/v1/deployments | Routing & Deployments | Master Admin Key | Register an upstream model deployment. |
| GET | /admin/v1/deployments | Routing & Deployments | Master Admin Key | List configured deployments. |
| GET | /admin/v1/catalogue | Catalogue & Pricing | Master Admin Key | List discovered models and versioned pricing in the global catalogue. |
| POST | /admin/v1/catalogue/sync | Catalogue & Pricing | Master Admin Key | Trigger immediate upstream model discovery sync. |
| POST | /admin/v1/catalogue/import | Catalogue & Pricing | Master Admin Key | Import model catalogue and pricing definitions. |
| POST | /admin/v1/catalogue/pricing | Catalogue & Pricing | Master Admin Key | Update micro-dollar pricing for a model. |
| GET | /admin/v1/catalogue/pricing | Catalogue & Pricing | Master Admin Key | List versioned model pricing history. |
| GET | /admin/v1/observability/metrics | Health & Telemetry | Master Admin Key | Retrieve JSON snapshot of gateway telemetry and cache/routing metrics. |
| GET | /admin/v1/health/deployments | Health & Telemetry | Master Admin Key | Inspect circuit breaker and health status of all deployments. |
| POST | /admin/v1/health/probe | Health & Telemetry | Master Admin Key | Trigger active health probes across deployments. |
| POST | /admin/v1/cache/invalidate | Health & Telemetry | Master Admin Key | Invalidate L1/L2 exact-match response cache entries. |
| GET | /admin/v1/spend/summary | FinOps & Audit | Master Admin Key | Aggregated micro-dollar spend summary by org, team, or key. |
| GET | /admin/v1/spend/logs | FinOps & Audit | Master Admin Key | Paginated per-request FinOps spend ledger. |
| GET | /admin/v1/audit/logs | FinOps & Audit | Master Admin Key | Control-plane governance audit log entries. |
| POST | /admin/v1/mcp/servers | MCP Management | Master Admin Key | Register an upstream MCP server (HTTP or sandboxed stdio). |
| GET | /admin/v1/mcp/servers | MCP Management | Master Admin Key | List registered MCP servers. |
| POST | /admin/v1/mcp/servers/{serverID}/sync | MCP Management | Master Admin Key | Sync tool definitions from an MCP server. |
| POST | /admin/v1/mcp/toolsets | MCP Management | Master Admin Key | Create a curated MCP toolset. |
| GET | /admin/v1/mcp/toolsets | MCP Management | Master Admin Key | List curated MCP toolsets. |
| GET | /admin/v1/mcp/tools | MCP Management | Master Admin Key | List all synced MCP tools. |
| POST | /admin/v1/mcp/credentials | MCP Management | Master Admin Key | Store BYOK credentials for an MCP server. |
| POST | /admin/v1/a2a/agents | A2A Management | Master Admin Key | Register an A2A agent. |
| GET | /admin/v1/a2a/agents | A2A Management | Master Admin Key | List registered A2A agents. |
| GET | /admin/v1/a2a/agents/{id} | A2A Management | Master Admin Key | Get details for a registered A2A agent. |
| POST | /admin/v1/a2a/agents/{id}/kill-switch | A2A Management | Master Admin Key | Toggle the emergency kill-switch for an A2A agent. |
| POST | /admin/v1/a2a/push-configs | A2A Management | Master Admin Key | Configure webhook push notifications for A2A tasks. |
| GET | /healthz | Probes | Public | Liveness probe returning service OK status. |
| GET | /readyz | Probes | Public | Readiness probe verifying PostgreSQL and Redis connectivity. |
| GET | /metrics | Probes | Metrics Auth | Prometheus exposition endpoint for gateway, cache, and upstream HTTP metrics. |
API Reference Guides
| Specification Guide | Endpoints Base | Core Coverage |
|---|---|---|
| Gateway Data Plane API | /v1/* | All 24 primary /v1/* paths: Chat Completions, Text Completions, Embeddings, Models, Rerank, Moderations, Anthropic Messages, Tokenization, Standalone Guardrails (/v1/guardrails/apply), Audio (STT & TTS), Images, Files, Batches, Responses, and Realtime WebSockets. |
| Admin Control Plane API | /admin/v1/* | All management groups: Organizations, Provider Subscriptions, Model Policies, Guardrails & Simulator, Teams, Users, Virtual Keys, Credentials Vault, Model Groups, Deployments, Catalogue/Pricing, Health/Cache, and FinOps Ledgers. |
| Model Context Protocol (MCP) API | /mcp/*, /mcp-rest/* | Virtual Hub aggregator, Scoped server execution, Curated toolsets, Plain REST tool bridge, and Progressive Tool Discovery catalog feed. |
| Agent-to-Agent (A2A) API | /a2a/v1/*, gRPC | Signed Agent Cards (/.well-known/agent-card.json), dual-binding message dispatch, Subscribe-First SSE task streaming, native gRPC service, and OpenAI SDK compatibility bridge. |
Authentication Schemes
# Data Plane, MCP, and A2A requests (Virtual API Key)
Authorization: Bearer sk-gw-prod-7f9a2b8c4d1e
# Admin Control Plane requests (Master Admin Key)
Authorization: Bearer sk-gw-master-admin-secret-key
Key Lifecycle Rules
- Virtual API Keys (
sk-gw-...): Scoped to specific Organizations and Teams, enforce sliding-window RPM/TPM rate limits, adhere to model allowlists, and cap monthly micro-dollar expenditure. - Master Admin Key: Bypasses rate limits and tenant isolation; used exclusively by automated control planes, CI/CD provisioning pipelines, and administrative operators.
- Provider Credentials: Kept strictly inside GoRoute's AES-256-GCM encrypted vault; never exposed to callers or sent across client network boundaries.
Standard Response Telemetry Headers
Every inference request executed by GoRoute returns real-time tracing, routing, and FinOps attribution headers:
| Header | Description | Example |
|---|---|---|
X-Gateway-Request-Id | Unique UUID assigned to the request lifecycle | req_991efda4-7fab-4b03 |
X-Trace-Id | W3C / OpenTelemetry distributed trace identifier | bad98e7deea34d7c810a963d9ed2c4ef |
X-Gateway-Provider | The winning upstream provider selected for execution | gemini, anthropic, openai |
X-Gateway-Model | The physical upstream model that executed the inference | gemini-2.5-flash, claude-3-5-sonnet-20241022 |
X-Gateway-Cost-Micros | Exact micro-dollar spend incurred ($0.000001 USD) | 45 ($0.000045 USD) |
X-Gateway-Routing-Time | Total Stage 1 + Stage 2 routing overhead | 14 µs |
X-Gateway-Cache | Exact-match cache evaluation status | HIT or MISS |
Retry-After | Cooldown period sent on HTTP 429 rate limit errors | 45 (seconds) |
Interactive Management via Operator Web UI
In addition to programmatic REST and gRPC interfaces, GoRoute serves an embedded single-page visual administration console directly from the binary at:
http://localhost:8080/ui/
Use the Operator UI to issue virtual keys, inspect live deployment latencies, simulate security guardrails, test streaming chat completions, and monitor real-time FinOps ledgers.