Retailopedia · Developers

Ask — JSON response

curl -X POST https://retailopedia.app/api/v1/ask \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{"role":"user","content":"What did Tata Trusts announce today?"}],
    "stream": false
  }'

Returns a JSON object with content (the answer markdown), citations (array of sig_ids the answer is grounded in), confidence, session_id, and session_slug. The slug is shareable: anyone can read at /ask/{session_slug}/{turn_ordinal} if the session is marked public.

Ask — SSE stream

curl -N -X POST https://retailopedia.app/api/v1/ask \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{"role":"user","content":"Quick commerce profitability"}],
    "stream": true
  }'

Anthropic-shaped SSE frames: message_start, content_block_start, content_block_delta, content_block_stop, message_stop, plus Retailopedia-specific events: clarity.citation_emitted, clarity.confidence_updated, clarity.research_promotion_available.

Research — synchronous

curl -X POST https://retailopedia.app/api/v1/research \
  -H "Content-Type: application/json" \
  -d '{
    "topic": "Quick commerce profitability in tier-2 cities",
    "preset": "standard"
  }'

Synchronous v1 returns { status: "completed", report_url, citation_count, cost_usd } once the runner is done (typically 30-90s for standard preset). v2 will return { status: "queued", status_url } immediately and require polling GET /api/v1/research/{id}.

Sources — health snapshot

curl https://retailopedia.app/api/v1/sources/health

Returns stats (roster counts, items/hr, signals/24h), oracle (latest miss-rate), and the full source list with health + cadence + items_24h. Cacheable for 60s — wire it into your status page.

Conventions

Every endpoint is JSON-only on input + output unless SSE-streaming.
Every error response carries error (machine code) + message (human-friendly).
Rate-limit headers on every response: x-rate-limit-remaining.
Every cite ID is sig_ + 16 hex chars. Resolvable at /signal/<slug> after looking up via GET /api/v1/sources/health or the Discover surface.

Versioning

v1 is the current contract. Breaking changes ship under /api/v2/... with a deprecation window of 6 months on the old version. Track every change at /developers/changelog.