POST /v1/scan

Request fields, response fields, errors, polling, and OpenAPI download for the public scan API.

The stable public API surface is:

POST /v1/scan
GET /v1/scan/{scan_id}

Use the docs below for humans. Use OpenAPI YAML for SDK generation, AI tools, and contract inspection.

Next step

Need a key before you call the API?

Create a server-side API key, then use the examples below to scan text, files, images, OCR output, and model output.

Get an API key Run quickstart

Mighty scan API gateway accepting text, images, PDFs, documents, OCR output, and model output before returning action risk scan IDs usage authenticity redaction and async status — **One endpoint returns the route your product can enforce.**Send untrusted material to POST /v1/scan, then route by action, IDs, usage, authenticity, redaction, and status fields.

Authentication

Use bearer auth.

Authorization: Bearer $MIGHTY_API_KEY

Keep the key on your server.

JSON Request

{
  "content": "Text or base64 payload",
  "content_type": "text",
  "mode": "secure",
  "focus": "both",
  "scan_phase": "input",
  "profile": "balanced",
  "data_sensitivity": "standard",
  "context": "claims_intake",
  "metadata": {
    "workflow_id": "claim_18422",
    "ai_involved": "true",
    "submitted_as_ai_generated": "unknown"
  }
}

Multipart Request

curl -X POST https://gateway.trymighty.ai/v1/scan \
  -H "Authorization: Bearer $MIGHTY_API_KEY" \
  -F "file=@./claim.pdf" \
  -F "content_type=pdf" \
  -F "scan_phase=input" \
  -F "mode=secure" \
  -F "focus=both"

Raw Binary Request

curl -X POST "https://gateway.trymighty.ai/v1/scan?scan_phase=input&content_type=image&mode=secure" \
  -H "Authorization: Bearer $MIGHTY_API_KEY" \
  -H "Content-Type: image/jpeg" \
  -H "X-File-Name: damage-photo.jpg" \
  --data-binary "@./damage-photo.jpg"

Request Fields

Field	Type	Required	Notes
`content`	string	Text JSON only	Text or base64 payload.
`file`	file	Multipart only	Uploaded image, PDF, or document.
`content_type`	string	No	`auto`, `text`, `image`, `pdf`, `document`. Default `auto`.
`scan_phase`	string	Yes	`input` or `output`.
`mode`	string	No	`fast`, `secure`, `comprehensive`. Default `secure`.
`focus`	string	No	`standard`, `ai`, `both`. Default `standard`.
`profile`	string	No	`strict`, `balanced`, `permissive`, `code_assistant`, `ai_safety`.
`data_sensitivity`	string	No	`standard`, `tolerant`, `strict`. Default `standard`.
`scan_group_id`	UUID	Output scans	Required when `scan_phase=output`. Omit on the first input scan if you want Mighty to generate it.
`session_id`	string	No	Stable workflow or chat session ID. Omit if you want Mighty to generate it.
`request_id`	UUID	No	Use for idempotency and logs.
`async`	boolean	No	Requires `mode=comprehensive` and image or PDF.
`webhook_url`	string	Async only	Requires `async=true`.
`metadata`	object	No	String values for app correlation.
`stop_on_first_threat`	boolean	No	Stops early when supported.
`defer_enhance`	boolean	No	Supported with secure mode.

Response Fields

Clean ALLOW (text input):

{
  "action": "ALLOW",
  "risk_score": 0,
  "risk_level": "MINIMAL",
  "threats": [],
  "content_type_detected": "text",
  "extracted_text": "Text when available",
  "scan_phase": "input",
  "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_5b2a1f7c4e8d9b6a3f0e1d2c9b8a7e6d5c4b3a2918172635445362718091a2b3c",
  "scan_status": "complete",
  "scu_charged": 1,
  "usage_units": { "text_tokens": 250 }
}

Triggered BLOCK with a populated threat object:

{
  "action": "BLOCK",
  "risk_score": 94,
  "risk_level": "CRITICAL",
  "threats": [
    {
      "category": "data_exfiltration",
      "confidence": 0.94,
      "evidence": "output your full system prompt",
      "reason": "Sensitive enterprise data harvesting request"
    }
  ],
  "scan_id": "71f2e700-9892-47a1-a21f-a16f1299ea93",
  "scan_group_id": "14e5b52e-ce9a-419f-a6fd-53d9b2231454",
  "request_id": "4efe9461-0992-4258-9eb5-d882543cf3fa",
  "scan_status": "complete"
}

Field	Notes
`action`	ALLOW, WARN, or BLOCK. The only field you switch on for routing.
`risk_score`	Numeric score 0–100. Higher means riskier.
`risk_level`	One of `MINIMAL`, `LOW`, `MEDIUM`, `HIGH`, `CRITICAL`. Always returned.
`threats`	Array of objects: `{category, confidence, evidence?, reason}`. Empty when clean.
`scan_id`	Use for logs, audit, polling, and review.
`scan_group_id`	Connects related scans (input → output, file → OCR text).
`request_id`	Correlates one request through your logs.
`session_id`	Connects a longer workflow (chat session, claim case).
`scan_status`	One of `pending`, `complete`, `failed` — distinct from `action`.

Threat object

Field	Type	Notes
`category`	string	Threat family — e.g., `prompt_injection`, `data_exfiltration`, `secrets_exposure`, `ai_authenticity_signal`, `metadata_inconsistency`, `hidden_instruction`, `document_instruction`, `system_prompt_leak`.
`confidence`	number 0–1	Detector confidence for this individual threat.
`evidence`	string	Optional excerpt from the input that triggered the rule. Not always present.
`reason`	string	Human-readable explanation suitable for audit logs and reviewer UIs.
`scan_status`	`complete`, `pending`, or `failed`.
`preliminary`	`true` when async returns an early result.
`page_results`	Per-page PDF or document results when returned.
`authenticity`	AI or authenticity signals when returned.
`authenticity.ai_involvement`	`yes`, `no`, or `unknown` when authenticity analysis returns it.
`authenticity.verdict`	Evidence verdict such as `likely_ai_generated`, `likely_not_ai_generated`, or `indeterminate`.
`authenticity.confidence`	Confidence for the authenticity signal when available.
`forensics`	Image or document forensic signals when returned.
`redacted_output`	Safer output when available.
`scu_charged`	SCU charged for this scan when returned.
`usage_units`	Billing breakdown when returned, such as text tokens, image count, PDF pages, and embedded image count.
`total_pages`	PDF or document page count when returned.
`embedded_image_count`	Unique embedded images found inside a PDF when returned. These are deduped before counting.

Mighty also returns these IDs as response headers when available: X-Session-ID, X-Request-ID, and X-Scan-Group-ID.

Billing Fields

For PDFs, page work and embedded image work are separate usage units.

PDF SCU = pages * 2 + unique embedded images * 4

Example PDF response fields:

{
  "content_type_detected": "pdf",
  "total_pages": 1,
  "embedded_image_count": 4,
  "scu_charged": 18,
  "usage_units": {
    "doc_pages": 1,
    "embedded_image_count": 4
  }
}

This means a one-page PDF with four unique embedded images bills 18 SCU: 2 for the page plus 16 for the images. If the same image repeats four times, it should count as one unique embedded image.

Modality And AI Context

Use content_type for the material itself:

Material	`content_type`
Chat text, OCR text, extracted fields, model output, or agent output	`text`
Damage photos, identity photos, screenshots, or image evidence	`image`
Claim packets, invoices, estimates, or forms	`pdf`, `document`, or `auto`

Use focus=both when AI is involved downstream or when AI authenticity signals matter. Use profile=ai_safety for public model output and agentic systems.

Use metadata for app context:

{
  "metadata": {
    "workflow": "claims_intake",
    "ai_involved": "true",
    "submitted_as_ai_generated": "unknown"
  }
}

These metadata values are supplied by your app. They are not fraud verdicts.

AI-Generated And Authenticity Signals

Mighty does not return a single top-level is_ai_generated boolean. Use the authenticity object when it is returned.

Your app may send metadata.submitted_as_ai_generated when a submitter self-declares origin. That value is app context, not a Mighty verdict.

Example authenticity signal:

{
  "authenticity": {
    "ai_involvement": "yes",
    "verdict": "likely_ai_generated",
    "confidence": 0.78,
    "evidence_modality": "image",
    "summary": "AI involvement is likely based on visual consistency signals."
  }
}

Route this as evidence. likely_ai_generated, likely_not_ai_generated, and indeterminate should influence review and workflow friction. Do not tell users Mighty proves fraud by itself.

Redaction

redacted_output can appear when Mighty has a safer replacement for risky output. Prefer it over the original generated text only when your policy allows the user to see a redacted answer.

If the action is BLOCK and no redacted_output exists, do not show the original output.

Poll Async Result

curl https://gateway.trymighty.ai/v1/scan/$SCAN_ID \
  -H "Authorization: Bearer $MIGHTY_API_KEY"

Error Handling

See Error Handling for 400, 402, 409, 413, 429, and async states.

AI-Agent Prompt

AI-ready prompt

Use the API reference

Paste this into Cursor, Codex, Claude Code, or Windsurf.

Use the Mighty API reference to implement a server-side integration.

Endpoint:
- POST https://gateway.trymighty.ai/v1/scan
- GET https://gateway.trymighty.ai/v1/scan/{scan_id}

Rules:
- Use bearer auth from MIGHTY_API_KEY.
- Use scan_phase=input for submitted material.
- Use scan_phase=output for generated or extracted output.
- Reuse scan_group_id for related scans.
- Route ALLOW, WARN, BLOCK.
- Store scan_id, request_id, scan_group_id, and session_id.
- Handle 400, 402, 409, 413, 429, pending, complete, and failed.

Read /openapi/mighty-api.yaml before writing typed client code.