SeguraDoc processes an untrusted PDF inside an isolated sandbox and returns:

• A safe reconstructed PDF rebuilt from page snapshots — no active PDF behavior (JavaScript, embedded files, launch actions, forms) survives the round-trip.
• OCR text, per page, for image-based PDFs (Mistral ministral-14b vision model).
• An AI-generated summary of the document content (Mistral mistral-small).
• A structured parse of the original file — headings, tables, links, form fields, annotations, embedded objects — with a list of security signals found along the way.

Sandbox sanitization, OCR, AI summary, and the structured parse are all included in the per-page price — no separate AI metering, no token counting on your end. See AI features and Structured parse for the details.

The value is deterministic transformation, not probabilistic detection. SeguraDoc does not promise to identify malware — it removes the active-content surface that malware lives in.

Base URL

https://api.seguradoc.com

Content type

All request bodies and responses are application/json, except file uploads which use multipart/form-data and downloads which return application/pdf.

Every request to /v1/ (except /v1/health and the /v1/x402/* family) requires a bearer token in the Authorization header:

Authorization: Bearer sk_live_…

Issuing a key

Log into the API Keys page in your dashboard and click New API key. The raw value (starting with sk_live_ for production or sk_test_ for test) is shown exactly once. Store it in your secret manager — we only persist its SHA-256 hash.

Revoking a key

Click Revoke on a key in the dashboard. Subsequent requests using that key return 401 Unauthorized within seconds. Rotation = revoke + create new.

Auth scope

Each key is scoped to one organization. All charges, document jobs, and ledger entries created with that key belong to its org. There are no read-only or limited-scope key tiers in v1.

End-to-end: check balance → upload a PDF → poll for completion → download the safe PDF.

export KEY="sk_live_…"

# 1. Verify the key works
curl -s -H "Authorization: Bearer $KEY" \
     https://api.seguradoc.com/v1/balance

# 2. Upload a PDF
JOB=$(curl -s -X POST \
  -H "Authorization: Bearer $KEY" \
  -F '[email protected]' \
  https://api.seguradoc.com/v1/documents)
ID=$(echo "$JOB" | jq -r .id)

# 3. Poll status (also: subscribe to a webhook — see Webhooks below)
while true; do
  STATUS=$(curl -s -H "Authorization: Bearer $KEY" \
                https://api.seguradoc.com/v1/documents/$ID | jq -r .status)
  echo "Status: $STATUS"
  [ "$STATUS" = "completed" ] && break
  [ "$STATUS" = "failed" ] && exit 1
  sleep 2
done

# 4. Download the safe PDF
curl -s -H "Authorization: Bearer $KEY" \
     -o sanitized.pdf \
     https://api.seguradoc.com/v1/documents/$ID/safe-pdf

PDF processing is a per-page rate + per-document fee, both billed in USD. Includes sandboxed sanitization, OCR (when needed), an AI summary, and the structured parse — no separate metering.

Examples:

• 1-page PDF: $0.03
• 10-page PDF: $0.12
• 100-page PDF: $1.02

Reservation flow

On every upload, we count pages with PyMuPDF, compute the estimated cost, and atomically reserve that amount from your organization balance. If the balance is insufficient, you get 402 insufficient_balance immediately — the job is never created.

After processing completes, the actual cost is computed from the sandbox-reported page count. If it differs from the reservation, we write an adjustment entry:

• Overage refunded: actual < reserved → the difference is returned to your balance (reservation_release ledger entry).
• Additional charge: actual > reserved → balance debited the difference (adjustment ledger entry).
• Job fails: full refund (reservation_release with full_release).

Document generation

The document generator is priced separately and flatly: $0.20 per create and $0.20 per revision, whatever the format and however long the document. It is not part of the per-page rate. It draws on the same organization balance this page documents, and every run shows up on /v1/usage.

A run is priced, held, then settled. Because the rate is flat, settling a successful run moves no money and writes no second row — so a completed generation is a single reservation debit carrying resource.type: "generator_run". A failed one is followed by a reservation_release credit for the whole amount.

The generator has no /v1/ surface yet — it is dashboard-only, so an agent holding a bearer token cannot invoke it. Its charges are still visible over the API.

Topping up

Add USD balance from the Usage & Balance page. Packs: $5, $10, $25, $50, $100. Payable by credit card (Stripe) or cryptocurrency (BlockBee). What you pay is what you get.

Errors return a JSON body with a stable error.code and a human-readable error.message. Code your retries against error.code, not the message.

{
  "error": {
    "code": "insufficient_balance",
    "message": "Your account does not have enough processing balance for this document.",
    "required_micro_usd": 120000,
    "available_micro_usd": 50000
  }
}

The one exception: 401

A bad or revoked bearer token is rejected before a view runs, so it does not carry an error.code. The body is the framework's own shape:

{"detail": "Invalid or revoked API key."}

Branch on the 401 status for this one rather than on a code. Everything else on /v1/ uses the envelope above. The generator uses a third envelope of its own — see its error codes.

The bearer-authenticated /v1/ endpoints are not rate-limited in v1. Heavy users should reach out so we can add per-key throttles cooperatively rather than reactively.

The unauthenticated x402 family is limited, per client IP:

• GET /v1/x402/bands — 60 / min
• POST /v1/x402/quote — 10 / min
• POST /v1/x402/documents — 10 / min

The generator quote, create and revise routes are limited to 6 / min. Those are session-authenticated, so the count is per account, not per address — an office behind one NAT address does not share a budget.

Exceeded: 429 rate_limited with retry_after_seconds in the body. If our cache is unreachable the limiter fails open rather than blocking traffic.

Every completed document carries two AI-generated outputs alongside the safe PDF. Both run on Mistralmodels hosted on Mistral's European infrastructure (EU data residency for the AI portion of the pipeline).

Pricing

Both AI calls are included in the $0.01/page + $0.02/document rate — see Pricing & balance. You do not see Mistral token counts and we do not pass through Mistral's rate limits to you.

Data handling

Page snapshots and extracted text are sent to Mistral's API during OCR and summarization. Original PDFs never leave your organization's isolated sandbox. Mistral does not retain prompts for training on their EU endpoints (their published policy at time of writing — verify if this matters to you).

When AI runs vs. doesn't

• OCR fires only when extracted text is < 50 characters (essentially: image-only PDFs). Text-native PDFs skip OCR entirely.
• Summary fires whenever the document has any extractable text. Empty / corrupt PDFs get summary: null in the response — no error, just nothing to summarize.
• Failed AI calls don't fail the whole job. The safe PDF still ships; the missing AI field is left null.

Scanned documents, photos saved as PDFs, and other image-only files get OCR'd page-by-page through Mistral's vision model. The output is plain text — formatting like headings and tables is preserved best-effort but not guaranteed structured.

Fetch the OCR result via GET /v1/documents/{id}/ocr. Each page comes back as a {page: N, text: "…"} object so you can match content back to page positions.

OCR uses image input on Mistral's API. Pages are rendered to PNG in our sandbox before transmission — Mistral never sees the original PDF bytes.

Every completed job that has any extractable text (whether native or via OCR) gets a Mistral-generated summary. Output is short HTML — typically a one-sentence overview followed by a 3–5 bullet list. We sanitize the output to remove code fences, markdown wrappers, and any stray tags.

Three places to read it:

• Inline — the summary field in the GET /v1/documents/{id} response.
• Dedicated endpoint — GET /v1/documents/{id}/summary if you only need the summary text and not the rest of the document metadata.
• x402 path — GET /v1/x402/documents/{id}/summary?token=… for x402-paid jobs.

Shape of the summary value:

{
  "html": "<p>Invoice from Acme Corp dated 2026-05-11.</p><ul><li><strong>Total: $1,240.00</strong></li><li>Net 30 terms</li><li>Three line items</li></ul>",
  "generated_at": "2026-05-11T12:00:07Z",
  "model": "mistral-small-latest"
}

Rendering safely

The html field is HTML from Mistral's output, already passed through our sanitizer. It contains only <p>, <ul>, <li>, and <strong>tags. We treat it as untrusted on our side — you should too. Render with your framework's safe-HTML primitive or strip tags if you want plain text:

// React (safe — DOMPurify is overkill here but recommended)
import DOMPurify from 'isomorphic-dompurify';
<div dangerouslySetInnerHTML={{ __html: DOMPurify.sanitize(doc.summary.html) }} />

// Strip to plain text
const text = doc.summary.html.replace(/<[^>]+>/g, '').replace(/\s+/g, ' ').trim();

Limitations

• Truncated to ~12k tokens of input. Documents longer than that get summaries based on the first portion only.
• No structured output schema in v1 — if you need fields like amount, vendor, due_date, extract them yourself from the OCR text. A structured-extraction endpoint is on the roadmap.
• English-optimized prompt. Non-English documents are summarized but the summary may revert to English even when the source isn't.

Alongside the safe PDF, every completed document carries a structured parse: what the file says, how it is laid out, and what it tries to do when opened. Read it at GET /v1/documents/{id}/parse. It is included in the per-page price.

The parse runs against the file you uploaded, not the safe rebuild. That is deliberate: sanitization strips the links, actions and embedded objects, so parsing the output would report a clean document every time and tell you nothing about what arrived.

Document level

• document — page count, pages actually parsed, PDF version, producer and creator strings, and the is_encrypted / is_linearized / has_acroform / has_xfa flags. Files that declare their own page labels also get a page_labels array.
• outline — the bookmark tree flattened, each entry with level (1–6), title, target page, a dest_kind of internal / uri / launch / other, and the uri when there is one.
• form_fields — name, resolved type, required and readonly, whether a value is present and how long it is (never the value itself), the action_kind and action_target attached to the field, and its box.
• annotations — everything that is not a form widget: subtype, whether an action hangs off it, the action kind, the URI for link annotations, the box, the length of the note text, and the raw flag bits.
• embedded_objects — attachment names, declared sizes and MIME types (never their bytes), plus counts of document-level JavaScript entries, embedded fonts, form XObjects and streams that point at an external file, and the kind of the document's open action.
• stats — how long the parse took, how big the payload is, and how many elements it describes.

Page level

Each page in pages.items carries its size and rotation, the extracted text with a text_truncated flag and a true char_count, and six arrays: blocks (text and image regions with boxes and line counts), headings (lines that stand out from the page's own body size, with an inferred level), tables (box, row and column counts, header row, and a preview of the first rows), links (kind, URI, box, and the anchor text sitting under the box), images (box, pixel size, colorspace, bit depth, soft mask), and fonts. A flags object then reports the five hidden-text findings for that page.

Which operations produce it

operation=full — the default — produces the document-level blocks and the per-page structures. operation=parse produces the document-level blocks only: a standalone parse job renders no pages, so pages.items comes back empty. If you want both halves, upload with full.

A parse that fails never fails the job. You still get the safe PDF and the snapshots you paid for; the parse route answers 404 no_parse instead.

Limits and truncation

The parse is bounded so that a hostile file cannot bill you for an afternoon of CPU. It stops at 300 pages, a 150-second budget, or a payload of about 8 MB, whichever comes first. When it stops early, truncated is true and truncation_reason is one of page_cap, time_budget or size_budget.

Within a page, the arrays are capped too — 200 blocks, 50 headings, 8 tables, 100 links, 50 images, 30 font names, 20 000 characters of text — and document-wide at 500 form fields, 1 000 annotations, 500 outline entries and 100 embedded files. Counts reported outside those arrays are the true totals, not the truncated ones.

The parse reports what it noticed as a list of coded signals. The set is closed — a detector cannot invent a code or pick its own severity:

Shape of a signal

{
  "code": "url.link_text_mismatch",
  "severity": "medium",
  "count": 2,
  "pages": [1, 4],
  "sample": "\"acme.com\" links to payments-acme.example"
}

count is how many times the signal fired across the document. pages lists up to 20 pages it fired on and is empty for document-level findings. sample is one short illustrative string. At most 50 signals are listed, highest severity first — but counts is computed from everything found, so the totals stay true even when the list is cut.

How the score is built

Each distinct code scores once, however many times it fired: high 30, medium 15, low 5, info 0. The total is capped at 100. risk.level is then read off the score:

• clean — score 0
• low — 1 to 14
• medium — 15 to 44
• high — 45 and above

counts groups the same findings by family — active_content, hidden_text, link_anomaly, form_anomaly, structure_anomaly — so you can route on a category without unpacking the signal list.

Note what the scoring implies: a document with one JavaScript action and a document with four hundred both score 30 for it. The count is in the signal; the score answers "how many kinds of thing are wrong here", not "how much".

Instead of polling /v1/documents/{id}, you can register a URL that we will POST to whenever one of your jobs reaches a terminal state.

Configure webhooks from the Webhooks page in your dashboard. Each webhook gets a signing secret (shown once on creation, format whsec_…) used to verify that incoming deliveries actually came from us.

Events:

• document.completed — job finished successfully
• document.failed — job errored

Subscribe to a subset of events by listing them in the webhook config, or subscribe to all by leaving that field empty.

Every delivery is a JSON POST with three custom headers:

POST <your-url> HTTP/1.1
Content-Type: application/json
User-Agent: SeguraDoc-Webhook/1.0
SeguraDoc-Event: document.completed
SeguraDoc-Delivery: 1f93e8c6-2b4a-4f3a-b1e8-9f3c0d8b7a5e   # dedupe key
SeguraDoc-Signature: t=1715432100,v1=abc123…

{
  "event": "document.completed",
  "delivery_id": "1f93e8c6-2b4a-4f3a-b1e8-9f3c0d8b7a5e",
  "document": {
    "id": "550e8400-…",
    "status": "completed",
    "page_count": 12,
    "safe_pdf_url": "https://api.seguradoc.com/v1/documents/550e…/safe-pdf",
    "ocr_text_url": "https://api.seguradoc.com/v1/documents/550e…/ocr"
  }
}

For document.failed, the document object carries error (≤500 chars) instead of the output URLs.

Acceptance contract

Your endpoint must respond with any 2xx status within 10 seconds. The response body is logged for debugging but otherwise ignored. Anything else triggers a retry.

Idempotency

Retries reuse the same SeguraDoc-DeliveryUUID. Dedupe against it so a re-sent delivery doesn't double-process the same logical event.

Signatures are HMAC-SHA256(secret, "{t}.{raw_body}"), formatted as t=<unix-seconds>,v1=<hex-digest>. Reject signatures with a timestamp older than 5 minutes — that prevents replay attacks.

Node.js

import crypto from 'node:crypto';

export function verifySeguraDocSignature(req, secret) {
  const header = req.header('SeguraDoc-Signature');
  if (!header) return false;
  const parts = Object.fromEntries(header.split(',').map(p => p.split('=')));
  const t = parseInt(parts.t, 10);
  if (Math.abs(Date.now() / 1000 - t) > 300) return false;
  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${t}.${req.rawBody}`)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(parts.v1),
  );
}

Python

import hmac, hashlib, time

def verify_seguradoc_signature(header: str, raw_body: bytes, secret: str) -> bool:
    try:
        parts = dict(p.split('=', 1) for p in header.split(','))
        t = int(parts['t'])
        sig = parts['v1']
    except (KeyError, ValueError):
        return False
    if abs(int(time.time()) - t) > 300:
        return False
    expected = hmac.new(
        secret.encode(),
        f"{t}.".encode() + raw_body,
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(expected, sig)

Go

func verifySeguraDocSignature(header string, rawBody []byte, secret string) bool {
    var t int64
    var v1 string
    for _, p := range strings.Split(header, ",") {
        kv := strings.SplitN(p, "=", 2)
        if len(kv) != 2 { continue }
        switch kv[0] {
        case "t":  fmt.Sscanf(kv[1], "%d", &t)
        case "v1": v1 = kv[1]
        }
    }
    if math.Abs(float64(time.Now().Unix()-t)) > 300 { return false }
    h := hmac.New(sha256.New, []byte(secret))
    fmt.Fprintf(h, "%d.", t)
    h.Write(rawBody)
    return hmac.Equal(h.Sum(nil), []byte(v1))
}

A non-2xx response (or no response within 10s) schedules a retry:

• 1st retry: 6 minutes after the failure
• 2nd retry: 12 minutes after the 1st retry
• 3rd retry: 24 minutes after the 2nd retry

After 4 failed attempts total, the delivery is marked terminal. After 5 consecutive failed deliveries, the webhook is auto-disabled and won't fire for new events until you re-enable it from the dashboard.

Terminal deliveries can be replayed manually from the deliveries modal in the dashboard. Replays carry the same SeguraDoc-Delivery UUID as the original — so your dedupe logic still applies.

x402 lets AI agents pay for a single PDF sanitization request without creating an account or pre-loading a balance. It implements the Coinbase x402 protocol — HTTP 402 responses with on-chain USDC settlement on Base mainnet.

The flow:

1. Agent calls POST /v1/x402/documents with no X-Payment header.
2. Server returns 402 Payment Required with an accepts array describing each price band.
3. Agent picks a band, signs an EIP-3009 transfer authorization for the band's exact USDC amount, base64-encodes the payment payload.
4. Agent retries the same POST with X-Payment: <base64> and the file body.
5. Server verifies the authorization, counts pages, settles the payment on-chain, queues the job, returns 202 with an access_token.
6. Agent polls GET /v1/x402/documents/{id}?token=… for completion.

The generator writes a document from a prompt and renders it. Ask for one, and you get back a template — the document — and a run, one attempt at producing it. Revising a template starts another run against the same template and bumps its revision.

Work is asynchronous. Create and revise answer 202: the row exists and the money is held, but the file does not exist yet. Poll the run.

Response envelope

Every generator route answers with its own envelope, not the /v1/ one:

// success
{"status": "success", "data": { … }}

// failure
{
  "status": "error",
  "error": {"code": "insufficient_balance", "message": "…"},
  "error_message": "…"
}

error_message is a plain-string copy of error.message, kept for one release so an older client build does not render an object. Read error.code. Machine-readable detail — required_micro_usd, active_run_id — rides inside error alongside the code.

Money shape

Generator money is a superset of the /v1/ shape, carrying the integer you should compute against as well as the string you should display:

{"micro_usd": 200000, "display": "0.20", "currency": "USD"}

Rules worth knowing up front

• One active run per template. The database enforces it, not a read-then-write check, so a second request loses cleanly with 409 generation_in_progress and the id of the run that holds the template.
• Price is flat: $0.20 to create, $0.20 to revise, whatever the format. Held before the work is queued, charged on success, refunded in full on failure.
• A stuck run refunds itself. A run that is still not finished after 20 minutes is failed and refunded by a sweeper, so a broker outage does not strand your money.
• Formats: docx and odt. ods is declared and rendered but switched off — ask for it and you get 400 unsupported_format. Do not hard-code the list; read capabilities.
• Ownership is invisible. Somebody else's template is a 404, never a 403.

The generator's codes are a closed set. Branch on them; treat anything outside the set as a generic failure rather than crashing.

A run that fails after it was accepted produces no HTTP error — the request already returned 202. Poll the run instead: its status goes to failed, error.code reads generation_failed, and error.message says which of the four failures it was. Every one of them refunds the hold in full.