AIOrouter API Versioning
Document Type: API Specification Version: 1.0.0 Date: 2026-05-02 Current API Version:
2026-06-01
§1 — Versioning Scheme
AIOrouter uses a dual versioning scheme:
| Mechanism | Purpose | Example |
|---|---|---|
URL path (/v1/) |
API shape: endpoint paths, response structure | /v1/chat/completions |
Header (API-Version) |
Semantic behavior: deprecation timeline, feature gates | API-Version: 2026-06-01 |
URL Path Versioning
/v1/is the first-generation API shape- Breaking URL path changes (endpoint rename, response restructure) will increment to
/v2/ /v1/remains available as a legacy alias for the current version
Header-Based Versioning
- All requests SHOULD include the
API-Versionheader with a date-based version string - If omitted, the server defaults to the current version (
2026-06-01) - All responses include the
API-Versionheader indicating the version used - Deprecated versions include
Sunsetheader with removal date - Deprecated versions include
API-Version-Warningheader
§2 — Current Version: 2026-06-01
The initial API version with the following endpoint shape:
| Method | Path | Description |
|---|---|---|
POST |
/v1/chat/completions |
Chat completion (streaming + non-streaming) |
GET |
/v1/models |
List available models |
GET |
/v1/models/:modelId |
Get model details |
Supported features:
- Chat completion with messages, temperature, max_tokens, top_p, stop
- Streaming (SSE) via
stream: true - Function calling (tools + tool_choice)
- Structured output (response_format: json_object | text)
- API key authentication (Bearer token in Authorization header)
§3 — Deprecation Policy
| Policy | Value |
|---|---|
| Backward compatibility | 12 months from deprecation announcement |
| Sunset notice | 3 months before removal via Sunset header |
| Migration guide | Published in docs for each version transition |
| Grace period | Deprecated versions return API-Version-Warning header |
§4 — Version History
| Version | Release Date | Status | Sunset Date |
|---|---|---|---|
2026-06-01 |
2026-06-01 | ✅ Current | — |
§5 — Client Requirements
Required Headers
Authorization: Bearer ak- + 43 base64url chars
Content-Type: application/json
Recommended Headers
API-Version: 2026-06-01
X-Request-Id: <uuid-v4>
SDK Compatibility
AIOrouter is compatible with the OpenAI SDK. Set the base URL:
# Python
from openai import OpenAI
client = OpenAI(
base_url="https://api.aiorouter.ca/v1",
api_key="ak-..."
)
// TypeScript
import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://api.aiorouter.ca/v1",
apiKey: "ak-...",
});