Skip to main content

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 via Authorization: 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.

112Total Endpoints
31Data Plane
64Admin Control
14MCP & A2A
Method:
Showing 112 of 112 endpoints
MethodPathGroupAuthSummary
POST/v1/chat/completionsText & ChatVirtual API KeyUnified OpenAI-compatible chat completions with streaming SSE, tool calling, reasoning, and FinOps headers.
POST/v1/completionsText & ChatVirtual API KeyLegacy text completions endpoint with streaming support.
POST/v1/embeddingsEmbeddings & RerankVirtual API KeyGenerate vector embeddings across OpenAI, Cohere, Gemini, Bedrock, Vertex, and dialect providers.
GET/v1/modelsModelsVirtual API KeyList models accessible to the authenticated virtual key or tenant.
POST/v1/rerankEmbeddings & RerankVirtual API KeyRerank candidate documents against a query (Cohere, Voyage, Jina, Together, Fireworks, Novita, NVIDIA).
POST/v1/moderationsSafety & TokensVirtual API KeyClassify text inputs for policy and content safety violations.
POST/v1/messagesText & ChatVirtual API KeyAnthropic Messages API ingress supporting Claude SDKs and extended thinking.
POST/v1/messages/count_tokensSafety & TokensVirtual API KeyCount input tokens using the Anthropic Messages token-counting schema.
POST/v1/tokenizeSafety & TokensVirtual API KeyPre-flight token count estimation for request payloads.
POST/v1/audio/transcriptionsAudioVirtual API KeySpeech-to-text transcription via multipart audio upload.
POST/v1/audio/translationsAudioVirtual API KeySpeech-to-English audio translation.
POST/v1/audio/speechAudioVirtual API KeyText-to-speech audio synthesis returning binary audio streams.
POST/v1/images/generationsImagesVirtual API KeyGenerate images from text prompts.
POST/v1/images/editsImagesVirtual API KeyEdit or inpaint an existing image with a prompt and optional mask.
POST/v1/images/variationsImagesVirtual API KeyCreate visual variations of an uploaded source image.
POST/v1/filesFilesVirtual API KeyUpload a file for batch processing or assistants.
GET/v1/filesFilesVirtual API KeyList uploaded files scoped to the tenant.
GET/v1/files/{file_id}FilesVirtual API KeyRetrieve metadata for a specific uploaded file.
GET/v1/files/{file_id}/contentFilesVirtual API KeyDownload the raw contents of an uploaded file.
DELETE/v1/files/{file_id}FilesVirtual API KeyDelete an uploaded file.
POST/v1/batchesBatchesVirtual API KeyCreate an asynchronous batch inference job.
GET/v1/batchesBatchesVirtual API KeyList asynchronous batch jobs for the tenant.
GET/v1/batches/{batch_id}BatchesVirtual API KeyInspect status and output file IDs for a batch job.
POST/v1/batches/{batch_id}/cancelBatchesVirtual API KeyCancel an in-progress batch job.
POST/v1/responsesResponses & RealtimeVirtual API KeyOpenAI Responses API for stateful multi-turn reasoning and tool execution.
WS/v1/realtimeResponses & RealtimeVirtual API KeyFull-duplex WebSocket proxy for low-latency realtime audio and text sessions.
POST/v1/guardrails/applySafety & TokensVirtual API KeyEvaluate input/output text or tool calls directly against Pipeline v2 guardrails.
POST/openai/v1/responsesResponses & RealtimeVirtual API KeyDirect OpenAI-prefixed Responses API alias.
WS/openai/v1/realtimeResponses & RealtimeVirtual API KeyDirect OpenAI-prefixed Realtime WebSocket alias.
POST/anthropic/v1/messagesAnthropic IngressVirtual API KeyNative Anthropic Messages endpoint for Claude Code and Anthropic SDKs.
POST/anthropic/v1/messages/count_tokensAnthropic IngressVirtual API KeyNative Anthropic token-counting endpoint.
GET/mcp/subscriptions/listenMCP HubVirtual API KeySSE stream for MCP resource and tool list change notifications.
POST/mcpMCP HubVirtual API KeyMCP Virtual Hub JSON-RPC endpoint aggregating tools across upstream servers.
POST/mcp/{serverSlug}MCP HubVirtual API KeyScoped MCP JSON-RPC endpoint targeting a single registered MCP server.
POST/mcp/toolsets/{toolsetSlug}MCP HubVirtual API KeyCurated MCP toolset endpoint exposing an approved subset of tools.
GET/mcp-rest/tools/listMCP REST BridgeVirtual API KeyPlain REST bridge listing available MCP tools without JSON-RPC framing.
POST/mcp-rest/tools/callMCP REST BridgeVirtual API KeyPlain REST bridge invoking an MCP tool by name and arguments.
GET/v1/goroute/mcp/registryProgressive DiscoveryVirtual API KeyProgressive tool catalog registry feed returning compact tool handles.
GET/.well-known/agent-card.jsonDiscoveryPublicSigned gateway Agent Card JSON for A2A capability discovery.
POST/a2a/v1/agents/{agentSlug}/Agent MessagingVirtual API KeySend an A2A message/task to a registered agent.
GET/a2a/v1/agents/{agentSlug}/tasksTasksVirtual API KeyList A2A tasks for the specified agent.
GET/a2a/v1/agents/{agentSlug}/tasks/{taskID}TasksVirtual API KeyRetrieve current state and artifacts of an A2A task.
POST/a2a/v1/agents/{agentSlug}/tasks/{taskID}:cancelTasksVirtual API KeyCancel an active A2A task.
GET/a2a/v1/agents/{agentSlug}/tasks/{taskID}:subscribeTasksVirtual API KeySubscribe-first SSE stream for live A2A task status and artifact updates.
POST/a2a/v1/agents/{agentSlug}/tasks/{taskID}:subscribeTasksVirtual API KeyPOST variant for subscribing to an A2A task SSE stream.
POST/admin/v1/organizationsOrganizations & PoliciesMaster Admin KeyCreate a new tenant organization.
GET/admin/v1/organizationsOrganizations & PoliciesMaster Admin KeyList all organizations.
POST/admin/v1/organizations/{orgID}/subscriptionsOrganizations & PoliciesMaster Admin KeySet provider subscription access for an organization.
GET/admin/v1/organizations/{orgID}/subscriptionsOrganizations & PoliciesMaster Admin KeyGet provider subscriptions for an organization.
POST/admin/v1/organizations/{orgID}/modelsOrganizations & PoliciesMaster Admin KeyConfigure model allowlist/denylist policies for an organization.
GET/admin/v1/organizations/{orgID}/modelsOrganizations & PoliciesMaster Admin KeyRetrieve model policies for an organization.
POST/admin/v1/organizations/{orgID}/guardrailsGuardrailsMaster Admin KeySet input/output security guardrail policies for an organization.
GET/admin/v1/organizations/{orgID}/guardrailsGuardrailsMaster Admin KeyGet configured guardrail policies for an organization.
POST/admin/v1/organizations/{orgID}/guardrails/simulateGuardrailsMaster Admin KeyDry-run guardrail rules and Pipeline v2 drivers against a sample payload.
POST/admin/v1/organizations/{orgID}/guardrail-definitionsGuardrailsMaster Admin KeyCreate a named guardrail definition backed by one of 19 drivers, Starlark, or webhooks.
GET/admin/v1/organizations/{orgID}/guardrail-definitionsGuardrailsMaster Admin KeyList named guardrail definitions configured for an organization.
GET/admin/v1/guardrail-definitions/{guardrailID}GuardrailsMaster Admin KeyRetrieve a named guardrail definition by ID.
PUT/admin/v1/guardrail-definitions/{guardrailID}GuardrailsMaster Admin KeyReplace configuration and credentials for a guardrail definition.
PATCH/admin/v1/guardrail-definitions/{guardrailID}GuardrailsMaster Admin KeyPartially update a named guardrail definition.
DELETE/admin/v1/guardrail-definitions/{guardrailID}GuardrailsMaster Admin KeyDelete a named guardrail definition.
POST/admin/v1/guardrail-definitions/{guardrailID}/statusGuardrailsMaster Admin KeyEnable or disable a named guardrail definition.
POST/admin/v1/guardrail-bindingsGuardrailsMaster Admin KeyBind a guardrail definition to an Org, Team, VirtualKey, EndUser, ModelGroup, or Tag.
GET/admin/v1/organizations/{orgID}/guardrail-bindingsGuardrailsMaster Admin KeyList hierarchical guardrail bindings for an organization.
DELETE/admin/v1/guardrail-bindings/{bindingID}GuardrailsMaster Admin KeyRemove a guardrail binding.
POST/admin/v1/organizations/{orgID}/tool-policiesGuardrailsMaster Admin KeyCreate or update tool permission and cross-turn taint trust policies.
GET/admin/v1/organizations/{orgID}/tool-policiesGuardrailsMaster Admin KeyList tool trust policies configured for an organization.
DELETE/admin/v1/organizations/{orgID}/tool-policies/{policyID}GuardrailsMaster Admin KeyDelete a tool trust policy.
GET/admin/v1/organizations/{orgID}/guardrail-usageGuardrailsMaster Admin KeyQuery micro-dollar guardrail usage rollups and evaluation counts.
POST/admin/v1/teamsTeams & UsersMaster Admin KeyCreate a team within an organization.
GET/admin/v1/teamsTeams & UsersMaster Admin KeyList teams.
POST/admin/v1/usersTeams & UsersMaster Admin KeyCreate a user.
GET/admin/v1/usersTeams & UsersMaster Admin KeyList users.
POST/admin/v1/keysVirtual KeysMaster Admin KeyIssue a scoped Virtual API Key (sk-gw-...) with rate and budget limits.
GET/admin/v1/keysVirtual KeysMaster Admin KeyList issued Virtual API Keys.
POST/admin/v1/keys/{keyID}/revokeVirtual KeysMaster Admin KeyRevoke a Virtual API Key.
DELETE/admin/v1/keys/{keyID}Virtual KeysMaster Admin KeyDelete/revoke a Virtual API Key.
POST/admin/v1/credentialsCredentials VaultMaster Admin KeyStore an upstream provider credential encrypted with AES-256-GCM.
GET/admin/v1/credentialsCredentials VaultMaster Admin KeyList stored provider credentials (secrets redacted).
POST/admin/v1/credentials/validateCredentials VaultMaster Admin KeyPreflight-validate a provider credential before storing.
POST/admin/v1/credentials/{credID}/rotateCredentials VaultMaster Admin KeyRotate a stored provider credential.
POST/admin/v1/credentials/{credID}/validateCredentials VaultMaster Admin KeyLive-validate an existing stored credential against the upstream provider.
POST/admin/v1/model-groupsRouting & DeploymentsMaster Admin KeyCreate a logical model alias group with routing strategy.
GET/admin/v1/model-groupsRouting & DeploymentsMaster Admin KeyList model groups.
POST/admin/v1/deploymentsRouting & DeploymentsMaster Admin KeyRegister an upstream model deployment.
GET/admin/v1/deploymentsRouting & DeploymentsMaster Admin KeyList configured deployments.
GET/admin/v1/catalogueCatalogue & PricingMaster Admin KeyList discovered models and versioned pricing in the global catalogue.
POST/admin/v1/catalogue/syncCatalogue & PricingMaster Admin KeyTrigger immediate upstream model discovery sync.
POST/admin/v1/catalogue/importCatalogue & PricingMaster Admin KeyImport model catalogue and pricing definitions.
POST/admin/v1/catalogue/pricingCatalogue & PricingMaster Admin KeyUpdate micro-dollar pricing for a model.
GET/admin/v1/catalogue/pricingCatalogue & PricingMaster Admin KeyList versioned model pricing history.
GET/admin/v1/observability/metricsHealth & TelemetryMaster Admin KeyRetrieve JSON snapshot of gateway telemetry and cache/routing metrics.
GET/admin/v1/health/deploymentsHealth & TelemetryMaster Admin KeyInspect circuit breaker and health status of all deployments.
POST/admin/v1/health/probeHealth & TelemetryMaster Admin KeyTrigger active health probes across deployments.
POST/admin/v1/cache/invalidateHealth & TelemetryMaster Admin KeyInvalidate L1/L2 exact-match response cache entries.
GET/admin/v1/spend/summaryFinOps & AuditMaster Admin KeyAggregated micro-dollar spend summary by org, team, or key.
GET/admin/v1/spend/logsFinOps & AuditMaster Admin KeyPaginated per-request FinOps spend ledger.
GET/admin/v1/audit/logsFinOps & AuditMaster Admin KeyControl-plane governance audit log entries.
POST/admin/v1/mcp/serversMCP ManagementMaster Admin KeyRegister an upstream MCP server (HTTP or sandboxed stdio).
GET/admin/v1/mcp/serversMCP ManagementMaster Admin KeyList registered MCP servers.
POST/admin/v1/mcp/servers/{serverID}/syncMCP ManagementMaster Admin KeySync tool definitions from an MCP server.
POST/admin/v1/mcp/toolsetsMCP ManagementMaster Admin KeyCreate a curated MCP toolset.
GET/admin/v1/mcp/toolsetsMCP ManagementMaster Admin KeyList curated MCP toolsets.
GET/admin/v1/mcp/toolsMCP ManagementMaster Admin KeyList all synced MCP tools.
POST/admin/v1/mcp/credentialsMCP ManagementMaster Admin KeyStore BYOK credentials for an MCP server.
POST/admin/v1/a2a/agentsA2A ManagementMaster Admin KeyRegister an A2A agent.
GET/admin/v1/a2a/agentsA2A ManagementMaster Admin KeyList registered A2A agents.
GET/admin/v1/a2a/agents/{id}A2A ManagementMaster Admin KeyGet details for a registered A2A agent.
POST/admin/v1/a2a/agents/{id}/kill-switchA2A ManagementMaster Admin KeyToggle the emergency kill-switch for an A2A agent.
POST/admin/v1/a2a/push-configsA2A ManagementMaster Admin KeyConfigure webhook push notifications for A2A tasks.
GET/healthzProbesPublicLiveness probe returning service OK status.
GET/readyzProbesPublicReadiness probe verifying PostgreSQL and Redis connectivity.
GET/metricsProbesMetrics AuthPrometheus exposition endpoint for gateway, cache, and upstream HTTP metrics.

API Reference Guides​

GoRoute API Surface Data Plane API(/v1/*) Admin Control Plane(/admin/v1/*) MCP Virtual Hub(/mcp, /mcp-rest) A2A Protocol Service(/a2a/v1/*, gRPC) Chat, Completions and Reasoning Audio, Images, Embeddings and Rerank Stateful Files, Batches and Realtime Orgs, Teams, Users and Virtual Keys Credentials Vault, Deployments and Pricing FinOps Ledgers, Guardrails and Health Probes tools/list Aggregator and tools/call Plain REST Bridge and Progressive Handles Signed Agent Cards and Message Dispatch SSE Task Streams, Native gRPC and Bridge
Specification GuideEndpoints BaseCore 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/*, gRPCSigned 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​

  1. 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.
  2. Master Admin Key: Bypasses rate limits and tenant isolation; used exclusively by automated control planes, CI/CD provisioning pipelines, and administrative operators.
  3. 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:

HeaderDescriptionExample
X-Gateway-Request-IdUnique UUID assigned to the request lifecyclereq_991efda4-7fab-4b03
X-Trace-IdW3C / OpenTelemetry distributed trace identifierbad98e7deea34d7c810a963d9ed2c4ef
X-Gateway-ProviderThe winning upstream provider selected for executiongemini, anthropic, openai
X-Gateway-ModelThe physical upstream model that executed the inferencegemini-2.5-flash, claude-3-5-sonnet-20241022
X-Gateway-Cost-MicrosExact micro-dollar spend incurred ($0.000001 USD)45 ($0.000045 USD)
X-Gateway-Routing-TimeTotal Stage 1 + Stage 2 routing overhead14 µs
X-Gateway-CacheExact-match cache evaluation statusHIT or MISS
Retry-AfterCooldown period sent on HTTP 429 rate limit errors45 (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.


Next Steps​