{"openapi":"3.1.0","info":{"title":"Liminal AI Service","version":"0.1.0"},"x-ai-mode-defaults":[{"mode":"lite-instant","provider":"fireworks","model":"accounts/fireworks/models/deepseek-v4-flash","reasoning":"none"},{"mode":"lite","provider":"fireworks","model":"accounts/fireworks/models/deepseek-v4-flash","reasoning":"medium"},{"mode":"lite-deep","provider":"fireworks","model":"accounts/fireworks/models/deepseek-v4-flash","reasoning":"xhigh"},{"mode":"standard-instant","provider":"fireworks","model":"accounts/fireworks/models/kimi-k2p6","reasoning":"none"},{"mode":"standard","provider":"fireworks","model":"accounts/fireworks/models/kimi-k2p6","reasoning":"medium"},{"mode":"standard-deep","provider":"fireworks","model":"accounts/fireworks/models/kimi-k2p6","reasoning":"xhigh"},{"mode":"lumenal-instant","provider":"fireworks","model":"accounts/fireworks/routers/kimi-k2p6-turbo","reasoning":"none"},{"mode":"lumenal","provider":"fireworks","model":"accounts/fireworks/routers/kimi-k2p6-turbo","reasoning":"medium"},{"mode":"lumenal-deep","provider":"fireworks","model":"accounts/fireworks/routers/kimi-k2p6-turbo","reasoning":"xhigh"}],"x-liminal-ai-invocation-contract":{"allowedSelectionFields":["mode"],"forbiddenSelectionFields":["provider","model","reasoning","thinking","thinkingLevel"],"modes":["lite-instant","lite","lite-deep","standard-instant","standard","standard-deep","lumenal-instant","lumenal","lumenal-deep"],"note":"Product callers select exactly one AI mode. Provider, model, and reasoning are service-owned runtime choices."},"paths":{"/health":{"get":{"summary":"Check service health","responses":{"200":{"description":"Service is healthy","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}}}}},"/openapi.json":{"get":{"summary":"Read the OpenAPI contract","responses":{"200":{"description":"OpenAPI document"}}}},"/v1/ui/settings":{"get":{"summary":"Read AI console settings","responses":{"200":{"description":"AI console settings"}}}},"/v1/sessions":{"post":{"summary":"Create an AI session","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionCreateRequest"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Session"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid service bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"413":{"description":"Request body too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Runtime error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/chat":{"post":{"summary":"Run a non-agentic model turn","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatRequest"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid service bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"413":{"description":"Request body too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Runtime error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/embeddings":{"post":{"summary":"Create embeddings","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmbeddingRequest"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmbeddingResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid service bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"413":{"description":"Request body too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Runtime error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/agent/runs":{"post":{"summary":"Run a Pi Mono agent","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentRunRequest"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentRun"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid service bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"413":{"description":"Request body too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Runtime error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/runs/{runId}":{"get":{"summary":"Read an agent run","security":[{"bearerAuth":[]}],"parameters":[{"name":"runId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Agent run","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentRun"}}}},"404":{"description":"Run not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/runs/{runId}/status":{"get":{"summary":"Read current agent run status","security":[{"bearerAuth":[]}],"parameters":[{"name":"runId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Agent run status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunStatusSnapshot"}}}},"404":{"description":"Run not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/runs/{runId}/events":{"get":{"summary":"Stream agent run events and status snapshots","security":[{"bearerAuth":[]}],"parameters":[{"name":"runId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Server-sent run events. Emits event and status messages.","content":{"text/event-stream":{"schema":{"type":"string"}}}},"404":{"description":"Run not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/spend":{"get":{"summary":"Summarize AI spend by caller, org, user, provider, model, and mode","security":[{"bearerAuth":[]}],"parameters":[{"name":"since","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"until","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"caller","in":"query","schema":{"type":"string"}},{"name":"orgId","in":"query","schema":{"type":"string"}},{"name":"userId","in":"query","schema":{"type":"string"}},{"name":"model","in":"query","schema":{"type":"string"}},{"name":"provider","in":"query","schema":{"$ref":"#/components/schemas/ProviderName"}},{"name":"mode","in":"query","schema":{"$ref":"#/components/schemas/AiMode"}}],"responses":{"200":{"description":"Spend data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SpendSummary"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/spend/records":{"get":{"summary":"List AI spend records","security":[{"bearerAuth":[]}],"parameters":[{"name":"since","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"until","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"caller","in":"query","schema":{"type":"string"}},{"name":"orgId","in":"query","schema":{"type":"string"}},{"name":"userId","in":"query","schema":{"type":"string"}},{"name":"model","in":"query","schema":{"type":"string"}},{"name":"provider","in":"query","schema":{"$ref":"#/components/schemas/ProviderName"}},{"name":"mode","in":"query","schema":{"$ref":"#/components/schemas/AiMode"}}],"responses":{"200":{"description":"Spend data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SpendRecordsResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"AiMode":{"type":"string","enum":["lite-instant","lite","lite-deep","standard-instant","standard","standard-deep","lumenal-instant","lumenal","lumenal-deep"]},"ProviderName":{"type":"string","enum":["openai","fireworks","deepinfra","google"]},"ReasoningLevel":{"type":"string","enum":["none","minimal","low","medium","high","xhigh"]},"SpendRecordKind":{"type":"string","enum":["chat","embedding","agent"]},"JsonObject":{"type":"object","additionalProperties":true},"HealthResponse":{"type":"object","required":["ok","service"],"properties":{"ok":{"type":"boolean"},"service":{"type":"string"}}},"ErrorResponse":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}},"AiMessage":{"type":"object","required":["role","content"],"properties":{"role":{"type":"string","enum":["system","user","assistant","tool"]},"content":{"type":"string"},"toolCallId":{"type":"string"},"name":{"type":"string"}}},"SessionCreateRequest":{"type":"object","properties":{"metadata":{"$ref":"#/components/schemas/JsonObject"}}},"Session":{"type":"object","required":["sessionId","createdAt","updatedAt","messages","metadata"],"properties":{"sessionId":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"messages":{"type":"array","items":{"$ref":"#/components/schemas/AiMessage"}},"metadata":{"$ref":"#/components/schemas/JsonObject"}}},"ChatRequest":{"type":"object","additionalProperties":false,"x-liminal-ai-invocation-contract":{"allowedSelectionFields":["mode"],"forbiddenSelectionFields":["provider","model","reasoning","thinking","thinkingLevel"],"modes":["lite-instant","lite","lite-deep","standard-instant","standard","standard-deep","lumenal-instant","lumenal","lumenal-deep"],"note":"Product callers select exactly one AI mode. Provider, model, and reasoning are service-owned runtime choices."},"required":["mode","prompt"],"properties":{"sessionId":{"type":"string","minLength":1},"mode":{"$ref":"#/components/schemas/AiMode"},"prompt":{"type":"string","minLength":1},"systemPrompt":{"type":"string","minLength":1},"temperature":{"type":"number","minimum":0,"maximum":2},"maxOutputTokens":{"type":"integer","minimum":1},"responseFormat":{"$ref":"#/components/schemas/AiResponseFormat"},"metadata":{"$ref":"#/components/schemas/JsonObject"}}},"ChatResponse":{"type":"object","required":["session","text","usage"],"properties":{"session":{"$ref":"#/components/schemas/Session"},"text":{"type":"string"},"usage":{"$ref":"#/components/schemas/UsageRecord"}}},"EmbeddingRequest":{"type":"object","additionalProperties":false,"x-liminal-ai-invocation-contract":{"allowedSelectionFields":["mode"],"forbiddenSelectionFields":["provider","model","reasoning","thinking","thinkingLevel"],"modes":["lite-instant","lite","lite-deep","standard-instant","standard","standard-deep","lumenal-instant","lumenal","lumenal-deep"],"note":"Product callers select exactly one AI mode. Provider, model, and reasoning are service-owned runtime choices."},"required":["mode","texts"],"properties":{"mode":{"$ref":"#/components/schemas/AiMode"},"texts":{"type":"array","minItems":1,"maxItems":256,"items":{"type":"string","minLength":1}},"dimensions":{"type":"integer","minimum":1,"maximum":4096},"metadata":{"$ref":"#/components/schemas/JsonObject"}}},"EmbeddingUsageRecord":{"type":"object","required":["provider","model","mode","inputTokens","totalTokens","costUsd"],"properties":{"provider":{"$ref":"#/components/schemas/ProviderName"},"model":{"type":"string"},"mode":{"$ref":"#/components/schemas/AiMode"},"inputTokens":{"type":["integer","null"],"minimum":0},"totalTokens":{"type":["integer","null"],"minimum":0},"costUsd":{"type":"number","minimum":0}}},"EmbeddingResponse":{"type":"object","required":["embeddings","usage"],"properties":{"embeddings":{"type":"array","items":{"type":"array","items":{"type":"number"}}},"usage":{"$ref":"#/components/schemas/EmbeddingUsageRecord"}}},"McpAuthorization":{"oneOf":[{"type":"object","additionalProperties":false,"required":["type"],"properties":{"type":{"type":"string","enum":["forward_bearer"]}}},{"type":"object","additionalProperties":false,"required":["type"],"properties":{"type":{"type":"string","enum":["client_credentials"]}}},{"type":"object","additionalProperties":false,"required":["type","token"],"properties":{"type":{"type":"string","enum":["bearer_token"]},"token":{"type":"string","minLength":1}}}]},"McpServerDefinition":{"type":"object","additionalProperties":false,"required":["name","authorization"],"properties":{"name":{"type":"string","pattern":"^[a-zA-Z0-9_-]{1,80}$"},"url":{"type":"string","format":"uri"},"audience":{"type":"string","format":"uri"},"authorization":{"$ref":"#/components/schemas/McpAuthorization"},"headers":{"type":"object","additionalProperties":{"type":"string"}}}},"AiResponseFormat":{"oneOf":[{"type":"object","additionalProperties":false,"required":["type"],"properties":{"type":{"type":"string","enum":["json_object"]}}},{"type":"object","additionalProperties":false,"required":["type","jsonSchema"],"properties":{"type":{"type":"string","enum":["json_schema"]},"jsonSchema":{"type":"object","additionalProperties":false,"required":["name","schema"],"properties":{"name":{"type":"string","pattern":"^[a-zA-Z0-9_-]{1,80}$"},"description":{"type":"string","minLength":1},"schema":{"type":"object","additionalProperties":true,"description":"JSON Schema object for the model response."},"strict":{"type":"boolean"}}}}}]},"AgentRunRequest":{"type":"object","additionalProperties":false,"x-liminal-ai-invocation-contract":{"allowedSelectionFields":["mode"],"forbiddenSelectionFields":["provider","model","reasoning","thinking","thinkingLevel"],"modes":["lite-instant","lite","lite-deep","standard-instant","standard","standard-deep","lumenal-instant","lumenal","lumenal-deep"],"note":"Product callers select exactly one AI mode. Provider, model, and reasoning are service-owned runtime choices."},"required":["mode","goal","mcpServers"],"properties":{"sessionId":{"type":"string","minLength":1},"mode":{"$ref":"#/components/schemas/AiMode"},"goal":{"type":"string","minLength":1},"temperature":{"type":"number","minimum":0,"maximum":2},"maxOutputTokens":{"type":"integer","minimum":1},"maxIterations":{"type":"integer","minimum":1,"maximum":50,"default":8},"parallelToolCalls":{"type":"boolean","default":true},"mcpServers":{"type":"array","minItems":1,"maxItems":16,"items":{"$ref":"#/components/schemas/McpServerDefinition"}},"responseFormat":{"$ref":"#/components/schemas/AiResponseFormat"},"metadata":{"$ref":"#/components/schemas/JsonObject"}}},"UsageRecord":{"type":"object","required":["provider","model","mode","reasoning","promptTokens","completionTokens","totalTokens","cachedTokens","costUsd"],"properties":{"provider":{"$ref":"#/components/schemas/ProviderName"},"model":{"type":"string"},"mode":{"$ref":"#/components/schemas/AiMode"},"reasoning":{"$ref":"#/components/schemas/ReasoningLevel"},"promptTokens":{"type":"integer","minimum":0},"completionTokens":{"type":"integer","minimum":0},"totalTokens":{"type":"integer","minimum":0},"cachedTokens":{"type":"integer","minimum":0},"costUsd":{"type":"number","minimum":0}}},"SpendAttribution":{"type":"object","properties":{"caller":{"type":"string"},"orgId":{"type":"string"},"userId":{"type":"string"},"sourceRepo":{"type":"string"},"requestId":{"type":"string"}}},"SpendRecord":{"type":"object","required":["spendId","occurredAt","kind","attribution","provider","model","mode","promptTokens","completionTokens","inputTokens","totalTokens","cachedTokens","costUsd"],"properties":{"spendId":{"type":"string"},"occurredAt":{"type":"string","format":"date-time"},"kind":{"$ref":"#/components/schemas/SpendRecordKind"},"sessionId":{"type":"string"},"runId":{"type":"string"},"attribution":{"$ref":"#/components/schemas/SpendAttribution"},"provider":{"$ref":"#/components/schemas/ProviderName"},"model":{"type":"string"},"mode":{"$ref":"#/components/schemas/AiMode"},"reasoning":{"$ref":"#/components/schemas/ReasoningLevel"},"promptTokens":{"type":"integer","minimum":0},"completionTokens":{"type":"integer","minimum":0},"inputTokens":{"type":["integer","null"],"minimum":0},"totalTokens":{"type":["integer","null"],"minimum":0},"cachedTokens":{"type":"integer","minimum":0},"costUsd":{"type":"number","minimum":0}}},"SpendQuery":{"type":"object","properties":{"since":{"type":"string","format":"date-time"},"until":{"type":"string","format":"date-time"},"caller":{"type":"string"},"orgId":{"type":"string"},"userId":{"type":"string"},"model":{"type":"string"},"provider":{"$ref":"#/components/schemas/ProviderName"},"mode":{"$ref":"#/components/schemas/AiMode"}}},"SpendBreakdown":{"type":"object","required":["key","costUsd","recordCount","totalTokens"],"properties":{"key":{"type":"string"},"costUsd":{"type":"number","minimum":0},"recordCount":{"type":"integer","minimum":0},"totalTokens":{"type":"integer","minimum":0}}},"SpendSummary":{"type":"object","required":["query","totalCostUsd","recordCount","totalTokens","byModel","byCaller","byOrgId","byUserId","byProvider","byMode"],"properties":{"query":{"$ref":"#/components/schemas/SpendQuery"},"totalCostUsd":{"type":"number","minimum":0},"recordCount":{"type":"integer","minimum":0},"totalTokens":{"type":"integer","minimum":0},"byModel":{"type":"array","items":{"$ref":"#/components/schemas/SpendBreakdown"}},"byCaller":{"type":"array","items":{"$ref":"#/components/schemas/SpendBreakdown"}},"byOrgId":{"type":"array","items":{"$ref":"#/components/schemas/SpendBreakdown"}},"byUserId":{"type":"array","items":{"$ref":"#/components/schemas/SpendBreakdown"}},"byProvider":{"type":"array","items":{"$ref":"#/components/schemas/SpendBreakdown"}},"byMode":{"type":"array","items":{"$ref":"#/components/schemas/SpendBreakdown"}}}},"SpendRecordsResponse":{"type":"object","required":["query","records"],"properties":{"query":{"$ref":"#/components/schemas/SpendQuery"},"records":{"type":"array","items":{"$ref":"#/components/schemas/SpendRecord"}}}},"RunEvent":{"type":"object","required":["id","runId","occurredAt","type","attributes"],"properties":{"id":{"type":"string"},"runId":{"type":"string"},"sessionId":{"type":"string"},"occurredAt":{"type":"string","format":"date-time"},"type":{"type":"string","enum":["session.created","chat.model_call","chat.model_return","embedding.model_call","embedding.model_return","agent.started","agent.mcp_connect","agent.mcp_tools","agent.model_call","agent.message_start","agent.message_update","agent.thinking_start","agent.thinking_end","agent.text_start","agent.text_delta","agent.text_end","agent.tool_prepare","agent.model_return","agent.tool_call","agent.tool_update","agent.tool_return","agent.completed","agent.failed"]},"attributes":{"$ref":"#/components/schemas/JsonObject"}}},"AgentRun":{"type":"object","required":["runId","sessionId","status","goal","mode","reasoning","provider","model","startedAt","usage","events","metadata"],"properties":{"runId":{"type":"string"},"sessionId":{"type":"string"},"status":{"type":"string","enum":["running","completed","failed"]},"goal":{"type":"string"},"mode":{"$ref":"#/components/schemas/AiMode"},"reasoning":{"$ref":"#/components/schemas/ReasoningLevel"},"provider":{"$ref":"#/components/schemas/ProviderName"},"model":{"type":"string"},"startedAt":{"type":"string","format":"date-time"},"completedAt":{"type":"string","format":"date-time"},"outputText":{"type":"string"},"error":{"type":"string"},"usage":{"type":"array","items":{"$ref":"#/components/schemas/UsageRecord"}},"events":{"type":"array","items":{"$ref":"#/components/schemas/RunEvent"}},"metadata":{"$ref":"#/components/schemas/JsonObject"}}},"RunActivity":{"type":"string","enum":["starting","connecting_mcp","loading_tools","waiting_for_model","thinking","writing","preparing_tool","calling_tool","completed","failed"]},"RunToolStatus":{"type":"object","required":["toolName","toolCallId"],"properties":{"toolName":{"type":"string"},"toolCallId":{"type":"string"},"startedAt":{"type":"string","format":"date-time"},"completedAt":{"type":"string","format":"date-time"},"ok":{"type":"boolean"}}},"RunStatusSnapshot":{"type":"object","required":["runId","sessionId","status","activity","summary","updatedAt","startedAt","eventCount"],"properties":{"runId":{"type":"string"},"sessionId":{"type":"string"},"status":{"type":"string","enum":["running","completed","failed"]},"activity":{"$ref":"#/components/schemas/RunActivity"},"summary":{"type":"string"},"updatedAt":{"type":"string","format":"date-time"},"startedAt":{"type":"string","format":"date-time"},"completedAt":{"type":"string","format":"date-time"},"eventCount":{"type":"integer","minimum":0},"lastEvent":{"$ref":"#/components/schemas/RunEvent"},"toolExecutionMode":{"type":"string","enum":["sequential","parallel"]},"activeToolCalls":{"type":"array","items":{"$ref":"#/components/schemas/RunToolStatus"}},"currentToolCall":{"$ref":"#/components/schemas/RunToolStatus"},"lastToolCall":{"$ref":"#/components/schemas/RunToolStatus"}}}}}}