Create a scan

Scan text, TXT, Markdown, HTML, PDF, DOCX, static public HTTPS webpages, or public remote MCP server metadata. API keys require scan:write. Raw file uploads may be up to 10 MB. Anonymous, Free, and Personal extracted content is limited to 100,000 bytes; Pro extracted content is limited to 1,000,000 bytes. Free and Personal allow at most 25,000 input tokens. Every input type costs max(1, ceil(input_tokens / 1000)) Scan Units. Token rate limits apply to every input type. Query parameters are not supported.

post/api/v1/scan

Request

  • Base URL: https://control.patronus.studio
  • URL: https://control.patronus.studio/api/v1/scan
  • Auth: one of:
    • HTTP bearer
    • none

Headers

X-Patronus-Client'cli'

Set to cli for anonymous CLI submissions. Authenticated API-key requests do not need this header.

Preferstring

Text without Prefer is synchronous: HTTP 200 contains completed jobs that are not stored for polling. URL, file, and MCP server inputs are asynchronous by default and return HTTP 202 jobs to poll. Use respond-async for asynchronous text. Use wait=1 for an asynchronous job with a capped short wait: one terminal job returns 200, otherwise 202. Multiple wait=1 jobs return 202.

Idempotency-Keystring

Optional visible-ASCII key (1–128 characters). Reuse with the same request content and Prefer header (exact JSON bytes and Content-Type; multipart fields and files in the same order, ignoring its boundary) to replay its response for 15 minutes without another scan or charge. A conflicting request or in-flight submission returns 409.

Request body

OR
OR

Example request

{
  "url": "https://example.com"
}

Response

Completed jobs from a synchronous text request without Prefer, or one terminal asynchronous job with Prefer: wait=1. Synchronous text jobs are not stored for polling; wait=1 jobs can be retrieved through their status endpoint.

ark_version'1' required

Version of the internal Ark result contract interpreted by the Control Plane.

status'completed' required
categoriesobject
decision'allow' | 'review' | 'block'
safety_status'benign' | 'review' | 'attack'

Final verdict: benign or attack; review flags an inconclusive final classification or a differing decisive l3 attack chunk above 0.1 confidence at union stage and category level L3.

Changes

No recorded changes to this operation across all 1 revision of this API.