Sessions And Scan Groups
Use session IDs, scan groups, and request IDs to connect multistep scans across chats, files, OCR, output, and review.
Most real integrations are multistep. A user uploads a file, OCR extracts text, an AI system summarizes it, and a reviewer makes a decision. Citadel 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.
Multistep workflows
A session is the case. A scan group is one evidence chain.
1
1. First input scanSend the prompt, file, image, or OCR text with scan_phase=input.
no session_id required2
2. Citadel returns IDsStore session_id for the workflow and scan_group_id for this item.
session_id + scan_group_id3
3. Derived scans reuseOutput scans, OCR rescans, and summaries reuse the same scan_group_id.
scan_phase=output requires scan_group_idOptional app-owned IDchat thread, claim, case, batch, or agent run
session_idCitadel-generated chain IDprompt plus response, file plus OCR, photo plus analysis
scan_group_idFor the first input scan, you can omit both IDs. Citadel returns them. If your app already has a stable chat, claim, or case ID, you may send it as session_id. Output scans must reuse the returned scan_group_id.
Use this rule:
session_idis the whole workflow, such as one claim, chat, batch, case, or agent run.scan_group_idis one item or message inside that workflow.- Reuse
scan_group_idonly for derived scans from the same item. - Create a new
scan_group_idfor a different photo, file, invoice, chat turn, or evidence item. - For the first input scan, you can omit both IDs. Citadel 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 Citadel generate it. |
scan_group_id | One item or related evidence chain inside the session. | Let Citadel 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 Citadel generate it, or pass your own stable chat, claim, case, upload batch, or agent run ID. |
Example Multistep Claim
- Claim note arrives.
- Scan the note with
scan_phase=input. - Store the returned
session_idandscan_group_id. - Upload a PDF and scan it with the same
session_id. - OCR extracts text from the PDF.
- Scan OCR text using the PDF scan's
scan_group_id. - AI summarizes the PDF.
- Scan the summary with
scan_phase=outputand the PDFscan_group_id. - A second photo arrives, so let Citadel create a different
scan_group_idunder the samesession_id. - Review stores all scan IDs and final human decision.
Input Scan
{
"content": "Customer note text",
"content_type": "text",
"scan_phase": "input"
}Citadel returns session_id, scan_group_id, request_id, and scan_id. Store them.
{
"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
{
"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_idfor model output. Reuse the input group. - Using one
scan_group_idfor a whole batch. Use one group per item. - Dropping
request_idfrom logs. You need it to debug retries. - Treating Citadel scan results as review decisions. Store human review outcomes separately.
Next step
Ready to scan real traffic?
Book a working session on your files. Starting October 1, 2026, new commercial terms are enterprise or custom.
AI-Agent Prompt
AI-ready prompt
Add session and scan group tracking
Paste this into Cursor, Codex, Claude Code, or Windsurf.
Add Citadel 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.