ASK AI conversations
Wiki home · Practical examples · All endpoints · Exact schemas
Current access: ask_ai on a scoped key or first-party *. A customer-owned key can isolate its end users with X-End-User-Ref on the supported subject routes. Keep the bearer key on the server.
Ask a question
POST /v1/ai/ask accepts required question (3–2,000 characters), optional as_of, format, deck {text}, Limited pool {text,kind}, conversation_id, file_id, up to four image attachments, request-scoped location/timezone, and stream. Unknown body fields are rejected. The API's server-side tools check facts and the final answer's grounding. Persona is configured on the key; it is not a per-request field.
curl -sS https://api.chaosdraft.com/v1/ai/ask \
-H "Authorization: Bearer $CHAOSDRAFT_API_KEY" \
-H "X-End-User-Ref: $END_USER_REF" \
-H 'Content-Type: application/json' \
--data '{"question":"How many lands should this deck run?","format":"commander","deck":{"text":"Commander\n1 Atraxa, Praetors Voice\nDeck\n1 Sol Ring\n1 Forest"}}'The list above illustrates request format, not a complete Commander deck. Send the returned data.conversation.id on later turns, using the same verified end-user ref. If you send a new deck, it becomes a new snapshot for the conversation; it does not overwrite an external saved deck.
The final chat text is data.message.content (plain) or data.message.markdown (safe Markdown subset with [[Card Name]] markers). data.answer.summary is not the whole reply. data.segments can split a short reply into optional conversational bubbles. data.cards supplies checked card previews. data.grounding, tool_results, trace, deck_proposal, coverage and meta are supporting fields. Do not assert an unverified or uncovered result as fact.
Streaming
Set stream:true in the JSON body and parse text/event-stream. Progress events can be status, tool_call and deck_summary; delta is provisional text; reset clears it. The final event carries the authoritative normal {data,meta} answer. An error event may follow HTTP 200. Replace provisional text with final data.message. A pre-stream validation error is ordinary JSON with its HTTP status.
Conversation operations
| Operation | Use |
|---|---|
| GET /v1/ai/access | Key activation, scopes and allowance; not an end-user plan |
| GET /v1/ai/conversations | List/search chats with limit 1–100 and opaque cursor |
| POST /v1/ai/conversations | Create an empty conversation, optionally named |
| GET /v1/ai/conversations/{id} | Read state and recent turns; page turns with turn_limit and before_turn or after_turn |
| PATCH /v1/ai/conversations/{id} | Rename with title |
| DELETE /v1/ai/conversations/{id} | Delete chat, turns, files and feedback |
| GET /v1/ai/events | Live end-user changes over SSE; event IDs prompt the client to refetch |
Only the correct owner can retrieve a chat. The list cursor is opaque and bound to owner/search. A turn's saved answer may be absent for older or oversized records; fall back to its saved reply. Live events include turn.started, turn.completed and turn.failed, so another open client can notice a finished background answer.
Files, memory and feedback
| Operation | Use |
|---|---|
| GET; POST /v1/ai/conversations/{id}/files | List/add deck or Limited-pool file |
| GET; DELETE /v1/ai/conversations/{id}/files/{file_id} | Read/remove one file |
| GET; PATCH; DELETE /v1/ai/memory | Read, edit/remove individual memory items, or erase all |
| GET; PUT; DELETE /v1/ai/conversations/{id}/turns/{turn}/feedback | Read, replace or remove one answer's rating/comment/flag/correction |
| GET /v1/ai/feedback | Customer-wide feedback export; separate ai:feedback:read scope, no end-user ref |
To add a file, POST JSON {kind:"deck",text:"..."} or {kind:"limited_pool",pool_kind:"sealed",text:"..."}. The parser accepts supported plain-text, CSV and MTGO .dek exports; 20 files maximum per conversation, 50,000 characters each. Use its returned file_id in an ask with conversation_id. Images sent as attachments are sanitized and not saved as these files. Memory learning depends on key configuration; GET exposes the enabled state even when saved items are not currently used.
Use the final data.message field for the conversational bubble, then attach supporting card previews, source links and grounding details as needed. The OpenAPI contract gives the exact response fields and SSE event shapes.