{"openapi":"3.1.0","info":{"title":"Bolrach AI API","version":"1.0.0","description":"Text generation, summarizing, classification and content moderation on the shared Bolrach AI engine. Generation runs the current cheap-best GPT-5 lane; moderation combines a deterministic Nigeria-aware keyword floor with an LLM pass, so it always answers.","contact":{"url":"https://docs.bolrach.com/ai"}},"servers":[{"url":"https://api.bolrach.com"}],"security":[{"bearerKey":[]},{"headerKey":[]}],"paths":{"/v1/ai/answer":{"post":{"operationId":"aiAnswer","summary":"Answer a prompt","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"prompt":{"type":"string","maxLength":32000,"description":"The instruction or question."},"system":{"type":"string","maxLength":4000,"description":"Optional system framing."},"max_tokens":{"type":"integer","minimum":1,"maximum":1024,"default":512}},"required":["prompt"]},"example":{"prompt":"Write a one-line product tagline for a Nigerian B2B marketplace."}}}},"responses":{"200":{"description":"The answer.","content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","description":"The generated text."},"model":{"type":"string","description":"The model that produced it (upgraded over time, always GPT-5 family)."}},"required":["text","model"]}}}},"400":{"description":"Bad input (`bad_request`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"status":{"type":"integer"}},"required":["code","message","status"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"status":{"type":"integer"}},"required":["code","message","status"]}},"required":["error"]}}}},"403":{"description":"Key lacks the `ai:invoke` scope.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"status":{"type":"integer"}},"required":["code","message","status"]}},"required":["error"]}}}},"429":{"description":"Rate limit or daily quota exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"status":{"type":"integer"}},"required":["code","message","status"]}},"required":["error"]}}}},"502":{"description":"The AI backend or provider failed (`upstream_error`). Safe to retry with backoff.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"status":{"type":"integer"}},"required":["code","message","status"]}},"required":["error"]}}}}}}},"/v1/ai/summarize":{"post":{"operationId":"aiSummarize","summary":"Summarize text","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","maxLength":32000},"length":{"type":"string","enum":["short","medium","long"],"default":"short"}},"required":["text"]},"example":{"text":"Long article text...","length":"short"}}}},"responses":{"200":{"description":"The summary.","content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","description":"The generated text."},"model":{"type":"string","description":"The model that produced it (upgraded over time, always GPT-5 family)."}},"required":["text","model"]}}}},"400":{"description":"Bad input (`bad_request`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"status":{"type":"integer"}},"required":["code","message","status"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"status":{"type":"integer"}},"required":["code","message","status"]}},"required":["error"]}}}},"403":{"description":"Key lacks the `ai:invoke` scope.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"status":{"type":"integer"}},"required":["code","message","status"]}},"required":["error"]}}}},"429":{"description":"Rate limit or daily quota exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"status":{"type":"integer"}},"required":["code","message","status"]}},"required":["error"]}}}},"502":{"description":"The AI backend or provider failed (`upstream_error`). Safe to retry with backoff.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"status":{"type":"integer"}},"required":["code","message","status"]}},"required":["error"]}}}}}}},"/v1/ai/classify":{"post":{"operationId":"aiClassify","summary":"Classify text into one of your labels","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","maxLength":32000},"labels":{"type":"array","items":{"type":"string"},"minItems":2,"maxItems":20,"description":"You always get exactly one of these back."}},"required":["text","labels"]},"example":{"text":"My card was charged twice","labels":["billing","technical-support","sales"]}}}},"responses":{"200":{"description":"The chosen label.","content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string"},"model":{"type":"string"}},"required":["label","model"]}}}},"400":{"description":"Bad input (`bad_request`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"status":{"type":"integer"}},"required":["code","message","status"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"status":{"type":"integer"}},"required":["code","message","status"]}},"required":["error"]}}}},"403":{"description":"Key lacks the `ai:invoke` scope.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"status":{"type":"integer"}},"required":["code","message","status"]}},"required":["error"]}}}},"429":{"description":"Rate limit or daily quota exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"status":{"type":"integer"}},"required":["code","message","status"]}},"required":["error"]}}}},"502":{"description":"The AI backend or provider failed (`upstream_error`). Safe to retry with backoff.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"status":{"type":"integer"}},"required":["code","message","status"]}},"required":["error"]}}}}}}},"/v1/ai/moderate":{"post":{"operationId":"aiModerate","summary":"Moderate user content","description":"Never fails open or closed on provider errors: a deterministic keyword floor always runs, the LLM adds nuance when available.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","maxLength":20000}},"required":["text"]},"example":{"text":"double your money fast, whatsapp me"}}}},"responses":{"200":{"description":"The verdict.","content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","enum":["allow","review","block"]},"flagged":{"type":"boolean"},"scores":{"type":"object","properties":{"toxicity":{"type":"number"},"spam":{"type":"number"},"nsfw":{"type":"number"}}},"reasons":{"type":"array","items":{"type":"string"}},"engine":{"type":"string","description":"`keyword` or `llm` (which lane decided)."}},"required":["action","flagged","scores","reasons"]}}}},"400":{"description":"Bad input (`bad_request`).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"status":{"type":"integer"}},"required":["code","message","status"]}},"required":["error"]}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"status":{"type":"integer"}},"required":["code","message","status"]}},"required":["error"]}}}},"403":{"description":"Key lacks the `ai:invoke` scope.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"status":{"type":"integer"}},"required":["code","message","status"]}},"required":["error"]}}}},"429":{"description":"Rate limit or daily quota exceeded.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"status":{"type":"integer"}},"required":["code","message","status"]}},"required":["error"]}}}},"502":{"description":"The AI backend or provider failed (`upstream_error`). Safe to retry with backoff.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"status":{"type":"integer"}},"required":["code","message","status"]}},"required":["error"]}}}}}}}},"components":{"securitySchemes":{"bearerKey":{"type":"http","scheme":"bearer","description":"Authorization: Bearer bt_..."},"headerKey":{"type":"apiKey","in":"header","name":"x-api-key"}}}}