API Reference

Request body

Response

Example response

{
  "question": "What are the key risks of deploying LLMs in production?",
  "optimized_question": null,
  "answers": [
    { "label": "gemini", "model": "gemini-2.5-flash", "text": "...", "error": null },
    { "label": "openrouter", "model": "openai/gpt-oss-120b:free", "text": "...", "error": null },
    { "label": "cohere", "model": "command-a-03-2025", "text": "...", "error": null }
  ],
  "consensus_available": true,
  "provider_count": 3,
  "final_answer": "Deploying LLMs in production carries several key risks...",
  "synthesizer": "gemini",
  "source_count": 3,
  "notes": "All three providers agreed on the core risk categories...",
  "init_errors": {},
  "conversation_id": 42,
  "consensus_sentences": [
    { "text": "Deploying LLMs in production carries several key risks.", "corroborated_by": 3 },
    { "text": "Hallucination is the most cited failure mode.", "corroborated_by": 2 }
  ]
}

Identical request body, auth, tier limits, and rate limiting to /api/ask above — the only difference is the response shape: a text/event-stream of Server-Sent Events instead of one blocking JSON payload, so a client can render each provider's answer as it arrives instead of waiting for the full panel plus synthesis. Event types (each a JSON payload under data:): provider_result (one per provider, as it completes), synthesis_result (the final combined answer, same shape as /api/ask's response body), error, and done (stream end).

Thumbs up or down on a past call. Use the conversation_id from any /api/ask response.

curl -X POST https://askarei.com/api/conversations/42/rating \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"rating": 1}'  # 1 = thumbs up, -1 = thumbs down

Returns a structured, provenance-complete report for a single past call. Includes: original question, every per-provider raw answer with lexical overlap scores, the synthesized answer, and per-sentence corroboration rates computed at report-generation time.

curl https://askarei.com/api/conversations/42/report \
  -H "Authorization: Bearer YOUR_API_KEY"

Requires either the caller to be the conversation's own owner (the key/session that asked it), or a valid share_token query parameter from POST .../share below. Returns 404 for unknown IDs and for a real ID that isn't yours — the id itself is not a capability token; a paying-tier key or free-tier session only ever sees its own conversations.

Owner-only. Mints a single active, unguessable share_token for this conversation and returns a ready-to-send report URL — the explicit, revocable way to hand a report to someone else (a client, an auditor) without giving them your key. Calling it again replaces the previous link.

curl -X POST https://askarei.com/api/conversations/42/share \
  -H "Authorization: Bearer YOUR_API_KEY"

Owner-only. Immediately invalidates any previously-issued share_token for this conversation — the link stops working right away.

curl -X POST https://askarei.com/api/conversations/42/unshare \
  -H "Authorization: Bearer YOUR_API_KEY"

Owner-only. Permanently removes one of your own past questions and its answers from your history — cannot be undone. Same 404-for-unauthorized reasoning as .../report above: a real id that isn't yours 404s, it never reveals whether the id exists.

curl -X DELETE https://askarei.com/api/conversations/42 \
  -H "Authorization: Bearer YOUR_API_KEY"

Owner-only. Returns a downloadable JSON file with the full per-provider raw answers, synthesis, and metadata for one past call — Business tier additionally includes a human-readable provenance_text field suitable for pasting directly into a client report. Requires Plus or Business tier; a Free or Personal key gets 403 export_requires_professional. Same 404-for-unauthorized reasoning as .../report above, but with no share_token variant — export is a "get my own data" feature, not a sharing mechanism.

curl https://askarei.com/api/conversations/42/export \
  -H "Authorization: Bearer YOUR_API_KEY"

Returns up to 50 of your own past questions and their synthesis summaries, plus aggregate stats — scoped to the caller's identity, never another user's.

curl https://askarei.com/api/conversations \
  -H "Authorization: Bearer YOUR_API_KEY"

curl https://askarei.com/api/health
# → {"status": "ok"}