Parse, extract, index and answer from one API

Methods

Upload parametersPOST /api/v1/documents

Engine versionsGET /api/v1/parse-engines

standard-ultra-2 lets you pin the engine a document is parsed with, so a run next month uses the same engine as a run today. Send engine_version with the upload (POST /api/v1/documents or /documents/images). The version does not change the price.

• Omit engine_version and the default version is used: 2.0 today.
• The version a document is parsed with is pinned on it when it is uploaded and shown as engine_version on the upload response, on GET /api/v1/documents/{id} and in the list. A parse that is re-queued or resumed keeps it. engine_version is null for other methods and for documents uploaded before engine versions existed.
• A pinned version keeps giving the same engine until its deprecation, which we announce in advance. The default only moves to a newer version with advance notice.
• 2.5 is in beta: it may change before it becomes stable.
• 422 engine_version_not_supported: an engine_version with a method that has none. 422 invalid_engine_version: an unknown version; details.allowed lists the accepted ones. Both are returned before any credits are held.

GET /api/v1/parse-engines lists every method with its versions, their status and which one is the default (an empty versions list for a method without versions).

curl https://api.infratex.io/api/v1/documents \
  -H "Authorization: Bearer $INFRATEX_API_KEY" \
  -F file=@report.pdf -F method=standard-ultra-2 -F engine_version=2.5

Word documentsPOST /api/v1/documents

A Word .docx is accepted natively on the same endpoint as a PDF (and in Studio and the MCP create_document tools). It is parsed from the file itself, with no model call, so what Word already knows is kept exactly:

A .docx is billed per page at the standard price, 1 credit a page, whatever method you send; the document reports standard as its method. The billed page_count is the number of marked pages, but at least one page per 6,000 characters of text; a file with a single marked page is billed its saved Word page count, but at least one page per 3,000 characters. So for a .docx, page_count can be higher than the number of <!-- page:N --> markers. A .docx that counts more than 20,000 pages returns 400 invalid_document. Legacy .doc files are not supported yet and return 415 unsupported_media_type (save as .docx or PDF), as do macro-enabled .docm files; a damaged .docx returns 400 invalid_document.

Because nothing is sent to a model, a .docx is the one upload an EU-only account can parse: it is read on our own servers in the EU. The file's content decides, not its name, so a PDF renamed .docx is refused like any PDF. See Data processing location.

Parse optionsinfratex-gamma

Pass these in the options field of an upload as one JSON object, for example -F 'options={"merge_tables": false, "ignore_labels": ["header", "footer"]}'. Studio shows them when Infratex Gamma is selected.

LayoutGET /api/v1/documents/{id}/layout

Documents parsed with infratex-gamma also record where each region sits on the page. Each page gives the width and height of the page image the boxes were measured on, and each region gives a label, a bbox of [x1, y1, x2, y2] in pixels of that image, and the region's recognised content. Divide by width and height to place a box on your own rendering of the page. Labels are title, heading, text, table, chart, figure, formula, caption, footnote, reference, header, footer, page_number and other. Other methods return 404 layout_not_available; a document that is still parsing returns 409.

Markdown parametersGET /api/v1/documents/{id}/markdown

Output conventions

Every method returns Markdown with a few machine-readable markers, so you can split by page, find figures, and see what could not be read. Nothing is dropped silently.

<!-- page:12 -->
## 3.2 Capital ratios

<figure type="chart">
<caption>Figure 3 – CET1 ratio by scenario</caption>
<description>Bar chart of the CET1 ratio (%) under the baseline and adverse scenarios, 2027–2029.</description>
<otsl data-source="chart"><ched>Year<ched>Baseline<ched>Adverse<nl>
<rhed>2027<fcel>15.3<fcel>15.1<nl>
<rhed>2029<fcel>15.6<fcel>11.8<nl></otsl>
</figure>

[table not transcribed]

<!-- page:13 status=failed -->
<!-- page:14 -->
…

ProgressGET /api/v1/documents/{id}

While a document is pending or processing, it carries a progress object, on GET /api/v1/documents/{id} and on each document in the list. It is null once the document is parsed or error, and can be null for a moment while processing starts: keep polling.

{
  "id": "2b1f6f0e-3c8e-4d64-9a7c-6d5f0f0d8a11",
  "status": "processing",
  "page_count": 808,
  "error_message": null,
  "progress": {
    "stage": "parsing",
    "pages_done": 412,
    "pages_total": 808,
    "attempt": 1,
    "max_attempts": 3,
    "updated_at": "2026-11-10T09:41:07.512Z"
  }
}

To avoid polling, register a webhook for document.parsed and document.failed.

When processing stalls

If the server running its parse stops (a crash, a restart), the document goes back to the queue on its own: right away for a planned restart, within about six minutes otherwise. The next run picks up the pages already finished, so they are not parsed again (PDFs with standard, max, infratex-phi and standard-ultra-2; infratex-gamma and image batches start again from the first page). attempt shows each such restart, and after max_attempts the document fails with an error_message that says it was interrupted.

Each parse also has a time limit that grows with the page count, up to two hours. When it runs out, the pages already finished are delivered and the rest are marked <!-- page:N status=failed -->; if no page finished, the document fails.

A document is billed once, when it is parsed, for the pages that were parsed. A re-queued or resumed parse is not charged twice, failed pages are not charged, and a document that ends in error is not charged at all: its reserved credits are released and its error_message says what went wrong.

List parametersGET /api/v1/documents

Field types

Every field needs name (1–64, ^[a-zA-Z_][a-zA-Z0-9_]*$) and a description (required). Optional instructions and required refine behaviour. Nest with object.properties and array.items; an array<object> field is what CSV/XLSX export reads. Up to 100 top-level fields per run.

Values come back typed, not as printed: date is normalised to ISO 8601 (YYYY-MM-DD, so 17/04/2025 returns 2025-04-17), and number / integer return JSON numbers (1.354,00 returns 1354). Use string to keep a value exactly as it is printed.

Exhaustive completeness

completeness: "exhaustive" changes how array fields are read; other fields are unaffected.

• A document up to ~30k tokens is read whole, once per array field, so the model sees a summary page and its detail pages together. If that pass fails or the check below finds it skipped many items, the field is read again in slices as for a larger document.
• A larger document is read in ~8k-token slices and every slice is read. An object item that appears in more than one slice (no value disagrees and at least two agree, with numbers compared by value) becomes one item: missing values are filled from the other mention and nested lists are combined. Repeats inside one passage are kept, as are plain-text list items.
• Then one more pass per array field looks for items missing from the list. An item it returns again is merged into the one already found.

Each array field re-reads the document (twice, with the check), so exhaustive runs take longer and bill more input tokens, at the direct rate.

v2 (beta)

Set pipeline: "v2" on a run to use the new extraction engine. The default, legacy, is the current engine; nothing changes unless you ask for v2. The beta is opened per account, on request: ask your Infratex contact to open it for yours. GET /api/v1/extraction-pipelines says whether your account can choose v2 right now (available).

A run is never moved to another engine than the one you asked for. Asking for v2 before the beta is open for your account answers 422 pipeline_not_available; any pipeline other than legacy or v2 answers 422 invalid_pipeline. pipeline goes in the request body (inside extraction when you upload a file): sent as a query parameter, it also answers invalid_pipeline. Nothing is created or billed when a run is refused, and legacy is always accepted.

How v2 reads a document:

• The parsed document is mapped first: every paragraph, table and table cell gets a stable address, such as p4.t2.r6c3 (page 4, table 2, row 6, column 3).
• For each top-level string, number, integer or date field, the model returns the address it read the value from as well as the value. Rows of an array field carry no address in this beta.
• Fixed rules, with no model involved, then check those values against the whole document. A value comes back as null when it is printed nowhere in the document (allowing for thousands, millions, billions and percentages), when it is a template placeholder, a blank or a form label instead of the value, when it is a zero that is not printed where it was cited, or when it is printed only in a table of contents or in running page headers or footers. A number or integer read from a table also comes back as null when a higher-ranked table prints a different figure for the same line item and period: the financial statements rank above summaries, highlights and key-figures tables, which rank above other tables, and a table whose column headers do not line up with its values (a year printed over the row labels, or a percent-change column that prints amounts) ranks below all of them, its columns not taken to match the field's period. The other table can be anywhere in the document, not only in the part that was read for the field. A table labelled adjusted or pro forma, a table in another currency, or a column for another period (such as a full year for a quarterly field) does not count, and a value whose own row and column match the field can be overruled only by the financial statements. This does not apply when the field asks for such a figure: its name contains adjusted, non_gaap, pro_forma or underlying (such as adjusted_eps, but not net_income_non_adjusted), or its description or instructions name a summary as the source after the line item in the field's name or after a verb ("Net income for 2024 from the five-year summary" for net_income_2024, "Take it from the financial highlights") or ask for the adjusted figure of the field's own line item ("Adjusted EBITDA", "on an adjusted basis"). Text that describes, warns about or excludes summaries or adjusted figures, such as "figures in the summary may be adjusted", "beware of adjusted figures" or "adjusted figures must not be used", is not read as such a request, and neither is a request in text that also excludes them or points to the financial statements: the check then applies. The check matches wording, not meaning: a description that names the field's own line item next to a summary can still be read as a request, so state the source you want plainly. With include_evidence, its evidence carries the reason.
• A value that is printed in the document, but not at the address it was cited from, is kept, and its evidence points to where it is printed. Other findings, such as a competing figure in a table of the same or a lower rank, are recorded internally and do not change the value. v2 never replaces a value with another figure.
• enum, boolean, object and array fields are not checked by these rules in this beta.
• The models, the verification step, the result shape and the pricing are the same as the current engine's.

Because of these rules, a field can come back null where the current engine returned a value. When the same line item is printed with different figures in a multi-year summary and in the income statement, for example, v2 refuses the summary's figure and returns null; it does not switch to the statement's. Known limitations of this beta: v2 does not choose between tables of the same rank that print different figures, such as two financial statements (consolidated and standalone, or a pro forma statement beside the reported one) or two summaries, and keeps the figure it read; a table labelled adjusted or pro forma never overrules another figure, so a figure that only such a table contradicts is kept; and when the parsed document lost the title that marks a table as a financial statement, v2 can still take the figure from the wrong table (a balance sheet is still recognised by its total assets and total liabilities and equity rows). Compare v2 with the current engine on your own documents before you rely on it.

Every run reports the engine that ran in pipeline once it finishes. If v2 cannot run on a document (for example, parsed Markdown above 8 MB), the run uses the current engine, reports pipeline: "legacy" and is billed as a run of the current engine. If the current engine's result for the same document, template and model is already cached, the run reuses it at no charge, as a legacy request would. A later v2 request on a document v2 cannot run on can therefore reuse that result instead of being billed again. In Studio, choose v2 (beta) under Extract → Options; Studio takes PDFs up to 4 MB, so send larger files through the API.

Run parametersPOST /api/v1/documents/{id}/extractions

A run reports status, tier, pipeline (the engine that ran; null until it finishes), input_tokens, output_tokens and credits_charged (null until it finishes; 0 when it failed or was cached), plus the engine_version that computed it. Running the same fields, prompt, model, completeness and pipeline on the same document again returns the earlier result at no charge, with cached: true (except a v2 request on a document v2 could not run on: see v2 (beta)).

Parse and extract in one callPOST /api/v1/extractions

Send the file as multipart/form-data with the run as a JSON string in extraction. The document is parsed and the run starts as soon as the parse ends, so there is one request instead of upload, poll, extract, poll. The parse and the extraction are billed as usual; if the balance can't cover both, the call answers 402 and nothing is created.

Self-hosted extraction (infratex-phi)

With model: "infratex-phi", every step of the run (reading the document, verifying each value against its source, the exhaustive passes) runs on Infratex Phi, our own model. No third-party model provider sees the document during extraction. Parse it with infratex-phi to keep the whole pipeline on our own model; POST /api/v1/extractions parses with it by default, and parses tables as HTML, which the model reads directly. These are the engines for on-premises deployments.

• The document is always read directly, never through an index: up to about 36k tokens of Markdown (roughly 50–90 pages) in one pass, larger documents in slices of about 24k tokens, every slice read.
• The fields, their descriptions and the system prompt share the model's window with the document, so together they may take about 12,000 tokens (roughly 80 typical fields). A larger template is refused with 422 instructions_too_long.
• Verification reasons before it answers, which adds about 10–20 s to a run.
• If the model is unavailable, runs are refused with 503 model_unavailablebefore anything is reserved.

Pricing

Extraction is billed on the tokens the run reads and writes, across every model call it makes: reading the document, checking each field against its source and, in exhaustive mode, the extra passes. Output includes the model's reasoning on pro. One rate per model, however the document is read: directly in one pass (up to ~30k tokens of Markdown), chunk by chunk with every chunk read (up to ~165k tokens indexed or not, and larger documents with no index), or through a ready vector or hybrid index above ~165k tokens. Credits per 1M tokens (1 credit = €0.005):

Example: a pro run on a 12-page document that reads 50,000 input tokens and writes 15,000 output tokens costs 50,000 × 1,250 / 1M + 15,000 × 7,500 / 1M = 62.5 + 112.5 = 175 credits (€0.88). The same reading on fast, with 3,000 output tokens, costs 18.75 + 6.75 = 25.5 credits. Every run returns its credits_charged.

infratex-phi always reads directly; its reasoning is included in the output tokens.

ParametersPOST /api/v1/documents/{id}/indexes

ParametersPOST /api/v1/searches

ParametersPOST /api/v1/responses

Stream events

Events

{
  "id": "evt_5f0c3e8a9b7d4c2e8f1a6b3d9e0c7a24",
  "type": "document.parsed",
  "created_at": "2026-10-22T14:03:11.204Z",
  "data": {
    "object": "document",
    "id": "2b1f6f0e-3c8e-4d64-9a7c-6d5f0f0d8a11",
    "status": "parsed",
    "filename": "contract.pdf",
    "method": "standard",
    "page_count": 12,
    "collection_id": null,
    "error_message": null
  }
}

data holds the ids and the status; fetch the full document, index or run with its GET. Index events carry document_id, method and chunk_count; extraction events document_id, model and tier.

Verifying signatures

Compute the HMAC over the raw body exactly as received, before any JSON parsing, compare in constant time and reject timestamps more than five minutes old.

import hashlib, hmac, time

def verify(secret: str, body: bytes, header: str, tolerance: int = 300) -> bool:
    fields = dict(part.split("=", 1) for part in header.split(","))
    timestamp = int(fields["t"])
    if abs(time.time() - timestamp) > tolerance:
        return False  # too old: a replay
    expected = hmac.new(secret.encode(), f"{timestamp}.".encode() + body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, fields["v1"])

# Flask: verify(SECRET, request.get_data(), request.headers["Infratex-Signature"])

Delivery and retries

Answer with any 2xx within 10 seconds; do the work afterwards. Anything else, a redirect, a timeout or a refused connection is retried after 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours and 12 hours, then marked failed. Delivery is at least once and not ordered: deduplicate on the event id, and read the current state with a GET when order matters.

Tools that read

Tools that create

Error codes

Every error has the same body: an error object with a machine-readable code, a message and the request_id to quote when you contact us, plus details when there is more to say (for a validation error, the fields that failed).

{
  "error": {
    "code": "document_not_ready",
    "message": "Document status is 'processing', must be 'parsed' or 'indexed'",
    "request_id": "6f1c0e5b2a8d4c51b0e7a9d3c4f2e1a0"
  }
}

Retries and idempotencyIdempotency-Key

A request that times out may still have been accepted. To retry a create safely, send an Idempotency-Key header (any unique string up to 255 characters, a UUID is usual) and reuse it on every retry of that request. Within 24 hours, a retry with the same key and the same request returns the first response, marked Idempotent-Replayed: true, and nothing is created or charged twice. It is accepted on:

• POST /api/v1/documents
• POST /api/v1/documents/images
• POST /api/v1/documents/{id}/indexes
• POST /api/v1/documents/{id}/extractions
• POST /api/v1/extractions

Keys belong to your account. While the first request is still running, a retry gets 409 idempotency_request_in_progress with Retry-After. The same key on a different request (another file, other fields) gets 422 idempotency_key_reused. Only successful responses are kept: when a request fails, its key is released, so you can fix the cause and retry with the same key.

curl https://api.infratex.io/api/v1/documents \
  -H "Authorization: Bearer $INFRATEX_API_KEY" \
  -H "Idempotency-Key: 6f1c2a52-7d0e-4c55-9a3e-2f0d1b8c4e77" \
  -F file=@contract.pdf -F method=standard

Data processing locationPATCH /api/v1/account/settings

Each account chooses where its requests may be processed with data_residency. Read it with GET /api/v1/account/settings and change it with PATCH /api/v1/account/settings, from an API key or from the dashboard (Settings, Data processing location). Any other value than the two below is a 422 validation_error. An API key may change only data_residency; the billing settings stay dashboard-only (403). An API key may switch the account to eu_only (or send eu_only again), but switching an EU-only account back to default is dashboard-only: an API key gets 403 dashboard_only, so a leaked key cannot lift the restriction.

curl -X PATCH https://api.infratex.io/api/v1/account/settings \
  -H "Authorization: Bearer $INFRATEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"data_residency": "eu_only"}'

A change applies from the next request. Background work reads the setting when it starts: work already running finishes, and queued work that has not started and needs processing outside the EU fails, with its credits released.

Credits1 credit = €0.005

Endpoint map