> ## Documentation Index > Fetch the complete documentation index at: https://docs.userintuition.ai/llms.txt > Use this file to discover all available pages before exploring further. # Intelligence Hub API > Organization sessions, sources, synchronous and asynchronous chat, and Studio outputs. Requires the Intelligence Hub backend release in PR #794. Use the [MCP tools](/mcp-server/tools/intelligence-hub) 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. | Method | Path | Purpose / request | | - | - | - | | POST | `/sessions` | Create: `{"name":"Customer research"}` | | GET | `/sessions` | List organization sessions | | GET | `/sessions/S` | Read session | | PATCH | `/sessions/S` | Rename: `{"name":"New name"}` | | DELETE | `/sessions/S` | Soft-delete session | | PUT | `/sessions/S/studies/{study_id}` | Add or resync an organization study | | POST | `/sessions/S/sources` | Upload external evidence, multipart `file` | | GET | `/sessions/S/sources` | List study and document sources | | DELETE | `/sessions/S/sources/{source_id}` | Remove a source using its returned opaque ID | | POST | `/sessions/S/chat` | Synchronous chat with durable timeout recovery | | POST | `/sessions/S/chat/jobs` | Asynchronous chat | | GET | `/sessions/S/chat/history` | Read chat turns, including pending turns | | GET | `/sessions/S/jobs/{job_id}` | Poll preparation, chat, generation, or edit | | POST | `/sessions/S/outputs` | Generate report, PowerPoint, or Highlights | | GET | `/sessions/S/outputs` | List Studio outputs, including synced default reports | | GET | `/sessions/S/outputs/O` | Read output and verified references | | PATCH | `/sessions/S/outputs/O` | Rename: `{"name":"New name"}` | | POST | `/sessions/S/outputs/O/edits` | Edit in place: `{"prompt":"Shorten the executive summary"}` | | DELETE | `/sessions/S/outputs/O` | Soft-delete output | | GET | `/sessions/S/outputs/O/download` | Download Markdown, PPTX, PDF, or MP4 | | POST | `/sessions/S/templates?kind=report` | Upload a report template, multipart `file` | | POST | `/sessions/S/templates?kind=presentation` | Upload a presentation template | 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: ```json theme={null} {"prompt":"What drives trust? Include verified quotations.","parent_job_id":null,"include_synthetic":false} ``` 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: ```json theme={null} {"type":"powerpoint","name":"Trust findings","prompt":"Summarize the saved findings for the product team.","template_id":null} ``` 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. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.