Skip to main content
Requires the Intelligence Hub backend release in PR #794. Use the MCP tools for the same workflow from an agent.
Base path: /api/public/v1/intelligence-hub. Authenticate with the existing Authorization: Bearer ui_sk_… organization API key. GET requests require read; mutations require write. All resources are scoped to the authenticated organization and application, including for administrators. Platform admins can select an organization using the existing X-UI-Organization-ID convention; there is no global session-list bypass. Personal sessions are not exposed through this API. Existing dashboard routes and the older /api/public/v1/intelligence alias remain compatible. These endpoints reuse the Hub’s durable jobs, Gemini File Search retrieval, verified references, saved reports, and native PowerPoint renderer. They do not introduce a second analysis pipeline. The Hub feature configuration and worker must be enabled in the serving environment.

​
Endpoints

Paths below are relative to the base path. S is a session UUID; O is an output UUID. Request and response schemas and examples are included in the generated public OpenAPI specification. Lists use limit (default 50, maximum 200 per page) and after. Pass the returned next_cursor unchanged to fetch the next page. This page size does not limit the total number of sessions, sources, or outputs. Chat history is chronological and excludes automatic study-preparation runs.

​
Retry and async contracts

Session creation, chat, generation, and edits require Idempotency-Key. Reuse the same key and body after an uncertain network response; use a new key for a new operation. Conflicting reuse returns 409. Sync and async chat share the same underlying job, so callers can switch between them with the original key. Completed edits also replay the original job after the output has changed; retry keys are matched to the submitted request, not the current model settings or output revision. Both chat endpoints accept:
For a follow-up, set parent_job_id to a completed chat job in the same session. POST /chat waits up to 120 seconds (wait_seconds=0..120). If still running, it returns 202, the existing job_id, and poll_url; it does not cancel or restart the job. /chat/jobs returns 202 immediately. Poll until status is succeeded or failed. On success, result.answer and result.references contain the response. A partial completed analysis sets result.partial=true. Failed jobs return a public-safe error, without internal exception details. Study sync returns a preparation_job_id when preparation is needed. Poll it using the same jobs endpoint. Repeated sync reuses revision-aware preparation. External evidence supports TXT, Markdown, CSV, JSON, text PDFs, and DOCX up to 10 MB, using the same parser as the dashboard.

​
Outputs and references

Example generation body:
Generation and edits return 202 with a job. result.output_id identifies the saved output when successful. PowerPoint jobs remain running until the rendered file is ready. Edits retain the output ID and reuse the saved evidence; default reports cannot be edited or renamed. Report and PowerPoint edits are supported; Highlights are derived from default reports, not edited with prompts. type:"highlights" requests the saved default-report video, generated once per report revision. Its required prompt describes the request but does not change quote selection. Original participant audio is used where available; chat-only sources do not receive artificial narration. Reads include structured references: display label, study/interview ID, message index, and verified quotation. Document references include a source ID and page when available. Provider call identifiers, evidence hashes, and hidden dashboard reference catalogs are not part of the public content contract. Downloads default to Markdown for reports, PPTX for PowerPoints, and MP4 for Highlights. Use ?format=pdf for a rendered presentation PDF. Video downloads redirect to a short-lived download capability. Access to source evidence is checked again when reading results or downloading files. Removing evidence can make earlier results unavailable; it does not grant continued access through saved output IDs. Templates use the dashboard’s existing 5 MB upload and validation rules. Pass the returned template ID when generating the matching output type. Report templates accept Markdown, TXT, or DOCX with placeholders such as {{title}} and {{findings}}. Presentation templates accept 16:9 PPTX files and reuse their theme and layouts. Templates provide formatting, not research evidence. Expired or revoked outputs remain listable with status: "unavailable"; one unavailable artifact does not prevent listing the other session outputs.

​
Read a chat reference

GET /intelligence-hub/sessions/{session_id}/jobs/{job_id}/references/{label} resolves a verified citation from a completed chat answer. Use the exact label returned with that job. The response includes reference, study_name, participant_label, and an optional interview with speech around the cited turn and available playback links. Document references have no interview. Organization, session and source access are checked again; an unknown label or mismatched session does not return evidence.