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

> Manage research sessions, chat with verified evidence, and generate or edit Studio outputs.

> [!NOTE]
>
> All Hub tools use `/api/public/v1/intelligence-hub/*`, including analysis and export polling.

Use the organization-scoped public Hub API through these tools. Platform admins can
add studies from other organizations within the same application to a session in
their own selected workspace. Create a session,
add/sync studies or upload sources, then chat or generate outputs. File Search
retrieves relevant evidence; reports and PowerPoints reuse saved findings. You do
not need to start exhaustive analysis before creating an output.

| Tool | Description |
| - | - |
| `create_research_session` | Create a Hub session with an idempotency key |
| `rename_research_session` | Rename a Hub session |
| `delete_research_session` | Delete a Hub session |
| `sync_research_study` | Add or refresh one study in a session |
| `remove_research_study` | Remove a study source from a session |
| `remove_research_source` | Remove a study or document by its opaque source ID |
| `add_all_research_studies` | Attach all available studies |
| `clear_research_sources` | Remove all source associations from a session |
| `inspect_research_session` | List sessions, sources, chat history, outputs; read a session, output, or job |
| `upload_research_source` | Upload external evidence as base64 file contents (10 MB decoded maximum) |
| `chat_research_session` | Synchronous chat; returns a durable job when the wait expires |
| `queue_research_chat` | Queue chat immediately; shares retry keys with synchronous chat |
| `generate_research_output` | Queue a report, native PowerPoint, or saved Highlights video |
| `edit_research_output` | Prompt an in-place report or PowerPoint edit; retains the output ID |
| `rename_research_output` | Rename a saved Studio output |
| `delete_research_output` | Delete a saved Studio output |
| `upload_research_template` | Upload a report or presentation template (5 MB maximum) |
| `download_research_output` | Download Markdown/PPTX/PDF bytes or get a private Highlights video link |
| `start_research_analysis` | Start an advanced exhaustive, quick, aggregate, or exploratory run |
| `resume_research_analysis` | Resume a run with an additional call allowance |
| `cancel_research_analysis` | Cancel an active run |
| `get_research_analysis` | Inspect canonical evidence, coverage and analysis run history |
| `queue_research_deliverable` | Advanced run-bound presentation, clip, reel or default-report video export |
| `get_research_deliverable` | Poll an export job and obtain its private download link |
| `cancel_research_deliverable` | Cancel an export job |

Use `inspect_research_session` with `view: "job"`, `session_id`, and the returned
`job_id` to poll chat, preparation, generation and edits. On success, read the
answer/references or the returned `output_id`. Use `parent_job_id` for a chat
follow-up. Preserve the required `idempotency_key` (1–200 characters) and the exact input on retries. A sync wait
expiring never cancels or duplicates the backend job. Native Tasks remain
available for the existing low-level `queue_research_deliverable` tool; the new
session tools use explicit durable job polling on both transports.

Read outputs before editing. Edits publish in place after success; default
reports are read-only. Highlights are generated once per default-report revision,
with learning-goal chapters and the report's verified quotations. Original audio
is used when available; chat-only studies have no artificial narration.

Uploads accept `file_name` and `data_base64`, never server-local paths or arbitrary
URLs. The host must supply an attachment's bytes. Downloads return structured
`filename`, `mime_type`, `data_base64` and `size_bytes` (64 MB transfer maximum),
or a short-lived `download_url` for video. Decode file bytes to a local artifact;
do not display base64 to the human. Source access is rechecked on every read.

These tools are available on full, core and compact profiles; read-only includes
five read tools: `inspect_research_session`, `get_research_analysis`, `get_research_deliverable`, `download_research_output`, and `view_research_answer`. The directory profile exposes eight research read tools.

## Example: research to Studio

```json theme={null}
{"tool":"create_research_session","arguments":{"name":"Product research","idempotency_key":"session-001"}}
```

Add a study with `sync_research_study`, or upload an external source. Save the
returned session ID and preparation job ID. Then queue a question:

```json theme={null}
{"tool":"queue_research_chat","arguments":{"session_id":"SESSION_UUID","prompt":"What drives trust? Include verified quotations.","idempotency_key":"chat-001"}}
```

Poll `inspect_research_session` with `view: "job"` until it succeeds or fails.
Return the answer and its source references to the human. For another turn, use
`parent_job_id` to preserve the conversation context.

```json theme={null}
{"tool":"generate_research_output","arguments":{"session_id":"SESSION_UUID","type":"powerpoint","prompt":"Summarize the saved findings for the product team.","idempotency_key":"deck-001"}}
```

After success, inspect the returned output ID. To apply a user-requested change:

```json theme={null}
{"tool":"edit_research_output","arguments":{"session_id":"SESSION_UUID","output_id":"OUTPUT_UUID","prompt":"Shorten the executive summary, retaining citations.","idempotency_key":"edit-001"}}
```

The output ID remains the same. Wait for the edit job to succeed before reading or
downloading the updated file. Default reports cannot be edited. Generation and
editing need a `write`-scoped key; inspection/download need `read`. A human's
request to generate Highlights authorizes using the original participant audio
when available; no artificial narrator is introduced for chat studies.

See the [REST API reference](https://docs.userintuition.ai/api-reference/intelligence-hub.md) for exact schemas,
source IDs, pagination, templates and retry contracts.

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.

## Study questions and clickable evidence

| Tool | Description |
| - | - |
| `view_research_answer` | Show a saved Hub chat answer with clickable citations and authenticated reference cards; also checks pending jobs. |

For study findings, comparisons and quotations, resolve the intended studies, create a Hub session if needed, and attach only the requested missing studies. Retain the session for the conversation. Reuse unchanged sources; do not resync or run exhaustive analysis for every question. Follow-ups use the last completed chat job as `parent_job_id`. Study-plan changes still use `customize_study`; status questions use their dedicated tools. Read-only and directory profiles cannot create chat turns.

The answer and its reference cards stay inside the MCP conversation. Always call `view_research_answer` after the chat job completes to display the full answer with clickable citations; do not replace it with a link to the Intelligence Hub dashboard. In clients that support MCP Apps, clicking a citation opens a card in the embedded answer, with original audio or video playback and transcript context. Clients without MCP Apps receive the readable answer and quotes, but cannot display interactive cards.

`chat_research_session` and `queue_research_chat` expose an MCP App that polls the same durable job. `view_research_answer` can reopen it using `session_id` and `job_id`. Clicking a citation fetches its exact quotation, nearby transcript context, study name and available original recording. Reference access is checked again on every read. Citation labels identify transcript turns, not distinct participants. Hub answer generation and verification group citations by source interview so multiple quotes from one interview are not described as different people. Chat interviews have no generated narration. External-document cards show their verified excerpt and page when available.

The App preserves the backend's citation labels and displays no internal IDs or raw JSON. In clients without MCP Apps, the viewer returns readable answer text and quotation labels. Interactive cards are supported inside the embedded App; the MCP server cannot control citation rendering in a host assistant's prose.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.