8.8 KiB
OpenRouter (src/openrouter)
Namespace molo::openrouter. Whole public OpenRouter API
(https://openrouter.ai/api/v1) over the shared llm::ApiClient foundation.
Status 2026-10-24: implemented and locally tested; no OpenRouter key exists in
this environment, so only unauthenticated routes were verified live.
Scope
Chat completions (streaming incl. SSE heartbeats and mid-stream errors, tools,
structured outputs, reasoning, usage and cost), legacy completions, the
Responses API (beta), the Anthropic-compatible messages endpoint, routing
(provider preferences, models fallbacks, route, model variants, plugins,
server tools), models (list with every filter, one model, per-model endpoints,
count, user models, ZDR endpoints, embedding / image / video model lists),
providers, generation stats / content / feedback, key info, credits, activity
and analytics, API key management, embeddings, rerank, images, video, audio
(speech, transcription), batches, files and containers, presets, server tool
registry and public datasets, guardrails, BYOK, workspaces and budgets,
observability destinations, private endpoints, external users, organization
settings, SCIM, vault secrets, OAuth (PKCE code exchange, authorization code
creation, JWKS, workload token exchange), attribution headers, error semantics,
OpenrouterChatModel : llm::ChatModel.
Module map (one class per concern)
| File | Class | Concern |
|---|---|---|
calls.h |
kCalls |
the ONE call table: 140 rows (139 spec operations + POST /completions) |
call_plan |
CallPlanner, Query, PlannedCall |
table-checked request planning; no network |
gateway |
Gateway, AnonymousClient, Attribution, Endpoint |
two keyed ApiClients + keyless client, attribution headers |
errors |
ErrorBody, ErrorInfo |
envelope, typed error_type, 200-with-error shapes |
model_ref |
ModelRef |
author/slug + catalog (:free :batch :thinking :extended) and routing (:nitro :floor :exacto :online) variants |
provider_preferences |
ProviderPreferences |
order, only, ignore, allow_fallbacks, require_parameters, data_collection, zdr, quantizations, sort(+partition), max_price, preferred_max_latency / min_throughput, options |
reasoning |
ReasoningConfig |
reasoning object |
plugins |
Plugin family |
web, file-parser, response-healing, moderation, context-compression, auto-router, web-fetch, RawPlugin for the rest |
server_tools |
ServerTools |
function tools and openrouter:* server tools |
chat_params |
ChatParams, ResponseFormats |
validated /chat/completions body |
chat_result, chat_stream |
ChatResult, ChatStreamParser |
response and SSE folding |
chat_service |
ChatService |
chat + legacy completions, blocking and streaming |
chat_model |
OpenrouterChatModel |
neutral ChatModel |
inference_services, stream_summary |
ResponsesService, MessagesService, stream parsers |
Responses (beta) and Messages skins |
models |
ModelsService, ProvidersService, ModelFilter |
catalog |
account |
AccountService, GenerationService, KeysService |
key, credits, activity, generation stats, key management |
admin |
guardrails, BYOK, workspaces, observability, private endpoints, directory, vault | management surface |
platform |
embeddings, media, batches, files, presets, catalog, auth | the rest |
pkce.cpp |
PkcePair |
RFC 7636 S256 |
Credentials
Two separate keys, two ApiClients, never a fallback between them:
OPENROUTER_API_KEY (inference and reads) and OPENROUTER_MANAGEMENT_KEY
(rows with key mgmt). Public rows (key none: models, providers, counts,
jwks, ...) go through a keyless client. Optional: OPENROUTER_APP_URL
(HTTP-Referer, required for app attribution), OPENROUTER_APP_TITLE
(X-OpenRouter-Title and legacy X-Title), OPENROUTER_APP_CATEGORIES
(X-OpenRouter-Categories, at most 2), OPENROUTER_BASE_URL (https or
loopback http only). Router metadata opt-in is Attribution::router_metadata
(X-OpenRouter-Metadata: enabled).
Contracts
- Every path, query parameter and body field goes through
CallPlannerand must be declared incalls.h; undeclared input is rejected before any I/O. - Ids are
Service::valid_idchecked (author may carry the alias marker~); partner text ({user}) is 1..512 bytes, URL-encoded,./..refused. - Caps live in
caps.h; list walks (ModelsService::list_all) stop atkMaxModelPagesand reporttruncated. - Destructive calls are separate methods without defaults (
remove,delete_*,unassign_*); the demo adds a dry-run gate. - A top-level
erroron a 200 body and a choice withfinish_reason: "error"are thrown asllm::ApiError(type =error_typewhen sent, else the code). - Streaming: SSE comments (
: OPENROUTER PROCESSING) are dropped bySseDecoder; a mid-stream error is thrown after the chunks before it. Usagemaps prompt/completion/total,prompt_tokens_details.cached_tokens,completion_tokens_details.reasoning_tokens; cost (USD) is onChatResult.
Sources
https://openrouter.ai/openapi.json(OpenAPI 3.1, info version 1.0.0, fetched 2026-10-24): 139 operations, 919 schemas. Primary source. Saved copy used for exploration only; the checker fetches it live.https://openrouter.ai/docs/llms-full.txt(docs plus generated SDK references, 4.6 MB, 2026-10-24): errors guide (typed error codes, mid-stream errors, 200-with-error), streaming guide (heartbeat comments), model variants, plugins, app attribution, router metadata, reasoning.- Live unauthenticated probes (below).
Cross-checks: paths and fields come from (1) and the SDK reference pages in (2) (they are generated from the same document, so they are not independent for field lists); behavior (errors, SSE, variants, headers) comes from (2) and was checked against live responses where a key is not needed.
Verified against spec
python3 -I src/openrouter/tools/check_spec.py --probe on 2026-10-24: 140
rows checked (1 documented-only), 139 spec operations, 0 problems. The checker
verifies method, path, operationId, public-vs-keyed (401 present), body
fields (both directions), query parameters (both directions), multipart / form
formats, and fails on any spec operation missing from the table.
Verified live (2026-10-24, no key)
GET /models200, 469 models,total_countandlinks.nextpresent; pricing values are decimal strings; ids include~alias/...authors and:free/:batchvariants.list_allwalk read the whole catalog and every id parsed as aModelRef(MOLO_LIVE_NET=1 ./build/ai_test).GET /providers200 (114 providers);GET /models/count200;GET /models/openai/gpt-4o/endpoints200;GET /model/openai/gpt-4o200;GET /embeddings/models,GET /endpoints/zdr200 without a key.GET /key,GET /credits,POST /chat/completions,POST /messages,POST /completionsanswer 401{"error":{"message":"No cookie auth credentials found","code":401}}(numeric code);POST /auth/keyswith{}answers 400 (public).
Unverified
- Every authenticated response shape (chat, responses, messages, generation, keys, admin lists) is taken from spec examples and docs, not seen.
POST /completionsexists (401 live, docs list it under router metadata) but is absent from the OpenAPI document; its field list incalls.his the OpenAI legacy set plus OpenRouter routing fields, inferred.reasoning.excludeis documented but not in the spec schema; kept as sent.- Server tool
typenames beyond the spec's ten are accepted by form only. - The
grant_typeliteral for/oauth/token(RFC 8693 URN) is the standard value; the spec lists the field without an enum. modelsfallback count: no vendor limit found, local ceiling 16.- Streaming of
/images(streamfield) is not parsed (raw body only). - Rows keyed
mgmtfollow the spec descriptions ("Management key required"); vault rows are keyedapiper their securitySchemes.
Gaps
llm::ApiErrorcarries noerror.metadata,Retry-Afteror response headers (foundation,src/llm/error.h);describe()works from status and type only. Mid-stream and 200-with-error shapes keep full metadata viaErrorBody.SseDecoderdrops comment lines, so heartbeats cannot be counted or surfaced as progress (src/llm/sse.cpp).ai.mkdoes not linksrc/securitybeyond Base64, sopkce.cppcarries its own SHA-256 and reads/dev/urandom.reasoning_detailscannot round-trip through the neutralllm::Message; tool loops with reasoning models needChatServicewith raw messages.- Files upload takes the whole file in memory (
Capsupload ceiling of the foundation); no resumable upload. - Typed result classes exist for chat, models, endpoints, providers, key info,
credits, generation; other responses are returned as
Json.