Endpoint Matrix

Base URL:

https://api.rout.my/v1

Endpoint	Method	Body shape	Output	Notes
GET /models	GET	none	OpenAI-style model list	Use this first to copy exact model IDs.
POST /chat/completions	POST	model, messages, optional stream, tools, vision content	Chat completion or SSE stream	Best for OpenAI-compatible chat clients.
POST /responses	POST	model, input, optional tools/stream-like fields	Responses-style object or stream	Useful when an app expects the newer Responses shape.
POST /embeddings	POST	model, input, optional encoding_format	Embedding list	For search, RAG, clustering, and semantic matching.
POST /systemone	POST	model, state, questions	answers, usage	Native TypeSafe: noul, choice, score; confidence and structured legend; no streaming.
/typesafe/v1/systemone, /typesafe/v1/models	POST, GET	Native SDK prefix; inference/reseller key	System One response / {models: [...]}	SDK base URL: https://api.rout.my/typesafe.
POST /images/generations	POST	model, prompt, optional n, size, quality, image_config	data[].url or data[].b64_json	Single-prompt image generation.
POST /images/edits	POST	model, prompt, images or multipart image, optional edit fields	data[].url or data[].b64_json	OpenAI-style image editing through OpenAI-compatible providers.
POST /video/generations	POST	model, prompt, optional unified video fields (duration, resolution, audio, quality, media inputs)	Video generation response	rout.my maps unified fields into provider-specific video options when supported.
GET https://api.rout.my/embed/image:{model}	GET	query params	Raw image bytes	Convenient for embedding generated images in pages. This route is outside /v1.
POST /messages	POST	Anthropic-style messages body	Anthropic-compatible response	For Anthropic-native clients.
POST https://api.rout.my/compatible/v1beta/models/{model}:generateContent	POST	Gemini-style contents	Gemini-compatible response	For Gemini-compatible clients. This route is outside /v1; do not prepend the base URL above.

Compatibility Notes

Reserve quota resets

Method	Endpoint	Auth	Purpose
GET	/api/v1/user/quota-resets	User JWT	Own reset balance, weekly allowance, and auto_reset_enabled
PUT	/api/v1/user/quota-resets	User JWT	Save {auto_reset_enabled: boolean}; default is false; returns the saved flag
POST	/api/v1/user/quota-resets/use	User JWT	Use one available reset manually

Enabling automatic resets does not immediately spend a reset. When fewer than 100 daily tokens remain, the next quota-billed request uses one available reset and continues with the restored daily allowance. Weekly resets are used before gifted resets. Without an available reset, the usual quota error remains. Free models, Kimi fixed quota, reseller PAYG and trusted read-only requests do not consume automatic daily resets. The setting persists across daily/weekly resets.

Daily token transfers

Method	Endpoint	Auth	Purpose
GET, POST	/api/v1/user/token-transfers	User JWT	Read own limits/history; send {recipient, amount, idempotency_key}
POST	/api/v1/user/token-transfers/preview	User JWT	Preview {recipient, amount} and confirm the exact recipient
PATCH	/api/v1/user/token-transfers/preferences	User JWT	Set {receive_disabled}
GET, PUT	/api/v1/admin/token-transfers/policy	Admin; CSRF for PUT	Read/save policy with optimistic revision
GET	/api/v1/admin/token-transfers	Admin	Latest 100 operations; optional user_id

Transfers refill spent daily tokens within the recipient's existing quota until 00:00 UTC. Sending/receiving and service-wide limits include pending operations and do not restart after quota resets. Received gifts cannot be forwarded that day. 202 means pending: retain the same payload and idempotency key when checking an uncertain outcome. The authenticated session selects the sender; an inference API key does not authorize these browser endpoints.

General

• rout.my forwards model-specific fields when the selected provider supports them.
• Unknown fields can be ignored or rejected depending on endpoint family and provider behavior.
• For browser tools, keep keys user-supplied. Do not hardcode a shared key into public frontend code.
• For retries, prefer exponential backoff on 429, 500, 502, and 503.

Routy support workspace

These endpoints use asynchronous jobs; they do not run an LLM inside the gateway. Request diagnosis checks the authenticated request owner in ClickHouse before creating a durable case. Stored request facts exclude raw payloads, provider mappings, credentials, IPs and upstream error bodies. A log that has not reached ClickHouse yet returns 404 and can be retried after analytics refreshes.

Method	Path	Auth	Purpose
GET, POST	/api/v1/user/routy/cases	User JWT	List own cases; create with {request_id, locale, question?}; reuse an open case for the same own request
GET	/api/v1/user/routy/cases/{id}	User JWT + owner	Bounded transcript, request facts, structured card and published incident summary
POST	/api/v1/user/routy/cases/{id}/messages	User JWT + owner	Add {content} and queue diagnosis or a private staff draft during handoff
POST	/api/v1/user/routy/cases/{id}/{resolve,reopen,handoff,retry}	User JWT + owner	Resolve, reopen, request staff or retry a failed answer job
GET	/api/v1/routy/cases	Admin	Staff workspace case list, cursor pagination
GET	/api/v1/routy/cases/{id}	Admin	Private operator/bug drafts, case usage and transcript
POST	/api/v1/routy/cases/{id}/{takeover,resume,resolve}	Admin + CSRF	Persistent staff hold and revision invalidation
POST	/api/v1/routy/cases/{id}/messages	Admin + CSRF	Explicit reviewed in-app staff reply; dashboard cases only
POST	/api/v1/routy/cases/{id}/{operator-draft,bug-draft}	Admin + CSRF	Generate with {} or save reviewed {content}; no external publication
GET	/api/v1/routy/incidents	Admin	Candidate/confirmed incidents with independent affected-user and technical aggregates
POST	/api/v1/routy/incidents/{id}	Admin + CSRF	Update {status?, public_summary?, publish?}; publication requires confirmed/resolved status and recorded technical corroboration
POST	/api/v1/internal/support/routy/jobs/claim	SUPPORT_BOT_TOKEN only	Claim {limit:1..5, lease_seconds:30..300, worker_id}; max three attempts
POST	/api/v1/internal/support/routy/jobs/{id}/complete	SUPPORT_BOT_TOKEN + lease	Commit {lease_token, revision, content, card, evidence, usage, disposition}; stale answers are discarded, repeated results are idempotent
POST	/api/v1/internal/support/routy/jobs/{id}/fail	SUPPORT_BOT_TOKEN + lease	Bounded retry with {lease_token, error_code, retryable, usage?}
POST	/api/v1/internal/support/routy/cases/discord/control	SUPPORT_BOT_TOKEN only	Read fresh {staff_hold, case_id?, revision?} using {source_ref} immediately before Discord delivery; unknown channel returns false without creating state
POST	/api/v1/internal/support/routy/cases/discord	SUPPORT_BOT_TOKEN only	Upsert scrubbed private Discord snapshot {source_ref, locale?, card?, staff_active?, messages}; source message IDs deduplicate intake; caller cannot assign an account owner

List responses are {cases, next_cursor?} and accept limit (1–100) and cursor. Detail responses are {case, messages, evidence, usage, history_truncated}. Message roles are user, assistant, staff; private drafts are not transcript messages. Case cards contain problem, facts, hypotheses, checks, missing, next_step, confidence. Facts preserve {field, value, evidence_ids, observed_at?, request_id?}; evidence references must accompany completion. Worker usage includes model_calls, tool_calls, input_tokens, output_tokens and nullable cost_usd; missing upstream prices remain unknown, not zero. User responses omit private drafts, account IDs and private incident aggregates. Staff takeover prevents an already running answer from publishing and persists across Discord snapshot refreshes until an explicit resume.

Request facts label coarse HTTP-only fallback text with error_detail_available: false and error_summary_source: "status_fallback". The client protocol stays empty when not known; upstream wire_profile is not a client endpoint.