Skip to content

API reference

Version 2026-11-01 · 270 operations. The machine-readable document is GET /openapi.json (also openapi/openapi.json in the repository). Operations tagged mcp are also MCP tools (see MCP). Errors are RFC 9457 problems (see API conventions).

health

GET /healthz

Liveness probe · operationId healthz

Answers 200 while the process serves requests. No authentication.

GET /readyz

Readiness probe · operationId readyz

Answers 200 when the database answers, 503 otherwise. No authentication.

GET /v1/status

Service status · operationId get_status

State of the database, the run queue, the object storage and the workers, for status pages and monitors. No authentication; cached for a few seconds. Always 200: read status (up, degraded or down).

me

GET /v1/me

Who am I · operationId get_me · MCP tool · permission authenticated

The credential of the request: organization, project, role, scopes and the effective permissions (scopes intersected with the role). Web sessions also get the user and its organizations.

projects

GET /v1/projects

List projects · operationId list_projects · MCP tool · permission project:read

Projects of the organization in creation order (keyset pages). A credential without project:manage sees only its own project.

POST /v1/projects

Create a project · operationId create_project · permission project:manage

Creates a project in the organization with the limits of the server's plan.

GET /v1/projects/{project_id}

Get a project · operationId get_project · MCP tool · permission project:read

One project with its ETag; If-None-Match with the current ETag answers 304.

PATCH /v1/projects/{project_id}

Update a project · operationId update_project · permission project:manage

Changes the slug or name. Requires If-Match with the current ETag (428 without it, 412 when stale).

api-keys

GET /v1/api-keys

List API keys · operationId list_api_keys · permission apikey:manage

Keys of the credential's project, without their secrets (keyset pages).

POST /v1/api-keys

Create an API key · operationId create_api_key · permission apikey:manage

Creates a key in the credential's project. The full key appears only in this response. Scopes are bounded by the creator's permissions (403 scope-exceeds-role); expiry defaults to 90 days (at most 365); a project has at most 20 active keys (409).

DELETE /v1/api-keys/{key_id}

Revoke an API key · operationId revoke_api_key · permission apikey:manage

Revokes the key; it answers 401 key-revoked within 5 seconds everywhere.

POST /v1/api-keys/{key_id}:rotate

Rotate an API key · operationId rotate_api_key · permission apikey:manage

Creates a replacement key with the same name and scopes; the old key keeps working for overlap_hours (default 24, at most 168) and then answers 401 key-expired.

audit

GET /v1/audit-events

List audit events · operationId list_audit_events · permission audit:read

Audit events of the credential's project, oldest first (keyset pages), filtered by actor, action, target and time range.

auth

GET /auth/providers

List login providers · operationId list_auth_providers

The OIDC issuers this deployment trusts (public).

GET /auth/login

Start a login · operationId start_login

Redirects (302) to the issuer's authorization endpoint with PKCE S256, state and nonce; redirect must be a relative path of this site (anything else becomes /).

GET /auth/callback

Finish a login · operationId finish_login

The issuer redirects here. On success sets __Host-dx_session and dx_csrf and redirects (303) to the path given to /auth/login; a wrong state or nonce answers 400 without creating a session.

POST /auth/email/start

Email a sign-in link · operationId start_email_login

Mails a single-use sign-in link valid for 15 minutes; a new link invalidates the previous one. The answer is the same 202 whether the email has an account or not. 429 rate-limited beyond the per-address or global limit (the per-email limit sends no mail, silently). 404 when sign-in links are not enabled.

Look at a sign-in link · operationId get_email_link

What the confirmation page shows («Sign in as …»). It never uses the link: mail scanners open links with GET. 410 email-link-expired when it expired, was used or was replaced by a newer one.

POST /auth/email/confirm

Sign in with a sign-in link · operationId confirm_email_login

Uses the link (once) and starts a session: sets __Host-dx_session and dx_csrf like /auth/callback. Requires the application's Origin. With DX_SIGNUP=open the first sign-in of a new email creates its organization. 410 email-link-expired when it expired, was used or was replaced.

POST /auth/logout

Log out · operationId logout · permission authenticated

Destroys the server session and clears the cookies (CSRF header required).

POST /v1/session/context

Choose the active organization and project · operationId set_session_context · permission authenticated

Web sessions only. The organization must be one of the user's memberships; restricted roles can only choose one of their projects.

members

GET /v1/members

List members · operationId list_members · permission member:manage

Members of the organization in joining order (keyset pages).

GET /v1/members/{user_id}

Get a member · operationId get_member · permission member:manage

One member with its ETag (send it in If-Match to change the role).

PATCH /v1/members/{user_id}

Change a member's role · operationId update_member · permission member:manage

Changes the role and/or the project restriction. Requires If-Match (428 without it, 412 when stale). 403 self-role-change, 403 role-escalation, 409 last-owner.

DELETE /v1/members/{user_id}

Remove a member · operationId remove_member · permission member:manage

Removes the user from the organization; its sessions lose access within 5 seconds. 409 last-owner for the only Owner. If-Match is honoured when sent.

invitations

GET /v1/invitations

List invitations · operationId list_invitations · permission member:manage

Invitations of the organization in creation order (keyset pages).

POST /v1/invitations

Invite someone · operationId create_invitation · permission member:manage

Mails an invitation link valid for 7 days. Inviting the same email again revokes the pending invitation. 403 role-escalation when an Admin invites an Owner or Admin; 409 invitation-limit-reached beyond 50 pending invitations.

DELETE /v1/invitations/{invitation_id}

Revoke an invitation · operationId revoke_invitation · permission member:manage

The link stops working at once (410 invitation-expired).

POST /v1/invitations/accept

Accept an invitation · operationId accept_invitation · permission authenticated

Web sessions only: joins the organization of the invitation with its role and projects, and makes it the active organization of the session.

organization

GET /v1/organization

Get the organization · operationId get_organization · permission project:read

The organization of the caller (its id, slug and name).

PATCH /v1/organization

Rename the organization · operationId update_organization · permission org:manage

Changes the display name (Owner or Admin). The slug stays.

packets

POST /v1/packets

Create a packet · operationId create_packet · permission run:create

Uploads 1-100 files as one packet (multipart files[], optional metadata JSON of at most 64 KiB and notes), or imports 1-100 HTTPS URLs (JSON {urls, metadata}): the import runs asynchronously, atomically, and the packet is importing until it is ready or failed (with errors[{url_hash, code}]). Types are decided by content (415), sizes and pages by the project limits (413); duplicate names become a (2).pdf.

GET /v1/packets/{packet_id}

Get a packet · operationId get_packet · permission run:read

The packet and its files (sha256, size, media_type, page_count, source).

DELETE /v1/packets/{packet_id}

Delete a packet (certified) · operationId delete_packet · permission run:create

Crypto-shreds the packet: its files, the artifacts and results of its runs and the rows that describe them are destroyed (a blob another packet still references is retained and listed as such), each store is verified and a signed deletion certificate is issued: 202 with its dcert_id (GET /v1/deletion-certificates/{id}). A project under legal hold answers 409 legal_hold_active; if a store is unavailable the deletion can be retried (503 erasure-retry) and resumes where it stopped.

uploads

POST /v1/uploads

Start a direct upload · operationId create_upload · permission run:create

Opens an upload session for one file of size bytes and answers where to PUT it: a presigned S3 URL, or PUT /v1/uploads/{id}/content?token=… with local storage. Both are valid for 15 minutes; then call complete.

PUT /v1/uploads/{upload_id}/content

Upload the content (local storage) · operationId put_upload_content · permission run:create

Body: the raw bytes of the file. Only with local storage (with S3 the client PUTs to the presigned URL). token comes from POST /v1/uploads and expires in 15 minutes (403 upload-token-expired).

POST /v1/uploads/{upload_id}/complete

Complete a direct upload · operationId complete_upload · permission run:create

Verifies size (422 upload-size-mismatch), checksum_sha256 (422 upload-checksum-mismatch), type and limits, encrypts the content and creates the file (a one-file packet). Repeating it returns the same file.

runs

POST /v1/parse

Parse a document · operationId parse_document · permission run:create

Creates a parse run for one file (multipart file, or JSON packet_id or url): conversion to PDF when needed, DocIR, anchored markdown and page images. Answers 202 with the Run and Location; with ?wait=N (≤ 60 s) it waits for the run.

POST /v1/extract

Extract data from a document · operationId extract_document · permission run:create

Creates an extract run: prepare, parse, extract, verify_score and persist as durable steps. The schema (and optional rules) are validated first (400 with a pointer, no run). A packet with several files is 422 packet-multi-file-unsupported. dedup: reprocess (default), reuse (200 with the previous run, Deduplicated: true) or reject (409 duplicate-document). With ?wait=N (≤ 60 s) a finished run answers 200 with {run, result}.

GET /v1/runs

List runs (the documents table) · operationId list_runs · MCP tool · permission run:read

Runs of the project in keyset pages (no offset: it is a 400), one row per document with its table state (display_status: not_started, queued, in_progress, processed, verified, error, cancelled), version, minimum confidence, failed rules and — for the paths in fields — the effective value of each field. Filters: workflow (wf_… or name), status (a run status or a table state), version (wfv_…), q (finds a value: exact or contained), confidence_lt, rule_failed, purpose (default production: test runs stay out; all lists every one), kind and created_from. sort is created_at (default), finished_at, status, confidence or cost, - for descending.

GET /v1/runs/{run_id}

Get a run · operationId get_run · MCP tool · permission run:read

The Run with its steps (status, time, cost), usage, error, timings and links. ?wait=N (≤ 60 s) waits for it to finish: 200 when it finished, 202 with the current state when the wait expires (or when the project already has 50 waits in progress).

POST /v1/runs/{run_id}:cancel

Cancel a run · operationId cancel_run · MCP tool · permission run:create

Requests cancellation: a queued run never starts, a running one stops at its next step boundary (≤ 5 s for steps that check it). Cancelling a cancelled run is 200 (idempotent); a run that already finished otherwise is 409.

POST /v1/runs/{run_id}:resume

Resume a run · operationId resume_run · permission run:create

Re-runs a failed or cancelled run from the first unfinished step; completed steps are not executed again. Any other status is 409 run-not-resumable.

POST /v1/runs:batch

Resume, re-run or cancel many runs · operationId batch_runs · permission run:create

selection is {mode: include, ids} or {mode: exclude, ids, filter} (every run the filter matches except ids): the server resolves the run ids, the client never sends the list of a big selection. resume retries failed or cancelled runs from the failed step (the cache keeps what finished), rerun creates a new run per selected run (with version_id another version) and cancel stops active runs. A run that cannot take the action is skipped with its reason. Up to 500 runs are acted on before answering (200); a larger selection answers 202 processing.

GET /v1/runs/{run_id}/events

Stream the progress of a run · operationId stream_run_events · permission run:read

Server-sent events (text/event-stream) of the run: run.started, node.started, node.completed, run.succeeded… Each event's SSE id is the run's sequence number (1..N without gaps). Reconnect with Last-Event-ID: k (or ?since=k) to get k+1..N exactly once; the server sends retry: 3000, a : ping comment every 15 s, and closes after the terminal event (run.succeeded, run.partially_succeeded, run.failed, run.cancelled). A project can keep 100 streams open (429 beyond). A run of another project is a 404.

results

GET /v1/runs/{run_id}/result

Get a run's result · operationId get_run_result · MCP tool · permission result:read

format=full (default: {run_id, kind, document{pdoc_id, pages[]}, output} where output follows the output contract of T08), data, fields or flat (path → value). Results above 5 MiB answer {result_url, expires_at, size}: a signed URL valid for 15 minutes.

GET /v1/runs/{run_id}/result/download

Download a large result · operationId download_run_result · permission result:read

Target of result_url: the full result while the token is valid (403 upload-token-expired after 15 minutes).

GET /v1/runs/{run_id}/evidence

Get the evidence of a field · operationId get_run_evidence · MCP tool · permission result:read

The extracted field at path (value, status, confidence) and its evidence (page, anchors, quote, boxes).

GET /v1/runs/{run_id}/document

Get the parsed document · operationId get_run_document · permission result:read

format=docir (DocIR JSON of T02), markdown (anchored markdown: one anchor per line) or blocks (layout blocks).

GET /v1/runs/{run_id}/pages/{n}.png

Get a page image · operationId get_run_page_image · permission result:read

PNG of page n (1-based) with ETag = sha256 and Cache-Control: private, max-age=3600; If-None-Match answers 304.

workflows

GET /v1/workflows

List workflows · operationId list_workflows · MCP tool · permission workflow:read

Workflows of the project ordered by name (keyset pages), each with its aliases (prod -> version number), owner and stats (documents and cost per page of the last 30 days, last run; accuracy_30d and stp_30d are null until a provider registers them). q searches the name (case-insensitive substring), tag keeps the workflows with that tag, archived=true lists only the archived ones and include_archived=true adds them to the active ones.

POST /v1/workflows

Create a workflow · operationId create_workflow · MCP tool · permission workflow:write

Creates an empty workflow. name is the slug used in references such as facturas@prod; it is unique among the project's active workflows.

GET /v1/workflows/{workflow_id}:export

Export a workflow (dx.workflow/v1) · operationId export_workflow · permission workflow:read

The portable document {format, workflow, graph, schemas} of the draft (else the latest published version), or of version_id. The schemas carry every x-dx.field_id, so importing the document again yields the same graph hash.

GET /v1/workflows/{workflow_id}

Get a workflow · operationId get_workflow · MCP tool · permission workflow:read

One workflow with its ETag; If-None-Match with the current ETag answers 304.

PATCH /v1/workflows/{workflow_id}

Update a workflow · operationId update_workflow · permission workflow:write

Changes the name or description. Requires If-Match with the current ETag (428 without it, 412 when stale).

DELETE /v1/workflows/{workflow_id}

Archive a workflow · operationId archive_workflow · MCP tool · permission workflow:write

Archives the workflow (it keeps its versions and aliases, and frees its name). Requires If-Match. Returns the archived workflow.

POST /v1/workflows/{workflow_id}:archive

Archive a workflow (action form) · operationId archive_workflow_action · permission workflow:write

Same as DELETE /v1/workflows/{id}: archives the workflow (versions and aliases stay readable) and frees its name. Requires If-Match.

POST /v1/workflows:import

Import a workflow (dx.workflow/v1) · operationId import_workflow · permission workflow:write

Creates a workflow and its draft from an exported document (field_id are kept). Topology violations do not prevent the import: the draft's report lists them. Errors: 409 WORKFLOW_NAME_TAKEN, 400 INVALID_SCHEMAS (a repeated field_id, an invalid schema).

POST /v1/workflows/{workflow_id}:duplicate

Duplicate a workflow · operationId duplicate_workflow · permission workflow:write

A new workflow with the content of the draft (else the latest published version) of this one, as a draft; field_id are kept. Without name the copy is <name>-copy.

POST /v1/workflows/{workflow_id}:validate

Validate a workflow graph (dry run) · operationId validate_workflow · MCP tool · permission workflow:read

Validates the given graph and schemas (or the current draft when the body is empty) and answers 200 with the full topology report: every violation, not only the first. Nothing is stored.

GET /v1/workflows/{workflow_id}/versions

List the versions of a workflow · operationId list_workflow_versions · MCP tool · permission workflow:read

Drafts, published and archived versions in creation order (keyset pages), without their graphs.

POST /v1/workflows/{workflow_id}/versions

Create the draft of a workflow · operationId create_workflow_version · MCP tool · permission workflow:write

Creates the workflow's draft (one per workflow) from {graph, schemas} or, to restore, from {from_version_id} (the original stays untouched). The draft is stored even with topology violations; the response carries the report.

GET /v1/workflow-versions/{version_id}:diff

Diff two versions · operationId diff_workflow_versions · MCP tool · permission workflow:read

What changed going from against to this version: nodes and edges added, removed or changed, fields added, removed or renamed (same field_id, another key), rules changed and the severity (the semver level of the change).

POST /v1/workflow-versions/{version_id}:publish

Publish a draft · operationId publish_workflow_version · MCP tool · permission workflow:publish

Validates the draft and makes it an immutable version with its graph_hash and semantic version (major when the output contract changes, minor for structural changes, patch for descriptive text; the first is 1.0.0). 400 TOPOLOGY_INVALID lists every violation; 409 NOTHING_TO_PUBLISH when nothing changed.

POST /v1/workflow-versions/{version_id}:archive

Archive a version · operationId archive_workflow_version · permission workflow:publish

Archives a published version, or discards a draft. Refused (409 VERSION_IN_USE) while an alias points at it.

GET /v1/workflow-versions/{version_id}

Get a workflow version · operationId get_workflow_version · MCP tool · permission workflow:read

A version with its graph, schemas, hash and output contract. A draft also carries its topology report. ETag is the revision; If-None-Match answers 304.

PUT /v1/workflow-versions/{version_id}

Save a draft · operationId save_workflow_version · MCP tool · permission workflow:write

Replaces the graph and schemas of a draft (published and archived versions are immutable: 409 version-immutable). Requires If-Match with the draft's ETag; concurrent writers with the same ETag get exactly one 200 and 412 for the rest. Saved even with violations: the response carries the report.

GET /v1/workflows/{workflow_id}/aliases

List the aliases of a workflow · operationId list_workflow_aliases · MCP tool · permission workflow:read

Environment aliases (dev, staging, prod…) and the published version each one points at.

PUT /v1/workflows/{workflow_id}/aliases/{alias}

Point an alias at a version · operationId set_workflow_alias · MCP tool · permission workflow:publish

Creates or moves the alias to a published version of the workflow and records the move in the alias history. 422 ALIAS_TARGET_NOT_PUBLISHED for a draft or an archived version.

DELETE /v1/workflows/{workflow_id}/aliases/{alias}

Remove an alias · operationId delete_workflow_alias · MCP tool · permission workflow:publish

Removes the alias and records the removal in its history.

GET /v1/workflows/{workflow_id}/aliases/{alias}/history

History of an alias · operationId list_workflow_alias_history · MCP tool · permission workflow:read

Every movement of the alias (set, moved, removed) with author and date, oldest first (keyset pages).

overview

GET /v1/overview

Overview of the project · operationId get_overview · permission run:read

Runs and errors of the last 24 hours and pages of the month for the active project (needs run:read).

node-types

GET /v1/node-types

Node types of the workflow graph · operationId list_node_types · MCP tool · permission workflow:read

Every node type the project can use, in palette order, with its typed ports, the JSON Schema of its configuration and the default configuration of a new node. Plugins installed in the project are listed as extra plugin entries.

workflow-runs

POST /v1/runs

Run a workflow · operationId create_workflow_run · MCP tool · permission run:create

Runs a published workflow version on a packet (JSON packet_id) or on uploaded files (multipart files[], which become a packet). workflow is name@alias, name@1.2.0, a wfv_… id or {version_id}; an alias is resolved once, now, and the run keeps that version. Answers 202 with the Run and Location; ?wait=N (≤ 60 s) waits for it. A missing alias is 404 ALIAS_NOT_FOUND; a draft or archived version 422 VERSION_NOT_PUBLISHED.

POST /v1/runs/{run_id}:rerun

Re-run a workflow run · operationId rerun_workflow_run · permission run:create

Creates a new run (trigger.kind = rerun, parent_run_id) on the same packet with another version (workflow; the same version when omitted). Nodes whose configuration and inputs did not change are reused from the cache (cache_hit), parse included while the parse profile is the same. Only finished workflow runs re-run (409 otherwise).

GET /v1/runs/{run_id}/nodes

List the node runs of a workflow run · operationId list_run_nodes · permission run:read

One entry per (node, scope): status (pending, running, waiting, succeeded, failed, skipped with skip_reason, cancelled), attempts, cache key and hit, timings, usage and output references (blob hashes, never document content).

POST /v1/runs/{run_id}/nodes/{node_id}:complete

Complete a review node · operationId complete_run_node · permission run:create

Delivers a human review to the review node waiting in this run (scope scope_key, default _): decision (approve|reject), corrections by field path or a whole extraction. The run leaves waiting_review and continues. Completing a node that is no longer waiting is a no-op (status: noop).

GET /v1/runs/{run_id}/artifacts/{artifact_id}

Download an artifact of a run · operationId download_run_artifact · permission run:read

The bytes of a file a node produced, with ETag = sha256 (If-None-Match answers 304).

GET /v1/runs/{run_id}/classifications

List the classifications of a workflow run · operationId list_run_classifications · permission run:read

What each classify node decided, per scope: label (category id) and label_name, labels (every label a multi-label node activated), the heuristic confidence (not a probability), the ranking, the verified evidence, abstained (below the threshold: the unclassified branch) and hierarchy_path.

GET /v1/runs/{run_id}/segments

List the segments of a workflow run · operationId list_run_segments · permission run:read

The document segments each split node produced: rule_id, partition_value, pages (file_id, file_page, packet_page; they may not be consecutive), boundary_evidence (reason and score per boundary), the confidence (the minimum of its pages and boundaries), status (assigned or unassigned, with unassigned_reason no_rule or low_confidence and suggested_rule_id). id is the scope key of the extractions below the split.

GET /v1/runs/{run_id}/segments/{segment_id}/pdf

Download the PDF of a segment · operationId download_segment_pdf · permission run:read

The pages of the segment, in order, as an independent PDF (from the files of the packet; several files when the pages come from several). It is made on the first request and stored as a run artifact: asking again creates nothing. ETag is the sha256 of the PDF and If-None-Match answers 304. A segment that does not exist, or of another project, is 404.

review

GET /v1/runs/{run_id}/review

Get the review of a run · operationId get_run_review · permission result:read

The effective fields (the immutable extraction with the reviewer's decisions applied), the validations recomputed on them, the state of the review and the counters of the filters (below is the confidence threshold, 0.80 by default). ETag goes in If-Match of every change.

PATCH /v1/runs/{run_id}/fields/{path}

Approve, correct, mark absent or reject a field · operationId decide_run_field · permission review:act

Appends an immutable decision. path is the field's positional path (line_items[2].amount) or stable path (line_items[r2].amount). correct takes a typed value or text (normalized with the T07 normalizers) and optionally the region it was read from; the server resolves the words of the region into kind=human evidence. Answers the recomputed field and validations. Needs If-Match.

POST /v1/runs/{run_id}/rows

Add a table row · operationId add_run_row · permission review:act

Inserts an empty row at index (0..N) of the table table_path; rows have a stable row_id so the overrides of the other rows do not move. Answers the whole review. Needs If-Match.

DELETE /v1/runs/{run_id}/rows/{path}

Delete a table row · operationId delete_run_row · permission review:act

path names the row (line_items[2], line_items[r2]) or any of its fields. Answers the whole review. Needs If-Match.

POST /v1/runs/{run_id}:approve

Verify the document · operationId approve_run_review · permission review:act

Marks the review verified, saves the final snapshot and deposits one review.completed in the outbox (plus one extraction.corrected per corrected field), all in the same transaction. Repeating it changes nothing. A failing blocking rule answers 409 blocking-rule-failing unless acknowledge_blocking is true and a reason is given.

POST /v1/runs/{run_id}:reject

Reject the document · operationId reject_run_review · permission review:act

Marks the review rejected: its data will not be consumed. Idempotent.

GET /v1/runs/{run_id}/review/history

Decisions on a field · operationId get_run_review_history · permission result:read

The immutable decisions on path in order: action, previous and new value, who, when, time spent and the reason code.

GET /v1/review/next

Next run to review · operationId get_next_review · permission result:read

The next run of the workflow (creation order, after after) whose review is not verified or rejected; run_id is null when none is left. T33 replaces this order with the assigned queue.

review-tasks

GET /v1/review-tasks

List review tasks · operationId list_review_tasks · permission result:read

The inbox: tasks of the project, most urgent first (due_at, then id), keyset paginated with cursor. Filters: queue, state (pending = open, in progress or escalated), assignee (me, unassigned or an id), reason, workflow_id, kind.

GET /v1/review-tasks/summary

Counters of the inbox · operationId get_review_tasks_summary · permission result:read

open counts every pending task (open, in progress, escalated): it is what the badge of the sidebar shows. mine counts the tasks assigned to the caller.

GET /v1/review-tasks/{task_id}

Get a review task · operationId get_review_task · permission result:read

One task. An adjudicator task also carries both reviewers' values.

GET /v1/review-tasks/{task_id}/decisions

Decisions made for a task · operationId get_review_task_decisions · permission result:read

What the reviewer of the task decided, applied or not. In a double review each reviewer sees only their own task's decisions: asking for the other's answers 404. Admins see both.

POST /v1/review-tasks/{task_id}:claim

Claim a task · operationId claim_review_task · permission review:act

Takes the task: it becomes in_progress and, if nobody held it, yours. Claiming your own task again changes nothing.

POST /v1/review-tasks/{task_id}:release

Release a task · operationId release_review_task · permission review:act

Gives the task back to the queue (unassigned).

POST /v1/review-tasks/{task_id}:complete

Complete a task · operationId complete_review_task · permission review:act

Verifies (or rejects) the document for this task. The last task of a review wakes the run up: the review node continues with the corrected data and exactly one review.completed is emitted. In a double review the document is verified when both reviewers finish (system:double_review when they agree; an adjudicator task opens when they do not). Completing twice changes nothing.

POST /v1/review-tasks:assign

Assign tasks in batch · operationId assign_review_tasks · permission project:manage

Assigns up to 1 000 pending tasks, listed in task_ids or selected by filter (minus exclude), to one assignee or round-robin over reviewers (by default the members with the Reviewer role or above; the position of each queue is kept, so batches continue where the last stopped). Tasks that are no longer pending are skipped. A task in progress goes back to open for its new assignee.

GET /v1/review-reviewers

Members who can review · operationId list_review_reviewers · permission project:manage

The members with the Reviewer role or above that the project accepts: who a task can be assigned to.

GET /v1/review-metrics

Metrics per reviewer · operationId get_review_metrics · permission result:read

Per reviewer with a task completed in the period: documents per hour (tasks completed / hours of recorded time), percentage of corrected fields and the agreement of their double reviews (matching / compared fields). Each figure comes with the counts it was computed from.

edit

GET /v1/edit-references

List the reference documents of the project · operationId list_edit_references · permission workflow:read

The reference documents (edr_…) a fill_form node can name in reference_ids, newest first, in keyset pages.

POST /v1/edit-references

Upload reference documents for the Edit node · operationId create_edit_references · permission workflow:write

Multipart file (repeat it for up to 5 files): CSV, TXT, MD, RST (UTF-8) or PDF, at most 5 MiB each. A fill_form node names them in reference_ids; their text reaches the model as data, never as instructions. 415 unsupported-media-type for another type, 422 reference-limits for more than 5 files or more than 5 MiB in one.

GET /v1/edit-references/{reference_id}

Get a reference document · operationId get_edit_reference · permission workflow:read

Name, media type, size and sha256 of one reference document of the project.

DELETE /v1/edit-references/{reference_id}

Delete a reference document · operationId delete_edit_reference · permission workflow:write

Removes the row and, when no other row of the tenant uses the same bytes, the blob. A workflow version that still names the id fails its fill_form node with REFERENCE_NOT_FOUND.

POST /v1/edit:preview

Preview the filling of a PDF form · operationId preview_edit · permission run:create

Multipart: file (a PDF, <= 25 MB) or packet_id + file_id, instructions, reference_ids[] (up to 5 ids of /v1/edit-references), output_mode (flattened | editable) and font (sans | serif | mono). Runs detect, match and write without a run, in at most 60 seconds, and returns the EditResult with a preview_id: the PDF is at GET /v1/edit-previews/{id}/pdf and each page at …/pages/{n}.png?boxes=1, both for 15 minutes. The fields are detected from the PDF; no upstream extraction exists here.

GET /v1/edit-previews/{preview_id}/pdf

Download the PDF of a preview · operationId download_edit_preview_pdf · permission run:read

The filled PDF of POST /v1/edit:preview, for 15 minutes (then 404).

GET /v1/edit-previews/{preview_id}/pages/{n}.png

A page of a preview as a PNG · operationId get_edit_preview_page · permission run:read

The filled page rendered at dpi (default 110). With boxes=1 the fields are outlined: blue empty, green filled, orange prefilled and untouched. 404 for a page beyond the document, an expired preview or another project's.

plugins

GET /v1/plugins

List plugins · operationId list_plugins · permission project:read

Node and parser-engine plugins installed on the server, with their manifest, distribution sha256 and their state in the credential's project.

GET /v1/plugins/{plugin_id}

Get a plugin · operationId get_plugin · permission project:read

One installed plugin (404 plugin_not_available when it is not installed).

POST /v1/plugins/{plugin_id}:enable

Enable a plugin in the project · operationId enable_plugin · permission project:manage

Records the installed version and distribution sha256 as approved and enables the plugin. Server profile: 403 plugin_not_allowlisted unless the sha256 is in plugins.allowlist. approved_secrets must be declared by the manifest (422).

POST /v1/plugins/{plugin_id}:disable

Disable a plugin in the project · operationId disable_plugin · permission project:manage

Turns the plugin off in the project; running workflows that use it fail with plugin_not_available and validating them reports PLUGIN_NOT_AVAILABLE.

datasets

GET /v1/datasets

List datasets · operationId list_datasets · permission workflow:read

Datasets of the project in creation order (keyset pages), with the number of items per split. workflow_id lists the datasets of one workflow.

POST /v1/datasets

Create a dataset · operationId create_dataset · permission dataset:write

A named set of ground-truth items of a workflow; a workflow can have several. Splits are 40/20/40 by default (proportions), stratified by tag and deterministic per seed.

GET /v1/datasets/{dataset_id}

Get a dataset · operationId get_dataset · permission workflow:read

One dataset with its number of items per split and the SPLIT_TOO_SMALL warnings.

GET /v1/datasets/{dataset_id}/items

List the items of a dataset · operationId list_dataset_items · permission workflow:read

Keyset pages of the items, filtered by split and tag. The test split is sealed: for the agent, optimizer and calibration contexts split=test is 403 TEST_SPLIT_SEALED and a listing without split leaves test out; a person's read of test is logged in test_split_access.

POST /v1/datasets/{dataset_id}/items

Upload ground-truth pairs · operationId upload_dataset_items · permission dataset:write

Multipart files[] of a.pdf + a.json pairs (the JSON is the ground truth). Every JSON is validated against the output contract of the workflow: if any violates it the whole upload is refused with 422 GT_INVALID listing every violation (pointer, rule) and nothing is created. Files without a pair come back in unpaired. ?dry_run=true validates and creates nothing. A key with a value is labelled, null is absent, a missing key is unlabelled.

GET /v1/datasets/{dataset_id}/items/{item_id}/ground-truth

Get the ground truth of an item · operationId get_item_ground_truth · permission workflow:read

The current version (or ?version=), with its ETag ("v<version>"). The test split is sealed for the agent, optimizer and calibration contexts (403).

PUT /v1/datasets/{dataset_id}/items/{item_id}/ground-truth

Edit the ground truth of an item · operationId update_item_ground_truth · permission dataset:write

Creates version n + 1 (the history keeps the old ones and the snapshots that use them). Requires If-Match with the current ETag (428 without it, 412 when stale). The body is validated against the output contract (422 GT_INVALID).

GET /v1/datasets/{dataset_id}/items/{item_id}/ground-truth/history

History of the ground truth of an item · operationId get_item_ground_truth_history · permission workflow:read

Every version of the ground truth, oldest first, with who changed it, when and why. The test split is sealed for the agent, optimizer and calibration contexts (403).

GET /v1/datasets/{dataset_id}/tags

Tags of a dataset · operationId get_dataset_tags · permission workflow:read

Item count per tag, untagged and total (an item with several tags counts once in each).

GET /v1/datasets/{dataset_id}/subsets

List the sub-datasets of a dataset · operationId list_dataset_subsets · permission workflow:read

The saved filters of the dataset with the number of items each one selects.

POST /v1/datasets/{dataset_id}/subsets

Create a sub-dataset · operationId create_dataset_subset · permission dataset:write

A saved filter over the items (tags_all, tags_any, splits): a sub-dataset is a view, not a copy, and can be snapshotted (POST …/snapshots with subset_id).

GET /v1/datasets/{dataset_id}/snapshots

List the snapshots of a dataset · operationId list_dataset_snapshots · permission workflow:read

Keyset pages of the snapshots in creation order.

POST /v1/datasets/{dataset_id}/snapshots

Snapshot a dataset · operationId create_dataset_snapshot · permission dataset:write

Freezes the items (or a sub-dataset's) with their ground-truth version, split and tags under a content_hash (SHA-256 of the RFC 8785 form of the sorted list). Asking again without changes returns the same snapshot with 200; a new one is 201.

GET /v1/datasets/{dataset_id}/snapshots/{snapshot_id}

Get a snapshot · operationId get_dataset_snapshot · permission workflow:read

One snapshot with its content_hash, item_ids and item_refs ({item_id, gt_version}).

POST /v1/datasets/{dataset_id}:resplit

Re-split a dataset · operationId resplit_dataset · permission dataset:write

Deals every item again (new seed unless seed is given). reason is mandatory and a new snapshot is created: existing snapshots keep their hash, ground truth and splits. Outside a re-split no existing item ever changes split.

GET /v1/datasets/{dataset_id}/test-split-access

Reads of the sealed test split · operationId list_test_split_access · permission workflow:read

Who read the items or ground truth of test, as which context, why and when.

POST /v1/datasets/{dataset_id}/items:promote

Promote a verified run to a dataset · operationId promote_run_to_dataset · permission dataset:write

Turns a document verified in production into a ground-truth item: the values are the effective result of the review (approved and corrected fields are labelled, fields marked absent are absent) and the item keeps its own copy of the document, so deleting the production packet does not touch it. 409 PROMOTION_INCOMPLETE while the document is not verified or a field is still needs_review (errors[].pointer names each one: /fields/<path>, /state). Idempotent per (dataset, run): promoting the same run again returns the existing item with 200.

evaluations

GET /v1/evaluations

List evaluations · operationId list_evaluations · permission workflow:read

Evaluations of the project in creation order (keyset pages); workflow_id and status filter; version_id keeps the evaluations of that workflow version (the Studio's publish dialog asks for one).

POST /v1/evaluations

Start an evaluation · operationId create_evaluation · permission eval:run

Evaluates a published version (version_id or alias) on one or more snapshots (snapshot_ids) and a scope (splits, tags). Returns 202 with the evaluation (queued) and its number (#1, #2… per workflow). Each item runs as a run of the workflow with trigger eval; the results are immutable once completed. A scope with test needs confirm_test=true and is logged in test_split_access; the optimizer, agent and calibration contexts get 403 TEST_SPLIT_SEALED.

GET /v1/evaluations:compare

Compare two evaluations · operationId compare_evaluations · permission workflow:read

Paired comparison of two completed evaluations of the same snapshots and scope (delegated to the evaluation harness): differences a - b of field accuracy, F1 and hallucination with paired bootstrap intervals, the difference of perfect documents, and the exact McNemar test with Holm's correction (a_only, b_only, p_value). 422 SNAPSHOTS_DIFFER when they were not made on the same snapshots.

GET /v1/evaluations/{evaluation_id}

Get an evaluation · operationId get_evaluation · permission workflow:read

One evaluation with its status, number, metrics with bootstrap intervals and, once completed or failed, immutable: true.

GET /v1/evaluations/{evaluation_id}/fields

Expected versus obtained, per field · operationId list_evaluation_fields · permission workflow:read

Keyset pages of every scored field: expected, obtained, class (correct, omission, hallucination, wrong_value, format_only), confidence and citation verdict. Filter by class, tag, path, split. unlabelled fields have no row (they are in no denominator). Ground truth of the sealed test split is withheld from the sealed contexts.

GET /v1/evaluations/{evaluation_id}/items

Results per item · operationId list_evaluation_items · permission workflow:read

Keyset pages of the per-item results (accuracy, perfect, failed runs, duplicate_across_datasets and, for segmented items, the partition scores). Filter by tag, split and status.

GET /v1/evaluations/{evaluation_id}/tags

Accuracy per tag · operationId list_evaluation_tags · permission workflow:read

Field accuracy, support and perfect-document rate of each tag of the evaluated items (split:<name> tags break the result down by split).

GET /v1/evaluations/{evaluation_id}/error-matrix

Error matrix by field and error class · operationId get_evaluation_error_matrix · permission workflow:read

Per field, how many scored instances are correct, format_only (right after normalization), omission, hallucination or wrong_value; errors is the sum of the deviations (everything but correct), as in metrics.per_field[].errors. unlabelled fields are in no denominator.

GET /v1/evaluations/{evaluation_id}/reliability

Reliability diagram of the confidence · operationId get_evaluation_reliability · permission workflow:read

15 equal-mass bins of the field confidence with mean confidence, accuracy, a 95 % Clopper-Pearson interval and n, the ECE and the noise floor (the ECE a perfectly calibrated evaluator would show with this n). scores_kind=heuristic means the confidence is a score, not a probability. An evaluation without confidence answers n: 0.

GET /v1/evaluations/{evaluation_id}/risk-coverage

Risk-coverage curve · operationId get_evaluation_risk_coverage · permission workflow:read

Accepting the most confident fields first, the error rate among the accepted ones for each coverage (at most 200 points, by increasing coverage) and the area under the curve. Descriptive: it gates nothing.

GET /v1/evaluations:compare-details

Differences of two evaluations by field and by document · operationId compare_evaluations_details · permission workflow:read

For two completed evaluations of the same snapshots and scope (422 SNAPSHOTS_DIFFER otherwise): the accuracy difference a - b overall and per field with a paired bootstrap 95 % interval over the documents, the smallest difference the comparison could detect (5 %, 80 % power), the documents where B is worse and the McNemar minimum detectable difference of the perfect documents. Complements /v1/evaluations:compare.

optimizations

GET /v1/optimizations

List optimizations · operationId list_optimizations · permission workflow:read

Optimizations of the project in creation order (keyset pages); workflow_id and status filter.

POST /v1/optimizations

Start an optimization · operationId create_optimization · permission eval:run

Optimizes the field descriptions of a published workflow version on the train/validation splits of a dataset snapshot: up to budget.max_rounds rounds, each writing a draft candidate and accepting it only if the lower bound of the paired bootstrap interval of the validation F1 gain is above 0 and no label regresses. budget.max_cost_usd and budget.max_rounds are mandatory. Returns 202 with the optimization (queued). With fewer than 10 train, 20 validation or 20 test items the answer is 409 OPTIMIZATION_INSUFFICIENT_DATA unless acknowledge_low_data is true (then a LOW_DATA warning is kept). one_shot proposes one unmeasured improvement from 1-5 sample runs. Nothing published is ever written.

GET /v1/optimizations/{optimization_id}

Get an optimization · operationId get_optimization · permission workflow:read

One optimization with its rounds (proposal, candidate draft, scores on train and validation, verdict and rejection reason), the budget spent, the suspect ground-truth fields, the test report once it exists and the state of its strategy (experimental|validated). The screen refetches every 2 seconds until completed.

POST /v1/optimizations/{optimization_id}:cancel

Cancel an optimization · operationId cancel_optimization · permission eval:run

Cooperative: checked between documents and between rounds, so it takes effect within seconds. The drafts already written are kept, nothing is promoted and the published version and the aliases stay as they were. 409 once it has finished.

POST /v1/optimizations/{optimization_id}:promote

Promote the winner of an optimization · operationId promote_optimization · permission workflow:publish

Publishes the winning draft as an immutable version (a patch bump) and moves alias to it, emitting workflow.version.published and optimization.completed. Only a person or an API key with approval promotes: the agent context gets 403 AGENT_CANNOT_PROMOTE. It needs the test report, or acknowledge_unmeasured=true (409 NO_TEST_REPORT otherwise). The confidence calibrators of the workflow are invalidated by the new prompt: recalibrate (T39) after promoting.

lookup-tables

GET /v1/lookup-tables

List reference tables · operationId list_lookup_tables · MCP tool · permission workflow:read

Tables of the project in creation order (keyset pages).

POST /v1/lookup-tables

Create a reference table · operationId create_lookup_table · permission workflow:write

Multipart {name, description?, key_column, file}: a CSV (UTF-8 with or without BOM, , ; or tab) or Parquet file. Creates version 1, immutable and named by its sha256. key_column must be unique (422 lookup-duplicate-keys); more than 500 000 rows or 100 MB is 413 lookup-too-large.

GET /v1/lookup-tables/{table_id}

Get a reference table · operationId get_lookup_table · MCP tool · permission workflow:read

One table with its ETag (used by the PATCH).

PATCH /v1/lookup-tables/{table_id}

Rename or describe a reference table · operationId update_lookup_table · permission workflow:write

Only name and description change; versions never do. Requires If-Match with the current ETag (428 without it, 412 when stale).

GET /v1/lookup-tables/{table_id}/versions

List the versions of a table · operationId list_lookup_table_versions · MCP tool · permission workflow:read

Versions in creation order (keyset pages).

POST /v1/lookup-tables/{table_id}/versions

Upload a new version · operationId create_lookup_table_version · permission workflow:write

Multipart file. The same content as an existing version is a 200 with created=false (versions are named by content); new content is a 201 with the next number.

GET /v1/lookup-tables/{table_id}/versions/{version}

Get a version (and its first rows) · operationId get_lookup_table_version · MCP tool · permission workflow:read

latest resolves to a number; ?preview=N adds the first N rows (at most 100).

POST /v1/lookup-tables/{table_id}/versions/{version}:match

Score candidate rows for a query (no model) · operationId match_lookup_table_version · MCP tool · permission workflow:read

Returns up to k candidates with their match scores, best first; complete means every queried column reached threshold. No model is called and nothing is stored.

exports

GET /v1/exports

List exports · operationId list_exports · permission result:read

The project's exports, newest first. status=pending lists the ones still building (pending or running): the notification bell polls it every 2 s.

POST /v1/exports

Export the runs of a workflow · operationId create_export · permission result:read

Creates an export job and answers 202 immediately (even for 10 000 runs). format is csv, xlsx, json, jsonl or markdown_zip; filters are the documents table's (status, version, q, confidence_lt, rule_failed); the values are the effective ones, with the reviewers' corrections. columns limits the fields (visible: the ones the user shows); layout documents is one row per run and rows one per table row. Poll GET /v1/exports/{id}: ready has a download link, failed says why.

GET /v1/exports/{export_id}

Get an export · operationId get_export · permission result:read

The job: pending, running, ready (with download) or failed (with its error).

GET /v1/exports/{export_id}/download

Download an export · operationId download_export · permission result:read

The finished file (Content-Disposition: attachment). 409 export-not-ready while it is pending, running or failed.

GET /v1/workflows/{workflow_id}/documents/columns

Columns a user shows in the documents table · operationId get_document_columns · permission workflow:read

columns: the field paths the calling user chose to show, in order (null until they pick); available: every scalar field and table the workflow's runs have.

PUT /v1/workflows/{workflow_id}/documents/columns

Choose the columns of the documents table · operationId set_document_columns · permission workflow:read

Stores the columns the calling user shows for this workflow; an export with columns: visible uses them.

governance

GET /v1/projects/{project_id}/retention

Get the retention policy of a project · operationId get_retention · permission project:read

TTLs, ZDR and legal hold of the project, and zdr_required (the flag the policy resolver reads).

PUT /v1/projects/{project_id}/retention

Set the retention policy of a project · operationId put_retention · permission project:manage

Replaces the TTLs and the ZDR of the project (delete_after_hours 1-168, default 24; TTLs 1-36500 days). Out-of-range values are 422. The legal hold has its own endpoint.

POST /v1/projects/{project_id}/legal-hold

Set or lift the legal hold of a project · operationId set_legal_hold · permission project:manage

While the hold is active nothing of the project is deleted: the retention sweep skips it and DELETE /v1/packets/{id} answers 409 legal_hold_active. A reason is mandatory to activate it.

GET /v1/deletion-certificates

List deletion certificates · operationId list_deletion_certificates · permission audit:read

Certificates of the credential's project, oldest first (keyset pages).

GET /v1/deletion-certificates/{certificate_id}

Get a deletion certificate · operationId get_deletion_certificate · permission audit:read

The signed certificate file {certificate, signature}: canonical JSON (RFC 8785) and a detached JWS (RFC 7515 Appendix F). Verify it offline with extractit cert verify and /.well-known/dx-deletion-jwks.json. It proves what the operator asserts about its own stores and keys, not the absence of copies it does not control.

GET /.well-known/dx-deletion-jwks.json

Public keys that verify deletion certificates · operationId deletion_jwks

JWKS with the public keys of the deletion signer, including every historical kid. No authentication; never a private key.

GET /.well-known/dx-audit-jwks.json

Public keys that verify audit checkpoints · operationId audit_jwks

JWKS with the public keys of the audit-checkpoint signer, including every historical kid. No authentication; never a private key.

GET /v1/audit/verify

Verify the audit chain of the organization · operationId verify_audit_chain · permission audit:read

Recomputes every hash of the organization's chain and checks the signed checkpoints. first_break_seq and reason say where and why it breaks; anchored is false when the checkpoints are not in WORM storage (no Object Lock).

GET /v1/audit/checkpoints

List the signed checkpoints of the audit chain · operationId list_audit_checkpoints · permission audit:read

Checkpoints of the organization in seq_to order, with anchored.

GET /v1/audit-events/export

Export the audit chain as NDJSON · operationId export_audit_events · permission audit:read

One JSON object per line: event records (with seq, prev_hash, event_hash), checkpoint records (detached JWS) and a final head. With the JWKS of /.well-known/dx-audit-jwks.json, extractit audit verify --export FILE --jwks FILE verifies it offline.

schemas

POST /v1/schemas:normalize

Validate and normalize an extraction schema (dry run) · operationId normalize_schema · permission workflow:read

Runs the validator of the schema dialect (T02) and answers 200 with every violation (errors[] with pointer, rule and message) and, when there are none, the schema with an x-dx.field_id on every field. Ids already in the schema are kept; with previous_schema, a field without an id that matches it by name (or by position after a rename) keeps its id. Nothing is stored.

POST /v1/schemas:import

Import a JSON Schema or the output of Model.model_json_schema() · operationId import_schema · permission workflow:read

Converts a JSON Schema into the dialect: local $defs and $ref are inlined, anyOf [X, null] becomes an optional field and keywords the dialect does not know are reported in errors[]. Code is never executed: Python source is 422 PYTHON_SOURCE_NOT_ACCEPTED.

rules

POST /v1/rules:validate

Validate a rule (dry run) · operationId validate_rule · permission workflow:read

Parses the rule with the ValidationRule model of the engine (T09: the 15 Check types, RE2 patterns, CEL syntax) and, with context.schema, resolves every reference by field_id, path or name. Answers 200 with every error (pointer, rule, message, position for CEL) and, when there are none, the rule with its references rewritten to field_id. Nothing is stored.

POST /v1/rules:estimate

Estimate the cost of the AI rules · operationId estimate_rules · permission workflow:read

Tokens of the prompt and of the cited fields times the input price plus the maximum output times the output price, from the price table of the capability registry. It is an estimate by length (about 4 characters per token); the real cost comes with :test. Deterministic rules cost nothing.

POST /v1/rules:test

Test rules on up to 20 runs · operationId test_rules · permission workflow:write

Evaluates the rules on the stored extraction of each run (nothing is extracted again): pass, fail, inconclusive (a missing field) or skipped (applies_when is false). Deterministic rules use the pure evaluator; AI rules call the model gateway. When the estimated cost of the AI rules over the runs is above max_usd the answer is 422 budget-exceeded and no model is called.

calibration

POST /v1/calibrators:fit

Fit calibrators from evaluations · operationId fit_calibrators · permission eval:run

Fits one calibrator per field type with at least 300 fields and 30 errors and one global per model snapshot (Platt below 3 000 fields or 200 errors, isotonic above) on the train rows of completed evaluations, and gates each on the validation documents (adaptive ECE ≤ noise floor + 0.01; with 1 000 fields or more, ≤ 0.03 and AUROC ≥ 0.85). Returns the new calibrators (fitted or rejected) and the segments skipped for lack of data.

GET /v1/calibrators

List calibrators · operationId list_calibrators · permission workflow:read

Calibrators of the project in creation order (keyset pages); filter by workflow_id, status and field_type.

POST /v1/calibrators/{calibrator_id}:activate

Activate a calibrator · operationId activate_calibrator · permission workflow:publish

Makes a fitted calibrator the active one of its segment (field type and model snapshot) and archives the previous one. Runs with that snapshot and prompt hash then report kind = calibrated_probability. 409 CALIBRATOR_STATE for a rejected, stale or archived calibrator.

POST /v1/calibrators/{calibrator_id}:archive

Archive a calibrator · operationId archive_calibrator · permission workflow:publish

Archives a calibrator: it is no longer applied (idempotent).

POST /v1/threshold-policies:certify

Certify auto-approval thresholds · operationId certify_threshold_policy · permission eval:run

Certifies, per field type, the lowest threshold of the fixed grid (0.50…0.99, 0.995, 0.999; its sha256 is grid_hash) whose selective error is at most alpha with probability 1 - delta, with exact binomial p-values on the calibrated probabilities of the validation split (at least 1 000 fields per type) and a fixed sequence starting at the lowest threshold whose risk on train is ≤ alpha/2. The final threshold is max(cost threshold, certified threshold). Heuristic scores give 422 NOT_CALIBRATED and create nothing.

GET /v1/threshold-policies

List threshold policies · operationId list_threshold_policies · permission workflow:read

Threshold policies of the project in creation order (keyset pages); filter by workflow_id and status.

POST /v1/threshold-policies/{policy_id}:tighten

Tighten a threshold policy · operationId tighten_threshold_policy · permission workflow:publish

Moves every threshold one grid step up and marks the policy needs_recertification; only a new certification relaxes it. 409 POLICY_STATE for an invalidated policy or a threshold at the top of the grid.

POST /v1/threshold-policies/{policy_id}:invalidate

Invalidate a threshold policy · operationId invalidate_threshold_policy · permission workflow:publish

Retires the policy: no document is auto-approved under it (idempotent).

POST /v1/audit-samples:consider

Consider an auto-approved run for the audit · operationId consider_audit_sample · permission review:act

Records an auto-approved run and selects it for the audit with probability pi (the workflow's rate, 2 % by default) by HMAC-SHA256 of its id under the workflow's secret seed. A selected run gets an audit.sampled event and an audit task. Idempotent per run; a decision that is not an auto-approval is not recorded (considered: false).

GET /v1/audit-samples

List audit samples · operationId list_audit_samples · permission result:read

Runs considered for the audit in creation order (keyset pages), with stratum, pi and whether they were selected; filter by workflow_id, selected and run_id.

learning

GET /v1/routing-runs

List routing runs · operationId list_routing_runs · permission workflow:read

Routing runs of the project in creation order; filter by workflow_id.

POST /v1/routing-runs

Start a per-field routing search · operationId create_routing_run · permission eval:run

Groups the fields of the base version's extract node by type and difficulty (≥ 50 validation instances per group), tries the routes tier x model of the capability registry cheaper than the base in increasing cost on validation and keeps the first whose Wilson lower bound of accuracy reaches base - min_accuracy_drop (no_feasible_cheaper_route otherwise). The routed candidate is saved as a draft with field_routes; one evaluation on test decides promotable (paired lower bound ≥ -1 point and ≥ 10 % cheaper per 1 000 pages). Returns 202 with the run (queued).

GET /v1/routing-runs/{routing_run_id}

Get a routing run · operationId get_routing_run · permission workflow:read

Status, spend (sum of the calls tagged with the run), groups, policy and verdict.

POST /v1/routing-runs/{routing_run_id}:cancel

Cancel a routing run · operationId cancel_routing_run · permission eval:run

Asks the search to stop: it stops before its next probe (cooperative). 409 ROUTING_RUN_STATE for a finished run.

POST /v1/routing-runs/{routing_run_id}:promote

Promote a routing run · operationId promote_routing_run · permission workflow:publish

Publishes the routed draft and moves alias to it. Only a person (a web session) may promote, only a promotable run, and once; the run keeps needs_recalibration = true (recalibrate the confidence, T39).

POST /v1/learning/examples:harvest

Harvest examples from corrections · operationId harvest_learned_examples · permission eval:run

Turns the corrections of verified reviews of the workflow's runs into candidate examples: the corrected value with the field's evidence (extract) or the corrected label with the first page (classify, ≤ 800 tokens). At most 5 per document; examples with cosine ≥ 0.95 count once. Idempotent per review decision.

GET /v1/learning/examples

List learned examples · operationId list_learned_examples · permission workflow:read

Learned examples of the project in creation order; filter by workflow, node, kind and status.

POST /v1/learning/gate

Run the few-shot gate · operationId run_learning_gate · permission eval:run

Evaluates the dataset snapshot's sealed test split twice (context learning, logged in test_split_access): without examples and with the 3 most similar per document, never from the document's packet, from packets of the snapshot or near-duplicates (cosine ≥ 0.95). The examples become active (an ExampleSnapshot and a draft that references it) only if the paired lower bound of the improvement is > 0, no field loses > 1 point, hallucination grows ≤ 0.2 points and the cost stays ≤ 110 %. One attempt per set of examples (409 GATE_ALREADY_RUN); fewer than 20 examples or test items is 422.

GET /v1/learning/snapshots/{snapshot_id}

Get an example snapshot · operationId get_example_snapshot · permission workflow:read

The frozen examples a version references, their hash and status.

POST /v1/learning/snapshots/{snapshot_id}:activate

Activate an example snapshot · operationId activate_example_snapshot · permission workflow:publish

Re-activates a disabled snapshot: a new draft references it (409 SNAPSHOT_STATE for a stale or active one).

POST /v1/learning/snapshots/{snapshot_id}:disable

Disable an example snapshot · operationId disable_example_snapshot · permission workflow:publish

Stops using an active snapshot: its examples become disabled and a new draft has no snapshot on the node.

meta

GET /v1/meta

Server edition and features · operationId get_meta · permission authenticated

The edition of this server (community or ee), the core version and the features the installed extensions declare. Any authenticated credential may read it.

agent

GET /v1/agent/sessions

List agent sessions · operationId list_agent_sessions · permission workflow:read

Sessions of the project with status, goal, cost and last activity.

POST /v1/agent/sessions

Open a builder agent session · operationId create_agent_session · permission workflow:write

A conversation with the builder agent about one workflow: workflow_id to edit an existing one, or workflow_name for the one it will create on the first approval. max_cost_usd defaults to DX_AGENT_MAX_COST_USD (1.00).

GET /v1/agent/sessions/{session_id}

Get an agent session · operationId get_agent_session · permission workflow:read

The session with its whole history (messages), attachments, ChangeSets and budget. Clients rebuild a conversation from here after a reload or a lost stream.

PATCH /v1/agent/sessions/{session_id}

Change an agent session · operationId update_agent_session · permission workflow:write

Raise (or lower) max_cost_usd — the only way to continue a session whose budget is exhausted —, rename it or close it.

GET /v1/agent/sessions/{session_id}/actions

List the actions of an agent session · operationId list_agent_actions · permission workflow:read

Every tool call, model call and proposal with arguments, result (or result_ref for large ones), error, cost, model call ids and approval state.

POST /v1/agent/sessions/{session_id}/messages

Send a message to the agent (SSE) · operationId post_agent_message · permission workflow:write

Runs one turn (at most 12 steps) and streams it as text/event-stream. Only content and attachments (≤ 3 packets) are read; any other field (a forged history or approval) is ignored. 409 AGENT_BUDGET_EXHAUSTED before streaming when the budget is spent; 422 AGENT_LIMIT_EXCEEDED for a fourth attachment.

GET /v1/change-sets/{change_set_id}

Get a ChangeSet · operationId get_change_set · permission workflow:read

Ops, RFC 6902 patch, validation, evidence, risk flags, status and approval.

POST /v1/change-sets/{change_set_id}:approve

Approve and apply a ChangeSet · operationId approve_change_set · permission workflow:write

Only a person (or an API key with workflow:write); the agent actor gets 403. patch_hash must be the hash of the reviewed patch (403 APPROVAL_MISMATCH otherwise, also when the stored patch changed after approval). Flags new_egress, code_node and secret_reference must be in acknowledge_risks (422 RISKS_NOT_ACKNOWLEDGED). Applies by CAS on the draft revision: 409 CHANGESET_BASE_CHANGED when it drifted (nothing applied; rebased_change_set_id when the patch still applies). Writes a new draft revision; never publishes or moves an alias. Approving an applied ChangeSet again answers the same result. With the project policy require_evidence_before_approval on, a ChangeSet without measured before/after evidence answers 409 EVIDENCE_REQUIRED; with it off the approval is allowed and records evidence: none.

POST /v1/change-sets/{change_set_id}:reject

Reject a ChangeSet · operationId reject_change_set · permission workflow:write

Nothing is applied; the agent can propose again.

GET /v1/run-requests/{run_request_id}

Get a run request · operationId get_run_request · permission workflow:read

One evaluation or optimization the agent asked for: estimated cost, documents, status and, once started, the evaluation or optimization it created. A started request moves to done when its evaluations or optimization finish.

POST /v1/run-requests/{run_request_id}:approve

Approve a run request and start it · operationId approve_run_request · permission workflow:write

Only a person (or an API key with workflow:write); the agent actor gets 403. Starts the evaluation (trigger agent) or the optimization, whose max_cost_usd is capped to the approved amount. 409 RUN_REQUEST_NOT_PENDING when it was decided already.

POST /v1/run-requests/{run_request_id}:reject

Reject a run request · operationId reject_run_request · permission workflow:write

Nothing runs. Only a person (or an API key with workflow:write).

GET /v1/agent/policy

Get the agent policy of the project · operationId get_agent_policy · permission workflow:read

require_evidence_before_approval (default false: approving without evidence is allowed and marked evidence: none), the cost threshold (2.00 USD) and the document count (20) above which an evaluation needs approval.

PATCH /v1/agent/policy

Update the agent policy of the project · operationId update_agent_policy · permission workflow:write

Only a person (or an API key with workflow:write).

model-policy

GET /v1/org/model-policy

Get the organization's model policy · operationId get_org_model_policy · permission project:manage

The organization layer of the model policy (the default policy, revision 0, while none was stored).

PUT /v1/org/model-policy

Set the organization's model policy · operationId put_org_model_policy · permission org:manage

Replaces the organization layer. Projects and nodes can only tighten it.

GET /v1/projects/{project_id}/model-policy

Get a project's model policy · operationId get_project_model_policy · permission project:manage

The project layer of the model policy.

PUT /v1/projects/{project_id}/model-policy

Set a project's model policy · operationId put_project_model_policy · permission project:manage

Replaces the project layer; merged with the organization's it can only tighten.

POST /v1/model-policy/resolve

Resolve the effective model policy · operationId resolve_model_policy · permission workflow:write

Merges platform, organization, project and node policies (only ever tighter) and returns the route the resolver picks, its fallbacks and every discarded candidate with its reason. Deterministic: the same inputs give the same route and policy_hash. With workflow_version_id, nodes holds the answer of every model node of that version.

provider-credentials

GET /v1/provider-credentials

List BYOK provider keys · operationId list_provider_credentials · permission project:manage

Credentials of the project: metadata only (last4, fingerprint, status).

POST /v1/provider-credentials

Store a BYOK provider key · operationId create_provider_credential · permission project:manage

Seals the key with the tenant data key (AAD: organization, project and credential) and answers 201 with its id, last4 and fingerprint. The secret is never returned or logged.

GET /v1/provider-credentials/{credential_id}

Get a BYOK provider key · operationId get_provider_credential · permission project:manage

Metadata of one credential; never the secret.

DELETE /v1/provider-credentials/{credential_id}

Revoke a BYOK provider key · operationId revoke_provider_credential · permission project:manage

Destroys the sealed key; model calls that would use it fail closed from the next call on (also in the middle of a run).

POST /v1/provider-credentials/{credential_id}/test

Test a BYOK provider key · operationId test_provider_credential · permission project:manage

Opens the sealed key and, when the deployment configures a provider check, asks the provider to accept it. Nothing about the key is returned.

webhooks

GET /v1/webhook-events

List the webhook event types · operationId list_webhook_events · permission project:read

Every event a webhook can subscribe to, with its description and the JSON Schema of its data object (ids only, never document content).

GET /v1/webhooks

List webhook endpoints · operationId list_webhooks · permission project:read

Endpoints of the project with their state and last delivery (no secrets).

POST /v1/webhooks

Create a webhook endpoint · operationId create_webhook · permission webhook:manage

Registers an HTTPS URL. The URL must resolve only to public addresses (400 otherwise). The response carries the whsec_ secret once; it is stored sealed and never returned again.

GET /v1/webhooks/{webhook_id}

Get a webhook endpoint · operationId get_webhook · permission project:read

One endpoint with its state; the secret is never returned.

PATCH /v1/webhooks/{webhook_id}

Update a webhook endpoint · operationId update_webhook · permission webhook:manage

Changes the URL, filters, description or enabled flag. Enabling an endpoint that the system disabled (HTTP 410, five abandoned deliveries) clears the reason and the failure streak.

DELETE /v1/webhooks/{webhook_id}

Delete a webhook endpoint · operationId delete_webhook · permission webhook:manage

Deletes the endpoint, its deliveries and their attempts.

POST /v1/webhooks/{webhook_id}:rotate-secret

Rotate the signing secret · operationId rotate_webhook_secret · permission webhook:manage

Generates a new secret and returns it once. For overlap_hours (0-168, default 24) every delivery carries two signatures — new and previous — so the receiver can switch without losing events; afterwards only the new one.

POST /v1/webhooks/{webhook_id}:test

Send a test event · operationId test_webhook · permission webhook:manage

Creates a delivery of webhook.ping; follow it in the delivery log.

GET /v1/webhooks/{webhook_id}/deliveries

List the deliveries of a webhook · operationId list_webhook_deliveries · permission project:read

Newest first, keyset-paginated. Each entry has its state, number of attempts and the status, duration and error of the last one.

GET /v1/webhooks/{webhook_id}/deliveries/{delivery_id}

Get a delivery with its attempts · operationId get_webhook_delivery · permission project:read

The delivery, the exact signed body and every attempt (time, status, duration, error).

POST /v1/webhooks/{webhook_id}/deliveries/{delivery_id}:redeliver

Redeliver an event · operationId redeliver_webhook_delivery · permission webhook:manage

Creates a new delivery of the same event with the same webhook-id and body (receivers deduplicate by webhook-id).

notification-channels

GET /v1/notification-channels

List notification channels · operationId list_notification_channels · permission webhook:manage

Channels of the project with their non-secret settings.

POST /v1/notification-channels

Create a notification channel · operationId create_notification_channel · permission webhook:manage

Registers a channel that notify nodes reference by name. The configuration is validated (Teams hosts, at most 10 email recipients, SSRF-safe webhook URL: 400) and stored sealed. A webhook channel returns its whsec_ secret once.

GET /v1/notification-channels/{channel_id}

Get a notification channel · operationId get_notification_channel · permission webhook:manage

One channel; tokens, passwords and secrets are never returned.

PATCH /v1/notification-channels/{channel_id}

Update a notification channel · operationId update_notification_channel · permission webhook:manage

Renames it or replaces its whole configuration (validated like on create; a webhook channel keeps its secret).

DELETE /v1/notification-channels/{channel_id}

Delete a notification channel · operationId delete_notification_channel · permission webhook:manage

Deletes the channel; nodes that name it fail validation on their next publish.

POST /v1/notification-channels/{channel_id}:test

Send a test message · operationId test_notification_channel · permission webhook:manage

Sends a message prefixed [TEST] through the channel (it counts against the rate limit). With dry_run=true nothing is sent: the response shows the rendered subject and body.

monitoring

GET /v1/workflows/{workflow_id}/metrics

Production metrics of a workflow by version · operationId get_workflow_metrics · permission workflow:read

Production runs finished in [from, to) (default: the last 30 days, at most 90): STP, review rate, error rate, accuracy from corrections (Wilson 95 %), cost per document and page, latency p50 and p95 (nearest rank), a 10-bin confidence histogram with its kind and the published-version markers. Test, evaluation, optimizer and learning runs are excluded. Buckets are UTC. Undefined metrics are null.

GET /v1/workflows/{workflow_id}/monitoring/quality

Silent error, drift and threshold policy of a workflow · operationId get_workflow_monitoring_quality · permission workflow:read

The silent-error estimate among auto-approved fields from the random audit (inverse-inclusion-probability ratio, Clopper-Pearson upper bound with equal pi, stratified bootstrap otherwise), the error of accepted documents, calibration drift (PSI over 7 days against the policy's reference histogram, rolling ECE over 30 days against the noise floor) and the state of the threshold policy. With fewer than 300 labelled fields the values are null with reason.

GET /v1/workflows/{workflow_id}/monitoring/reliability

Production reliability diagram of a workflow · operationId get_workflow_monitoring_reliability · permission workflow:read

15 equal-mass bins with 95 % Clopper-Pearson intervals over the audited auto-approved fields (unbiased: the audit is random). scores_kind is heuristic when no calibrator produced the scores: a heuristic score is not a probability. calibrator_id restricts the diagram to the fields scored by that calibrator.

GET /v1/workflows/{workflow_id}/alerts

List the alert rules and their latest firings · operationId list_workflow_alerts · permission workflow:read

The alert rules of the workflow with their state, and the latest 50 firings, newest first.

POST /v1/workflows/{workflow_id}/alerts

Create an alert rule · operationId create_workflow_alert · permission workflow:write

A threshold on a monitoring metric. It fires one event when the metric crosses the threshold and re-arms when it recovers; it does not repeat while the metric stays on the wrong side.

DELETE /v1/workflows/{workflow_id}/alerts/{rule_id}

Delete an alert rule · operationId delete_workflow_alert · permission workflow:write

Deletes the rule and its firings.

connections

GET /v1/connection-kinds

List connection kinds · operationId list_connection_kinds · permission project:read

Per kind: the JSON Schema of its configuration, its secret (write-only) fields and its OAuth provider, if any. The Settings page draws its forms from this.

GET /v1/connections

List connections · operationId list_connections · permission project:read

Connections of the project: configuration without secrets, state and last error.

POST /v1/connections

Create a connection · operationId create_connection · permission project:manage

Seals the secret fields with the tenant key and answers 201 with the configuration and the names of the secrets that are saved. Kinds with OAuth start pending until they are authorized (or a token is pasted).

GET /v1/connections/{connection_id}

Get a connection · operationId get_connection · permission project:read

Configuration without secrets, which secret fields are saved, state and last error. The page polls this while a Drive or OneDrive authorization is open.

PATCH /v1/connections/{connection_id}

Update a connection · operationId update_connection · permission project:manage

Changes the name, the access or fields of the configuration; a secret field that is omitted keeps its saved value.

DELETE /v1/connections/{connection_id}

Delete a connection · operationId delete_connection · permission project:manage

Destroys the connection and its sealed credentials. 409 CONNECTION_IN_USE while connectors still use it.

POST /v1/connections/{connection_id}:test

Test a connection · operationId test_connection · permission project:manage

Checks that the remote answers with the saved credentials (a top-level listing, a login or a token); nothing is changed except the connection's state. With destination=true it also requires access=read_write (422 CONNECTION_READ_ONLY).

POST /v1/connections/oauth/{provider}:start

Start the OAuth authorization of a connection · operationId start_connection_oauth · permission project:manage

Authorization code with PKCE (S256). Returns the authorization_url to open in a popup (Google: access_type=offline, prompt=consent; Microsoft: offline_access). The page then polls GET /v1/connections/{id} until state is active or error.

GET /v1/connections/oauth/callback

OAuth callback · operationId complete_connection_oauth · permission project:manage

The identity provider redirects here with code and state. Validates the state (single use, 10 minutes), exchanges the code, stores the token sealed and activates the connection; answers a small HTML page that closes the popup.

connectors

GET /v1/connectors

List connectors · operationId list_connectors · permission project:read

Connectors of the project with state, last error, last run and element counts (keyset pages).

POST /v1/connectors

Create a connector · operationId create_connector · permission project:manage

Binds a connection and a path to workflow_ref (name@alias). 422 ALIAS_NOT_FOUND when the reference does not resolve to a published version. A continuous connector gets its schedule; mode=once waits for :run.

GET /v1/connectors/{connector_id}

Get a connector · operationId get_connector · permission project:read

Configuration, state, last error, last run and element counts.

PATCH /v1/connectors/{connector_id}

Update a connector · operationId update_connector · permission project:manage

Changes the workflow reference (revalidated), interval, duplicate policy or settle time, or pauses and resumes it with enabled (the DBOS schedule follows).

DELETE /v1/connectors/{connector_id}

Delete a connector · operationId delete_connector · permission project:manage

Deletes the connector, its schedule and its element history. Runs it started are kept.

POST /v1/connectors/{connector_id}:run

Run a connector once · operationId run_connector · permission project:manage

One synchronous tick: lists, ingests (at most 200 elements; truncated says there are more) and answers with a summary — new, duplicates, failed, skipped. Ignores enabled and the backoff; files are judged by age only. mode=once connectors bring only the changes after the first run.

GET /v1/connectors/{connector_id}/items

List the elements of a connector · operationId list_connector_items · permission project:read

What the connector did with each remote element, oldest first (keyset pages).

models

GET /v1/models

List models and where they process data · operationId list_models · permission project:read

The model registry: per route its provider, snapshot, capabilities, context, price, regions, ZDR, retention class and tiers. effective=true keeps only the routes the caller's effective policy allows.

approvals

POST /v1/approvals

Request the approval of a destructive action · operationId create_approval · permission project:read

Records the tool and the SHA-256 of its canonical arguments as pending; a person approves it within 10 minutes with :approve.

GET /v1/approvals/{approval_id}

Get an approval · operationId get_approval · permission project:read

State of an approval (pending, approved, rejected, consumed, expired).

POST /v1/approvals/{approval_id}:approve

Approve a destructive action · operationId approve_approval · permission project:manage

Needs a human Admin or Owner, or a key with the admin scope. Valid for one execution with exactly the approved arguments, until expires_at.

POST /v1/approvals/{approval_id}:reject

Reject a destructive action · operationId reject_approval · permission project:manage

Same requirements as :approve; the agent is told not to retry.

knowledge

GET /v1/workflows/{workflow_id}/knowledge

Knowledge corpus status · operationId get_knowledge_status · permission workflow:read

Counters of the corpus (indexed, pending, failed, stale) and last_indexed_at. Pending entries left by finished runs are indexed first (bounded).

GET /v1/workflows/{workflow_id}/knowledge/documents

List the documents of the corpus · operationId list_knowledge_documents · MCP tool · permission workflow:read

Keyset pages in upload order; filters by upload date, category, name substring and metadata (JSON containment).

GET /v1/workflows/{workflow_id}/knowledge/documents/{entry_id}

Read a document of the corpus · operationId read_knowledge_document · MCP tool · permission workflow:read

The anchored markdown of pages (2-3, 1,4) or anchors (p2_l10-p2_l40, p3_l1- to the end); without either, the whole document from the top with its header. At most 64 KB per response: truncated and next_anchor say where to continue.

GET /v1/workflows/{workflow_id}/knowledge:search

Search the corpus · operationId search_knowledge · MCP tool · permission workflow:read

Full-text search (Postgres websearch_to_tsquery, case and diacritics insensitive; quotes, - and or are operators, anything else is text and never an error). One hit per document, ordered by ts_rank_cd, with a fragment of at most 300 characters. A corpus over 100 000 documents needs a filter (FILTER_REQUIRED).

GET /v1/workflows/{workflow_id}/knowledge:snapshot

Download a snapshot of the corpus · operationId get_knowledge_snapshot · permission workflow:read

A deterministic tar.gz (one markdown per document and index.json); the same corpus gives the same bytes and the ETag is their sha256 (If-None-Match → 304).

POST /v1/workflows/{workflow_id}/knowledge:reindex

Reindex the corpus · operationId reindex_knowledge · permission workflow:write

all (re)registers every successful run of the history (latest per packet); failed retries only the failed entries. The work runs in the background (durable run knowledge_index); follow it with GET …/knowledge.

POST /v1/workflows/{workflow_id}/knowledge:ask

Ask the corpus · operationId ask_knowledge · MCP tool · permission workflow:read

Answers a question with read-only tools over the corpus. Every claim carries citations checked word by word against the document (verification, regions in [0,1]); with strict (default) unsupported claims are dropped (dropped_claims) and the answer abstains when none is left. Threads (kb_…) keep up to 6 turns on the server. Budget: max_steps ≤ 8 and max_input_tokens ≤ 60 000; when exhausted incomplete is true with reason. usage sums the model calls of this question.

POST /v1/workflows/{workflow_id}/knowledge:query

Structured query over the extractions · operationId query_knowledge · MCP tool · permission workflow:read

One SELECT over kb_extractions and kb_documents (joins between them; functions count, sum, avg, min, max, lower, upper, coalesce, date_trunc, cast). No subqueries, CTEs, set operations or comments (QUERY_NOT_ALLOWED). It runs read-only as dx_knowledge_ro with RLS, a 2 s timeout and at most 500 rows; rows of kb_extractions carry entry_id, path, anchor and the evidence of the field.