Workflow Playbooks
Pick the workflow, then copy the Citadel scan plan.
Where should Citadel go? Pick the workflow that matches the file, then follow the scan plan.
For setting recipes, see Choose Scan Settings.
The pattern
customer file -> Citadel scan -> product route -> next stepRun the scan before the file reaches:
- Funding or bind.
- Payout or approval.
- A model call.
- Extraction.
- Permanent storage.
- Search or indexing.
- Agent tools.
- A review queue.
Pick your workflow
| If your app has | Use this playbook | First scan goes before |
|---|---|---|
| Paystubs, W-2s, bank statements | File intake | Funding. |
| New-business applications | File intake | Bind. |
| Damage photos | Damage photo review | Claim, repair, or payment decisions. |
| Invoices or estimates | Invoice review | Approval or payment. |
| PDF, image, or document uploads | File intake | Storage or extraction. |
| Text already read from a file | Extracted text | Extracted fields become workflow data. |
| A chat assistant | Chat apps | The model call. |
| Public AI answers | Output scanning | The user sees the answer. |
| Agents or tools | Agent tool review | Tool output enters model context. |
| Large batches | Batch intake | Batch automation writes state. |
| Human reviewers | Review queues | Reviewers act on scan results. |
Chat Apps
Goal: stop risky prompts before the model runs, then scan public output before users see it when strict output safety matters.
Scan plan:
| Step | What to scan | Settings | Route |
|---|---|---|---|
| 1 | Latest user message | content_type=text, scan_phase=input, mode=secure, focus=steg | ALLOW calls the model. REVIEW pauses because a required check did not finish. WARN adds friction or review for suspicious evidence. BLOCK stops. |
| 2 | Assistant answer for strict routes | scan_phase=output, profile=ai_safety, data_sensitivity=strict | Show ALLOW. Show redacted_output when returned. Block otherwise. |
| 3 | Tool output or retrieval content | scan_phase=output, profile=ai_safety | Only clean output enters model context. |
Use Vercel AI SDK Chat Integration when this is a Next.js AI SDK route.
Settings recipe: user prompt before AI and public AI answer.
File Intake
Goal: stop suspicious uploads before storage, OCR, extraction, indexing, or automation trusts them.
Scan plan:
| Step | What to scan | Settings | Route |
|---|---|---|---|
| 1 | Original upload | content_type=auto, scan_phase=input, mode=secure, focus=steg | ALLOW continues. REVIEW stays quarantined because a required check did not finish. WARN stays quarantined for suspicious evidence. BLOCK stops. Use focus=all only after routing known image/PDF evidence that needs authenticity or edit review. |
| 2 | OCR text or extracted fields | content_type=text, same scan_group_id, data_sensitivity=tolerant | Keep extracted data untrusted until scan passes. |
| 3 | AI summary of the file | scan_phase=output, same scan_group_id | Show or store only after routing. |
Use one scan_group_id for the original file and all derived scans from that file.
Settings recipe: mixed file upload.
OCR And IDP
Goal: prevent hidden document instructions, OCR errors, and poisoned extracted text from becoming workflow facts.
Scan plan:
| Step | What to scan | Settings | Route |
|---|---|---|---|
| 1 | Original PDF or image | content_type=pdf, image, or auto, focus=all | Review suspicious original evidence. |
| 2 | OCR text | content_type=text, data_sensitivity=tolerant | WARN marks fields untrusted. BLOCK stops automation. |
| 3 | Structured fields or summary | scan_phase=output if generated by extraction or AI | Store only routed output. |
Common mistake: scanning only the extracted text. Scan the original file first when possible.
Settings recipe: OCR text before automation.
Damage Photo Review
Goal: flag suspicious image evidence before it drives a claim, repair, or payment decision.
Scan plan:
| Step | What to scan | Settings | Route |
|---|---|---|---|
| 1 | Damage photo | content_type=image, scan_phase=input, focus=all, profile=strict | ALLOW continues. REVIEW pauses and follows guidance.next_step. WARN reviews suspicious evidence. BLOCK stops automation. |
| 2 | High-value or suspicious photo | mode=comprehensive, async=true | Show pending review until final result. |
| 3 | AI-generated damage summary | scan_phase=output, same scan_group_id | Do not trust generated summary without output routing. |
Say Citadel flagged suspicious evidence. Do not say Citadel proved fraud.
Settings recipe: image authenticity, image edits, and full image/PDF evidence review.
Invoice And Estimate Review
Goal: check invoices and repair estimates before approval, payment, or AI summarization.
Scan plan:
| Step | What to scan | Settings | Route |
|---|---|---|---|
| 1 | Invoice PDF, estimate PDF, or image | content_type=auto, scan_phase=input, data_sensitivity=tolerant | WARN queues review. BLOCK stops approval. |
| 2 | Extracted line items | content_type=text, same scan_group_id | Do not write risky fields to payment workflow. |
| 3 | AI comparison or recommendation | scan_phase=output, profile=strict | Review WARN, BLOCK, and indeterminate. |
Use metadata such as workflow=invoice_review, vendor_id, claim_id, and invoice_id when available.
Settings recipe: mixed file upload, office document, and OCR text.
Agent Tool Review
Goal: keep unsafe tool output, retrieved documents, and browser content out of the next model step.
Scan plan:
| Step | What to scan | Settings | Route |
|---|---|---|---|
| 1 | User prompt | scan_phase=input, focus=steg | Only ALLOW starts the agent. |
| 2 | Retrieved documents or tool output | scan_phase=output, profile=ai_safety or code_assistant | ALLOW can enter context. REVIEW and WARN stay out until resolved. BLOCK stays out. |
| 3 | Final answer or plan | scan_phase=output, same session_id | Scan before user or tools act on it. |
Agents are multistep. Use one session_id for the agent run. Use scan groups for related prompt, retrieval, tool output, and final answer chains.
Settings recipe: agent tool output and generated output inspection.
Batch Intake
Goal: scan many records or files without losing traceability.
Scan plan:
| Step | What to scan | Settings | Route |
|---|---|---|---|
| 1 | Each item | One scan per item, unique request_id | Do not use one result for the whole batch. |
| 2 | Batch session | One session_id for the batch | Use one scan_group_id per item. |
| 3 | Failures and limits | Handle 402, 413, 429 | Retry with backoff or route item to review. |
Common mistake: one scan_group_id for the whole batch. Use one group per item.
Human Review Queues
Goal: give reviewers enough context to decide what happens next.
Store:
| Field | Why |
|---|---|
scan_id | Link to the scan result. |
request_id | Debug request and retry behavior. |
scan_group_id | Show the evidence chain for one item. |
session_id | Show the wider claim, chat, case, batch, or agent run. |
action, risk_score, risk_level, threats | Explain why the item was routed. |
content_type_detected, authenticity | Show file-type and authenticity evidence when returned. |
| Human decision | Keep final review outcome separate from the Citadel scan result. |
Citadel routes risk. Your team makes the final business decision.
Default Routing
Three response fields drive workflow decisions, and each comes from a different part of the response.
action — the routing decision. Switch on this:
action | Default product route |
|---|---|
| ALLOW | Continue. Store IDs. |
| REVIEW | Pause. Read guidance.reason and retry temporary failures once. Do not treat the result as suspicious evidence or permission to continue. |
| WARN | Review suspicious evidence, add friction, constrain the model, or request more evidence. |
| BLOCK | Stop automation. Use redacted_output only when returned and policy allows it. |
scan_status — async lifecycle. Only meaningful for mode=comprehensive + async=true:
scan_status | Default product route |
|---|---|
pending | Keep pending, poll GET /v1/scan/<scan_id>, or wait for the webhook. |
complete | The action field is final — apply routing. |
failed | High-risk workflows go to review. Low-risk workflows can retry once. |
authenticity.verdict is authenticity evidence for image or PDF content, separate from routing:
authenticity.verdict | Meaning |
|---|---|
likely_real | Camera capture or signed-document signals match. |
likely_ai_generated | Mid-confidence synthetic-content signals — usually pairs with WARN. |
ai_generated | High-confidence synthetic — usually pairs with BLOCK. |
indeterminate | The authenticity check did not reach a conclusion. Route on the top-level action; use this verdict as supporting context. |
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
Paste this into Cursor, Codex, Claude Code, or Windsurf.
Choose the Citadel workflow for this product and implement it.
First identify the workflow:
- chat app
- public AI output
- file upload
- OCR or IDP
- damage photo review
- invoice or estimate review
- agent tool review
- batch intake
- human review queue
For each workflow:
- Put POST /v1/scan before funding, bind, payout, storage, or a model call.
- Use scan_phase=input for the submitted file.
- Use scan_phase=output for generated, extracted, summarized, or tool-created material.
- Choose content_type from text, image, pdf, document, or auto.
- Use mode=secure by default.
- Use mode=comprehensive and async=true for high-value image or PDF review.
- Use focus=steg for mixed file intake and structured documents. Use focus=all when known image/PDF evidence needs threat, authenticity, and edit evidence together.
- Use data_sensitivity=tolerant when normal business PII is expected.
- Use data_sensitivity=strict for public AI output.
- Store scan_id, request_id, scan_group_id, session_id, action, risk_score, and risk_level.
- Route ALLOW, REVIEW, WARN, and BLOCK separately; treat indeterminate authenticity evidence as supporting context, and handle pending and failed independently.
Acceptance criteria:
- Every workflow has a clear scan point before funding, bind, or payout.
- Derived extraction, model, and tool output scans reuse the correct scan_group_id.
- Review wording says Citadel flagged risk, not that Citadel proved fraud.
- Tests cover ALLOW, REVIEW, WARN, BLOCK, scan failure, and output scanning.