API Documentation

Authentication

All /v2/* and /account/* endpoints require an API key passed in the X-API-Key header. Keys have the prefix riq_live_ followed by 32 hex characters.

X-API-Key: riq_live_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4

Getting your API key

Sign in via Supabase Auth (Google or email). On first login, call POST /auth/provision with your Supabase JWT to provision an org and receive your key. The key is shown exactly once — save it immediately.

curl -X POST https://api.samidhareviews.xyz/auth/provision \
  -H "Authorization: Bearer <supabase-jwt>"

# Response (key shown once — copy it now):
# { "api_key": "riq_live_...", "org_id": "...", "key_prefix": "riq_live_a1b2" }

Endpoints

Extraction response fields

All fields except product and extraction_meta may be null when the information is absent or uninferable from the source review.

Example response

{
  "product": "BoAt Bassheads",
  "stars": null,
  "stars_inferred": 3,
  "pros": ["sound quality"],
  "cons": ["battery life", "overpriced for 2000 rupees"],
  "buy_again": false,
  "sentiment": "mixed",
  "urgency": "low",
  "topics": ["battery", "sound quality", "price"],
  "competitor_mentions": [],
  "feature_requests": [],
  "language": "hi-en",
  "review_length_chars": 104,
  "confidence": 0.91,
  "extraction_meta": {
    "model": "openai/gpt-oss-120b",
    "prompt_version": "v2.3",
    "schema_version": "1.0.0",
    "extracted_at": "2025-01-15T10:23:45.123456",
    "latency_ms": 842,
    "input_hash": "sha256:a1b2c3..."
  }
}

CSV Upload

Use POST /v2/ingest/csv to upload a CSV file for bulk asynchronous extraction. Results are stored per-org and downloadable via GET /v2/ingest/{job_id}/result.

Example CSV

review_text,product,date
"Great earphones, sound is excellent","BoAt Bassheads","2024-01-15"
"Battery dies too fast for the price","BoAt Bassheads","2024-01-16"

Upload request + response

# Upload
curl -X POST https://api.samidhareviews.xyz/v2/ingest/csv \
  -H "X-API-Key: riq_live_your_key" \
  -F "file=@reviews.csv"

# Response — poll job_id for status
{"job_id": "b3f1a2d4-...", "total": 2, "status": "pending"}

# Poll status
curl https://api.samidhareviews.xyz/v2/ingest/b3f1a2d4-.../  \
  -H "X-API-Key: riq_live_your_key"

# Download results when status == "done"
curl https://api.samidhareviews.xyz/v2/ingest/b3f1a2d4-.../result \
  -H "X-API-Key: riq_live_your_key"

Rate Limits & Quotas

When a rate limit is exceeded, the API returns HTTP 429 Too Many Requests with a Retry-After header indicating seconds until the window resets.

Language Support

Language is auto-detected from the review text — no parameter needed. The detected code is returned in the language field of the response, together with code_mixed and language_signal_strength. The label is a heuristic: on a corpus of real reviews its agreement with the corpus label is low, and that label is itself noisy, so treat language as a hint, not a scored accuracy claim (see the README's held-out section for the measured agreement, its confidence interval and the label's inter-rater alpha).

Re-measured against the models actually deployed: The headline accuracy figure was measured under the models production actually runs today (openai/gpt-oss-20b / openai/gpt-oss-120b) after Groq deprecated the previous models on 2026-08-16 — see the headline accuracy for its confidence interval, sample size, gate status and known calibration differences vs. the previous models.