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 · required · style: form · explode: true

Project to retrieve items for. Format: UUID. Example: 3c9e2625-7342-6d80-0219-6221506e7890.

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?projectId=<string>' \
  --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

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 · required · style: form · explode: true

Project to retrieve items for. Format: UUID. Example: 3c9e2625-7342-6d80-0219-6221506e7890.

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