Usage

Rate Limits and Concurrency

Per‑key quotas are enforced automatically:

• Requests per minute and in‑flight concurrency are limited using key quotas.
• If minute limit exceeded → 429:

{"error": {"type": "rate_limit", "message": "too_many_requests", "retry_after": 60}}

• If concurrency exceeded → 429:

{"error": {"type": "rate_limit", "message": "too_many_concurrent", "retry_after": 1}}

Idempotency

• Supported on POST /v1/research/ask with Idempotency-Key.
• Identical requests (same key, same endpoint) within a window return the cached result.

Streaming Usage (SSE)

POST /v1/research/stream responds as text/event-stream. The server emits newline‑delimited data: messages, each a compact JSON object:

• Generation ID (first line):

{"type":"generation_id","data":"<job_id>"}

• Status updates (progress, phase changes, counts):

{"type":"status","data":{"type":"started" | "searching" | "sql_querying" | "vector_querying" | "processing" | "completed" | "error","message":"string","data":{...},"timestamp":"ISO-8601"}}

• Tokens (partial assistant content as it streams):

{"type":"token","data":"<text-fragment>"}

• Final result (always sent once at the end with compiled data):

{"type":"final","data":{"response":"string","chat_id":"string|null","research":[...],"internal_data":{...},"internal_document":{...}}}

• Error (if any):

{"type":"error","data":{"message":"string"}}

The response also includes:

• X-Quickpulse-Job-Id, X-Job-Id, X-Generation-Id headers for resume/polling with GET /v1/research/jobs/{job_id}.

Request Parameters — Research

• query string (required)
• chat_id string|null
• user_id string|null
• source enum (preferred over deprecated use_silver):
  • govt — prioritize official/government sources
  • govt_news — official + trusted media
  • whole_web — broad web
• advanced_config object (optional) to tune behavior:

QuickPulse advanced_config reference:

{
  "source_mode": "government_only | govt_plus_trusted_media | whole_web",
  "geo_bias": "india | none",
  "language": "en | hi | auto",

  "search_depth": "basic | advanced",
  "max_results_per_query": 1,
  "included_domains": [],
  "excluded_domains": [],
  "recency_window": "latest_only | last_12m | last_3y | all_time",

  "use_indian_data": true,
  "min_confidence": "low | medium | high",
  "max_items": 5,

  "use_indian_documents": true,

  "creativity": 0.7,
  "max_output_tokens": 1500,
  "tool_use": "auto | never",
  "give_thinking_updates": true,

  "include_inline_citations": true,
  "include_references_section": true,
  "format_style": "markdown_report | bullet_summary | concise",

  "blocked_terms": []
}

Notes:

• Fields are optional; unset fields inherit your key’s defaults.
• source_mode roughly maps to source intent.
• blocked_terms allows you to prevent processing certain queries.

Request Parameters — Conversation

• message string (required)
• chat_id string|null
• user_id string|null

Request Parameters — Clarify

• topic string (required)
• reason string (required)
• chat_id string|null
• user_id string|null

Error Handling

All error responses follow:

{"error": {"type": "<string>", "message": "<string>"}}

Clients should check HTTP status and parse error.type for programmatic behavior.

Admin Key Management (restricted)

Admin endpoints (not public; excluded from OpenAPI schema) require:

• X-Admin-Secret: <server-configured-secret>

Endpoints:

• GET /admin/api-keys — list keys (includes quotas/config)
• POST /admin/api-keys — create a key (accepts advanced_config)
• POST /admin/api-keys/{key_id}/revoke — revoke key
• POST /admin/api-keys/{key_id}/rotate — rotate key (returns a new raw key)
• GET /admin/api-keys/by-user/{user_id} — list keys by user