Schemas

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 (seconds) at which the access token stops being valid.

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 execution status. Lowercase string, one of pending, running, completed, failed. Cancellation is not recorded as a distinct status.

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.

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. Cancelled 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. Consumers should treat this value case-insensitively.

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.

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.