§ Developers

Build on Retailopedia.
Anthropic-shaped APIs. Signal-grounded answers.

The same endpoints that power retailopedia.app, exposed for your stack. JSON + SSE on every endpoint that streams. Cited answers from a continuously-updated India retail signal feed. Stable contract — version bumps go through /developers/changelog.

Get started

# Ask a question, stream the answer.
curl -N https://retailopedia.app/api/v1/ask \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{"role":"user","content":"What did Tata Trusts announce today?"}],
    "stream": true
  }'

Anonymous OK for /api/v1/ask (rate limited per IP). Bring a Clerk Bearer for paid surfaces (research, follow, predict). Full quickstart →

Endpoints

POST /api/v1/ask
Cited answer over India retail signals. JSON or SSE. Reference →
POST /api/v1/research
Compose a research briefing on a topic. Returns a markdown report with linked citations. Reference →
GET /api/v1/research/{id}
Poll an investigation's status; fetch the completed report.
POST /api/v1/follow
Track a brand, theme, signal, or source. Inbox channel live; email + webhook + SMS in v2.
GET /api/v1/follow
List the authenticated user's follows + unread inbox count.
DELETE /api/v1/follow/{id}
Remove a follow.
GET /api/v1/sources/health
Roster + Oracle SLO snapshot. Cacheable. Power your status page.
POST /api/v1/sources/propose
Suggest a source for the catalogue. Anonymous-friendly.

OpenAPI 3.1 spec lives at /.well-known/openapi.yaml. Generate a client in any language — Stainless, openapi-generator, or copy the curl examples in the quickstart.

Your account

/developers/keys
Issue + revoke API keys. Keys are shown once at create time.
/developers/usage
14-day request chart + endpoint breakdown. Same stream that drives your invoice.
/developers/webhooks
Subscribe to follow.signal.delivered, forecast.resolved, research.completed. HMAC-SHA256 signed.
/developers/sandbox
Auto-authed cURL + fetch snippets for every endpoint, pre-filled with your key prefix.

Authentication

v1 supports Clerk Bearer JWTs and anonymous traffic. Pass Authorization: Bearer <clerk-jwt> on every request to surfaces that require auth (Follow, Research at write paths, Webhooks). Anonymous requests count against the per-IP bucket. API keys with SHA-256 hashing are available — issue from /developers/keys.

Rate limits

Endpoint	Limit	Window
`/api/v1/ask`	30 req	60s
`/api/v1/research`	5 req	5 min
`/api/v1/sources/propose`	3 req	1 hr
`/api/v1/follow`	per-tier (auth-gated)	—

Limits are per-IP for anonymous, per-user for authed. Each response includes x-rate-limit-remaining; 429s carry Retry-After in seconds.