{"openapi":"3.1.0","info":{"title":"Oracle API","version":"1.0.0","description":"Unified LLM gateway for nuvocode apps. Routes chat, embedding and structured-JSON requests across OpenAI, Anthropic and Workers AI behind a single authenticated endpoint."},"servers":[{"url":"https://oracle.nuvocode.com","description":"production"}],"tags":[{"name":"meta","description":"Service metadata and health"},{"name":"inference","description":"LLM inference endpoints"}],"components":{"securitySchemes":{"oracleApp":{"type":"apiKey","in":"header","name":"x-oracle-app","description":"Registered app name."},"oracleSecret":{"type":"apiKey","in":"header","name":"x-oracle-secret","description":"Secret paired with the app name."}},"schemas":{"Message":{"type":"object","required":["role","content"],"properties":{"role":{"type":"string","enum":["system","user","assistant","tool"]},"content":{"type":"string"},"name":{"type":"string"}}},"Usage":{"type":"object","required":["tokensIn","tokensOut","estimatedCost"],"properties":{"tokensIn":{"type":"integer","minimum":0},"tokensOut":{"type":"integer","minimum":0},"estimatedCost":{"type":"number","minimum":0}}},"ChatRequest":{"type":"object","required":["messages"],"properties":{"task":{"type":"string","description":"Optional task hint for model routing."},"messages":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/Message"}},"model":{"type":"string"},"provider":{"type":"string","enum":["openai","anthropic","workers-ai"]},"temperature":{"type":"number","minimum":0,"maximum":2},"maxTokens":{"type":"integer","minimum":1},"stream":{"type":"boolean","default":false,"description":"When true, responds with SSE."},"metadata":{"type":"object","additionalProperties":true}}},"ChatResponse":{"type":"object","required":["id","provider","model","message","usage","latencyMs"],"properties":{"id":{"type":"string"},"provider":{"type":"string","enum":["openai","anthropic","workers-ai"]},"model":{"type":"string"},"message":{"$ref":"#/components/schemas/Message"},"usage":{"$ref":"#/components/schemas/Usage"},"latencyMs":{"type":"number","minimum":0}}},"EmbedRequest":{"type":"object","required":["input"],"properties":{"input":{"oneOf":[{"type":"string","minLength":1},{"type":"array","minItems":1,"items":{"type":"string","minLength":1}}]},"model":{"type":"string"},"provider":{"type":"string","enum":["openai","anthropic","workers-ai"]},"metadata":{"type":"object","additionalProperties":true}}},"EmbedResponse":{"type":"object","required":["id","provider","model","embeddings","usage","latencyMs"],"properties":{"id":{"type":"string"},"provider":{"type":"string","enum":["openai","anthropic","workers-ai"]},"model":{"type":"string"},"embeddings":{"type":"array","items":{"type":"array","items":{"type":"number"}}},"usage":{"$ref":"#/components/schemas/Usage"},"latencyMs":{"type":"number","minimum":0}}},"JsonRequest":{"type":"object","required":["messages","schema"],"properties":{"task":{"type":"string"},"messages":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/Message"}},"schema":{"type":"object","description":"JSON Schema the response must conform to."},"schemaName":{"type":"string"},"model":{"type":"string"},"provider":{"type":"string","enum":["openai","anthropic","workers-ai"]},"temperature":{"type":"number","minimum":0,"maximum":2},"metadata":{"type":"object","additionalProperties":true}}},"JsonResponse":{"type":"object","required":["id","provider","model","data","usage","latencyMs"],"properties":{"id":{"type":"string"},"provider":{"type":"string","enum":["openai","anthropic","workers-ai"]},"model":{"type":"string"},"data":{"description":"Model output validated against the requested schema."},"raw":{"$ref":"#/components/schemas/Message"},"usage":{"$ref":"#/components/schemas/Usage"},"latencyMs":{"type":"number","minimum":0}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}},"responses":{"Unauthorized":{"description":"Missing or invalid oracle credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"BadRequest":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/health":{"get":{"tags":["meta"],"summary":"Health check","description":"Liveness probe. No authentication required.","responses":{"200":{"description":"Service is up.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"service":{"type":"string"},"environment":{"type":"string"},"requestId":{"type":"string"}}}}}}}}},"/v1/chat":{"post":{"tags":["inference"],"summary":"Chat completion","description":"Generate a chat completion. Set `stream: true` for an SSE response.","security":[{"oracleApp":[],"oracleSecret":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatRequest"}}}},"responses":{"200":{"description":"Chat completion, or an SSE stream when `stream` is true.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatResponse"}},"text/event-stream":{"schema":{"type":"string"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/embed":{"post":{"tags":["inference"],"summary":"Create embeddings","description":"Embed one or more strings into vectors.","security":[{"oracleApp":[],"oracleSecret":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmbedRequest"}}}},"responses":{"200":{"description":"Embedding vectors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmbedResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/json":{"post":{"tags":["inference"],"summary":"Structured JSON completion","description":"Generate output validated against a caller-supplied JSON Schema.","security":[{"oracleApp":[],"oracleSecret":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRequest"}}}},"responses":{"200":{"description":"Structured JSON result.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}}