Schemas

Height of the box, in pixels. Measured on the same page image x and y are relative to.

Width of the box, in pixels. Measured on the same page image x and y are relative to.

Horizontal offset, in pixels, of the box's left edge from the page image's left edge.

Vertical offset, in pixels, of the box's top edge from the page image's top edge.

Unique identifier for this source. Format: UUID.

Pages and bounding boxes within the source document where the value was found. Empty for source types that are not document-based.

Kind of source that produced this contribution to the value. DOCUMENT — read from one of the item's documents; carries documentId and locations. API — reserved for future explicit API provenance, not produced today. EXTERNAL — a non-document source such as a flow-configured external system or a web-search result; carries displayName/url. DERIVED — computed, aggregated, or entered directly during review; carries neither. Like API, nothing produces DERIVED sources today: a value entered during review has an empty sources array rather than a derived one.

Human-readable name for an EXTERNAL source. For the web-search citations that produce these today it is the search result's title, or null when the provider returned none. Absent for other source types.

Document this source was read from. Present for DOCUMENT sources; null or absent for other source types. Format: UUID.

Display name of the source document, resolved for the caller's access. Null when this source has no associated document, or when the document could not be resolved for display — see stale.

Whether this source's grounding no longer holds against the source document's current state. Currently set only when the source document could not be resolved. Detecting a replaced, split, or reorganized document is computed by a separate internal check and is not yet reflected here. Applies only to document-backed sources; absent for other source types.

Reason this source is stale, present when stale is true. Only UNAVAILABLE is currently produced, meaning the source document could not be resolved. SUPERSEDED (replaced by a newer version), DOCUMENT_SPLIT (pages now span more than one document) and PAGE_MOVED (page now belongs to a different document) are computed by a separate internal check and are not yet surfaced here. Absent when not stale.

URL of an EXTERNAL source, such as a web page cited during extraction. Absent for other source types.

Unique identifier for this location. Format: UUID.

Page number to display or scroll to for this location. A display hint only. sourcePageKey, not this value, is what identifies the page across document reorganization.

Stable identifier for the source page. Used to match this location to the correct page even after the document has been reorganized. Opaque — treat it only as a matching key, not as a value to parse.

Pixel-coordinate box on the page where the value was found. Absent means the value is grounded to the page as a whole, with no specific box to highlight.

The access token to use for subsequent requests. JWT format. Pass it in the Authorization Bearer header. Example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9....

Resolved authentication/authorization context for the caller.

Token expiration time. Unix epoch timestamp in milliseconds — pass it straight to new Date(...) or compare it against Date.now(). Note this is a different unit from the exp claim inside the token itself, which follows the JWT spec and is in seconds. Example: 1786454684000.

Storage path within the organization's blob container. Not a public URL — use downloadUrl to fetch content.

File category. Defaults to DOCUMENT_PROCESSING when not specified at upload time.

ISO timestamp when the file record was created.

ID of the user or process that created the file record. Format: UUID.

A presigned URL to download the file content directly from storage. Time-limited; re-fetch the file if it expires.

File size in bytes. Example: 102400.

Original filename, with extension. Example: document.pdf.

Unique identifier for the file. Format: UUID. Example: 70326069-1786-01c4-4653-066594021234.

MIME type of the file. Example: application/pdf.

Count of immediate children for this file

Recursive array of child files - populated up to MAX_DEPTH levels

Free-form metadata attached to the file, if any. Represents any valid JSON value that can be stored in a JSONB column.

ID of the parent file, for files created as part of a hierarchy. Format: UUID.

ISO timestamp when the execution record was created.

ID of the user or process that created the execution. Format: UUID.

ID of the flow that was executed. Format: UUID. Example: 5e104847-9564-8fa2-2431-844372809012.

Unique identifier for the flow execution. Format: UUID. Example: 81437170-2897-12d5-5764-177605132345.

Organization that owns this execution. Format: UUID.

When the execution started. ISO timestamp. Example: 2026-03-31T10:00:00Z.

Current lifecycle status. Lowercase string, one of pending, running, in_review, completed, failed, canceled. Five of the six are stored on the execution itself; in_review is derived at read time, and means the execution is still open and has produced a work item that is waiting on human review.

Child executions for flows that spawn sub-flows.

When the execution finished, if it has. ISO timestamp; null/absent while still running.

Error details, if the execution failed. Represents any valid JSON value that can be stored in a JSONB column.

Provenance reference indicating which version/draft was executed. Format: "v:1.0.0" for published versions, "draft:{id}@{opCount}" for drafts, null for legacy.

Input payload the execution was started with. Represents any valid JSON value that can be stored in a JSONB column.

Output payload produced by the execution, once available. Represents any valid JSON value that can be stored in a JSONB column.

Internal run identifier for the processing engine. Not part of the stable public contract; do not use it for API calls.

Internal workflow identifier for the processing engine. Not part of the stable public contract; do not use it for API calls.

ISO timestamp of the last update to the execution record.

ID of the user or process that last updated the execution. Format: UUID.

ID of the work item. Format: UUID.

Project the item belongs to. Format: UUID.

Human-facing sequence number for the item within its project. Absent for items that have not yet been assigned one.

Path into the review UI for this item, relative to the app root. Example: /items/{itemId}/review?projectId={projectId}. Present only while the item is awaiting review and the execution has not reached completed, failed or canceled. Absent otherwise.

Work items produced by this execution.

Projected lifecycle status of the execution. One of pending, running, in_review, completed, failed, canceled. Distinct from the internal ItemStatus/ReviewStatus vocabularies, which are never surfaced here.

Bounded, best-effort summary of why the execution failed. Present only when status is failed.

Canvas position by node ID. Node IDs correspond to step names in the DSL workflow; absence means the step isn't a canvas node.

Count of iterations. Equal to iterations.length.

All executions of this step. Multiple entries when the step is inside a for loop, one per iteration.

Overall status - "completed" if all iterations completed, "failed" if any failed, "running" otherwise

Display name derived from step_ref (e.g., "process_item"). Used for grouping iterations together.

The full step reference path (e.g., "/do/0/for/2/process_item"). For grouped steps with iterations, this is the ref from the first iteration.

The step type. Example: task, for, set.

ISO timestamp when the page record was created.

ID of the file this page belongs to. Format: UUID.

Unique identifier for the page record. Format: UUID.

1-indexed page number within the file.

ID of the document this page is associated with, if any. Format: UUID.

Presigned URL to download the rendered page image.

Storage path of the rendered page image, if generated.

Presigned URL to download the OCR output for this page.

Storage path of the OCR output for this page, if generated.

Database primary key for the newly created FlowExecution record. Use this for API calls. Format: UUID.

Internal workflow identifier for the processing engine. Not part of the stable public contract; do not use it for API calls.

Database primary key for the FlowExecution record. Use this for API calls. Format: UUID. Example: 81437170-2897-12d5-5764-177605132345.

Internal workflow identifier for the processing engine. Not part of the stable public contract; do not use it for API calls.

ISO timestamp when the step execution record was created.

ID of the parent flow execution this step belongs to. Format: UUID.

Unique identifier for the step execution record. Format: UUID.

Organization that owns this step execution. Format: UUID.

Number of times this step has been retried.

When the step started. ISO timestamp.

Current execution status of the step. Lowercase string, one of active, completed, failed. Canceled activities are recorded as failed.

Display name derived from step_ref (e.g., "process_item"). The last non-numeric segment of the ref path.

The full step reference path (e.g., "/do/0/for/2/process_item"). Provides complete execution context for debugging.

The step type. Example: task, for, set.

Child steps from module workflows that were spawned by this step. Only populated for parent workflow steps that trigger child workflows.

When the step finished, if it has. ISO timestamp; absent while still running.

Error details, if the step failed. Represents any valid JSON value that can be stored in a JSONB column.

Input payload the step was invoked with. Represents any valid JSON value that can be stored in a JSONB column.

Output payload produced by the step, once available. Represents any valid JSON value that can be stored in a JSONB column.

ISO timestamp of the last update to the step execution record.

Status derived from the associated DSL child execution for this response, not necessarily the root/parent flow execution. One of pending, running, in_review, completed, failed, canceled — the same six-value vocabulary returned by the other flow-execution endpoints. in_review means the run is still open and has produced a work item waiting on human review.

Steps grouped by step_name, with iterations and canvas visibility. Use this instead of a flat step list to correctly render loop iterations.

Total number of step executions, including all loop iterations. Greater than totalSteps when any step has multiple iterations.

Total number of unique step names. Equal to groupedSteps.length.

Layout information showing which step names are visible canvas nodes. Node IDs in this map correspond to step names in the DSL workflow.

Search query that surfaced this citation. Null if the citation was not associated with a specific query.

Title of the cited page. Null if the search provider did not return a title.

URL of the web page cited as a source for this value. Example: [https://example.com/article](https://example.com/article).

ISO timestamp when this field was first created. Set once and never updated afterward.

ID of the version currently treated as this field's value. Null if the field has no versions yet. Format: UUID.

Document this field belongs to. Null for an item-level field (one that is not scoped to a specific document). Format: UUID.

Unique identifier for this field. Format: UUID. Example: 6f215958-0675-90b3-3542-955483910123.

Item this field belongs to. Format: UUID.

Name of the field. Unique within the item (for item-level fields) or within the document (for document-scoped fields), so a flow that produces two fields under the same key for one document yields a single field rather than two. Example: invoice_total.

Organization that owns this field. Format: UUID.

Data type of the field's value. Example: string, number, date, table.

ISO timestamp of the last change to this field. Updates whenever a new version becomes current.

This field's current version, wrapped in an array. Contains at most one entry, the version referenced by currentVersionId, and is empty when the field has no current version. It is not the field's full version history.

Confidence the extraction model assigned to this value. Between 0 and 1, or null for values that were not model-extracted, such as a value entered during human review.

ISO timestamp when this version record was created. May differ from versionTimestamp, which reflects when the value was actually produced.

ID of the user who created this version. Null if it was created by an automated process rather than a person. Format: UUID.

Field this is a version of. Format: UUID.

Unique identifier for this field version. Format: UUID.

Whether this value currently passes all validation rules configured for the field. Set independently of validationMessages. A rule can invalidate a value without attaching any message, so this can be false while validationMessages is empty.

Organization that owns this field version. Format: UUID.

Internal reference path to the workflow step that produced this version. Prefer stepName for a readable label; this value is meaningful only in combination with the flow's own definition.

How this version's value was produced. Example values include EXTRACTION (automated extraction) and REVIEW (created or edited during human review).

Input sources that contributed to this version's value, listed individually. Empty when no provenance was recorded for this version.

Review/lifecycle status of this version's value. One of: PENDING (not yet processed), EXTRACTED (produced by automated extraction, awaiting review), SAVED (edited during review but not yet submitted), REVIEWED (kept for backward compatibility), APPROVED (finalized, via review submission or auto-approval), REJECTED (explicitly rejected), or ARCHIVED (superseded when the flow looped back and re-extracted). An ARCHIVED version can still be the one referenced by currentVersionId, when the re-extraction did not produce a value for that key, so check this status rather than assuming the current version is live.

ID of the workflow step execution that produced this version. Null if the version was not created by an automated step — for example, one entered during human review. Format: UUID.

Readable label for the workflow step that produced this version, extracted from parentStepRef. Null when the version was not created by an automated step, or when a label could not be extracted.

Messages attached by validation rules that fired against this value. Only rules configured with message text add an entry, whether or not the rule invalidated the value, so this can be non-empty while isValid is true. Each entry names the rule that fired (ruleId) alongside its configured explanation (message).

The extracted or entered value for this version. A scalar, a nested object, or — for table fields — an array of row objects. Interpret its shape using the field's type.

Time this version's value was produced, as reported by the process that created it. Determines this version's position in the field's history; may differ from createdAt, which is when the record was stored.

Deprecated single-location bounding box for this value, kept for backward compatibility. Mirrors the first location of this version's first source. New integrations should read sources[].locations[] instead, which supports multiple sources and multiple locations per source.

Web-search citations backing this value, if any. Populated only by the item-review endpoints. This endpoint always omits it, whether or not the value has citations.

Deprecated single-location page number for this value, kept for backward compatibility. Mirrors the first location of this version's first source. New integrations should read sources[].locations[] instead.

1-based position of this version within its field's history. 1 is the oldest version; the highest number is the newest. Absent in contexts that return a version without its field's full history.

Time in milliseconds the agent spent processing this item, or null if unavailable.

AI-generated summary of the item, or null if not yet generated.

ID of the user who made the current assignment. Format: UUID.

ID of the user currently assigned to the item. Format: UUID.

The assigned user's profile, or null if unassigned.

ISO timestamp when the item was created. Example: 2026-03-31T15:55:41.222Z.

Human-readable sequential ID within the AI Agent. Example: 1001.

Document metadata for this item. Lean — omits inline content and nested fields[]; use GET /items/:id/fields for field detail.

Unique identifier for the item. Format: UUID. Example: 6f215958-0675-90b3-3542-955483910123.

Review history for this item. Lean — fieldVersions[] entries are references only, not full field/version copies.

ID of the user or process that last updated the item. Format: UUID.

Organization that owns this item. Format: UUID. Example: 1d7c0403-5120-4b68-8097-4009384c5678.

Project this item belongs to. Format: UUID. Example: 3c9e2625-7342-6d80-0219-6221506e7890.

Current processing status of the item.

ISO timestamp of the last update to the item. Example: 2026-03-31T15:55:41.222Z.

ISO timestamp when the item was soft-deleted, or null/absent if active.

User-facing display name for the item, null to indicate cleared, absent if never set.

ID of the flow execution that produced this item, if any. Format: UUID.

ID of the flow that produced this item, if any. Format: UUID.

Name of the flow that produced this item, if any.

Internal run identifier for the processing engine. Not part of the stable public contract; do not use it for API calls.

Internal workflow identifier for the processing engine. Not part of the stable public contract; do not use it for API calls.

AI-generated summary of the item, or null if not yet generated.

ID of the user currently assigned to the item, or null if unassigned. Format: UUID.

The assigned user's profile, or null if unassigned.

ISO timestamp when the item was created.

Human-readable sequential ID within the AI Agent. Example: 1001.

User-facing display name for the item, or null if unset.

ID of the flow that produced this item, or null if not flow-generated. Format: UUID.

Name of the flow that produced this item, or null if not flow-generated.

Unique identifier for the item. Format: UUID. Example: 6f215958-0675-90b3-3542-955483910123.

The open (PENDING/IN_PROGRESS) review's status + lockedAt, or null when none. Backs the "Locked - View Only" badge (isItemLocked); the 7-minute TTL check stays client-side. Replaces the full itemReviews[] tree on the list.

Current processing status of the item.

User's email address.

User's first name, if set.

Unique identifier for the user. Format: UUID.

User's last name, if set.

Organization this access token is scoped to. Format: UUID.

Permission keys this token grants. Checked by @ApiPermission-guarded endpoints via the RBAC middleware.

Projects the token grants access to. Requests scoped outside this list should be rejected.

ID of the authenticated subject (user or service account). Format: UUID.

Kind of subject that authenticated. Distinguishes human users from service/system accounts.

Workspaces the token grants access to. Requests scoped outside this list should be rejected.

Error code

Error message

Error details