Framework Integration Map
Choose the right Citadel pattern for chat, uploads, backend APIs, serverless routes, and agent frameworks.
Every framework integration is the same idea: scan on the server before trust.
The framework only changes where you put the helper.
Core concept
Scan the file before the workflow acts on it.
Customer filePaystub, photo, PDF, extracted text, model output
Citadel scanPOST /v1/scan returns action, risk, IDs, and signals
Your routingContinue, review, redact, or block before automation acts
Citadel does not prove fraud. It flags risk on the file before funding, bind, payout, storage, or a model call.
Choose Your Pattern
| Stack | Put Citadel here | Use this guide |
|---|---|---|
| Vercel AI SDK chat | Inside app/api/chat/route.ts, before streamText, and before strict output returns. | Vercel AI SDK |
| Next.js uploads | Inside the upload Route Handler before storage, OCR, or extraction. | Next.js file upload |
| Backend API | In a server helper or middleware before the handler calls AI, OCR, storage, or tools. | Backend API helpers |
| OpenAI SDK | Scan prompt before model call. Scan output before public display or automation. | Backend API helpers |
| LangChain | Scan user input before chain invocation. Scan retrieved docs and tool output before adding them to context. | Backend API helpers |
| LlamaIndex | Scan query input, retrieved nodes, extracted text, and final response before trust. | Backend API helpers |
| Async review | Submit mode=comprehensive, async=true, then poll or handle webhooks. | Async scans |
Integration Rules
- Keep
MIGHTY_API_KEYon the server. - Scan before the model, OCR, storage, workflow automation, payment, or agent action.
- Use
scan_phase=inputfor submitted material. - Use
scan_phase=outputfor generated, extracted, summarized, or agent-created material. - Reuse
scan_group_idfor related input, file, OCR, output, and review scans. - Use
session_idfor the wider chat, claim, case, batch, or agent run. - Route ALLOW, WARN, BLOCK,
indeterminate, and asyncpending. - Use safe fallback behavior when Citadel cannot be reached.
Framework Traps
| Trap | Fix |
|---|---|
| Calling Citadel from browser code | Move scan calls to a server route. |
| Scanning only the initial prompt | Scan model output, tool output, OCR output, and extracted fields too. |
Returning JSON from a useChat route that expects a UI message stream | For Vercel AI SDK streaming routes, return toUIMessageStreamResponse or createUIMessageStreamResponse. |
Losing scan_group_id between upload and OCR | Persist it on the item, not only in logs. |
| Treating framework errors as safe | Fail closed or use review fallback for high-risk workflows. |
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
Choose the Citadel framework pattern
Paste this into Cursor, Codex, Claude Code, or Windsurf.
Choose the correct Citadel framework integration pattern.
Rules:
- Use server-side scan calls only.
- Put POST /v1/scan before AI, OCR, storage, workflow automation, payment, and agent action.
- Use the Vercel AI SDK route pattern for app/api/chat/route.ts.
- Use the Next.js upload route pattern for browser file uploads.
- Use the backend API helper for Node, Python, Express, FastAPI, Flask, Django, workers, queues, and custom APIs.
- For LangChain and LlamaIndex, scan before chain invocation, before retrieved content enters context, before tool output is reused, and before final output is shown.
- Preserve scan_id, request_id, scan_group_id, session_id, action, and risk_score.
Acceptance criteria:
- API key never reaches client code.
- Existing framework response shape is preserved.
- Tests cover ALLOW, WARN, BLOCK, and scan failure.