Skip to content

API changelog

Changes to the public contract (openapi/openapi.json). The api-contract CI job requires an entry here whenever the snapshot changes. /v1 only changes additively; deprecations announce a sunset at least 180 days ahead.

2026-11-17 — confidence column in the workflow list (T60), additive

  • GET /v1/workflows (and GET /v1/workflows/{id}): stats gains confidence_30d, the mean confidence of the last 30 days (null without scores; approximate, computed from the bin centres of the T40 histogram). stats.accuracy_30d is unchanged.
  • GET /v1/workflows/{id}/metrics: confidence_histogram gains mean (same Aggregator, no second computation). Existing fields do not change.

2026-11-13 — the measured optimizer (T41), additive

  • POST /v1/optimizations {workflow_id, base_version_id | alias, snapshot_id, strategy, budget{max_rounds 1..10, max_cost_usd}, field_ids?, sample_run_ids?, acknowledge_low_data?} (202); GET /v1/optimizations (keyset, workflow_id, status), GET /v1/optimizations/{id} (rounds with their candidate draft, scores on train and validation, verdict, edits, the budget spent, the test report and the state experimental|validated of the strategy), POST /v1/optimizations/{id}:cancel and POST /v1/optimizations/{id}:promote {alias, acknowledge_unmeasured?}. New tag optimizations.
  • New problem codes OPTIMIZATION_INSUFFICIENT_DATA, NO_TEST_REPORT, OPTIMIZATION_NOT_PROMOTABLE, OPTIMIZATION_ALREADY_PROMOTED, OPTIMIZATION_NOT_CANCELLABLE (409) and AGENT_CANNOT_PROMOTE (403).
  • workflow.version.published is emitted by :promote (the version is a patch of the latest one) and optimization.completed goes to the run's outbox; the run emits optimization.finished.

2026-11-13 — event streams, webhooks and notification channels (T27), additive

  • GET /v1/runs/{id}/events: server-sent events of a run (id = the run's sequence 1..N, Last-Event-ID / ?since=, retry: 3000, : ping every 15 s, closes after the terminal event; 429 beyond 100 open streams per project). Tag runs.
  • Webhooks (Standard Webhooks): POST/GET /v1/webhooks, GET/PATCH/DELETE /v1/webhooks/{id}, POST /v1/webhooks/{id}:rotate-secret, POST /v1/webhooks/{id}:test, GET /v1/webhooks/{id}/deliveries, GET …/deliveries/{delivery}, POST …/deliveries/{delivery}:redeliver and GET /v1/webhook-events (the event catalog with a JSON Schema per event). The whsec_ secret appears only when an endpoint is created or its secret rotated. Tag webhooks. Permission webhook:manage to change anything.
  • Notification channels for the notify node: POST/GET /v1/notification-channels, GET/PATCH/DELETE /v1/notification-channels/{id} and POST …/{id}:test. Tag notification-channels.
  • Workflow topology: the notify node reports NOTIFY_TEMPLATE_INVALID and NOTIFY_CHANNEL_KIND_MISMATCH as errors and NOTIFY_CHANNEL_UNKNOWN as a warning. See Webhooks, SSE and notifications.

2026-11-13 — Edit and Report nodes (T29), additive

  • Reference documents of the Edit node: POST /v1/edit-references (multipart file, up to 5 files of 5 MiB; 415 unsupported-media-type, 422 reference-limits), GET /v1/edit-references, GET/DELETE /v1/edit-references/{id}. Tag edit.
  • Dry run: POST /v1/edit:preview (EditResult with preview_id), GET /v1/edit-previews/{id}/pdf and GET /v1/edit-previews/{id}/pages/{n}.png (15 minutes, then 404). New problem codes reference-limits (422), invalid-form-pdf (422) and edit-preview-timeout (504). JSON Schemas schemas/edit/form-field.schema.json and edit-result.schema.json.
  • Workflow graph 1.1: fill_form.config.reference_table is an object (table_id, table_version, match_on, returns) and reference_ids is optional; fill_form node schema_version 1.1.0 tightens font to sans|serif|mono. New publication rules fill_form_reference_table and report_template_invalid.
  • GET /v1/runs/{id}/artifacts/{artifact_id} also serves an artifact the run reused from the cache. Node errors TEMPLATE_UNSAFE, TEMPLATE_INVALID and REPORT_TOO_LARGE (report); see Edit and Report.

2026-11-13 — storage connectors (T31)

Additive:

  • GET /v1/connection-kinds; POST/GET /v1/connections, GET/PATCH/DELETE /v1/connections/{id}, POST /v1/connections/{id}:test, POST /v1/connections/oauth/{google|microsoft}:start, GET /v1/connections/oauth/callback.
  • POST/GET /v1/connectors, GET/PATCH/DELETE /v1/connectors/{id}, POST /v1/connectors/{id}:run, GET /v1/connectors/{id}/items.
  • Problem codes CONNECTION_NOT_FOUND, CONNECTION_READ_ONLY, CONNECTION_NAME_TAKEN, CONNECTION_IN_USE, CONNECTION_INVALID, PRIVATE_ENDPOINT_FORBIDDEN, OAUTH_STATE_INVALID, OAUTH_EXCHANGE_FAILED, CONNECTOR_NAME_TAKEN, CONNECTOR_DISABLED, EXPORT_MAPPING_INVALID, EXPORT_FAILED. ALIAS_NOT_FOUND is 422 when a connector names the alias.
  • The export node configuration gains include and exclude; the node outcome error gains retryable.

2026-11-13 — MCP surface and approvals (T47), additive

  • Approvals of destructive MCP tool calls: POST /v1/approvals, GET /v1/approvals/{id}, POST /v1/approvals/{id}:approve and :reject (tag approvals). New problem codes approval-expired and approval-not-pending (409).
  • Metadata only: the tag mcp on list_runs, get_run, cancel_run, create_workflow_run, get_run_result, get_run_evidence, create_workflow, archive_workflow and list_node_types (they become MCP tools).
  • Outside the OpenAPI document: POST /mcp (MCP Streamable HTTP, stateless) and GET /.well-known/oauth-protected-resource[/mcp] (RFC 9728). See MCP.

2026-11-17 — credit packs and Stripe Managed Payments (T61), commercial edition only

No change to the community snapshot (openapi/openapi.json). With extractit-ee installed: POST /v1/billing/topups takes {"pack_id"} (credits is accepted only when it equals one pack; anything else is 400 validation-error) and answers with pack_id; GET /v1/billing/balance adds credit_packs; new POST /v1/billing/portal (Stripe Billing Portal URL); POST /webhooks/stripe now handles checkout.session.async_payment_succeeded, …async_payment_failed, charge.refunded and charge.dispute.created. New ee migration ee_0004 (ee_stripe_customer). See Usage and billing.

2026-11-13 — usage, credits and budgets (T51), commercial edition only

No change to the community snapshot (openapi/openapi.json). With dataextractor-ee installed: GET /v1/usage, GET /v1/usage/export.csv, GET /v1/billing/balance, /ledger, /plans, PUT /v1/billing/plan, POST /v1/billing/topups, POST /v1/billing/credits:grant, GET/PUT /v1/billing/notification-channels, GET/PUT /v1/budgets, DELETE /v1/budgets/{id}, GET /v1/budgets/{id}/alerts and POST /webhooks/stripe. New problem codes insufficient_credits (402), budget_exceeded (402) and TOPUPS_MANUAL (409); new run event budget.threshold_reached (schemas/events/budget.threshold_reached-1.0.json). Core, internal: hook points runs.created, runs.finished and interpreter.activity_closed, and register_error for codes added by extensions. See Billing.

2026-11-13 — organization administration (T49), additive

  • Model policies: GET/PUT /v1/org/model-policy, GET/PUT /v1/projects/{id}/model-policy, POST /v1/model-policy/resolve (effective policy, route, fallbacks, discarded candidates and policy_hash; per node with workflow_version_id). Tag model-policy.
  • BYOK: POST/GET /v1/provider-credentials, GET/DELETE /v1/provider-credentials/{id}, POST /v1/provider-credentials/{id}/test (the secret is write-only). Tag provider-credentials.
  • GET /v1/models (?effective=true), JSON Schema schemas/api/models.schema.json. Tag models.
  • GET /auth/login accepts org (organization SSO, commercial edition); issuer is no longer required when org is given.
  • Workflow graph 1.1: extract.config.model_policy also takes a policy fragment; publishing answers 422 NO_COMPLIANT_MODEL when a node has no compliant model. New problem codes NO_COMPLIANT_MODEL (422) and no-role (403).
  • Commercial edition only (not in the community snapshot): GET/PUT/DELETE /v1/org/sso, POST /v1/org/sso:test, POST/GET /v1/org/scim-tokens, DELETE /v1/org/scim-tokens/{id} and the SCIM 2.0 server under /scim/v2.

2026-11-12 — documents table, bulk actions, exports and the publish cycle (T36), additive

  • GET /v1/runs gains workflow, version, q, confidence_lt, rule_failed, purpose, sort and fields; status also takes the seven table states; each row gains display_status, review_state, version_id, version_number, document, confidence, rules_failed, error, usage and fields. offset is 400. Runs with purpose: test are not listed by default.
  • POST /v1/runs:batch (resume, rerun, cancel over an include/exclude selection resolved by the server).
  • POST /v1/exports (202), GET /v1/exports, GET /v1/exports/{id} and GET /v1/exports/{id}/download (csv, xlsx, json, jsonl, markdown_zip); GET/PUT /v1/workflows/{id}/documents/columns.
  • POST /v1/runs accepts purpose: "test" (a draft {version_id}, 1–5 documents).
  • GET /v1/workflow-versions/{id}:diff gains semver_bump, summary and changes[]; :publish accepts bump (never lower than semver_bump); GET /v1/evaluations filters by version_id; PATCH /v1/workflows/{id} accepts require_evaluation_to_publish.
  • Changed (v1 not yet released): saving a published version is 409 version-immutable (was VERSION_NOT_DRAFT); an invalid alias on PUT …/aliases/{alias} is 422 INVALID_REFERENCE.
  • New problem codes version-immutable, evaluation-required (409), bump-too-low, too-many-test-documents (422) and export-not-ready (409). New tag exports.

2026-11-12 — Health: promotion and derived evaluation views (T37), additive

  • POST /v1/datasets/{id}/items:promote {run_id, tags?}: promotes a document verified in the review (T32) into a dataset (201, or 200 with the existing item when the run was already promoted).
  • GET /v1/evaluations/{id}/error-matrix, …/reliability (15 equal-mass bins, Clopper-Pearson intervals, ECE and noise floor, scores_kind) and …/risk-coverage (≤ 200 points); GET /v1/evaluations:compare-details?a=&b= (differences per field with a paired interval, minimum detectable difference, documents that get worse).
  • GET /v1/evaluations/{id}/fields accepts item_id; ItemResultOut carries run_id.
  • PROMOTION_INCOMPLETE is now 409 (it was 422): the document is not ready, the request is not malformed. errors[].pointer names what is missing (/state, /fields/<path>, /run).

2026-11-12 — builder agent (T43), additive

  • POST /v1/agent/sessions, GET /v1/agent/sessions, GET and PATCH /v1/agent/sessions/{session_id} (max_cost_usd), GET /v1/agent/sessions/{session_id}/actions.
  • POST /v1/agent/sessions/{session_id}/messages answers text/event-stream (events message.delta, tool.started, tool.finished, changeset.proposed, approval.requested, session.budget, turn.completed, error; JSON Schema schemas/agent/agent-events.schema.json).
  • GET /v1/change-sets/{change_set_id}, POST /v1/change-sets/{change_set_id}:approve and :reject.
  • New tag agent; new problem codes CHANGESET_BASE_CHANGED (409), CHANGESET_NOT_PENDING (409), APPROVAL_MISMATCH (403), RISKS_NOT_ACKNOWLEDGED (422), AGENT_BUDGET_EXHAUSTED (409) and AGENT_LIMIT_EXCEEDED (422). See docs/agent.md.

2026-11-12 — service status for status pages (T53), additive

  • GET /v1/status (public, tag health, cached 5 s): {status, checked_at, components[{name, status, detail}]} with database, queue, storage and workers, each up, degraded or down; detail holds numbers (queue length and age, worker activity) or a fixed reason. Always 200 (the state is in the body). See docs/ops/observability.md.

2026-11-12 — schema and rules editors (T35), additive

  • POST /v1/schemas:normalize ({schema, previous_schema?} → {schema, errors[{pointer, rule, message}], field_count}) and POST /v1/schemas:import ({format, document}); POST /v1/rules:validate, POST /v1/rules:estimate and POST /v1/rules:test (up to 20 runs, max_usd).
  • New tags schemas and rules; new problem codes PYTHON_SOURCE_NOT_ACCEPTED and budget-exceeded (422). compared_values of an AI rule result gains cited_fields. See docs/schema-editor.md and docs/rules-editor.md.

2026-11-12 — deletion reaches the review values (T50 delta), additive

No change to openapi/openapi.json. The values of review_decision and field_override are sealed with a per-run data key that the certified deletion and the ZDR sweep destroy. After that, GET /v1/runs/{run_id}/review/history returns the decisions with previous_value, new_value, evidence and reason as null and redacted: true, and GET /v1/runs/{run_id}/review of a run whose result was deleted answers 200 with the fields that had been decided (value: null, status: erased, redacted: true, warnings: ["data_erased"]) instead of 409 run-not-finished (a run that was never reviewed still answers 409). The deletion certificate lists both tables in destroyed[]; the exclusions line about review_decision is gone.

2026-11-12 — data governance: retention, ZDR, certified deletion and the audit chain (T50)

  • GET and PUT /v1/projects/{project_id}/retention (TTLs, ZDR 1–168 h, zdr_required) and POST /v1/projects/{project_id}/legal-hold (mandatory reason).
  • GET /v1/deletion-certificates, GET /v1/deletion-certificates/{certificate_id} and the public GET /.well-known/dx-deletion-jwks.json and /.well-known/dx-audit-jwks.json (public keys only).
  • GET /v1/audit/verify, GET /v1/audit/checkpoints and GET /v1/audit-events/export (NDJSON).
  • GET /v1/audit-events: events gain seq, prev_hash and event_hash (additive).
  • Changed (v1 not yet released): DELETE /v1/packets/{packet_id} answers 202 with a dcert_id instead of 204; GET /v1/runs/{run_id}/result and /document answer 404 (not 409 run-not-finished) for a finished run whose content was deleted.
  • New problem codes legal_hold_active (409), retention-out-of-range (422) and erasure-retry (503). New tag governance; outbox event packet.deleted (schemas/governance/packet-deleted-event-1.0.json). See docs/security/.

2026-11-12 — reference tables for lookup sources (T24), additive

  • POST /v1/lookup-tables (multipart {name, description?, key_column, file}), GET /v1/lookup-tables, GET and PATCH /v1/lookup-tables/{table_id} (ETag, If-Match), POST and GET /v1/lookup-tables/{table_id}/versions, GET …/versions/{version}?preview= (latest allowed) and POST …/versions/{version}:match (scored candidates, no model).
  • New tag lookup-tables; new problem codes lookup-too-large (413), lookup-duplicate-keys, invalid-lookup-config (422), lookup-version-not-found (404) and lookup-name-taken (409).
  • Output 1.2: evidence gains lookup_ref, derivation, metadata_path, file_id, file_page and packet_page; DocIR 1.2: pages gain file_id, file_page and packet_page; dialect 1.2: x-dx.source accepts an object with a kind. See docs/extraction/field-sources.md.

2026-11-12 — calibrated confidence, threshold policies and audit (T39), additive

  • POST /v1/calibrators:fit, GET /v1/calibrators, POST /v1/calibrators/{calibrator_id}:activate and :archive; POST /v1/threshold-policies:certify, GET /v1/threshold-policies, POST /v1/threshold-policies/{policy_id}:tighten and :invalidate; POST /v1/audit-samples:consider and GET /v1/audit-samples.
  • New tag calibration; new problem codes NOT_CALIBRATED, CERT_SET_OVERLAPS_CALIBRATOR, INSUFFICIENT_DATA, NO_CERTIFIABLE_THRESHOLD, GRID_MISMATCH (422), CALIBRATOR_STATE and POLICY_STATE (409).
  • Output contract 1.2: ConfidenceScore.reason (optional, calibrator_stale).
  • New outbox event audit.sampled. JSON Schemas in schemas/calibration/. See docs/confidence.md.

2026-11-12 — editions and extension points (T57), additive

  • GET /v1/meta (any authenticated credential): {edition, version, features} — edition is community or ee (the commercial edition is installed), features the features declared by installed extensions (JSON Schema schemas/api/meta.schema.json). New tag meta.
  • New problem code run-not-admitted (403): a runs.admission hook of an installed extension rejected POST /v1/parse, POST /v1/extract, POST /v1/runs or POST /v1/runs/{run_id}:rerun before anything was enqueued (detail, optional reason).
  • The committed snapshot is the community edition; routes and tags of extensions (/v1/ee/...) appear only in the OpenAPI document of a server that has them installed.

2026-11-12 — review in the viewer (T32), additive

  • GET /v1/runs/{run_id}/review (?below=, ETag, If-None-Match), PATCH /v1/runs/{run_id}/fields/{path} (If-Match), POST /v1/runs/{run_id}/rows, DELETE /v1/runs/{run_id}/rows/{path}, POST /v1/runs/{run_id}:approve, POST /v1/runs/{run_id}:reject, GET /v1/runs/{run_id}/review/history?path= and GET /v1/review/next?workflow_id=&after=.
  • New tag review; new problem codes etag-mismatch (412), invalid-field-value (422) and blocking-rule-failing (409) (the error descriptions of every operation list them).
  • New outbox events review.completed and extraction.corrected (delivered by T27).
  • JSON Schemas of the review data in schemas/review/. See docs/review.md.

2026-11-12 — classify and split (T28), additive

  • GET /v1/runs/{run_id}/classifications and GET /v1/runs/{run_id}/segments: what the classify and split nodes of a workflow run decided (research/06 §8: label and name, heuristic confidence, ranking, verified evidence, abstention, hierarchy path; segment pages that may not be consecutive, boundary evidence, status assigned/unassigned).
  • GET /v1/runs/{run_id}/segments/{segment_id}/pdf: the segment as an independent PDF (application/pdf, ETag = sha256, 304 on If-None-Match; 404 for an unknown segment or another project).
  • The result of a workflow run lists outputs.classifications and outputs.segments; the extractions below a split are keyed by segment id. Workflow validation adds classify_categories_invalid, classify_unclassified_edge_unknown, classify_unclassified_missing and classify_many_leaves.

2026-11-11 — plugins and the Code node (T30), additive

  • GET /v1/plugins, GET /v1/plugins/{plugin_id}, POST /v1/plugins/{plugin_id}:enable (body {approved_secrets?}) and POST /v1/plugins/{plugin_id}:disable: installed node and parser-engine plugins (manifest, distribution sha256) and their state in the project.
  • New tag plugins; new problem codes plugin_not_available (404), plugin_not_allowlisted (403), plugin_invalid and plugin_secret_not_declared (422) (the error descriptions of every operation list them).
  • Node errors (GET /v1/runs/{run_id}/nodes) may carry error.exception_type (Code node and plugins); the internal traceback is never served. Workflow results add reproducibility.plugins ({node_id: {id, version, sha256}}).
  • Workflow validation adds the rules PLUGIN_NOT_AVAILABLE, PLUGIN_VERSION_INCOMPATIBLE, PORT_TYPE_MISMATCH, PLUGIN_CONFIG_INVALID and transform_* (see docs/plugins/authoring.md and docs/nodes/code.md).

2026-11-11 — workflow runs (T26), additive

  • POST /v1/runs (JSON {workflow, packet_id, metadata?, priority?, options?} or multipart workflow + files[]): runs a published workflow version by alias, number or id (?wait=).
  • POST /v1/runs/{run_id}:rerun, GET /v1/runs/{run_id}/nodes, POST /v1/runs/{run_id}/nodes/{node_id}:complete, GET /v1/runs/{run_id}/artifacts/{artifact_id} (ETag, 304).
  • New tag workflow-runs; new problem codes ALIAS_NOT_FOUND (404) and VERSION_NOT_PUBLISHED (422) (the error descriptions of every operation list them).
  • For runs of kind workflow, :cancel also cancels the run's child workflows and :resume re-runs only the failed node and its descendants. See docs/workflows/interpreter.md.

2026-11-10 — ingest and one-shot runs (T17)

Additive:

  • POST /v1/packets (multipart files or JSON URLs), GET /v1/packets/{packet_id}, DELETE /v1/packets/{packet_id}.
  • POST /v1/uploads, PUT /v1/uploads/{upload_id}/content, POST /v1/uploads/{upload_id}/complete.
  • POST /v1/parse, POST /v1/extract (?wait=).
  • GET /v1/runs, GET /v1/runs/{run_id} (?wait=), POST /v1/runs/{run_id}:cancel, POST /v1/runs/{run_id}:resume.
  • GET /v1/runs/{run_id}/result, /result/download, /evidence, /document, /pages/{page}.png.
  • Problem codes: payload-too-large, too-many-files, too-many-pages, unsupported-media-type, pdf-encrypted, invalid-document, url-not-allowed, import-timeout, import-failed, upload-token-expired, upload-checksum-mismatch, upload-size-mismatch, upload-not-found, duplicate-document, packet-multi-file-unsupported, packet-not-ready, run-not-resumable, run-not-finished.
  • Plan default: max_file_mb 25 and max_files_per_packet 100 (were 100 and 200).

2026-11-10 — Workflows (T25), additive

  • POST/GET /v1/workflows, GET/PATCH/DELETE /v1/workflows/{workflow_id} (DELETE archives), POST /v1/workflows/{workflow_id}:validate (dry run).
  • GET/POST /v1/workflows/{workflow_id}/versions, GET/PUT /v1/workflow-versions/{version_id}, POST /v1/workflow-versions/{version_id}:publish and :archive, GET /v1/workflow-versions/{version_id}:diff?against=….
  • GET /v1/workflows/{workflow_id}/aliases, PUT/DELETE …/aliases/{alias}, GET …/aliases/{alias}/history.
  • New problem codes TOPOLOGY_INVALID, INVALID_SCHEMAS, NOTHING_TO_PUBLISH, VERSION_NOT_DRAFT, DRAFT_EXISTS, VERSION_IN_USE, WORKFLOW_NAME_TAKEN, WORKFLOW_ARCHIVED, ALIAS_TARGET_NOT_PUBLISHED, ALIAS_REQUIRED, INVALID_REFERENCE (the error descriptions of every operation list them). See docs/workflows/graph.md.

2026-11-12 — datasets and evaluations (T38)

Additive. New tags datasets and evaluations; no existing operation changed.

  • POST/GET /v1/datasets, GET /v1/datasets/{id}; POST/GET /v1/datasets/{id}/items (multipart PDF + JSON pairs, ?dry_run=true, keyset pages filtered by split and tag); GET/PUT /v1/datasets/{id}/items/{item}/ground-truth (ETag/If-Match on the ground-truth version) and …/history; GET /v1/datasets/{id}/tags; POST/GET …/subsets; POST/GET …/snapshots (200 for an unchanged one, 201 for a new one) and …/snapshots/{id}; POST /v1/datasets/{id}:resplit (mandatory reason); GET …/test-split-access.
  • POST /v1/evaluations (202, number per workflow), GET /v1/evaluations, GET /v1/evaluations/{id}, …/fields, …/items, …/tags, GET /v1/evaluations:compare?a=&b=.
  • X-DX-Access-Context: agent|optimizer|calibration (narrows access; the test split is sealed for them) and X-DX-Access-Reason.
  • New problem codes TEST_SPLIT_SEALED (403), GT_INVALID, PROMOTION_INCOMPLETE, CONFIRM_TEST_REQUIRED, SNAPSHOTS_DIFFER, EVAL_NOT_APPLICABLE (422), EVALUATION_NOT_FINISHED, DATASET_NAME_TAKEN (409). See docs/datasets.md.

2026-11-10 — /v1, DX-Version 2026-11-01 (T12)

First version of the contract:

  • Conventions: RFC 9457 problems, keyset pagination (limit, cursor, X-Limit-Applied), Idempotency-Key, ETag/If-Match/If-None-Match, X-Request-ID, DX-Version, traceparent, RateLimit-Policy/RateLimit, Deprecation/Sunset.
  • GET /healthz, GET /readyz.
  • GET /v1/me.
  • GET /v1/projects, POST /v1/projects, GET /v1/projects/{project_id}, PATCH /v1/projects/{project_id}.
  • GET /v1/api-keys, POST /v1/api-keys, DELETE /v1/api-keys/{key_id}, POST /v1/api-keys/{key_id}:rotate.
  • GET /v1/audit-events.