{"openapi":"3.1.0","info":{"title":"AHKAM101 API","description":"Token-authenticated Q&A API for the Organization plan: answers to Islamic jurisprudence questions from Ayatollah Sistani's official rulings, with citations to the source texts. Send an API token as `Authorization: Bearer ahk_live_...`. The guide at `/api/v1/llms.txt` covers authentication, quota, rate limits and errors.","version":"1.0.0"},"servers":[{"url":"/api/v1"}],"paths":{"/questions":{"get":{"tags":["Questions"],"summary":"List questions","description":"Every question of this account, most recently active first, each with\nits first turn and latest five. Requires the `read` scope.","operationId":"listQuestions","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":50,"title":"Limit"}},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Opaque cursor from a previous page's `next_cursor`.","title":"Cursor"},"description":"Opaque cursor from a previous page's `next_cursor`."},{"name":"since","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Only questions with activity at or after this time.","title":"Since"},"description":"Only questions with activity at or after this time."},{"name":"until","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Only questions with activity before this time.","title":"Until"},"description":"Only questions with activity before this time."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuestionList"}}}},"401":{"description":"Missing, malformed, revoked or expired token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The token lacks the scope this endpoint needs, or the owning account is not on the Organization plan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The query failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorEnvelope"}}}}}},"post":{"tags":["Questions"],"summary":"Ask a new question","description":"Creates a question and answers its first turn. Requires the `ask`\nscope. With `Accept: text/event-stream` the turn is streamed.","operationId":"askQuestion","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"A UUID minted per ask. Scoped to the owning account and kept for 24 hours. A retry with the same key returns the first request's result.","title":"Idempotency-Key"},"description":"A UUID minted per ask. Scoped to the owning account and kept for 24 hours. A retry with the same key returns the first request's result."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AskRequest"}}}},"responses":{"200":{"description":"The ask finished: an answer, a clarification or a notice. With `Accept: text/event-stream`, the same turn as a stream.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Turn"}},"text/event-stream":{"schema":{"$ref":"#/components/schemas/StreamEvent"}}}},"400":{"description":"The request is well-formed but cannot be served as asked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, revoked or expired token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The token lacks the scope this endpoint needs, or the owning account is not on the Organization plan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The request conflicts with a turn in progress or an earlier idempotent request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is larger than 64 KiB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The body or query failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorEnvelope"}}}},"429":{"description":"Rate limit, in-flight cap or quota reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"The server failed before the turn started. No quota was spent.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A backing service was unavailable. No quota was spent.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/questions/{question_id}":{"get":{"tags":["Questions"],"summary":"Get a question with all its turns","description":"The question and every turn in order, with full answers and\ncitations. Requires the `read` scope.","operationId":"getQuestion","parameters":[{"name":"question_id","in":"path","required":true,"schema":{"type":"string","title":"Question Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Question"}}}},"401":{"description":"Missing, malformed, revoked or expired token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The token lacks the scope this endpoint needs, or the owning account is not on the Organization plan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource, it was deleted, or it belongs to another account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Questions"],"summary":"Delete a question","description":"Hides the question and all its turns from the API and the web app. A\nquestion with a turn in progress returns `409 question_busy`. Requires\nthe `delete` scope.","operationId":"deleteQuestion","parameters":[{"name":"question_id","in":"path","required":true,"schema":{"type":"string","title":"Question Id"}}],"responses":{"204":{"description":"Deleted."},"401":{"description":"Missing, malformed, revoked or expired token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The token lacks the scope this endpoint needs, or the owning account is not on the Organization plan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource, it was deleted, or it belongs to another account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The request conflicts with a turn in progress or an earlier idempotent request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/questions/{question_id}/turns/{turn_id}":{"get":{"tags":["Questions"],"summary":"Get one turn","description":"One turn with its answer and citations. Requires the `read` scope.","operationId":"getTurn","parameters":[{"name":"question_id","in":"path","required":true,"schema":{"type":"string","title":"Question Id"}},{"name":"turn_id","in":"path","required":true,"schema":{"type":"string","title":"Turn Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Turn"}}}},"401":{"description":"Missing, malformed, revoked or expired token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The token lacks the scope this endpoint needs, or the owning account is not on the Organization plan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource, it was deleted, or it belongs to another account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/questions/{question_id}/turns":{"post":{"tags":["Questions"],"summary":"Ask a follow-up","description":"Adds a turn to an existing question and answers it with the earlier\nturns as context. This is also how a clarification is answered. Requires\nthe `ask` scope. Behaves like `POST /questions`.","operationId":"askFollowUp","parameters":[{"name":"question_id","in":"path","required":true,"schema":{"type":"string","title":"Question Id"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"A UUID minted per ask. Scoped to the owning account and kept for 24 hours. A retry with the same key returns the first request's result.","title":"Idempotency-Key"},"description":"A UUID minted per ask. Scoped to the owning account and kept for 24 hours. A retry with the same key returns the first request's result."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FollowUpRequest"}}}},"responses":{"200":{"description":"The ask finished: an answer, a clarification or a notice. With `Accept: text/event-stream`, the same turn as a stream.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Turn"}},"text/event-stream":{"schema":{"$ref":"#/components/schemas/StreamEvent"}}}},"400":{"description":"The request is well-formed but cannot be served as asked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed, revoked or expired token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The token lacks the scope this endpoint needs, or the owning account is not on the Organization plan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The request conflicts with a turn in progress or an earlier idempotent request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is larger than 64 KiB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The body or query failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorEnvelope"}}}},"429":{"description":"Rate limit, in-flight cap or quota reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"The server failed before the turn started. No quota was spent.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A backing service was unavailable. No quota was spent.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource, it was deleted, or it belongs to another account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/questions/{question_id}/turns/{turn_id}/feedback":{"post":{"tags":["Questions"],"summary":"Rate an answer","description":"Records whether a turn's answer was helpful, with an optional\ncorrection. Only `answered` turns can be rated. Requires the `ask`\nscope.","operationId":"rateTurn","parameters":[{"name":"question_id","in":"path","required":true,"schema":{"type":"string","title":"Question Id"}},{"name":"turn_id","in":"path","required":true,"schema":{"type":"string","title":"Turn Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackRequest"}}}},"responses":{"204":{"description":"Recorded."},"401":{"description":"Missing, malformed, revoked or expired token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The token lacks the scope this endpoint needs, or the owning account is not on the Organization plan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource, it was deleted, or it belongs to another account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The turn is not an answered turn.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The request body is larger than 64 KiB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The body or query failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorEnvelope"}}}}}}},"/usage":{"get":{"tags":["Usage"],"summary":"Get quota position","description":"How much of the allowance the owning account has used, across the\nAPI and the web app together, and when it resets. Requires the `read`\nscope.","operationId":"getUsage","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Usage"}}}},"401":{"description":"Missing, malformed, revoked or expired token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The token lacks the scope this endpoint needs, or the owning account is not on the Organization plan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/rulings/{chunk_id}":{"get":{"tags":["Rulings"],"summary":"Get the full text of a cited ruling","description":"The complete ruling a citation's `chunk_id` points to, reassembled\nfrom its source so it does not start or end mid-sentence. Requires the\n`read` scope.","operationId":"getRuling","parameters":[{"name":"chunk_id","in":"path","required":true,"schema":{"type":"string","title":"Chunk Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Ruling"}}}},"401":{"description":"Missing, malformed, revoked or expired token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The token lacks the scope this endpoint needs, or the owning account is not on the Organization plan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such resource, it was deleted, or it belongs to another account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"A backing service was unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/llms.txt":{"get":{"tags":["Discovery"],"summary":"Plain-text guide to the API","description":"A guide to every route of the API and how to use it, in the llms.txt\nconvention. No token is needed. Rate limited by client IP. Cacheable for\none hour.","operationId":"getLlmsTxt","responses":{"200":{"description":"The guide.","headers":{"Cache-Control":{"schema":{"type":"string","example":"public, max-age=3600"}}},"content":{"text/plain":{"schema":{"type":"string"}}}},"429":{"description":"Rate limit reached.","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[]},"servers":[{"url":"/"}]}},"components":{"schemas":{"AskRequest":{"properties":{"question":{"type":"string","maxLength":8000,"minLength":1,"title":"Question","description":"The question, in any supported language."},"mode":{"type":"string","enum":["regular","scholar"],"title":"Mode","default":"regular"},"language":{"type":"string","enum":["auto","en","ar","fa","ur"],"title":"Language","default":"auto"}},"additionalProperties":false,"type":"object","required":["question"],"title":"AskRequest"},"Citation":{"properties":{"document":{"type":"string","title":"Document","description":"Stable identifier of the source book."},"document_display_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Document Display Name"},"document_native":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Document Native"},"volume":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Volume"},"page":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Page","description":"`null` when unknown."},"ruling_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ruling Number"},"excerpt":{"type":"string","title":"Excerpt"},"score":{"type":"number","title":"Score"},"language":{"type":"string","enum":["en","ar","fa","ur","unknown"],"title":"Language"},"chunk_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Chunk Id","description":"Pass to `GET /rulings/{chunk_id}` for the full ruling."},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url","description":"`null` when none exists."}},"type":"object","required":["document","page","excerpt","score","language","chunk_id","url"],"title":"Citation"},"Clarification":{"properties":{"questions":{"items":{"type":"string"},"type":"array","title":"Questions"},"options":{"items":{"type":"string"},"type":"array","title":"Options"},"language":{"type":"string","enum":["en","ar","fa","ur"],"title":"Language"}},"type":"object","required":["questions","options","language"],"title":"Clarification"},"Error":{"properties":{"error":{"type":"string","title":"Error","description":"Machine-readable code."},"message":{"type":"string","title":"Message","description":"Human-readable explanation."},"request_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Request Id","description":"This request's `X-Request-ID`. Quote it when reporting a problem."}},"type":"object","required":["error","message"],"title":"Error"},"FeedbackRequest":{"properties":{"rating":{"type":"string","enum":["helpful","not_helpful"],"title":"Rating"},"correction":{"anyOf":[{"type":"string","maxLength":4000},{"type":"null"}],"title":"Correction","description":"What the answer should have said, in your words."}},"additionalProperties":false,"type":"object","required":["rating"],"title":"FeedbackRequest"},"FollowUpRequest":{"properties":{"question":{"type":"string","maxLength":8000,"minLength":1,"title":"Question","description":"The follow-up, or a reply to a clarification."},"mode":{"type":"string","enum":["regular","scholar"],"title":"Mode","default":"regular"},"language":{"type":"string","enum":["auto","en","ar","fa","ur"],"title":"Language","default":"auto"}},"additionalProperties":false,"type":"object","required":["question"],"title":"FollowUpRequest"},"Quality":{"properties":{"passed":{"type":"boolean","title":"Passed"},"score":{"type":"number","title":"Score"},"issues":{"items":{"type":"string"},"type":"array","title":"Issues","default":[]}},"type":"object","required":["passed","score"],"title":"Quality"},"Question":{"properties":{"question_id":{"type":"string","title":"Question Id"},"question":{"type":"string","title":"Question"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"language":{"anyOf":[{"type":"string","enum":["en","ar","fa","ur"]},{"type":"null"}],"title":"Language"},"created_at":{"type":"string","title":"Created At"},"updated_at":{"type":"string","title":"Updated At"},"turns":{"items":{"$ref":"#/components/schemas/Turn"},"type":"array","title":"Turns"}},"type":"object","required":["question_id","question","language","created_at","updated_at","turns"],"title":"Question"},"QuestionList":{"properties":{"items":{"items":{"$ref":"#/components/schemas/QuestionSummary"},"type":"array","title":"Items"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor"}},"type":"object","required":["items","next_cursor"],"title":"QuestionList"},"QuestionSummary":{"properties":{"question_id":{"type":"string","title":"Question Id"},"question":{"type":"string","title":"Question"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"language":{"anyOf":[{"type":"string","enum":["en","ar","fa","ur"]},{"type":"null"}],"title":"Language"},"created_at":{"type":"string","title":"Created At"},"updated_at":{"type":"string","title":"Updated At"},"turn_count":{"type":"integer","title":"Turn Count"},"turns_truncated":{"type":"boolean","title":"Turns Truncated"},"turns":{"items":{"$ref":"#/components/schemas/TurnSummary"},"type":"array","title":"Turns"}},"type":"object","required":["question_id","question","language","created_at","updated_at","turn_count","turns_truncated","turns"],"title":"QuestionSummary"},"Ruling":{"properties":{"chunk_id":{"type":"string","title":"Chunk Id"},"text":{"type":"string","title":"Text"},"document_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Document Name"},"page_number":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Page Number"},"ruling_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ruling Number"},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url"},"language":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Language"}},"type":"object","required":["chunk_id","text","document_name","language"],"title":"Ruling"},"Turn":{"properties":{"turn_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Turn Id"},"question_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Question Id"},"kind":{"type":"string","enum":["answered","needs_clarification","notice","pending","failed"],"title":"Kind"},"question":{"type":"string","title":"Question"},"answer":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Answer"},"citations":{"items":{"$ref":"#/components/schemas/Citation"},"type":"array","title":"Citations","default":[]},"confidence":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Confidence"},"clarification":{"anyOf":[{"$ref":"#/components/schemas/Clarification"},{"type":"null"}]},"mode":{"anyOf":[{"type":"string","enum":["regular","scholar"]},{"type":"null"}],"title":"Mode"},"language":{"anyOf":[{"type":"string","enum":["en","ar","fa","ur"]},{"type":"null"}],"title":"Language"},"created_at":{"type":"string","title":"Created At"},"completed_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Completed At"},"response_time_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Response Time Ms"},"suggested_followups":{"items":{"type":"string"},"type":"array","maxItems":3,"title":"Suggested Followups","default":[]},"quality":{"anyOf":[{"$ref":"#/components/schemas/Quality"},{"type":"null"}]},"feedback":{"anyOf":[{"type":"string","enum":["helpful","not_helpful"]},{"type":"null"}],"title":"Feedback"},"error":{"anyOf":[{"$ref":"#/components/schemas/Error"},{"type":"null"}]}},"type":"object","required":["turn_id","question_id","kind","question","created_at"],"title":"Turn"},"TurnSummary":{"properties":{"turn_id":{"type":"string","title":"Turn Id"},"kind":{"type":"string","enum":["answered","needs_clarification","pending","failed"],"title":"Kind"},"question":{"type":"string","title":"Question"},"answer_preview":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Answer Preview"},"mode":{"anyOf":[{"type":"string","enum":["regular","scholar"]},{"type":"null"}],"title":"Mode"},"created_at":{"type":"string","title":"Created At"},"feedback":{"anyOf":[{"type":"string","enum":["helpful","not_helpful"]},{"type":"null"}],"title":"Feedback"}},"type":"object","required":["turn_id","kind","question","created_at"],"title":"TurnSummary"},"Usage":{"properties":{"plan":{"type":"string","title":"Plan"},"period":{"type":"string","enum":["daily","monthly"],"title":"Period"},"period_resets_at":{"type":"string","title":"Period Resets At"},"total":{"$ref":"#/components/schemas/UsageCounter"},"regular":{"$ref":"#/components/schemas/UsageCounter"},"scholar":{"$ref":"#/components/schemas/UsageCounter"}},"type":"object","required":["plan","period","period_resets_at","total","regular","scholar"],"title":"Usage"},"UsageCounter":{"properties":{"used":{"type":"integer","title":"Used"},"limit":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Limit","description":"`null` means unlimited."},"remaining":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Remaining"}},"type":"object","required":["used","limit","remaining"],"title":"UsageCounter"},"ValidationErrorDetail":{"properties":{"field":{"type":"string","title":"Field"},"message":{"type":"string","title":"Message"}},"type":"object","required":["field","message"],"title":"ValidationErrorDetail"},"ValidationErrorEnvelope":{"properties":{"error":{"type":"string","title":"Error","description":"Machine-readable code."},"message":{"type":"string","title":"Message","description":"Human-readable explanation."},"request_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Request Id","description":"This request's `X-Request-ID`. Quote it when reporting a problem."},"details":{"items":{"$ref":"#/components/schemas/ValidationErrorDetail"},"type":"array","title":"Details","default":[]}},"type":"object","required":["error","message"],"title":"ValidationErrorEnvelope"},"StreamClarification":{"properties":{"type":{"const":"clarification","title":"Type","type":"string"},"questions":{"items":{"type":"string"},"title":"Questions","type":"array"},"options":{"items":{"type":"string"},"title":"Options","type":"array"},"language":{"enum":["en","ar","fa","ur"],"title":"Language","type":"string"}},"required":["type","questions","options","language"],"title":"StreamClarification","type":"object"},"StreamDone":{"properties":{"type":{"const":"done","title":"Type","type":"string"},"kind":{"enum":["answered","needs_clarification","notice"],"title":"Kind","type":"string"},"turn_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Turn Id"}},"required":["type","kind"],"title":"StreamDone","type":"object"},"StreamError":{"properties":{"type":{"const":"error","title":"Type","type":"string"},"error":{"enum":["generation_failed","generation_unavailable","persistence_failed"],"title":"Error","type":"string"},"message":{"title":"Message","type":"string"}},"required":["type","error","message"],"title":"StreamError","type":"object"},"StreamFollowupSuggestions":{"properties":{"type":{"const":"followup_suggestions","title":"Type","type":"string"},"suggestions":{"items":{"type":"string"},"maxItems":3,"title":"Suggestions","type":"array"}},"required":["type","suggestions"],"title":"StreamFollowupSuggestions","type":"object"},"StreamMetadata":{"properties":{"type":{"const":"metadata","title":"Type","type":"string"},"turn_id":{"title":"Turn Id","type":"string"},"question_id":{"title":"Question Id","type":"string"},"citations":{"items":{"$ref":"#/components/schemas/Citation"},"title":"Citations","type":"array"},"confidence":{"title":"Confidence","type":"number"},"language":{"anyOf":[{"enum":["en","ar","fa","ur"],"type":"string"},{"type":"null"}],"default":null,"title":"Language"}},"required":["type","turn_id","question_id","citations","confidence"],"title":"StreamMetadata","type":"object"},"StreamNotice":{"properties":{"type":{"const":"notice","title":"Type","type":"string"},"message":{"title":"Message","type":"string"}},"required":["type","message"],"title":"StreamNotice","type":"object"},"StreamQuality":{"properties":{"type":{"const":"quality","title":"Type","type":"string"},"passed":{"title":"Passed","type":"boolean"},"score":{"title":"Score","type":"number"},"issues":{"default":[],"items":{"type":"string"},"title":"Issues","type":"array"}},"required":["type","passed","score"],"title":"StreamQuality","type":"object"},"StreamStatus":{"properties":{"type":{"const":"status","title":"Type","type":"string"},"stage":{"title":"Stage","type":"string"}},"required":["type","stage"],"title":"StreamStatus","type":"object"},"StreamText":{"properties":{"type":{"const":"text","title":"Type","type":"string"},"data":{"title":"Data","type":"string"}},"required":["type","data"],"title":"StreamText","type":"object"},"StreamUsage":{"properties":{"type":{"const":"usage","title":"Type","type":"string"},"usage":{"$ref":"#/components/schemas/Usage"}},"required":["type","usage"],"title":"StreamUsage","type":"object"},"StreamEvent":{"description":"One Server-Sent Event on a streamed ask: a `data: <json>` line and a blank line. Dispatch on `type`; ignore unknown types.","oneOf":[{"$ref":"#/components/schemas/StreamStatus"},{"$ref":"#/components/schemas/StreamMetadata"},{"$ref":"#/components/schemas/StreamText"},{"$ref":"#/components/schemas/StreamClarification"},{"$ref":"#/components/schemas/StreamNotice"},{"$ref":"#/components/schemas/StreamFollowupSuggestions"},{"$ref":"#/components/schemas/StreamQuality"},{"$ref":"#/components/schemas/StreamUsage"},{"$ref":"#/components/schemas/StreamError"},{"$ref":"#/components/schemas/StreamDone"}],"discriminator":{"propertyName":"type","mapping":{"status":"#/components/schemas/StreamStatus","metadata":"#/components/schemas/StreamMetadata","text":"#/components/schemas/StreamText","clarification":"#/components/schemas/StreamClarification","notice":"#/components/schemas/StreamNotice","followup_suggestions":"#/components/schemas/StreamFollowupSuggestions","quality":"#/components/schemas/StreamQuality","usage":"#/components/schemas/StreamUsage","error":"#/components/schemas/StreamError","done":"#/components/schemas/StreamDone"}}}},"securitySchemes":{"apiToken":{"type":"http","scheme":"bearer","bearerFormat":"ahk_live_<secret>","description":"An API token created in Settings → API tokens. Sent only in the `Authorization` header; cookies are ignored."}}},"tags":[{"name":"Questions","description":"Ask questions, follow up, and read past answers."},{"name":"Usage","description":"Quota position for the owning account."},{"name":"Rulings","description":"Full source text behind a citation."},{"name":"Discovery","description":"Unauthenticated guide to the API."}],"security":[{"apiToken":[]}]}