> ## 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.

> [!NOTE]
>
> Use the [MCP tools](https://docs.userintuition.ai/mcp-server/tools/intelligence-hub.md) for the same workflow from an agent.

Base path: `/api/public/v1/intelligence-hub`. Authenticate with an
`Authorization: Bearer ui_sk_…` organization API key. GET requests require
`read`; mutations require `write`. Sessions are scoped to the authenticated
organization and application, including for administrators. Users with multiple memberships can
select an accessible organization using `X-UI-Organization-ID`;
there is no global session-list bypass. Personal sessions
are not exposed through this API. Platform admins can discover and attach studies
from other organizations within the same application, while keeping the session
in their selected workspace. Non-admins can attach only their organization’s studies.

The Hub provides durable jobs, evidence retrieval, verified references, saved
reports, and native PowerPoint output.

## 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 accessible 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.

## Analysis and exports

Advanced operations also use the same base path and session authorization.
`R` is a run UUID; `J` is a deliverable job UUID. MCP uses these canonical routes.

| Method | Path | Purpose |
| - | - | - |
| GET | `/studies` | Discover accessible studies, including other organizations for platform admins |
| POST | `/sessions/S/sources/all` | Add all accessible studies |
| DELETE | `/sessions/S/sources` | Clear selected studies (external documents remain) |
| POST | `/sessions/S/runs` | Start analysis with `Idempotency-Key` |
| GET | `/sessions/S/runs` | List analysis runs |
| GET | `/runs/R` | Read analysis status/result |
| GET | `/runs/R/chat` | Read verified chat answer |
| GET | `/runs/R/studies` | Read study coverage |
| POST | `/runs/R/resume` | Resume analysis |
| POST | `/runs/R/cancel` | Cancel analysis |
| GET | `/runs/R/events` | Stream progress events |
| GET | `/runs/R/claims` | Read verified claims |
| GET | `/evidence/{evidence_id}?run_id=R` | Read evidence within an authorized run |
| GET | `/runs/R/export` | Export analysis |
| GET | `/runs/R/sources` | Read source manifest |
| GET | `/runs/R/exclusions` | Read exclusions |
| GET, POST | `/sessions/S/report-video` | Read or generate saved highlights |
| GET, POST | `/runs/R/report-video` | Read or generate run highlights |
| GET | `/runs/R/highlights` | Read highlight candidates |
| POST | `/runs/R/deliverables` | Queue presentation, clip or reel with `Idempotency-Key` |
| GET | `/runs/R/deliverables` | List exports |
| GET | `/deliverables/J` | Poll export and obtain a fresh download URL |
| POST | `/deliverables/J/cancel` | Cancel export |

Use `/sessions/S/sources` for the canonical study/document source list and
`/sessions/S/outputs` for saved Studio outputs. There are no duplicate public
session creation, document upload, or Studio-save routes.

## Availability

Hub endpoints return `404` when Hub analysis is disabled or the selected organization is outside the enabled organization list. A valid credential alone does not enable this feature.

## Retry and async contracts

Session creation, chat, generation, edits, analysis creation, and deliverable creation require `Idempotency-Key` (1–200 characters). 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.