EN
Open developer docs
HomeAPI REFERENCE

API REFERENCE

A concise compatibility contract for the Router.

The current Router source defines OpenAI/OpenRouter-compatible /v1 and /api/v1 surfaces. A production deployment is conformant only after its OpenAPI document passes the exact contract-drift gate; source availability alone is not live-service evidence.

01/v1Compatible API entrypoint
02BearerToken authentication pattern
03SSEIncremental streaming pattern
01

Prefixes and deployment truth.

OpenAI-compatible clients use https://api.octoryn.dev/v1. The Router source also exposes /api/v1. Anthropic Messages is intentionally available only at /api/v1/messages. Before production use, operators must compare the deployed /openapi.json with the immutable source contract and retain the result.

  • Treat source, container and deployed contracts as three separate evidence layersExpand details

    This is part of Prefixes and deployment truth.. Octoryn keeps its configuration, outcome and routing context together so teams can validate and review the capability independently.

    View implementation docs
  • Do not infer production support from a route existing in sourceExpand details

    This is part of Prefixes and deployment truth.. Octoryn keeps its configuration, outcome and routing context together so teams can validate and review the capability independently.

    View implementation docs
  • Use /healthz, /readyz and /status for public process and component checks after deploymentExpand details

    This is part of Prefixes and deployment truth.. Octoryn keeps its configuration, outcome and routing context together so teams can validate and review the capability independently.

    View implementation docs
02

Inference endpoints.

Both compatible prefixes define Chat Completions, legacy Completions, Responses, Embeddings, Moderations and Rerank. Streaming is defined for Chat Completions, Completions and Responses; Messages uses its native event topology at /api/v1/messages.

  • POST /v1/chat/completions, /completions and /responsesExpand details

    This is part of Inference endpoints.. Octoryn keeps its configuration, outcome and routing context together so teams can validate and review the capability independently.

    View implementation docs
  • POST /v1/embeddings, /moderations and /rerankExpand details

    This is part of Inference endpoints.. Octoryn keeps its configuration, outcome and routing context together so teams can validate and review the capability independently.

    View implementation docs
  • POST /api/v1/messages for Anthropic-compatible MessagesExpand details

    This is part of Inference endpoints.. Octoryn keeps its configuration, outcome and routing context together so teams can validate and review the capability independently.

    View implementation docs
03

Catalogue and governance endpoints.

Authenticated route-scoped credentials can read model, provider and embedding-model catalogues. Separate scopes protect route simulation and the bounded, content-free governance summary.

  • GET /v1/models, model detail, model endpoints and model countExpand details

    This is part of Catalogue and governance endpoints.. Octoryn keeps its configuration, outcome and routing context together so teams can validate and review the capability independently.

    View implementation docs
  • GET /v1/providers, provider detail and /v1/embeddings/modelsExpand details

    This is part of Catalogue and governance endpoints.. Octoryn keeps its configuration, outcome and routing context together so teams can validate and review the capability independently.

    View implementation docs
  • POST /v1/route/simulate and GET /v1/governance/summary require dedicated scopesExpand details

    This is part of Catalogue and governance endpoints.. Octoryn keeps its configuration, outcome and routing context together so teams can validate and review the capability independently.

    View implementation docs
04

Authenticate every request.

Use the API key supplied for the intended customer or product environment. Compatible clients place it in bearer-token authentication; never embed it in browser bundles, mobile binaries or source control.

  • Keep keys in a protected server-side environmentExpand details

    This is part of Authenticate every request.. Octoryn keeps its configuration, outcome and routing context together so teams can validate and review the capability independently.

    View implementation docs
  • Separate development and production credentialsExpand details

    This is part of Authenticate every request.. Octoryn keeps its configuration, outcome and routing context together so teams can validate and review the capability independently.

    View implementation docs
  • Rotate or revoke exposed credentials through the responsible operatorExpand details

    This is part of Authenticate every request.. Octoryn keeps its configuration, outcome and routing context together so teams can validate and review the capability independently.

    View implementation docs
05

Read errors by category.

Authentication and authorization failures require credential or policy correction. Rate-limit responses require pacing, while upstream and service failures require bounded, context-aware recovery.

  • Do not retry invalid authentication or malformed requests unchangedExpand details

    This is part of Read errors by category.. Octoryn keeps its configuration, outcome and routing context together so teams can validate and review the capability independently.

    View implementation docs
  • Use backoff for rate limits and transient failuresExpand details

    This is part of Read errors by category.. Octoryn keeps its configuration, outcome and routing context together so teams can validate and review the capability independently.

    View implementation docs
  • Capture status, response body and available correlation metadataExpand details

    This is part of Read errors by category.. Octoryn keeps its configuration, outcome and routing context together so teams can validate and review the capability independently.

    View implementation docs
06

Consume streaming incrementally.

When streaming is enabled and supported by the selected route, process server-sent events as they arrive. Your client should handle cancellation, disconnects and a stream ending before a complete application result.

  • Render or process incremental output without buffering the full responseExpand details

    This is part of Consume streaming incrementally.. Octoryn keeps its configuration, outcome and routing context together so teams can validate and review the capability independently.

    View implementation docs
  • Treat disconnects and partial output as explicit application statesExpand details

    This is part of Consume streaming incrementally.. Octoryn keeps its configuration, outcome and routing context together so teams can validate and review the capability independently.

    View implementation docs
  • Apply an application deadline to long-running streamsExpand details

    This is part of Consume streaming incrementally.. Octoryn keeps its configuration, outcome and routing context together so teams can validate and review the capability independently.

    View implementation docs
07

Treat capabilities as route-specific.

Tools, vision, structured output and other optional request features depend on the route and upstream model. Validate arguments and outputs at the application boundary even when the provider reports schema support.

  • Check capability support before production useExpand details

    This is part of Treat capabilities as route-specific.. Octoryn keeps its configuration, outcome and routing context together so teams can validate and review the capability independently.

    View implementation docs
  • Validate tool arguments before executionExpand details

    This is part of Treat capabilities as route-specific.. Octoryn keeps its configuration, outcome and routing context together so teams can validate and review the capability independently.

    View implementation docs
  • Preserve a fallback path when a capability is operationally criticalExpand details

    This is part of Treat capabilities as route-specific.. Octoryn keeps its configuration, outcome and routing context together so teams can validate and review the capability independently.

    View implementation docs

OCTORYN ROUTER

Use your existing SDK workflow.

See how OpenAI SDKs and compatible clients can be configured without adding a Router-specific application framework.

Open SDK guide