> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encrata.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Malware Scan

> Scan a URL, QR code, barcode, image, or file for malicious and suspicious content.

Malware Scan returns one safety verdict for a URL, QR code, barcode, image, or file.

`POST /api/lookup/malware/scan`

Requires an [Encrata API key](/authentication) in the `Authorization` header.

## Request

All five scan types use the same endpoint. Set `kind` to select the input and
scanner.

| `kind` | Required input | What the scan checks |
| - | - | - |
| `url` | `url` | Redirects, domain and TLS details, hosting, page signals, downloads, and threat intelligence |
| `qr` | `content_base64` | QR, Data Matrix, and Aztec payloads plus up to three embedded links |
| `bar` | `content_base64` | Code 128/39/93, Codabar, ITF, EAN-8/13, and UPC-A/E payloads |
| `image` | `content_base64` | File type, hashes, metadata, hidden data, OCR, embedded codes, and discovered links |
| `file` | `content_base64` or `source_url` | Malware and rule matches in a file |

<ParamField body="kind" type="string" required>
  One of `url`, `qr`, `bar`, `image`, or `file`.
</ParamField>

<ParamField body="url" type="string">
  URL to inspect. Required when `kind` is `url`.
</ParamField>

<ParamField body="content_base64" type="string">
  Base64-encoded bytes. Required for `qr`, `bar`, and `image`. For
  `file`, send either this field or `source_url`.
</ParamField>

<ParamField body="source_url" type="string">
  Short-lived download URL for a file. Available only when `kind` is `file`.
  The downloaded file can be up to 100 MiB.
</ParamField>

<ParamField body="filename" type="string">
  Original file name. Send it with uploaded images and files so extension checks
  and file scanners have the expected context.
</ParamField>

<ParamField body="stix" type="boolean" default="false">
  Include a STIX 2.1 bundle in `result.stix`.
</ParamField>

## Examples

<Tabs>
  <Tab title="URL">
    ```bash theme={"theme":{"light":"github-light","dark":"vesper"}}
    curl -X POST "https://developer.encrata.com/api/lookup/malware/scan" \
      -H "Authorization: Bearer enc_xxxxxxxxxxxx" \
      -H "Content-Type: application/json" \
      -d '{"kind":"url","url":"https://example.com"}'
    ```
  </Tab>

  <Tab title="QR code">
    ```bash theme={"theme":{"light":"github-light","dark":"vesper"}}
    CONTENT_BASE64="$(base64 < payment-qr.png | tr -d '\n')"
    curl -X POST "https://developer.encrata.com/api/lookup/malware/scan" \
      -H "Authorization: Bearer enc_xxxxxxxxxxxx" \
      -H "Content-Type: application/json" \
      -d "{\"kind\":\"qr\",\"content_base64\":\"$CONTENT_BASE64\",\"filename\":\"payment-qr.png\"}"
    ```
  </Tab>

  <Tab title="Barcode">
    ```bash theme={"theme":{"light":"github-light","dark":"vesper"}}
    CONTENT_BASE64="$(base64 < shipping-label.png | tr -d '\n')"
    curl -X POST "https://developer.encrata.com/api/lookup/malware/scan" \
      -H "Authorization: Bearer enc_xxxxxxxxxxxx" \
      -H "Content-Type: application/json" \
      -d "{\"kind\":\"bar\",\"content_base64\":\"$CONTENT_BASE64\",\"filename\":\"shipping-label.png\"}"
    ```
  </Tab>

  <Tab title="Image">
    ```bash theme={"theme":{"light":"github-light","dark":"vesper"}}
    CONTENT_BASE64="$(base64 < suspicious-image.png | tr -d '\n')"
    curl -X POST "https://developer.encrata.com/api/lookup/malware/scan" \
      -H "Authorization: Bearer enc_xxxxxxxxxxxx" \
      -H "Content-Type: application/json" \
      -d "{\"kind\":\"image\",\"content_base64\":\"$CONTENT_BASE64\",\"filename\":\"suspicious-image.png\"}"
    ```
  </Tab>

  <Tab title="File">
    ```bash theme={"theme":{"light":"github-light","dark":"vesper"}}
    FILE_BASE64="$(base64 < invoice.pdf | tr -d '\n')"
    curl -X POST "https://developer.encrata.com/api/lookup/malware/scan" \
      -H "Authorization: Bearer enc_xxxxxxxxxxxx" \
      -H "Content-Type: application/json" \
      -d "{\"kind\":\"file\",\"content_base64\":\"$FILE_BASE64\",\"filename\":\"invoice.pdf\"}"
    ```
  </Tab>
</Tabs>

## Response

Every scan returns the `{success, result, message}` envelope. Start with
`result.verdict`, then inspect `signals` and the fields for the selected
`kind`.

```json theme={"theme":{"light":"github-light","dark":"vesper"}}
{
  "success": true,
  "result": {
    "scan_id": "scn_9f3a1c2b7e4d",
    "kind": "url",
    "status": "done",
    "verdict": "clean",
    "score": 0,
    "submitted_url": "https://example.com",
    "final_url": "https://example.com/",
    "final_domain": "example.com",
    "category": "benign",
    "confidence": "high",
    "signals": [],
    "iocs": [
      {
        "type": "url",
        "value": "https://example.com",
        "source": "submitted"
      }
    ],
    "scanned_at": "2026-10-07T09:30:00Z"
  },
  "message": "No threats found."
}
```

### Common fields

<ResponseField name="success" type="boolean">
  Whether the scan completed.
</ResponseField>

<ResponseField name="message" type="string">
  `Malicious content detected.`, `This item looks suspicious - review the
      signals.`, `No threats found.`, or `Scan complete.`.
</ResponseField>

<ResponseField name="result" type="object">
  The scan verdict and kind-specific analysis.

  <Expandable title="result">
    <ResponseField name="scan_id" type="string">
      Unique scan ID.
    </ResponseField>

    <ResponseField name="kind" type="string">
      `url`, `qr`, `bar`, `image`, or `file`.
    </ResponseField>

    <ResponseField name="status" type="string">
      Scan status. Completed requests return `done`.
    </ResponseField>

    <ResponseField name="verdict" type="string">
      `clean`, `suspicious`, `malicious`, or `unknown`.
    </ResponseField>

    <ResponseField name="score" type="integer">
      Risk score from 0 to 100.
    </ResponseField>

    <ResponseField name="sha256" type="string">
      SHA-256 hash of an uploaded image, code, or file.
    </ResponseField>

    <ResponseField name="category" type="string">
      `c2`, `malware_distribution`, `phishing`, `malicious`,
      `suspicious`, `benign`, or `unknown`.
    </ResponseField>

    <ResponseField name="confidence" type="string">
      `high`, `medium`, or `low`.
    </ResponseField>

    <ResponseField name="attack" type="object[]">
      MITRE ATT\&CK mappings. Each item contains `id`, `name`, `tactic`,
      and `url`.
    </ResponseField>

    <ResponseField name="signals" type="object[]">
      Evidence used for the verdict. Each item contains `source`,
      `malicious`, `detail`, and optional `severity`.
    </ResponseField>

    <ResponseField name="iocs" type="object[]">
      Indicators of compromise. Each item contains `type`, `value`, and
      optional `source`.
    </ResponseField>

    <ResponseField name="data_residency" type="string">
      `global` or `eu`.
    </ResponseField>

    <ResponseField name="scanned_at" type="string">
      ISO 8601 timestamp for the scan.
    </ResponseField>

    <ResponseField name="stix" type="object">
      STIX 2.1 bundle. Present only when the request sets `stix: true`.
    </ResponseField>
  </Expandable>
</ResponseField>

### URL fields

| Field | Type | Description |
| - | - | - |
| `submitted_url` | string | URL received in the request |
| `final_url` | string | URL after redirects |
| `final_domain` | string | Registrable domain of the final URL |
| `redirects` | string\[] | Redirect URLs in order |
| `redirect_hops` | object\[] | Redirect details: `url`, `status_code`, and `host` |
| `domain` | object | Registration and DNS data: `name`, `registrar`, dates, `age_days`, `status`, `nameservers`, `dnssec`, registrant organization and country, `tld`, and `risky_tld` |
| `tls` | object | Certificate data: protocol, cipher, trust, expiry, issuer, subject, SANs, dates, fingerprint, and serial |
| `hosting` | object | Host data: IP, reverse DNS, ASN, organization, location, network, abuse contact, hosting flags, blocklists, and command-and-control attribution |
| `page` | object | Static page analysis: status, content type, headers, title, size, forms, frames, scripts, redirects, brand mentions, security headers, favicon, and download details |
| `threat_intel` | object\[] | Reputation results with status, threat type, malware families, tags, dates, confidence, detections, payloads, and detail |

<Note>
  Page analysis is static. Encrata does not execute scripts from the scanned URL.
</Note>

### QR code and barcode fields

| Field | Type | Description |
| - | - | - |
| `image` | object | Image `format`, dimensions, size, detected type, extension, and whether the extension matches |
| `codes` | object\[] | Every decoded symbol in the image |

Each `codes` item can contain `format`, `payload_type`, redacted `raw`
content, `final_url`, `verdict`, `score`, `signals`,
`error_correction`, pixel `position`, structured-append `sequence`, parsed
`payload`, and `url_scans`.

The parsed `payload` can describe URLs, Wi-Fi configuration without the
password, payment details, phone numbers, email messages, SMS messages,
coordinates, contacts, one-time password metadata without the secret, device
links, FIDO data, app-install links, scripts, or text.

### Image fields

| Field | Type | Description |
| - | - | - |
| `image` | object | Format, dimensions, size, detected type, extension, and extension match |
| `hashes` | object | `md5`, `sha1`, `sha256`, and perceptual `dhash` |
| `metadata` | object | Camera, owner, software, timestamps, GPS, comments, and text metadata |
| `appended_data` | object | Type, offset, and size of data stored after the image end marker |
| `steganography` | object | Hidden-data verdict, confidence, LSB analysis, transparency checks, polyglot type, thumbnail comparison, and carved files |
| `file_type` | string | File type reported by the file scanner |
| `ocr_text` | string | OCR text, capped at 5,000 characters |
| `ocr_urls` | string\[] | URLs found by OCR |
| `url_scans` | object\[] | Full URL results for up to three discovered links |

### File fields

A file result uses the common fields plus `sha256`, `file_type`, and a SHA-256
indicator in `iocs`. The `signals` array contains malware and rule matches.

## Errors

Errors use
`{"success": false, "result": {"code": "..."}, "message": "..."}`.

| Status | Cause |
| - | - |
| `400` | The JSON body is invalid, `kind` is unknown, a required field is missing, base64 is invalid, an image cannot be decoded, or a `source_url` cannot be fetched safely. |
| `401` | The API key is missing or invalid. |
| `402` | The account has no available credits. |
| `500` | The scan could not be stored or completed. |

## Credits

Each successful scan costs **1 credit**. Repeating the same `kind` with the
same content does not charge your account twice. See [Credits](/credits).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.