# Sessions And Scan Groups

Use session IDs, scan groups, and request IDs to connect multistep scans across chats, files, OCR, output, and review.

Source URL: https://trymighty.ai/docs/concepts/sessions

Most real integrations are multistep. A user uploads a file, OCR extracts text, an AI system summarizes it, and a reviewer makes a decision. Mighty gives you IDs so those scans stay connected.

This also protects against drift. When OCR, model output, review notes, or policy changes create new trusted material, rescan that material and keep it connected to the original item.

Session flow: one session can contain many scan groups. Reuse a scan group for related input, OCR, output, and review scans.

Illustration: Sessions keep the whole workflow connected. Use one session for the chat, claim, case, batch, or agent run. Use scan groups for each evidence chain.

Use this rule:

- `session_id` is the whole workflow, such as one claim, chat, batch, case, or agent run.
- `scan_group_id` is one item or message inside that workflow.
- Reuse `scan_group_id` only for derived scans from the same item.
- Create a new `scan_group_id` for a different photo, file, invoice, chat turn, or evidence item.
- For the first input scan, you can omit both IDs. Mighty returns them in the response and response headers.
- If your app already has a stable chat, claim, case, or batch ID, you may send it as `session_id`.

## The Three IDs

| ID | What it means | When to create it |
| --- | --- | --- |
| `request_id` | One API request. Use it for idempotency and logs. | Create a new one per scan request or let Mighty generate it. |
| `scan_group_id` | One item or related evidence chain inside the session. | Let Mighty generate it on the first input scan, then reuse it for OCR text, model output, and review from the same item. |
| `session_id` | One ongoing workflow. | Let Mighty generate it, or pass your own stable chat, claim, case, upload batch, or agent run ID. |

## Example Multistep Claim

1. Claim note arrives.
2. Scan the note with `scan_phase=input`.
3. Store the returned `session_id` and `scan_group_id`.
4. Upload a PDF and scan it with the same `session_id`.
5. OCR extracts text from the PDF.
6. Scan OCR text using the PDF scan's `scan_group_id`.
7. AI summarizes the PDF.
8. Scan the summary with `scan_phase=output` and the PDF `scan_group_id`.
9. A second photo arrives, so let Mighty create a different `scan_group_id` under the same `session_id`.
10. Review stores all scan IDs and final human decision.

## Input Scan

```json
{
  "content": "Customer note text",
  "content_type": "text",
  "scan_phase": "input"
}
```

Mighty returns `session_id`, `scan_group_id`, `request_id`, and `scan_id`. Store them.

```json
{
  "action": "ALLOW",
  "scan_id": "4e7c5fc1-6947-492b-bd22-0589d6477c8b",
  "request_id": "ab82f4ad-8d64-4bb4-b4ed-77df63291198",
  "scan_group_id": "9b3e4f8d-96c9-4f42-8338-8cf9571c1c70",
  "session_id": "sess_generated_by_mighty"
}
```

## Output Scan

```json
{
  "content": "Generated summary shown to an adjuster.",
  "content_type": "text",
  "scan_phase": "output",
  "session_id": "sess_generated_by_mighty",
  "scan_group_id": "9b3e4f8d-96c9-4f42-8338-8cf9571c1c70"
}
```

`scan_phase=output` requires `scan_group_id`. This prevents generated output from becoming disconnected from the material that caused it.

## Common Patterns

| Workflow | `session_id` | `scan_group_id` |
| --- | --- | --- |
| Chat app | Chat thread ID | Prompt and response pair |
| File upload | Case or user workflow ID | Original file, OCR text, extracted fields |
| Damage photo review | Claim ID | One photo and any generated analysis |
| Batch intake | Batch ID | One item in the batch |
| Agent run | Agent run ID | Prompt, retrieved content, tool output, final answer |

## Common Mistakes

- Creating a new `scan_group_id` for model output. Reuse the input group.
- Using one `scan_group_id` for a whole batch. Use one group per item.
- Dropping `request_id` from logs. You need it to debug retries.
- Treating Mighty scan results as review decisions. Store human review outcomes separately.

## AI-Agent Prompt

### Add session and scan group tracking

```text
Add Mighty session and scan group tracking to this product.

Requirements:
- Generate or preserve request_id per scan request.
- Reuse session_id across one chat, claim, case, upload batch, or agent run.
- Store scan_group_id returned by input scans.
- Reuse scan_group_id for OCR output, extracted fields, model output, agent output, and review artifacts from the same item.
- Require scan_group_id when scan_phase=output.
- Store scan_id, request_id, scan_group_id, session_id, action, risk_score, threats, and review outcome.

Acceptance criteria:
- Input and output scans are connected.
- Batch items do not share one scan_group_id unless they are the same item.
- Logs can find all scans from one session_id.
- Tests cover retry idempotency and output scan group reuse.
```