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(andGET /v1/workflows/{id}):statsgainsconfidence_30d, the mean confidence of the last 30 days (nullwithout scores; approximate, computed from the bin centres of the T40 histogram).stats.accuracy_30dis unchanged.GET /v1/workflows/{id}/metrics:confidence_histogramgainsmean(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 stateexperimental|validatedof the strategy),POST /v1/optimizations/{id}:cancelandPOST /v1/optimizations/{id}:promote{alias, acknowledge_unmeasured?}. New tagoptimizations.- New problem codes
OPTIMIZATION_INSUFFICIENT_DATA,NO_TEST_REPORT,OPTIMIZATION_NOT_PROMOTABLE,OPTIMIZATION_ALREADY_PROMOTED,OPTIMIZATION_NOT_CANCELLABLE(409) andAGENT_CANNOT_PROMOTE(403). workflow.version.publishedis emitted by:promote(the version is a patch of the latest one) andoptimization.completedgoes to the run's outbox; the run emitsoptimization.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,: pingevery 15 s, closes after the terminal event;429beyond 100 open streams per project). Tagruns.- 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}:redeliverandGET /v1/webhook-events(the event catalog with a JSON Schema per event). Thewhsec_secret appears only when an endpoint is created or its secret rotated. Tagwebhooks. Permissionwebhook:manageto change anything. - Notification channels for the
notifynode:POST/GET /v1/notification-channels,GET/PATCH/DELETE /v1/notification-channels/{id}andPOST …/{id}:test. Tagnotification-channels. - Workflow topology: the
notifynode reportsNOTIFY_TEMPLATE_INVALIDandNOTIFY_CHANNEL_KIND_MISMATCHas errors andNOTIFY_CHANNEL_UNKNOWNas 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(multipartfile, up to 5 files of 5 MiB; 415unsupported-media-type, 422reference-limits),GET /v1/edit-references,GET/DELETE /v1/edit-references/{id}. Tagedit. - Dry run:
POST /v1/edit:preview(EditResultwithpreview_id),GET /v1/edit-previews/{id}/pdfandGET /v1/edit-previews/{id}/pages/{n}.png(15 minutes, then 404). New problem codesreference-limits(422),invalid-form-pdf(422) andedit-preview-timeout(504). JSON Schemasschemas/edit/form-field.schema.jsonandedit-result.schema.json. - Workflow graph 1.1:
fill_form.config.reference_tableis an object (table_id,table_version,match_on,returns) andreference_idsis optional;fill_formnodeschema_version1.1.0 tightensfonttosans|serif|mono. New publication rulesfill_form_reference_tableandreport_template_invalid. GET /v1/runs/{id}/artifacts/{artifact_id}also serves an artifact the run reused from the cache. Node errorsTEMPLATE_UNSAFE,TEMPLATE_INVALIDandREPORT_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_FOUNDis 422 when a connector names the alias. - The
exportnode configuration gainsincludeandexclude; the node outcome error gainsretryable.
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}:approveand:reject(tagapprovals). New problem codesapproval-expiredandapproval-not-pending(409). - Metadata only: the tag
mcponlist_runs,get_run,cancel_run,create_workflow_run,get_run_result,get_run_evidence,create_workflow,archive_workflowandlist_node_types(they become MCP tools). - Outside the OpenAPI document:
POST /mcp(MCP Streamable HTTP, stateless) andGET /.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 andpolicy_hash; per node withworkflow_version_id). Tagmodel-policy. - BYOK:
POST/GET /v1/provider-credentials,GET/DELETE /v1/provider-credentials/{id},POST /v1/provider-credentials/{id}/test(the secret is write-only). Tagprovider-credentials. GET /v1/models(?effective=true), JSON Schemaschemas/api/models.schema.json. Tagmodels.GET /auth/loginacceptsorg(organization SSO, commercial edition);issueris no longer required whenorgis given.- Workflow graph 1.1:
extract.config.model_policyalso takes a policy fragment; publishing answers422 NO_COMPLIANT_MODELwhen a node has no compliant model. New problem codesNO_COMPLIANT_MODEL(422) andno-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/runsgainsworkflow,version,q,confidence_lt,rule_failed,purpose,sortandfields;statusalso takes the seven table states; each row gainsdisplay_status,review_state,version_id,version_number,document,confidence,rules_failed,error,usageandfields.offsetis400. Runs withpurpose: testare not listed by default.POST /v1/runs:batch(resume,rerun,cancelover aninclude/excludeselection resolved by the server).POST /v1/exports(202),GET /v1/exports,GET /v1/exports/{id}andGET /v1/exports/{id}/download(csv,xlsx,json,jsonl,markdown_zip);GET/PUT /v1/workflows/{id}/documents/columns.POST /v1/runsacceptspurpose: "test"(a draft{version_id}, 1–5 documents).GET /v1/workflow-versions/{id}:diffgainssemver_bump,summaryandchanges[];:publishacceptsbump(never lower thansemver_bump);GET /v1/evaluationsfilters byversion_id;PATCH /v1/workflows/{id}acceptsrequire_evaluation_to_publish.- Changed (v1 not yet released): saving a published version is
409 version-immutable(wasVERSION_NOT_DRAFT); an invalid alias onPUT …/aliases/{alias}is422 INVALID_REFERENCE. - New problem codes
version-immutable,evaluation-required(409),bump-too-low,too-many-test-documents(422) andexport-not-ready(409). New tagexports.
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}/fieldsacceptsitem_id;ItemResultOutcarriesrun_id.PROMOTION_INCOMPLETEis now409(it was422): the document is not ready, the request is not malformed.errors[].pointernames what is missing (/state,/fields/<path>,/run).
2026-11-12 — builder agent (T43), additive
POST /v1/agent/sessions,GET /v1/agent/sessions,GETandPATCH /v1/agent/sessions/{session_id}(max_cost_usd),GET /v1/agent/sessions/{session_id}/actions.POST /v1/agent/sessions/{session_id}/messagesanswerstext/event-stream(eventsmessage.delta,tool.started,tool.finished,changeset.proposed,approval.requested,session.budget,turn.completed,error; JSON Schemaschemas/agent/agent-events.schema.json).GET /v1/change-sets/{change_set_id},POST /v1/change-sets/{change_set_id}:approveand:reject.- New tag
agent; new problem codesCHANGESET_BASE_CHANGED(409),CHANGESET_NOT_PENDING(409),APPROVAL_MISMATCH(403),RISKS_NOT_ACKNOWLEDGED(422),AGENT_BUDGET_EXHAUSTED(409) andAGENT_LIMIT_EXCEEDED(422). Seedocs/agent.md.
2026-11-12 — service status for status pages (T53), additive
GET /v1/status(public, taghealth, cached 5 s):{status, checked_at, components[{name, status, detail}]}withdatabase,queue,storageandworkers, eachup,degradedordown;detailholds numbers (queue length and age, worker activity) or a fixedreason. Always 200 (the state is in the body). Seedocs/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}) andPOST /v1/schemas:import({format, document});POST /v1/rules:validate,POST /v1/rules:estimateandPOST /v1/rules:test(up to 20 runs,max_usd).- New tags
schemasandrules; new problem codesPYTHON_SOURCE_NOT_ACCEPTEDandbudget-exceeded(422).compared_valuesof an AI rule result gainscited_fields. Seedocs/schema-editor.mdanddocs/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)
GETandPUT /v1/projects/{project_id}/retention(TTLs, ZDR 1–168 h,zdr_required) andPOST /v1/projects/{project_id}/legal-hold(mandatory reason).GET /v1/deletion-certificates,GET /v1/deletion-certificates/{certificate_id}and the publicGET /.well-known/dx-deletion-jwks.jsonand/.well-known/dx-audit-jwks.json(public keys only).GET /v1/audit/verify,GET /v1/audit/checkpointsandGET /v1/audit-events/export(NDJSON).GET /v1/audit-events: events gainseq,prev_hashandevent_hash(additive).- Changed (v1 not yet released):
DELETE /v1/packets/{packet_id}answers202with adcert_idinstead of204;GET /v1/runs/{run_id}/resultand/documentanswer404(not409 run-not-finished) for a finished run whose content was deleted. - New problem codes
legal_hold_active(409),retention-out-of-range(422) anderasure-retry(503). New taggovernance; outbox eventpacket.deleted(schemas/governance/packet-deleted-event-1.0.json). Seedocs/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,GETandPATCH /v1/lookup-tables/{table_id}(ETag,If-Match),POSTandGET /v1/lookup-tables/{table_id}/versions,GET …/versions/{version}?preview=(latestallowed) andPOST …/versions/{version}:match(scored candidates, no model).- New tag
lookup-tables; new problem codeslookup-too-large(413),lookup-duplicate-keys,invalid-lookup-config(422),lookup-version-not-found(404) andlookup-name-taken(409). - Output
1.2: evidence gainslookup_ref,derivation,metadata_path,file_id,file_pageandpacket_page; DocIR1.2: pages gainfile_id,file_pageandpacket_page; dialect1.2:x-dx.sourceaccepts an object with akind. Seedocs/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}:activateand:archive;POST /v1/threshold-policies:certify,GET /v1/threshold-policies,POST /v1/threshold-policies/{policy_id}:tightenand:invalidate;POST /v1/audit-samples:considerandGET /v1/audit-samples.- New tag
calibration; new problem codesNOT_CALIBRATED,CERT_SET_OVERLAPS_CALIBRATOR,INSUFFICIENT_DATA,NO_CERTIFIABLE_THRESHOLD,GRID_MISMATCH(422),CALIBRATOR_STATEandPOLICY_STATE(409). - Output contract 1.2:
ConfidenceScore.reason(optional,calibrator_stale). - New outbox event
audit.sampled. JSON Schemas inschemas/calibration/. Seedocs/confidence.md.
2026-11-12 — editions and extension points (T57), additive
GET /v1/meta(any authenticated credential):{edition, version, features}—editioniscommunityoree(the commercial edition is installed),featuresthe features declared by installed extensions (JSON Schemaschemas/api/meta.schema.json). New tagmeta.- New problem code
run-not-admitted(403): aruns.admissionhook of an installed extension rejectedPOST /v1/parse,POST /v1/extract,POST /v1/runsorPOST /v1/runs/{run_id}:rerunbefore anything was enqueued (detail, optionalreason). - 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=andGET /v1/review/next?workflow_id=&after=.- New tag
review; new problem codesetag-mismatch(412),invalid-field-value(422) andblocking-rule-failing(409) (the error descriptions of every operation list them). - New outbox events
review.completedandextraction.corrected(delivered by T27). - JSON Schemas of the review data in
schemas/review/. Seedocs/review.md.
2026-11-12 — classify and split (T28), additive
GET /v1/runs/{run_id}/classificationsandGET /v1/runs/{run_id}/segments: what theclassifyandsplitnodes 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, statusassigned/unassigned).GET /v1/runs/{run_id}/segments/{segment_id}/pdf: the segment as an independent PDF (application/pdf,ETag= sha256, 304 onIf-None-Match; 404 for an unknown segment or another project).- The result of a workflow run lists
outputs.classificationsandoutputs.segments; the extractions below asplitare keyed by segment id. Workflow validation addsclassify_categories_invalid,classify_unclassified_edge_unknown,classify_unclassified_missingandclassify_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?}) andPOST /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 codesplugin_not_available(404),plugin_not_allowlisted(403),plugin_invalidandplugin_secret_not_declared(422) (the error descriptions of every operation list them). - Node errors (
GET /v1/runs/{run_id}/nodes) may carryerror.exception_type(Code node and plugins); the internal traceback is never served. Workflow results addreproducibility.plugins({node_id: {id, version, sha256}}). - Workflow validation adds the rules
PLUGIN_NOT_AVAILABLE,PLUGIN_VERSION_INCOMPATIBLE,PORT_TYPE_MISMATCH,PLUGIN_CONFIG_INVALIDandtransform_*(seedocs/plugins/authoring.mdanddocs/nodes/code.md).
2026-11-11 — workflow runs (T26), additive
POST /v1/runs(JSON{workflow, packet_id, metadata?, priority?, options?}or multipartworkflow+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 codesALIAS_NOT_FOUND(404) andVERSION_NOT_PUBLISHED(422) (the error descriptions of every operation list them). - For runs of kind
workflow,:cancelalso cancels the run's child workflows and:resumere-runs only the failed node and its descendants. Seedocs/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_mb25 andmax_files_per_packet100 (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}:publishand: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). Seedocs/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 bysplitandtag);GET/PUT /v1/datasets/{id}/items/{item}/ground-truth(ETag/If-Matchon 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(mandatoryreason);GET …/test-split-access.POST /v1/evaluations(202,numberper 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) andX-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). Seedocs/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.