# POST /v1/scan

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

Source URL: https://trymighty.ai/docs/api-reference/v1-scan

The stable public API surface is:

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

Use the docs below for humans. Use [OpenAPI YAML](/openapi/mighty-api.yaml) for SDK generation, AI tools, and contract inspection.

Illustration: 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.

```http
Authorization: Bearer $MIGHTY_API_KEY
```

Keep the key on your server.

## JSON Request

```json
{
  "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

```bash
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

```bash
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):

```json
{
  "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:

```json
{
  "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.

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

Example PDF response fields:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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

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

## Error Handling

See [Error Handling](/docs/integrate/errors) for `400`, `402`, `409`, `413`, `429`, and async states.

## AI-Agent Prompt

### Use the API reference

```text
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.
```