Skip to main content
Auriko’s public API follows strict semantic versioning. This document defines the stability tiers, change-control policy, and deprecation process for all public endpoints. See ADR-034 for the full architectural rationale.

​
Stability tiers

Every public endpoint belongs to one of two stability tiers (categories that determine the change-control policy for each endpoint).

​
Stable

Stable endpoints follow strict SemVer. You can depend on their request and response shape across minor and patch releases. Breaking changes require a major version bump.
  • POST /v1/chat/completions — create a chat completion
  • GET /v1/models — list available models

​
Preview

Preview endpoints carry a 6-month deprecation floor. Breaking changes are announced with x-deprecation-date and x-removal-date in the OpenAPI spec.
  • GET /v1/registry/providers — list providers
  • GET /v1/registry/models — list canonical models
  • GET /v1/directory/models — full model directory with pricing
  • GET /v1/workspaces/{workspace_id}/billing/balance — credit balance
  • GET /v1/me — API key identity
The /v1beta/* path prefix is reserved for future use. Zero operations exist there at 1.0.

​
SemVer policy

All /v1/* endpoints follow Semantic Versioning 2.0.0. A breaking change to any Stable endpoint requires a major version bump. Additive changes (new optional fields, new endpoints) land in minor releases.

​
Deprecation process

Auriko announces deprecations with two OpenAPI extension fields on the affected operation:
  • x-deprecation-date — the date the deprecation takes effect
  • x-removal-date — the earliest date the endpoint may be removed
The minimum deprecation window depends on the stability tier:
TierMinimum window
StableMajor version bump required (no silent removal)
Preview6 months from x-deprecation-date to x-removal-date

​
OpenAI-compatible scope

Auriko’s POST /v1/chat/completions endpoint is OpenAI-compatible. See Supported parameters for the full list of accepted request fields. The following OpenAI APIs are not part of Auriko’s scope:
  • Assistants API
  • Batch API
  • Files API
  • Audio API (speech, transcription, translation)
  • Images API
  • Embeddings API (planned, not yet available)
  • Fine-tuning API
  • Moderations API

​
Unlisted endpoints

Unlisted endpoints. Only endpoints listed in api_gateway/openapi/auriko-api.yaml are part of the public contract. The runtime may serve additional endpoints for internal use (console, dashboard, operational tools). These are unsupported: their shape, behavior, and availability may change at any time without notice. Use at your own risk; no deprecation commitments apply.

​
Authoritative artifacts

  • api_gateway/openapi/auriko-api.yaml — endpoint and schema contract
  • api_gateway/contracts/sdk-exposure.yaml — HIDDEN field/header suppression policy
  • ADR-034 — public surface contract (policy, architecture, conformance)
  • CHANGELOG.md — release history