{"openapi":"3.1.0","info":{"title":"AI Stupid Level Smart Router API","version":"1.0.0","description":"An OpenAI-compatible endpoint that routes each request to the model measuring best for it, on AI Stupid Level's continuously re-run benchmarks (coding, reasoning, tool use), using your own provider keys. Use any OpenAI client with base URL https://aistupidlevel.info/v1 and a router key (aism_…). Send X-ASL-Sandbox: true to test without calling a provider or spending anything.","contact":{"name":"AI Stupid Level","url":"https://aistupidlevel.info/contact"}},"servers":[{"url":"https://aistupidlevel.info","description":"Production"}],"security":[{"RouterKey":[]}],"tags":[{"name":"Chat","description":"Routed chat completions (OpenAI format)."},{"name":"Routing","description":"Inspect routing decisions and rate answers."},{"name":"Account","description":"Usage and limits of the calling key."},{"name":"Models","description":"Routable models and embeddings."},{"name":"Anthropic","description":"Anthropic Messages pass-through (no routing)."}],"paths":{"/v1/chat/completions":{"post":{"tags":["Chat"],"operationId":"createChatCompletion","summary":"Create a routed chat completion","description":"OpenAI Chat Completions format. `model` is an auto-* routing mode (see the RoutingModel schema), \"auto\" for your saved preference, or a model id from GET /v1/models to pin one. Text only. Tool calling, forced tool_choice, JSON output and streaming work on every model; a tool-calling conversation stays on the model that made the calls. On failure the router falls back along the chain (streaming: only before the first byte).","parameters":[{"name":"X-ASL-Sandbox","in":"header","required":false,"schema":{"type":"string","enum":["true","false"]},"description":"true: run the real routing (preferences, ranking, fallbacks) as if you had a key for every provider, then return a deterministic mock answer. No provider is called; nothing is spent or counted."},{"name":"X-ASL-Sandbox-Simulate","in":"header","required":false,"schema":{"type":"string","enum":["fallback","rate_limited","allowance_exhausted","insufficient_quota","provider_key_rejected","model_unavailable","server_error"]},"description":"Sandbox only: make the request fall back, or fail with the given error, to test your error handling."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Non-streaming only. Repeating a key within 24 h returns the stored response instead of routing again (Idempotent-Replayed: true); the same key with a different body is refused (422); a repeat while the first is still running gets 409. 5xx and 429 outcomes are not stored, so a retry after them is a new attempt."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatCompletionRequest"}}}},"responses":{"200":{"description":"The completion. With stream: true, a text/event-stream of chat.completion.chunk events ending with data: [DONE].","headers":{"X-AISM-Provider":{"description":"Provider that served the answer (openai, anthropic, google, deepseek, kimi, glm).","schema":{"type":"string"}},"X-AISM-Model":{"description":"Model that served the answer.","schema":{"type":"string"}},"X-AISM-Reasoning":{"description":"Why this model was chosen, including any fallback (ASCII).","schema":{"type":"string"}},"X-AISM-Latency":{"description":"Time to the answer in milliseconds (non-streaming).","schema":{"type":"string"}},"X-AISM-Request-Id":{"description":"Request id; the same as the completion id. Quote it when reporting a problem.","schema":{"type":"string"}},"X-AISM-Sandbox":{"description":"Present and \"true\" when the answer is a sandbox mock.","schema":{"type":"string"}},"Idempotent-Replayed":{"description":"\"true\" when the response was replayed for a repeated Idempotency-Key.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatCompletion"}},"text/event-stream":{"schema":{"type":"string","description":"Server-sent events: data: <ChatCompletionChunk JSON>, then data: [DONE]."}}}},"400":{"description":"Invalid request (invalid_messages, invalid_tools, unsupported_content, invalid_tool_choice, invalid_response_format, unsupported_parameter, model_not_found), provider_rejected_request, provider_key_rejected, no_provider_keys, no_routable_model, invalid_idempotency_key, invalid_sandbox_simulation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing, invalid or expired router key (invalid_api_key, expired_api_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"idempotency_in_progress: a request with this Idempotency-Key is still running (Retry-After).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"413":{"description":"Body over 32 MB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"idempotency_key_reused: the key was used with a different body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"allowance_exhausted, insufficient_quota (key budget), rate_limited (Retry-After), provider_quota_exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"internal_error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"model_unavailable (every model failed provider-side), tool_choice_not_honoured.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/route/preview":{"post":{"tags":["Routing"],"operationId":"previewRoute","summary":"Preview the routing decision without sending the request","description":"Same body as POST /v1/chat/completions (messages may be omitted). Returns the strategy, the model the request would go to, and the fallback chain. Nothing is called or counted. With X-ASL-Sandbox: true, answers as if you had a key for every provider.","parameters":[{"name":"X-ASL-Sandbox","in":"header","required":false,"schema":{"type":"string","enum":["true","false"]}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatCompletionRequest"}}}},"responses":{"200":{"description":"The decision.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RoutePreview"}}}},"400":{"description":"Invalid request, no_provider_keys or no_routable_model.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Invalid router key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/router/feedback":{"post":{"tags":["Routing"],"operationId":"rateCompletion","summary":"Rate an answer","description":"Ratings feed the production signals that adjust routing.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackRequest"}}}},"responses":{"200":{"description":"Recorded.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"note":{"type":"string"}}}}}},"400":{"description":"Missing id or invalid rating.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Invalid router key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No completion with that id for this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/usage":{"get":{"tags":["Account"],"operationId":"getUsage","summary":"Allowance, credits and key budget for this month","responses":{"200":{"description":"Usage.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Usage"}}}},"401":{"description":"Invalid router key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/models":{"get":{"tags":["Models"],"operationId":"listModels","summary":"List routing modes and routable models","responses":{"200":{"description":"Models.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModelList"}}}},"401":{"description":"Invalid router key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/embeddings":{"post":{"tags":["Models"],"operationId":"createEmbedding","summary":"Create embeddings (OpenAI embedding models)","description":"Requires an OpenAI provider key. auto-embedding = text-embedding-3-small.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmbeddingRequest"}}}},"responses":{"200":{"description":"Embeddings (OpenAI format).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmbeddingResponse"}}}},"400":{"description":"Invalid request or no OpenAI key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Invalid router key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Allowance or budget.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/messages":{"post":{"tags":["Anthropic"],"operationId":"createAnthropicMessage","summary":"Anthropic Messages pass-through","description":"Native Anthropic request and response, sent to Anthropic with your Anthropic key. No routing or fallbacks: `model` must be a Claude model id. Accepts the router key as x-api-key (Anthropic SDKs, Claude Code) or Authorization: Bearer. Streaming is native.","security":[{"RouterKey":[]},{"RouterKeyHeader":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Anthropic Messages API request.","additionalProperties":true}}}},"responses":{"200":{"description":"Anthropic Messages API response.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Invalid router key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/openapi.json":{"get":{"tags":["Account"],"operationId":"getOpenApi","summary":"This document","security":[],"responses":{"200":{"description":"OpenAPI 3.1 document.","content":{"application/json":{"schema":{"type":"object"}}}}}}}},"components":{"securitySchemes":{"RouterKey":{"type":"http","scheme":"bearer","bearerFormat":"aism_…","description":"A router key from https://aistupidlevel.info/router/keys"},"RouterKeyHeader":{"type":"apiKey","in":"header","name":"x-api-key"}},"schemas":{"RoutingModel":{"type":"string","description":"A routing mode. \"auto\" uses your saved preference. Any model id from GET /v1/models pins that model instead.","enum":["auto","auto-best","auto-coding","auto-reasoning","auto-tooling","auto-agentic","auto-value","auto-value-coding","auto-value-reasoning","auto-value-tooling","auto-value-agentic","auto-consistent","auto-fastest-quality","auto-fastest","auto-cheapest","auto-task","auto-split"]},"ChatCompletionRequest":{"type":"object","required":["model","messages"],"properties":{"model":{"type":"string","description":"A routing mode (RoutingModel) or a model id.","examples":["auto-coding"]},"messages":{"type":"array","items":{"$ref":"#/components/schemas/ChatMessage"},"minItems":1},"temperature":{"type":"number","minimum":0,"maximum":2},"top_p":{"type":"number"},"max_tokens":{"type":"integer","minimum":1},"max_completion_tokens":{"type":"integer","minimum":1},"stream":{"type":"boolean","default":false},"stream_options":{"type":"object","properties":{"include_usage":{"type":"boolean"}}},"tools":{"type":"array","items":{"$ref":"#/components/schemas/Tool"}},"tool_choice":{"$ref":"#/components/schemas/ToolChoice"},"parallel_tool_calls":{"type":"boolean"},"response_format":{"$ref":"#/components/schemas/ResponseFormat"},"reasoning_effort":{"type":"string","enum":["none","minimal","low","medium","high","xhigh","max"],"description":"Reasoning depth. Every value is accepted for every model: a level the chosen model does not support is mapped to the nearest one it does (a tie goes to the deeper level)."},"stop":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]},"frequency_penalty":{"type":"number"},"presence_penalty":{"type":"number"},"seed":{"type":"integer"},"n":{"type":"integer","enum":[1],"description":"Only 1 is supported."}}},"ChatMessage":{"type":"object","required":["role"],"properties":{"role":{"type":"string","enum":["system","developer","user","assistant","tool"]},"content":{"oneOf":[{"type":"string"},{"type":"null"},{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["text"]},"text":{"type":"string"}}}}],"description":"Text only: image, audio and file parts are refused (unsupported_content)."},"name":{"type":"string"},"tool_calls":{"type":"array","items":{"$ref":"#/components/schemas/ToolCall"}},"tool_call_id":{"type":"string"}}},"Tool":{"type":"object","required":["type","function"],"properties":{"type":{"type":"string","enum":["function"]},"function":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"description":{"type":"string"},"parameters":{"type":"object","description":"JSON Schema."}}}}},"ToolChoice":{"oneOf":[{"type":"string","enum":["auto","none","required"]},{"type":"object","required":["type","function"],"properties":{"type":{"type":"string","enum":["function"]},"function":{"type":"object","required":["name"],"properties":{"name":{"type":"string"}}}}}]},"ResponseFormat":{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["text","json_object","json_schema"]},"json_schema":{"type":"object","properties":{"name":{"type":"string"},"schema":{"type":"object"},"strict":{"type":"boolean"}}}}},"ToolCall":{"type":"object","required":["id","type","function"],"properties":{"id":{"type":"string"},"type":{"type":"string","enum":["function"]},"function":{"type":"object","required":["name","arguments"],"properties":{"name":{"type":"string"},"arguments":{"type":"string","description":"JSON string."}}}}},"Usage":{"type":"object","properties":{"object":{"type":"string","enum":["usage"]},"period":{"type":"string","examples":["2026-10"]},"plan":{"type":"string","enum":["free","pro","developer","teams","enterprise","legacy_pro"]},"requests":{"type":"object","properties":{"used":{"type":"integer","description":"Successful routed requests this month."},"included":{"type":["integer","null"],"description":"null when unlimited."},"remaining":{"type":["integer","null"]},"unlimited":{"type":"boolean"}}},"credits":{"type":"object","properties":{"requests":{"type":"integer","description":"Prepaid requests left."},"in_use":{"type":"boolean"}}},"allowed":{"type":"boolean","description":"Whether a routed request would be accepted now."},"key":{"type":["object","null"],"properties":{"id":{"type":"integer"},"name":{"type":"string"},"prefix":{"type":"string"},"project_id":{"type":["integer","null"]},"expires_at":{"type":["string","null"]},"budget":{"type":"object","properties":{"monthly_limit_usd":{"type":["number","null"]},"hard_limit":{"type":"boolean"},"spent_this_month_usd":{"type":"number"}}}}}}},"TokenUsage":{"type":"object","properties":{"prompt_tokens":{"type":"integer"},"completion_tokens":{"type":"integer"},"total_tokens":{"type":"integer"},"prompt_tokens_details":{"type":"object","properties":{"cached_tokens":{"type":"integer"}}},"completion_tokens_details":{"type":"object","properties":{"reasoning_tokens":{"type":"integer"}}}}},"ChatCompletion":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","enum":["chat.completion"]},"created":{"type":"integer"},"model":{"type":"string","description":"The model that answered."},"system_fingerprint":{"type":"string","description":"aism_v1_<provider>"},"choices":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"message":{"type":"object","properties":{"role":{"type":"string","enum":["assistant"]},"content":{"type":["string","null"]},"tool_calls":{"type":"array","items":{"$ref":"#/components/schemas/ToolCall"}},"refusal":{"type":["string","null"]}}},"finish_reason":{"type":"string","enum":["stop","length","tool_calls"]}}}},"usage":{"$ref":"#/components/schemas/TokenUsage"}}},"ChatCompletionChunk":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","enum":["chat.completion.chunk"]},"created":{"type":"integer"},"model":{"type":"string"},"choices":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"delta":{"type":"object","properties":{"role":{"type":"string"},"content":{"type":"string"},"tool_calls":{"type":"array","items":{"type":"object"}}}},"finish_reason":{"type":["string","null"]}}}},"usage":{"$ref":"#/components/schemas/TokenUsage"},"error":{"type":"object","description":"Only when a stream stops mid-answer (code stream_interrupted)."}}},"RouteSelection":{"type":"object","properties":{"model":{"type":"string"},"provider":{"type":"string"},"score":{"type":"number"},"reasoning":{"type":"string"},"estimated_cost_usd":{"type":["number","null"]}}},"RoutePreview":{"type":"object","properties":{"object":{"type":"string","enum":["route.preview"]},"requested_model":{"type":"string"},"strategy":{"type":"string","description":"The routing strategy used, or \"pinned\"."},"sandbox":{"type":"boolean"},"primary":{"$ref":"#/components/schemas/RouteSelection"},"fallbacks":{"type":"array","items":{"$ref":"#/components/schemas/RouteSelection"}},"fallback_enabled":{"type":"boolean"}}},"FeedbackRequest":{"type":"object","required":["id","rating"],"properties":{"id":{"type":"string","description":"The completion id (response id / X-AISM-Request-Id)."},"rating":{"oneOf":[{"type":"integer","enum":[1,-1]},{"type":"string","enum":["up","down","1","-1"]}]}}},"ModelList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string"},"created":{"type":"integer"},"owned_by":{"type":"string"}}}}}},"EmbeddingRequest":{"type":"object","required":["input"],"properties":{"model":{"type":"string","enum":["auto-embedding","text-embedding-3-small","text-embedding-3-large"],"default":"text-embedding-3-small"},"input":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]},"dimensions":{"type":"integer"},"encoding_format":{"type":"string","enum":["float","base64"]}}},"EmbeddingResponse":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"model":{"type":"string"},"data":{"type":"array","items":{"type":"object","properties":{"object":{"type":"string"},"index":{"type":"integer"},"embedding":{"type":"array","items":{"type":"number"}}}}},"usage":{"type":"object","properties":{"prompt_tokens":{"type":"integer"},"total_tokens":{"type":"integer"}}}}},"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["message"],"properties":{"message":{"type":"string"},"type":{"type":"string"},"code":{"type":["string","null"]},"param":{"type":["string","null"]}},"additionalProperties":true}}}}}}