Files
moloapp/src/openrouter/SPEC.md
T

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 CallPlanner and must be declared in calls.h; undeclared input is rejected before any I/O.
  • Ids are Service::valid_id checked (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 at kMaxModelPages and report truncated.
  • Destructive calls are separate methods without defaults (remove, delete_*, unassign_*); the demo adds a dry-run gate.
  • A top-level error on a 200 body and a choice with finish_reason: "error" are thrown as llm::ApiError (type = error_type when sent, else the code).
  • Streaming: SSE comments (: OPENROUTER PROCESSING) are dropped by SseDecoder; a mid-stream error is thrown after the chunks before it.
  • Usage maps prompt/completion/total, prompt_tokens_details.cached_tokens, completion_tokens_details.reasoning_tokens; cost (USD) is on ChatResult.

Sources

  1. 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.
  2. 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.
  3. 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 /models 200, 469 models, total_count and links.next present; pricing values are decimal strings; ids include ~alias/... authors and :free / :batch variants. list_all walk read the whole catalog and every id parsed as a ModelRef (MOLO_LIVE_NET=1 ./build/ai_test).
  • GET /providers 200 (114 providers); GET /models/count 200; GET /models/openai/gpt-4o/endpoints 200; GET /model/openai/gpt-4o 200; GET /embeddings/models, GET /endpoints/zdr 200 without a key.
  • GET /key, GET /credits, POST /chat/completions, POST /messages, POST /completions answer 401 {"error":{"message":"No cookie auth credentials found","code":401}} (numeric code); POST /auth/keys with {} 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 /completions exists (401 live, docs list it under router metadata) but is absent from the OpenAPI document; its field list in calls.h is the OpenAI legacy set plus OpenRouter routing fields, inferred.
  • reasoning.exclude is documented but not in the spec schema; kept as sent.
  • Server tool type names beyond the spec's ten are accepted by form only.
  • The grant_type literal for /oauth/token (RFC 8693 URN) is the standard value; the spec lists the field without an enum.
  • models fallback count: no vendor limit found, local ceiling 16.
  • Streaming of /images (stream field) is not parsed (raw body only).
  • Rows keyed mgmt follow the spec descriptions ("Management key required"); vault rows are keyed api per their securitySchemes.

Gaps

  • llm::ApiError carries no error.metadata, Retry-After or response headers (foundation, src/llm/error.h); describe() works from status and type only. Mid-stream and 200-with-error shapes keep full metadata via ErrorBody.
  • SseDecoder drops comment lines, so heartbeats cannot be counted or surfaced as progress (src/llm/sse.cpp).
  • ai.mk does not link src/security beyond Base64, so pkce.cpp carries its own SHA-256 and reads /dev/urandom.
  • reasoning_details cannot round-trip through the neutral llm::Message; tool loops with reasoning models need ChatService with raw messages.
  • Files upload takes the whole file in memory (Caps upload 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.