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.
GET /auth/email/link
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, [email protected], 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.