Quickstart

Get your first verdict in under five minutes once your Zaun operator has supplied an active project key with scan:write and confirmed that the organization is seeded and ready. Complete and document scans also need the service's model access to be enabled. You need curl; Python is optional for the second half.

Set up once

Load your key from your secret store into ZAUN_API_KEY. The placeholder below is not a working credential. Use HTTPS and keep the real secret out of source control and logs.

export ZAUN_BASE_URL='https://api.zaunsecurity.com'
export ZAUN_API_KEY='zaun_scan_REPLACE_WITH_YOUR_KEY'
export FAST_ID="$(uuidgen)"
export COMPLETE_ID="$(uuidgen)"
export DOCUMENT_ID="$(uuidgen)"
printf '%s' 'Explain least privilege.' > example.txt

Keep each Idempotency-Key unchanged when retrying the same request after a lost response. Generate a new key when you change the input or intentionally request another scan. The examples below are copied from the checked-in OpenAPI request and response examples. They illustrate a ready project with strong benign reference matches and no matching policy rule; they are not live service captures. IDs, timestamps, model/revision identifiers, usage, timing, scores, and verdicts depend on your deployment and input.

1. Fast prompt

Fast compares your message with curated reference examples. This is the first call you need to make:

curl --silent --show-error --fail-with-body --max-time 15 \
  "$ZAUN_BASE_URL/v1/scan/prompt" \
  -H "Authorization: Bearer $ZAUN_API_KEY" \
  -H "Idempotency-Key: $FAST_ID" \
  -H 'Content-Type: application/json' \
  --data-binary '{
  "scan_type": "fast",
  "messages": [
    {
      "role": "user",
      "content": "Explain least privilege."
    }
  ],
  "target": "all"
}'

Example HTTP 200 response:

{
  "request_uuid": "00000000-0000-4000-8000-000000000001",
  "status": "completed",
  "scan_type": "fast",
  "stages": {
    "embed": "ok",
    "knn": "ok",
    "t2": "skipped"
  },
  "verdict": "benign",
  "violation": false,
  "technique": null,
  "taxonomy": "mitre_atlas_tactic",
  "findings": [],
  "recommendation": null,
  "confidence": 0.9,
  "confidence_basis": "knn_heuristic_v1",
  "signals": {
    "path": "close_benign",
    "max_similarity": 0.98,
    "neighbor_count": 20,
    "adverse_share": 0,
    "support": 0.9,
    "margin": 1
  },
  "coverage": {
    "messages_assessed": 1,
    "messages_total": 1,
    "chunks": 1
  },
  "config_version": 1,
  "revisions": {
    "model": "configured-revision",
    "corpus": "configured-corpus",
    "confidence_basis": "knn_heuristic_v1"
  },
  "created_at": "2026-09-16T00:00:00Z",
  "completed_at": "2026-09-16T00:00:01Z",
  "expires_at": "2026-10-16T00:00:00Z",
  "latency_ms": {
    "total": 61,
    "embed": 38,
    "search": 9,
    "t2": null
  },
  "usage": []
}

2. Complete prompt

Complete always adds the second-stage classifier, even if the fast evidence looks benign. The example shows agreement and stages.t2: ok.

curl --silent --show-error --fail-with-body --max-time 60 \
  "$ZAUN_BASE_URL/v1/scan/prompt" \
  -H "Authorization: Bearer $ZAUN_API_KEY" \
  -H "Idempotency-Key: $COMPLETE_ID" \
  -H 'Content-Type: application/json' \
  --data-binary '{
  "scan_type": "complete",
  "messages": [
    {
      "role": "user",
      "content": "Explain least privilege."
    }
  ],
  "target": "all"
}'

Example HTTP 200 response:

{
  "request_uuid": "00000000-0000-4000-8000-000000000002",
  "status": "completed",
  "scan_type": "complete",
  "stages": {
    "embed": "ok",
    "knn": "ok",
    "t2": "ok"
  },
  "verdict": "benign",
  "violation": false,
  "technique": null,
  "taxonomy": "mitre_atlas_tactic",
  "findings": [],
  "recommendation": null,
  "confidence": 0.97,
  "confidence_basis": "t2_agreement_v1",
  "signals": {
    "path": "close_benign",
    "max_similarity": 0.98,
    "neighbor_count": 20,
    "adverse_share": 0,
    "support": 0.9,
    "margin": 1,
    "knn": {
      "verdict": "benign",
      "confidence": 0.9
    }
  },
  "coverage": {
    "messages_assessed": 1,
    "messages_total": 1,
    "chunks": 1
  },
  "config_version": 1,
  "revisions": {
    "model": "configured-revision",
    "corpus": "configured-corpus",
    "confidence_basis": "knn_heuristic_v1"
  },
  "created_at": "2026-09-16T00:00:00Z",
  "completed_at": "2026-09-16T00:00:02Z",
  "expires_at": "2026-10-16T00:00:00Z",
  "latency_ms": {
    "total": 1261,
    "embed": 38,
    "search": 9,
    "t2": 1200
  },
  "usage": [
    {
      "stage": "t2",
      "model": "configured-t2-model",
      "input_tokens": 620,
      "output_tokens": 12
    }
  ]
}

3. Upload a document

Upload the example.txt created above. Its bytes are exactly Explain least privilege., matching the OpenAPI multipart example. Curl sets the multipart boundary, so do not add a JSON Content-Type header. The API accepts one file up to 4,718,592 bytes (4.5 MiB); see limits for formats and coverage.

curl --silent --show-error --fail-with-body --max-time 110 \
  "$ZAUN_BASE_URL/v1/scan/document" \
  -H "Authorization: Bearer $ZAUN_API_KEY" \
  -H "Idempotency-Key: $DOCUMENT_ID" \
  -F 'scan_type=complete' \
  -F 'file=@example.txt;type=text/plain'

Example HTTP 200 response:

{
  "request_uuid": "00000000-0000-4000-8000-000000000003",
  "status": "completed",
  "scan_type": "complete",
  "stages": {
    "embed": "ok",
    "knn": "ok",
    "t2": "ok",
    "document_model": "ok"
  },
  "verdict": "benign",
  "violation": false,
  "technique": null,
  "taxonomy": "mitre_atlas_tactic",
  "findings": [],
  "recommendation": null,
  "confidence": 0.97,
  "confidence_basis": "t2_agreement_v1",
  "signals": {
    "path": "close_benign",
    "max_similarity": 0.98,
    "neighbor_count": 20,
    "adverse_share": 0,
    "support": 0.9,
    "margin": 1,
    "knn": {
      "verdict": "benign",
      "confidence": 0.9
    },
    "document_model": {
      "verdict": "benign",
      "partial": false
    }
  },
  "coverage": {
    "messages_assessed": 1,
    "messages_total": 1,
    "chunks": 1,
    "extraction": "complete",
    "extraction_source": "document_model",
    "pages_extracted": 1,
    "empty_pages": []
  },
  "config_version": 1,
  "revisions": {
    "model": "configured-revision",
    "corpus": "configured-corpus",
    "confidence_basis": "knn_heuristic_v1"
  },
  "created_at": "2026-09-16T00:00:00Z",
  "completed_at": "2026-09-16T00:00:04Z",
  "expires_at": "2026-10-16T00:00:00Z",
  "latency_ms": {
    "total": 3261,
    "embed": 38,
    "search": 9,
    "t2": 1200,
    "document_model": 2000
  },
  "usage": [
    {
      "stage": "document_model",
      "model": "configured-document-model",
      "input_tokens": 180,
      "output_tokens": 60
    },
    {
      "stage": "t2",
      "model": "configured-t2-model",
      "input_tokens": 620,
      "output_tokens": 12
    }
  ],
  "per_chunk": [
    {
      "index": 0,
      "offsets": {
        "start": 0,
        "end": 24
      },
      "evidence": {
        "chunk_index": 0,
        "page": 1,
        "offset": 0
      },
      "verdict": "benign",
      "confidence": 0.97,
      "stages": {
        "embed": "ok",
        "knn": "ok",
        "t2": "ok"
      }
    }
  ]
}

The document example reports one extracted page and one assessed chunk. per_chunk locates evidence without returning extracted text. Document bytes are sent to Bedrock even if you choose fast; see data handling.

The same three calls in Python

Use the same ZAUN_API_KEY and ZAUN_BASE_URL environment variables. Install requests in a virtual environment:

python3 -m venv .venv
. .venv/bin/activate
python3 -m pip install requests

Save this as quickstart.py and run python3 quickstart.py. It prints each full response in the same shape as the curl examples. Python generates three new request IDs, so these are new scans. For production retries, save the generated idempotency key and reuse it with the same request body.

import json
import os
from uuid import uuid4

import requests

base_url = os.environ.get("ZAUN_BASE_URL", "https://api.zaunsecurity.com").rstrip("/")
client = requests.Session()
client.headers["Authorization"] = f"Bearer {os.environ['ZAUN_API_KEY']}"
fast_id = str(uuid4())
complete_id = str(uuid4())
document_id = str(uuid4())

# 1. Fast prompt.
fast = client.post(
    f"{base_url}/v1/scan/prompt",
    headers={"Idempotency-Key": fast_id},
    json={
        "scan_type": "fast",
        "messages": [{"role": "user", "content": "Explain least privilege."}],
        "target": "all",
    },
    timeout=(5, 15),
)
print(json.dumps(fast.json(), indent=2))
fast.raise_for_status()

# 2. Complete prompt.
complete = client.post(
    f"{base_url}/v1/scan/prompt",
    headers={"Idempotency-Key": complete_id},
    json={
        "scan_type": "complete",
        "messages": [{"role": "user", "content": "Explain least privilege."}],
        "target": "all",
    },
    timeout=(5, 60),
)
print(json.dumps(complete.json(), indent=2))
complete.raise_for_status()

# 3. Upload exactly the same bytes as example.txt, without needing a local file.
document = client.post(
    f"{base_url}/v1/scan/document",
    headers={"Idempotency-Key": document_id},
    data={"scan_type": "complete"},
    files={"file": ("example.txt", b"Explain least privilege.", "text/plain")},
    timeout=(5, 110),
)
print(json.dumps(document.json(), indent=2))
document.raise_for_status()

Read the verdict before acting

HTTP 200 means an assessment result was returned, including inconclusive results. Check status, verdict, confidence_basis, coverage, and stages. A block recommendation is still HTTP 200; your application must enforce it.

A freshly seeded, ready organization can return verdict: unknown. This means its reference examples do not provide enough clear, independent evidence for your particular input. violation and confidence are then null. It is neither a benign verdict nor proof of a failed setup. Try complete for a contextual assessment and choose an explicit application policy for unknown. Repeated scans do not add examples to the reference set. An organization that has not been seeded or is not ready instead returns 503 reference_not_ready; ask your operator to finish onboarding.

401 means the credential was not accepted; 403 means it lacks permission. For 429, wait the Retry-After seconds before retrying with the same idempotency key and body. See keys, concepts, and the complete error catalogue. Retained results can be read at GET /v1/result/{request_uuid} with result:read, normally for 30 days.

Back to guide index

Concepts

A scan assesses the content you send and returns a verdict, supporting findings, and an optional recommendation. Your application decides what happens next. Start with the quickstart, then use these distinctions when deciding which results to allow, review, or block.

Fast and complete

Send scan_type explicitly for prompts. By default, target: all assesses every message, including system, assistant, and tool messages. Use target: last_user only when you intend to assess the last user message alone. Send the conversation you want assessed on every call: session_uuid is a correlation ID and does not save conversation history. Instructions inside submitted content are themselves assessed; scans do not execute tool calls or fetch linked resources.

Documents first go to a document model for text extraction and a document-level assessment, even with scan_type: fast. Every extracted chunk receives the fast assessment. Complete documents additionally send up to five selected chunks to T2. Inspect per_chunk, coverage, and stages alongside the overall verdict.

Verdict and unknown

unknown prevents missing evidence from becoming a false assurance. A fast scan can return it when the examples are too distant, too few independent examples match, or benign and adverse evidence is too evenly split. A freshly seeded, ready organization can therefore return unknown for unfamiliar content. Scans do not teach the reference set, so repeating the request does not build support. An organization whose reference set is not ready instead returns HTTP 503 reference_not_ready.

Content that exceeds the embedding window bypasses the fast comparison. The embedding representation also has a 2,000-character head/tail elision limit; content that would lose text at this boundary bypasses embedding too. A fast scan then cannot establish a benign verdict from that content. Complete can still assess the full selected text within its input limit. See limits.

If T2 times out, refuses, or returns unusable output, a complete prompt scan is inconclusive with verdict: unknown and confidence: null. Its earlier fast evidence remains in signals.knn; it is not a completed complete assessment. Your application should define a separate action for unknown, inconclusive, and unavailable scans.

Confidence

confidence describes support for the reported verdict. A benign result with confidence 0.90 expresses strong support for benign activity. It does not mean a 90% chance of a violation. These scores are heuristics, not calibrated probabilities, accuracy guarantees, or raw similarity scores. unknown has confidence: null, not zero.

Read confidence_basis with the number. The contract includes these three comparison outcomes, plus two cases where comparison cannot settle the result:

Each finding has its own confidence. The top-level score supports the overall verdict, not every category in findings. A low-confidence adverse finding can coexist with a benign verdict. Language, encoding, and obfuscation coverage should be evaluated on your own representative inputs; English examples do not establish coverage for every language.

Categories and the OWASP Agentic crosswalk

findings[] contains the categories and evidence locations. technique names the primary adverse finding for convenience. Despite that field name, the ATLAS values below are tactics, not technique IDs: taxonomy: mitre_atlas_tactic, scheme: mitre_atlas, kind: tactic. Evidence points to messages, pages, or chunk offsets without quoting your input.

The API's versioned catalogue contains the following labels. Its owasp_agentic values are a draft Zaun crosswalk, not an OWASP-endorsed equivalence. An empty list means there is no direct mapping; it does not mean the finding is harmless.

Risky covers concerning behavior that does not fit a named tactic, including project-policy concerns without an ATLAS equivalent. It is adverse, appears as technique: Risky with kind: risk, and has no OWASP mapping. Benign and Null are classifier labels for benign activity and insufficient evidence; neither is an adverse finding. Legitimate discussion of attacks is assessed in context, not treated as a violation simply because it contains an attack name.

Policy and recommendation

Your project's published policy can match the final verdict, selected categories, and a minimum confidence. For example:

{
  "rules": [
    {
      "when": {"verdict": "violation", "techniques": ["Exfiltration", "Credential Access"], "min_confidence": 0.85},
      "then": "block"
    },
    {"when": {"verdict": "violation", "min_confidence": 0.60}, "then": "alert"},
    {"when": {"verdict": "unknown"}, "then": "alert"}
  ]
}

Category rules compare each matching finding's confidence with the threshold, including equality, using the unrounded value. They do not substitute the overall verdict confidence for a category's score. block takes precedence over alert; no match yields recommendation: null. Unknown matches only a rule that explicitly names verdict: unknown.

Recommendations are advisory. block still returns HTTP 200 because the scan succeeded; your application enforces the decision. alert does not create a Zaun alert automatically. One configuration version applies to the whole scan and is recorded in config_version.

Coverage and stages

status describes whether the promised assessment finished: completed, inconclusive, or failed. Read it independently of verdict. In particular, a document can retain a violation finding while coverage is incomplete.

coverage.messages_assessed and messages_total show the assessed message count for prompts and chunk count for documents; chunks reports the chunk count. With target: last_user, earlier messages are outside the requested assessment. For documents, extraction_source: document_model, pages_extracted, and empty_pages are model-reported, not an independent verification that every page was read. extraction: truncated means extraction hit its output limit. Partial extraction or a failed chunk cannot justify a benign result.

stages records each stage's outcome: embed for text comparison preparation, knn for reference matching, t2 for the second-stage classifier, and document_model for document extraction and assessment. ok means it ran successfully; skipped means it did not run. bypassed_oversize explains an embedding bypass. Timeout, refusal, throttling, invalid output, and failure values identify the stage that prevented completion. See the API reference for every value.

Back to guide index

Limits and errors

Prompt scans (fast and complete), document scans, retained-result access, and usage queries are implemented in this checkout. Batch, proxy, and operator management routes are reserved and currently return 501. Their planned caps remain listed here so clients can distinguish the contract from availability.

Input and execution limits

These are service defaults. Your operator can publish stricter project limits. Byte and character caps reject oversized requests; an embedding-window bypass instead affects the scan's evidence and is reported in stages.

The accepted document format list follows Bedrock's document format contract. AWS describes its per-document limit as 4.5 MB; Zaun's exact byte cap is listed above. A provider can still reject an unreadable or unsupported document with document_unreadable.

Rate and admission budgets

All applicable budgets must admit a request. Extra keys do not increase project or organization allowance. These are defaults, not a promise that a deployment has higher capacity available.

Batch items count against their fast or complete class, with an additional batch-item budget defaulting to 50 items/s at each scope. Concurrency admission is separate from rate admission: 503 capacity means no execution slot; 429 rate_limited means an allowance is exhausted. Every retry, including idempotent replay, consumes admission allowance. Malformed requests can also consume admission allowance.

Ingress values are the specified production defaults; they are not provided by development Compose. Upstream WAF or nginx denials may not use the API's JSON error envelope. Clients sharing an outbound IP also share its ingress budget.

Successful API admissions and 429 responses include X-RateLimit-Remaining, the minimum remaining whole-token allowance across applicable budgets. Retry-After on 429 gives the wait in whole seconds, rounded up. API 503 responses also include it; capacity denials use 2 seconds. Wait at least that long before retrying with backoff. See key handling.

Error catalogue

API errors use this envelope. error.request_uuid is also returned as X-Request-Id; retain it when contacting support. A correlation ID does not promise a retrievable result if persistence failed.

{
  "error": {
    "code": "invalid_request",
    "message": "The request does not match the operation schema.",
    "request_uuid": "00000000-0000-4000-8000-000000000001"
  }
}

This table includes every public code from the binary's error catalogue. The internal model-throttling error shares public code capacity and status 503. A failed complete classifier can instead return HTTP 200 with status: inconclusive, verdict: unknown, and the cause in stages.t2. Always inspect the result body, not just HTTP status.

Results, usage, and retry boundaries

Use a unique Idempotency-Key for each new scan. The same key and body replay the original result within the same project and operation; a lost response is not permission to reuse the key for different content. Deletion leaves a retry-window tombstone so replay cannot recreate the deleted result. GET after deletion is 404; repeated own-project DELETE is 204. Cross-project read/delete is 404.

GET /v1/usage requires usage:read. group_by is day (default, UTC), model, or stage. A missing or foreign-project key_id filter returns 404. An interval with no usage returns an empty array and zero totals; a zero-length interval is invalid. Revoked and expired keys retain historical usage. Deleting a result does not erase usage. See data handling for retention boundaries.

Back to guide index

Keys

Use a project key over HTTPS:

Authorization: Bearer zaun_scan_<64 hexadecimal characters>

Your Zaun operator delivers the secret once. Store it in your application's secret store and load it at runtime. Keep it out of URLs, source control, logs, and browser code. Only a hash and key lifecycle metadata are stored by Zaun; the plaintext cannot be recovered. Keys can expire or be revoked.

Each key belongs to one project and organization. The request cannot change that scope. Same-project keys with the appropriate permissions can access retained results and historical usage created by earlier keys, including after rotation. Other projects' results and usage are not accessible.

Scopes

Ask for only the scopes your client needs. A read-only key cannot scan. Public health and documentation routes need no credential. Customer keys cannot administer organizations, projects, policy, or other keys.

Rotate a key

1. Ask your Zaun operator for a replacement with the required scopes and expiry.
2. Store the replacement and switch every client to it. Both keys work during this overlap, provided neither has expired or been revoked.
3. Verify a scan or permitted read with the replacement, then ask the operator to revoke the old key ID. A display prefix alone is not a unique ID.
4. Remove the old secret from client configuration. Existing project results and historical usage remain available to appropriately scoped replacements.

If a secret is exposed, ask for immediate revocation. Revocation and expiry reject subsequent authorization checks; work already admitted can finish. Restarting the service or losing the rate-limit store cannot reactivate a key. Creating replacements does not increase the project or organization rate budget.

Authentication and readiness errors

Disabled projects and organizations still allow otherwise active scoped keys to read and delete retained results until expiry. An unknown scan verdict is different from an authentication or readiness error; see concepts.

Rate limits and retries

X-RateLimit-Remaining reports the minimum remaining whole-token allowance across the applicable key, project, and organization budgets. It appears on successful admissions and rate-limit denials. HTTP 429 rate_limited includes Retry-After, rounded up to whole seconds. Wait at least that long, then retry with backoff. HTTP 503 also includes Retry-After; capacity denials use 2 seconds.

Send a unique Idempotency-Key for each new scan. Reuse it with the same body when retrying after a lost response. Every retry, including replay, consumes admission allowance. Do not rotate credentials or create extra keys to bypass tenant limits. See limits and errors for budgets and retry outcomes.

Operator boundary

Onboarding and key delivery are operator-managed; there is no customer self-service key UI. The management routes described in OpenAPI are reserved and return 501 operation_not_implemented in this checkout. Coordinate key changes with the operator instead of calling them from your application.

The management contract uses a separate admin credential for organization and project setup, policy publication, and key creation/listing/revocation. It does not authorize public scans. Key creation discloses a secret once with Cache-Control: no-store. A committed retry returns 409 key_already_created with metadata, never another secret. If the creation response was lost, the operator revokes the issued ID and creates a replacement under a new idempotency key. Configuration publication uses If-Match; a stale version returns 412. Key listings and audit records do not expose secrets or hashes.

Back to guide index

Data handling

Scan content is processed to produce an assessment. Raw prompt text and extracted document text are not retained by default (retain_input_days: 0) and never appear in returned results. This checkout rejects input-retention opt-in until its retention cleanup is available.

What is stored

Stored results include verdicts, findings with locations rather than quoted text, input hashes, caller-supplied metadata, session correlation IDs, observed client IP, configuration and revision identifiers, timestamps, and model usage. Results, usage, and idempotency records belong to the key's project. Metadata is caller-asserted, not proof of identity; it is never sent to the embedder or classifier. Keep secrets and raw input out of metadata because it is stored.

Customer key secrets are disclosed once; Zaun stores only their hashes and lifecycle metadata. Operational logs contain request IDs, status, counts, and timing, not raw input, document bytes, metadata, secrets, or key hashes.

Where content goes

Fast prompt scans send selected text to Zaun's private embedding service. Complete scans also send the full selected text and project context to Amazon Bedrock. Document bytes go to Bedrock in us-east-1 for extraction and assessment, even on fast scans. Extracted chunks then follow the scan path. Document bytes stay in memory rather than being written to local disk. Scans do not fetch remote URLs or add customer content to the curated reference set.

The production contract requires that submitted content is not retained by the provider. Bedrock does not give model providers access to prompts or outputs. AWS retention can depend on the selected model and account settings; the no-retention production configuration must be verified when those change. This checkout does not attest to live AWS settings. See AWS's data protection and data retention documentation.

The embedding representation has a 2,000-character head/tail elision limit. Messages that would be shortened are instead marked bypassed_oversize, as are messages over the embedding token window. Complete scans can still send the full selected text to Bedrock within the full-input cap. Elision therefore is not a privacy filter. Document page coverage is model-reported; truncation produces an inconclusive assessment rather than a claim of complete inspection.

Retention and deletion

Results expire after 30 days by default. Idempotency records outlive them by one day; an expired replay returns 410 instead of silently rescanning. Expiry prevents API access, but automated physical retention cleanup is not implemented in this checkout, so TTL is not a verified physical purge deadline.

DELETE /v1/result/{uuid} removes the result content, any retained input, and the replay link. A minimal tombstone remains during the retry window to prevent recreation by late work. Repeated deletion returns 204; reads after deletion return 404. Deletion cannot undo an already running provider request.

Usage accounting, key lifecycle records, and operator audit log entries survive result deletion. Backup copies survive until backup expiry; the specified production backup window is seven days. Usage and audit retention periods are not defined in this checkout. Ask your operator for the deployed retention policy when those periods matter to your application.

Back to guide index