QuickPulse API Overview

QuickPulse provides research and conversation endpoints with optional streaming, job resumption, and per-key quotas. All public endpoints are exposed under the /v1 prefix.

Base URL

• Production: https://api.rsi-data.com

Public Endpoints (/v1)

• GET /v1/ping — health check
• POST /v1/research/ask — non‑streaming research answer
• POST /v1/research/stream — streaming tokens and status via SSE
• GET /v1/research/jobs/{job_id} — check a running or completed streaming job
• POST /v1/conversation — general conversation agent
• POST /v1/clarify — topic/timeline clarification prompt

Authentication

• Include an API key in every request (except /v1/ping) using:
  • Authorization: Bearer <api_key>

Headers

• Authorization: Bearer <api_key> (required for all except /v1/ping)
• Content-Type: application/json
• Optional Idempotency-Key: <opaque-string> (dedupes identical POSTs for /v1/research/ask)
• Streaming clients may set Accept: text/event-stream

Request Models (high level)

• Research (non-stream/stream):
  • query string
  • chat_id string|null
  • user_id string|null
  • source enum: govt | govt_news | whole_web (preferred)
    • use_silver (deprecated int) backwards compat
  • advanced_config object (see full reference in Auth & Usage)
• Conversation:
  • message string
  • chat_id string|null
  • user_id string|null
• Clarify:
  • topic string
  • reason string
  • chat_id string|null
  • user_id string|null

Response Models (high level)

• Research (non-stream):
  • response string
  • chat_id string|null
  • web_searched_data array of objects
  • indian_data object
  • indian_documents object
• Research (stream):
  • Server‑Sent Events with JSON payloads (see event schema in Auth & Usage), final chunk contains:
    • response, chat_id, research, internal_data, internal_document
• Conversation:
  • response string
  • chat_id string|null
  • should_generate_report bool
  • report_topic string|null
• Clarify:
  • need_clarification bool
  • clarification_text string

Rate Limits, Concurrency, Credits

• Per‑key, per‑endpoint quotas are enforced:
  • quota.requests_per_min (default often 60)
  • quota.concurrent (default often 5)
• When limits are exceeded: 429 with standardized error body (see Auth & Usage)
• Usage is tracked and credits are debited per call based on token usage

Error Envelope (standard)

All errors normalize to:

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

Common type values include auth, quota, rate_limit, bad_request, server_error.

Streaming Semantics (SSE)

• /v1/research/stream streams JSON messages (one per line) where each SSE data: line is a JSON object with:
  • type: "generation_id" | "status" | "token" | "final" | "error"
  • data: event-specific payload
• Response headers also include job identifiers for resume:
  • X-Quickpulse-Job-Id, X-Job-Id, X-Generation-Id