{"openapi":"3.1.0","info":{"title":"ElseLane API","version":"1.1.0","summary":"Credits-first AI answer API with automatic cross-provider failover","description":"ElseLane classifies your prompt, routes across provider chains, and fails over when the primary lane errors, times out, or is circuit-open.\n\nAuthenticate with `Authorization: Bearer el_live_…` (or `el_test_…`). Create keys in the dashboard after sign-in.\n\nBase URL: `https://api.elselane.com` (paths under `/v1`).\n\nPrompts and answers are not stored — usage metadata only. Successful answers are charged at estimated provider token cost × 1.10, rounded up, with a minimum of 10 credits ($0.001).\n\nJSON mode: set `response_format: { \"type\": \"json_object\" }` to route only to providers with native JSON constraints (OpenAI / Google / Groq / Together), validate parseable JSON objects, and fail over on invalid JSON. Not compatible with `stream: true` in v1.\n\nModel disclosure: read `model_used` / `elselane.model_used`, or response headers `X-ElseLane-Model`, `X-ElseLane-Provider`, `X-ElseLane-Fallback`, `X-ElseLane-Task-Type`.","contact":{"name":"ElseLane","url":"https://elselane.com/contact","email":"contact@elselane.com"},"license":{"name":"Proprietary","url":"https://elselane.com/terms"}},"servers":[{"url":"https://api.elselane.com","description":"Production API. Paths are /v1/…"}],"tags":[{"name":"Answer","description":"Prompt-only answer API"},{"name":"Chat","description":"OpenAI-compatible chat completions (`model: auto` only)"}],"paths":{"/v1/answer":{"post":{"tags":["Answer"],"operationId":"createAnswer","summary":"Answer a prompt","description":"Send only a prompt. ElseLane classifies, routes, and fails over. Optional `Idempotency-Key` replays usage metadata for a prior success (answer body is not stored).","security":[{"bearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":256},"description":"Optional unique key. On replay of a successful prior request, returns metadata only (`answer: null`, `idempotent_replay: true`)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnswerRequest"},"examples":{"basic":{"summary":"Prompt only","value":{"prompt":"Explain CAP theorem simply"}},"withSystem":{"summary":"With system instruction","value":{"prompt":"Summarize this in one sentence","system":"Be concise. No fluff."}},"jsonMode":{"summary":"JSON structured output","value":{"prompt":"Return title and summary for a post about failover APIs","system":"Return JSON with keys title and summary.","response_format":{"type":"json_object"}}}}}}},"responses":{"200":{"description":"Successful answer (or idempotent metadata replay)","headers":{"X-ElseLane-Model":{"schema":{"type":"string"},"description":"Model that produced the answer"},"X-ElseLane-Provider":{"schema":{"type":"string"},"description":"Provider that produced the answer"},"X-ElseLane-Fallback":{"schema":{"type":"string","enum":["0","1"]}},"X-ElseLane-Task-Type":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnswerResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"422":{"$ref":"#/components/responses/PiiBlocked"},"503":{"$ref":"#/components/responses/AllProvidersFailed"}}}},"/v1/chat/completions":{"post":{"tags":["Chat"],"operationId":"createChatCompletion","summary":"Create a chat completion","description":"OpenAI-compatible shim. Use `model: \"auto\"` only. ElseLane metadata is under `elselane`.\n\nSet `stream: true` for Server-Sent Events (`text/event-stream`) ending with `data: [DONE]`. The final chunk includes `usage` and `elselane`.\n\nSet `response_format: { \"type\": \"json_object\" }` for guaranteed JSON object routing (not combined with streaming).","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatCompletionRequest"},"examples":{"basic":{"summary":"Non-streaming","value":{"model":"auto","messages":[{"role":"user","content":"Hello"}]}},"streaming":{"summary":"Streaming SSE","value":{"model":"auto","stream":true,"messages":[{"role":"user","content":"Hello"}]}},"jsonMode":{"summary":"JSON structured output","value":{"model":"auto","response_format":{"type":"json_object"},"messages":[{"role":"system","content":"Return JSON with keys title and summary."},{"role":"user","content":"Write a short blog brief about failover APIs."}]}}}}}},"responses":{"200":{"description":"Chat completion JSON, or SSE stream when `stream: true`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatCompletionResponse"}},"text/event-stream":{"schema":{"type":"string","description":"OpenAI-style SSE chunks (`data: {…}\\n\\n`), ending with `data: [DONE]\\n\\n`. Final chunk may include `usage` and `elselane`."}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"422":{"$ref":"#/components/responses/PiiBlocked"},"503":{"$ref":"#/components/responses/AllProvidersFailed"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"el_live_… / el_test_…","description":"API key from the ElseLane dashboard. Prefer `el_live_` in production."}},"schemas":{"TaskType":{"type":"string","enum":["chat","code","reasoning","summarize","creative","extraction"],"description":"Classifier task type used to select the provider chain"},"Attempt":{"type":"object","required":["provider","model"],"properties":{"provider":{"type":"string","description":"Provider id (e.g. openai, anthropic, google, groq)"},"model":{"type":"string"},"error":{"type":"string","description":"Present when this attempt failed"}}},"AnswerUsage":{"type":"object","required":["input_tokens","output_tokens","credits_charged"],"properties":{"input_tokens":{"type":"integer","minimum":0},"output_tokens":{"type":"integer","minimum":0},"credits_charged":{"type":"integer","minimum":0,"description":"Credits debited (minimum 10 on successful answers)"}}},"PiiInfo":{"type":"object","properties":{"types":{"type":"array","items":{"type":"string"},"description":"Detected high-risk PII categories (e.g. ssn, credit_card)"}}},"AnswerRequest":{"type":"object","required":["prompt"],"properties":{"prompt":{"type":"string","minLength":1,"maxLength":100000,"description":"User prompt to answer"},"system":{"type":"string","maxLength":20000,"description":"Optional system instruction"},"response_format":{"$ref":"#/components/schemas/ResponseFormat"}}},"AnswerResponse":{"type":"object","required":["id","task_type","model_used","provider","fallback_used","usage"],"properties":{"id":{"type":"string","description":"Usage event id"},"answer":{"type":["string","null"],"description":"Model answer. Null on idempotent replay (bodies are not stored)."},"task_type":{"$ref":"#/components/schemas/TaskType"},"model_used":{"type":"string"},"provider":{"type":"string"},"fallback_used":{"type":"boolean"},"attempts":{"type":"array","items":{"$ref":"#/components/schemas/Attempt"}},"pii_redacted":{"type":"boolean","description":"True when admin PII mode is redact and matches were replaced"},"pii":{"$ref":"#/components/schemas/PiiInfo"},"usage":{"$ref":"#/components/schemas/AnswerUsage"},"idempotent_replay":{"type":"boolean","description":"True when this response is a metadata-only idempotency replay"},"note":{"type":"string"}}},"ChatMessage":{"type":"object","required":["role","content"],"properties":{"role":{"type":"string","enum":["system","user","assistant"]},"content":{"type":"string"}}},"ChatCompletionRequest":{"type":"object","required":["messages"],"properties":{"model":{"type":"string","const":"auto","default":"auto","description":"Only `\"auto\"` is supported in v1"},"messages":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/ChatMessage"}},"stream":{"type":"boolean","default":false,"description":"When true, respond with OpenAI-style SSE. Incompatible with response_format json_object in v1."},"response_format":{"$ref":"#/components/schemas/ResponseFormat"}}},"ResponseFormat":{"type":"object","required":["type"],"properties":{"type":{"type":"string","const":"json_object","description":"Route only to native JSON providers and validate a parseable JSON object"}}},"ElseLaneMeta":{"type":"object","required":["task_type","model_used","provider","fallback_used","credits_charged"],"properties":{"task_type":{"$ref":"#/components/schemas/TaskType"},"model_used":{"type":"string"},"provider":{"type":"string"},"fallback_used":{"type":"boolean"},"credits_charged":{"type":"integer","minimum":0},"attempts":{"type":"array","items":{"$ref":"#/components/schemas/Attempt"}},"pii_redacted":{"type":"boolean"},"pii":{"$ref":"#/components/schemas/PiiInfo"}}},"ChatCompletionResponse":{"type":"object","required":["id","object","created","model","choices","usage","elselane"],"properties":{"id":{"type":"string"},"object":{"type":"string","const":"chat.completion"},"created":{"type":"integer","description":"Unix timestamp (seconds)"},"model":{"type":"string","const":"auto"},"choices":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"message":{"type":"object","properties":{"role":{"type":"string","const":"assistant"},"content":{"type":"string"}}},"finish_reason":{"type":"string","enum":["stop"]}}}},"usage":{"type":"object","properties":{"prompt_tokens":{"type":"integer"},"completion_tokens":{"type":"integer"},"total_tokens":{"type":"integer"}}},"elselane":{"$ref":"#/components/schemas/ElseLaneMeta"}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}},"responses":{"BadRequest":{"description":"Invalid request body or unsupported model","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalidBody":{"value":{"error":"Invalid request body"}},"model":{"value":{"error":"Only model \"auto\" is supported in v1"}}}}}},"Unauthorized":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Invalid API key"}}}},"InsufficientCredits":{"description":"Not enough prepaid credits for the estimated request","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Error"},{"type":"object","properties":{"balance":{"type":"integer"},"estimated_credits":{"type":"integer"}}}]},"example":{"error":"Insufficient credits","balance":5,"estimated_credits":50}}}},"PiiBlocked":{"description":"High-risk PII blocked before any provider call","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Error"},{"type":"object","properties":{"pii":{"$ref":"#/components/schemas/PiiInfo"}}}]},"example":{"error":"High-risk PII blocked","pii":{"types":["ssn"]}}}}},"AllProvidersFailed":{"description":"Every provider in the chain failed","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Error"},{"type":"object","properties":{"detail":{"type":"string"},"attempts":{"type":"array","items":{"$ref":"#/components/schemas/Attempt"}}}}]}}}}}}}