{"openapi":"3.1.0","info":{"title":"LENA API contract","version":"2026-05-17.30c49","description":"Session/plan based preview API contract. API keys, per-key quota, and key rotation remain intentionally deferred; route-scoped chef-process quota storage hardening is included."},"paths":{"/api/chef/process":{"get":{"operationId":"getChefProcessHealth","summary":"Read chef-process availability and safe usage limits","responses":{"200":{"description":"Health and safe session/plan metadata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChefProcessHealth"}}}}}},"post":{"operationId":"postChefProcess","summary":"Run the Chef preview conversion pipeline","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChefProcessRequest"},"examples":{"roastLispexToJavascript":{"value":{"code":"(define (square x) (* x x))","explicitLanguage":"lispex","targetLanguage":"javascript","stage":"roast"}}}}}},"responses":{"200":{"description":"Chef pipeline response with sanitized usage metadata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChefProcessResponse"}}}},"400":{"description":"E_BAD_REQUEST / E_BINARY / E_UNSUPPORTED_LANG","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"type":"string"},"code":{"type":"string","enum":["E_BAD_REQUEST","E_BINARY","E_UNSUPPORTED_LANG"]},"route":{"type":"string"},"tier":{"type":"string"},"maxBodyBytes":{"type":"number"}},"additionalProperties":true}}}},"401":{"description":"E_UNAUTHORIZED","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"type":"string"},"code":{"type":"string","enum":["E_UNAUTHORIZED"]},"route":{"type":"string"},"tier":{"type":"string"},"maxBodyBytes":{"type":"number"}},"additionalProperties":true}}}},"403":{"description":"E_FORBIDDEN / E_CSRF","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"type":"string"},"code":{"type":"string","enum":["E_FORBIDDEN","E_CSRF"]},"route":{"type":"string"},"tier":{"type":"string"},"maxBodyBytes":{"type":"number"}},"additionalProperties":true}}}},"411":{"description":"E_LENGTH_REQUIRED","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"type":"string"},"code":{"type":"string","enum":["E_LENGTH_REQUIRED"]},"route":{"type":"string"},"tier":{"type":"string"},"maxBodyBytes":{"type":"number"}},"additionalProperties":true}}}},"413":{"description":"E_TOO_LARGE","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"type":"string"},"code":{"type":"string","enum":["E_TOO_LARGE"]},"route":{"type":"string"},"tier":{"type":"string"},"maxBodyBytes":{"type":"number"}},"additionalProperties":true}}}},"429":{"description":"E_RATE_LIMIT / E_DAILY_LIMIT","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"type":"string"},"code":{"type":"string","enum":["E_RATE_LIMIT","E_DAILY_LIMIT"]},"route":{"type":"string"},"tier":{"type":"string"},"maxBodyBytes":{"type":"number"}},"additionalProperties":true}}}},"500":{"description":"E_INTERNAL","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"type":"string"},"code":{"type":"string","enum":["E_INTERNAL"]},"route":{"type":"string"},"tier":{"type":"string"},"maxBodyBytes":{"type":"number"}},"additionalProperties":true}}}},"503":{"description":"E_QUOTA_STORAGE_UNAVAILABLE","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"type":"string"},"code":{"type":"string","enum":["E_QUOTA_STORAGE_UNAVAILABLE"]},"route":{"type":"string"},"tier":{"type":"string"},"maxBodyBytes":{"type":"number"}},"additionalProperties":true}}}},"504":{"description":"E_TIMEOUT","content":{"application/json":{"schema":{"type":"object","required":["error","code"],"properties":{"error":{"type":"string"},"code":{"type":"string","enum":["E_TIMEOUT"]},"route":{"type":"string"},"tier":{"type":"string"},"maxBodyBytes":{"type":"number"}},"additionalProperties":true}}}}}}},"/api/openapi.json":{"get":{"operationId":"getOpenApiContract","summary":"Return the generated static OpenAPI contract","responses":{"200":{"description":"OpenAPI 3.1 document generated from shared constants."}}}}},"components":{"schemas":{"ChefProcessRequest":{"type":"object","required":["code"],"additionalProperties":false,"properties":{"code":{"type":"string","minLength":1},"filename":{"type":"string","maxLength":512},"mimeType":{"type":"string","maxLength":128},"explicitLanguage":{"type":"string","minLength":1},"targetLanguage":{"type":"string","minLength":1},"stage":{"type":"string","enum":["auto","detect","harvest","marinate","parbake","roast","distill"]}}},"ChefProcessResponse":{"type":"object","required":["detection","marinate","timings","usage"],"properties":{"detection":{"anyOf":[{"type":"null"},{"type":"object","properties":{"language":{"type":"string"},"confidence":{"type":"number"}},"additionalProperties":true}]},"marinate":{"anyOf":[{"type":"null"},{"type":"object","required":["code"],"properties":{"code":{"type":"string"}}}]},"distill":{"type":"object","additionalProperties":true},"roast":{"type":"object","required":["code","targetLanguage"],"properties":{"code":{"type":"string"},"targetLanguage":{"type":"string"}}},"verification":{"$ref":"#/components/schemas/ChefVerificationMetadata"},"timings":{"anyOf":[{"type":"null"},{"type":"object","additionalProperties":{"type":"number"}}]},"usage":{"$ref":"#/components/schemas/ChefProcessUsageMetadata"}},"additionalProperties":false},"ChefVerificationMetadata":{"type":"object","required":["inputLanguage","targetLanguage","inputStatus","targetStatus","pairKey","verified","preview","previewSides","reason"],"properties":{"inputLanguage":{"type":["string","null"]},"targetLanguage":{"type":["string","null"]},"inputStatus":{"type":"string","enum":["hardened","planned","closed-for-hardening","preview","unknown"]},"targetStatus":{"type":"string","enum":["hardened","planned","closed-for-hardening","preview","unknown"]},"pairKey":{"type":["string","null"]},"verified":{"type":"boolean"},"preview":{"type":"boolean"},"previewSides":{"type":"array","items":{"type":"string","enum":["input","output"]}},"reason":{"type":"string","enum":["contract-hardened","input-preview","output-preview","input-output-preview","planned-disabled","unverified-pair","unknown"]}},"additionalProperties":false},"ChefProcessUsageMetadata":{"type":"object","required":["route","plan","tier","authRequired","authenticated","authorized","limits"],"properties":{"route":{"type":"string","const":"chef-process"},"plan":{"type":"string","enum":["free","pro"]},"tier":{"type":"string","enum":["anon","non-admin","admin"]},"authRequired":{"type":"boolean"},"authenticated":{"type":"boolean"},"authorized":{"type":"boolean"},"limits":{"type":"object","required":["maxInputBytes","timeoutMs","rate","daily"],"properties":{"maxInputBytes":{"type":"number"},"timeoutMs":{"type":"number"},"rate":{"type":"object","required":["capacity","refillPerSec"],"properties":{"capacity":{"type":"number"},"refillPerSec":{"type":"number"}},"additionalProperties":false},"daily":{"$ref":"#/components/schemas/ChefDailyQuotaSnapshot"}},"additionalProperties":false}},"additionalProperties":false},"ChefDailyQuotaSnapshot":{"type":"object","required":["freeLimit","proLimit","planLimit","remaining","resetSec","countAvailable","storage","degraded"],"properties":{"freeLimit":{"type":"number"},"proLimit":{"type":"number"},"planLimit":{"type":["number","null"]},"remaining":{"type":["number","null"]},"resetSec":{"type":"number"},"countAvailable":{"type":"boolean"},"storage":{"type":"string","enum":["reliable","memory","unavailable"]},"degraded":{"type":"boolean"}},"additionalProperties":false},"ChefProcessHealth":{"type":"object","required":["ok","runtime","authRequired","authenticated","authorized","limits","usage"],"properties":{"ok":{"type":"boolean"},"runtime":{"type":"string","const":"nodejs"},"authRequired":{"type":"boolean"},"authenticated":{"type":"boolean"},"authorized":{"type":"boolean"},"limits":{"type":"object","required":["maxInputBytes","timeoutMs","rate","daily"],"properties":{"maxInputBytes":{"type":"number"},"timeoutMs":{"type":"number"},"rate":{"type":"object","required":["capacity","refillPerSec"],"properties":{"capacity":{"type":"number"},"refillPerSec":{"type":"number"}}},"daily":{"$ref":"#/components/schemas/ChefDailyQuotaSnapshot"}}},"usage":{"$ref":"#/components/schemas/ChefProcessUsageMetadata"}},"additionalProperties":false}}}}