Items

Retrieve and manage items. Items are the products of flow runs, representing the unit of work processed by the system.

List items

GET

https://platform.bevaya.ai/api/v1

/items

Retrieve a paginated list of items. Filter by projectId (required) and optionally by flowId, status, assignee, date range, and more.

List items › query Parameters

projectId

string · style: form · explode: true

Project to retrieve items for. Format: UUID. Example: 3c9e2625-7342-6d80-0219-6221506e7890. Either projectId or workspaceId must be provided.

workspaceId

string · style: form · explode: true

Workspace to retrieve items for. Returns all items across all agents in the workspace. Format: UUID. Example: 3c9e2625-7342-6d80-0219-6221506e7890. Either projectId or workspaceId must be provided.

status

client.ItemStatus[] · style: form · explode: true

Filter by item status. When omitted, items of all statuses are returned.

Enum values:

QUEUED

IN_PROGRESS

DEFERRED

REVIEW

COMPLETE

CLOSED

FAILED

CANCELED

assignedTo

string · style: form · explode: true

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

searchText

string · style: form · explode: true

Full-text search across item names, summaries, and extracted field values.

createdAfter

string · style: form · explode: true

Return only items created after this timestamp. ISO 8601 format. Example: 2026-01-01T00:00:00Z.

createdBefore

string · style: form · explode: true

Return only items created before this timestamp. ISO 8601 format. Example: 2026-12-31T23:59:59Z.

updatedAfter

string · style: form · explode: true

Return only items updated after this timestamp. ISO 8601 format.

updatedBefore

string · style: form · explode: true

Return only items updated before this timestamp. ISO 8601 format.

page

number · style: form · explode: true

1-indexed page number to retrieve. Default: 1.

limit

number · style: form · explode: true

Number of items per page. Default: 20, max: 100.

flowName

string · style: form · explode: true

Filter by flow name (fuzzy match) - prefix: flow:

flowId

string · style: form · explode: true

Filter by exact flow ID - prefix: flow-id:

summary

string · style: form · explode: true

Filter by agent summary (fuzzy match) - prefix: summary:

insight

string · style: form · explode: true

Filter by insight field (fuzzy match) - prefix: insight:

fieldValue

string · style: form · explode: true

Filter by extracted field value (fuzzy match) - prefix: field-value:

itemId

string · style: form · explode: true

Filter by exact item UUID - prefix: id:

displayId

string · style: form · explode: true

Filter by exact item displayId (numeric) - prefix: display-id:

displayNameFilter

string · style: form · explode: true

Filter by display name (fuzzy match) - prefix: name:

reviewer

string · style: form · explode: true

Filter by reviewer name (fuzzy match), "none" for unassigned - prefix: reviewer:

createdDate

string · style: form · explode: true

Filter by created date (MM/DD/YYYY) - prefix: date:

sortBy

dtos.ItemSortFieldType · enum · style: form · explode: true

Field to sort results by. Default: createdAt.

Type for sort field values

Enum values:

createdAt

updatedAt

status

displayId

displayName

flowName

assignedToUser

sortOrder

dtos.SortOrderType · enum · style: form · explode: true

Sort direction. Default: desc.

Type for sort order values

Enum values:

asc

desc

List items › Responses

Success response

dtos.ItemListEntryDto[] · required

The list of items

object · required

GET/items

curl https://platform.bevaya.ai/api/v1/items \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "data": [
    {
      "id": "6f215958-0675-90b3-3542-955483910123",
      "displayId": 1001,
      "displayName": "Invoice #INV-2026-001",
      "status": "COMPLETE",
      "assignedTo": null,
      "assignedToUser": null,
      "createdAt": "2026-03-31T10:00:00Z",
      "agentSummary": "Invoice from Acme Corp for $12,500.00 dated March 31, 2026.",
      "flowId": "5e104847-9564-8fa2-2431-844372809012",
      "flowName": "Invoice Processing",
      "reviewSummary": null
    }
  ],
  "meta": {
    "total": 1,
    "page": 1,
    "perPage": 20,
    "totalPages": 1
  },
  "links": {
    "first": "/items?page=1",
    "last": "/items?page=1",
    "prev": null,
    "next": null
  }
}

json

application/json

Get item details

GET

https://platform.bevaya.ai/api/v1

/items/{id}

Retrieve a single item by ID.

Get item details › path Parameters

id

string · required · style: simple

Get item details › query Parameters

projectId

string · required · style: form · explode: true

Get item details › Responses

Success response

dtos.ItemDetailDto · required

Lean payload for GET /items/:id. Bounds the single-item response and removes the 3x FieldVersion.value duplication: - NO fields[] — sourced from GET /items/:id/fields (paginated) - documents[] is metadata only (no content, no nested fields[]) - itemReviews[].fieldVersions[] are references only - temporalWorkflowId is retained (item-review service depends on it)

GET/items/{id}

curl 'https://platform.bevaya.ai/api/v1/items/:id?projectId=<string>' \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "data": {
    "id": "6f215958-0675-90b3-3542-955483910123",
    "organizationId": "1d7c0403-5120-4b68-8097-4009384c5678",
    "displayId": 1001,
    "projectId": "3c9e2625-7342-6d80-0219-6221506e7890",
    "assignedTo": "97ad76e9-9a71-421b-b28f-6f0aef88a675",
    "assignedBy": "97ad76e9-9a71-421b-b28f-6f0aef88a675",
    "lastUpdatedBy": "97ad76e9-9a71-421b-b28f-6f0aef88a675",
    "status": "COMPLETE",
    "createdAt": "2026-03-31T10:00:00Z",
    "updatedAt": "2026-03-31T10:05:00Z",
    "agentSummary": "Invoice from Acme Corp for $12,500.00 dated March 31, 2026.",
    "agentProcessingTime": 25000,
    "assignedToUser": null,
    "documents": [],
    "itemReviews": [],
    "flowId": "5e104847-9564-8fa2-2431-844372809012",
    "flowName": "Invoice Processing"
  }
}

json

application/json

List item fields

GET

https://platform.bevaya.ai/api/v1

/items/{id}/fields

Retrieve the extracted field values for a work item. Each field is one data point identified by its key, and carries only the version currently treated as its value. This endpoint does not return a field's full version history.

A field's value is JSON rather than a fixed type, because what a field holds depends on what was extracted: a scalar, an object, or an array of row objects for a table.

Filter by documentId to scope to a single document, or by key or type to narrow to particular fields. Fields with no documentId were extracted for the item as a whole rather than from one document.

List item fields › path Parameters

id

string · required · style: simple

List item fields › query Parameters

projectId

string · required · style: form · explode: true

The project the item belongs to. Format: UUID. Required, and the caller must have access to it.

documentId

string · style: form · explode: true

Return only fields extracted from this document. Format: UUID. Omit to include both document-scoped and item-level fields.

key

string · style: form · explode: true

Return only the field with this key. Matched exactly, not as a prefix or a pattern.

type

string · style: form · explode: true

Return only fields of this type. Matched exactly against the field's declared type.

page

number · style: form · explode: true

1-indexed page to retrieve. Defaults to 1. Capped at 100, so with the largest page size the last reachable field is the 10,000th.

limit

number · style: form · explode: true

Number of fields per page. Between 1 and 100. Defaults to the service-wide page size.

List item fields › Responses

Success response

dtos.FieldDto[] · required

The list of items

object · required

GET/items/{id}/fields

curl 'https://platform.bevaya.ai/api/v1/items/:id/fields?projectId=<string>' \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "data": [
    {
      "createdAt": "2024-08-25T15:00:00Z",
      "currentVersionId": "string",
      "documentId": "string",
      "id": "id",
      "itemId": "itemId",
      "key": "key",
      "organizationId": "organizationId",
      "type": "type",
      "updatedAt": "2024-08-25T15:00:00Z",
      "versions": [
        {
          "boundingBox": {
            "height": 0,
            "width": 0,
            "x": 0,
            "y": 0
          },
          "citations": [
            {
              "sourceQuery": "string",
              "title": "string",
              "url": "url"
            }
          ],
          "confidence": 0,
          "createdAt": "2024-08-25T15:00:00Z",
          "createdBy": "string",
          "fieldId": "fieldId",
          "id": "id",
          "isValid": true,
          "organizationId": "organizationId",
          "pageNumber": 0,
          "parentStepRef": "string",
          "sourceType": "string",
          "sources": [
            {
              "displayName": "string",
              "documentId": "string",
              "documentName": "string",
              "id": "id",
              "locations": [
                {
                  "boundingBox": {
                    "height": 0,
                    "width": 0,
                    "x": 0,
                    "y": 0
                  },
                  "id": "id",
                  "pageNumber": 0,
                  "sourcePageKey": "sourcePageKey"
                }
              ],
              "stale": true,
              "staleReason": "SUPERSEDED",
              "type": "DOCUMENT",
              "url": "string"
            }
          ],
          "status": "PENDING",
          "stepExecutionId": "string",
          "stepName": "string",
          "validationMessages": [
            {
              "message": "message",
              "ruleId": "ruleId"
            }
          ],
          "value": "string",
          "versionNumber": 0,
          "versionTimestamp": "2024-08-25T15:00:00Z"
        }
      ]
    }
  ],
  "links": {
    "next": "next",
    "prev": "prev"
  },
  "meta": {
    "page": 0,
    "perPage": 0,
    "total": 0
  }
}

json

application/json

Flow Executions

List items

GET

https://platform.bevaya.ai/api/v1

/items

Retrieve a paginated list of items. Filter by projectId (required) and optionally by flowId, status, assignee, date range, and more.

List items › query Parameters

projectId

string · style: form · explode: true

Project to retrieve items for. Format: UUID. Example: 3c9e2625-7342-6d80-0219-6221506e7890. Either projectId or workspaceId must be provided.

workspaceId

string · style: form · explode: true

status

client.ItemStatus[] · style: form · explode: true

Filter by item status. When omitted, items of all statuses are returned.

Enum values:

QUEUED

IN_PROGRESS

DEFERRED

REVIEW

COMPLETE

CLOSED

FAILED

CANCELED

assignedTo

string · style: form · explode: true

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

searchText

string · style: form · explode: true

Full-text search across item names, summaries, and extracted field values.

createdAfter

string · style: form · explode: true

Return only items created after this timestamp. ISO 8601 format. Example: 2026-01-01T00:00:00Z.

createdBefore

string · style: form · explode: true

Return only items created before this timestamp. ISO 8601 format. Example: 2026-12-31T23:59:59Z.

updatedAfter

string · style: form · explode: true

Return only items updated after this timestamp. ISO 8601 format.

updatedBefore

string · style: form · explode: true

Return only items updated before this timestamp. ISO 8601 format.

page

number · style: form · explode: true

1-indexed page number to retrieve. Default: 1.

limit

number · style: form · explode: true

Number of items per page. Default: 20, max: 100.

flowName

string · style: form · explode: true

Filter by flow name (fuzzy match) - prefix: flow:

flowId

string · style: form · explode: true

Filter by exact flow ID - prefix: flow-id:

summary

string · style: form · explode: true

Filter by agent summary (fuzzy match) - prefix: summary:

insight

string · style: form · explode: true

Filter by insight field (fuzzy match) - prefix: insight:

fieldValue

string · style: form · explode: true

Filter by extracted field value (fuzzy match) - prefix: field-value:

itemId

string · style: form · explode: true

Filter by exact item UUID - prefix: id:

displayId

string · style: form · explode: true

Filter by exact item displayId (numeric) - prefix: display-id:

displayNameFilter

string · style: form · explode: true

Filter by display name (fuzzy match) - prefix: name:

reviewer

string · style: form · explode: true

Filter by reviewer name (fuzzy match), "none" for unassigned - prefix: reviewer:

createdDate

string · style: form · explode: true

Filter by created date (MM/DD/YYYY) - prefix: date:

sortBy

dtos.ItemSortFieldType · enum · style: form · explode: true

Field to sort results by. Default: createdAt.

Type for sort field values

Enum values:

createdAt

updatedAt

status

displayId

displayName

flowName

assignedToUser

sortOrder

dtos.SortOrderType · enum · style: form · explode: true

Sort direction. Default: desc.

Type for sort order values

Enum values:

asc

desc

List items › Responses

Success response

dtos.ItemListEntryDto[] · required

The list of items

object · required

Get item details

GET

https://platform.bevaya.ai/api/v1

/items/{id}

Retrieve a single item by ID.

Get item details › path Parameters

id

string · required · style: simple

Get item details › query Parameters

projectId

string · required · style: form · explode: true

Get item details › Responses

Success response

dtos.ItemDetailDto · required

List item fields

GET

https://platform.bevaya.ai/api/v1

/items/{id}/fields

A field's value is JSON rather than a fixed type, because what a field holds depends on what was extracted: a scalar, an object, or an array of row objects for a table.

List item fields › path Parameters

id

string · required · style: simple

List item fields › query Parameters

projectId

string · required · style: form · explode: true

The project the item belongs to. Format: UUID. Required, and the caller must have access to it.

documentId

string · style: form · explode: true

Return only fields extracted from this document. Format: UUID. Omit to include both document-scoped and item-level fields.

key

string · style: form · explode: true

Return only the field with this key. Matched exactly, not as a prefix or a pattern.

type

string · style: form · explode: true

Return only fields of this type. Matched exactly against the field's declared type.

page

number · style: form · explode: true

1-indexed page to retrieve. Defaults to 1. Capped at 100, so with the largest page size the last reachable field is the 10,000th.

limit

number · style: form · explode: true

Number of fields per page. Between 1 and 100. Defaults to the service-wide page size.

List item fields › Responses

Success response

dtos.FieldDto[] · required

The list of items

object · required