Work items

Work Items are the unit of work a Worker agent processes. Use this API to queue work, track it through its lifecycle, attach files, and drive review and retries.

All paths are relative to the base URL and require an Authorization: Bearer YOUR_API_KEY header.

The Work Item object

Returned by create, get, continue, and restart.

Field	Type	Description
work_item_id	string	Unique identifier.
agent_id	string	Agent that will process the item.
status	WorkItemStatus	Current status (see below).
thread_id	string	Thread for this item (null until created).
payload	object	Arbitrary input data for the agent.
messages	array<ThreadMessage>	Conversation messages on the item.
initial_messages	array<ThreadMessage>	The messages the item started with.
callbacks	array<WorkItemCallback>	Status-change callbacks.
work_item_name	string	User-friendly name (max 255 chars).
work_item_url	string	Link to the item in the application.
created_by	string	User who created the item.
completed_by	`AGENT` \| `HUMAN`	Who completed it.
status_updated_by	`SYSTEM` \| `AGENT` \| `HUMAN`	Who last changed status.
created_at / updated_at / status_updated_at	string	Timestamps.

Status reference

WorkItemStatus is one of:

Status	Meaning
`DRAFT`	Created but not yet submitted for processing.
`PENDING`	Queued, waiting to be picked up.
`EXECUTING`	The agent is working on it.
`NEEDS_REVIEW`	The agent paused and needs a human decision (see below).
`COMPLETED`	Finished successfully.
`ERROR`	Failed.
`CANCELLED`	Cancelled before completion.
`INDETERMINATE`	State could not be determined.

Status drives what you can do. File uploads require DRAFT — a newly created item is PENDING, so it must be in draft to attach files. Lifecycle actions (continue / restart / cancel / complete) are only valid from certain statuses; an illegal transition returns 412 Precondition Failed (e.g. "Cannot continue work item from status PENDING").

Create a work item

POST /work-items

Queues a new work item for an agent.

Body

Field	Type	Required	Description
agent_id	string	Yes	Agent that will process the item.
payload	object	No	Input data for the agent.
messages	array<ThreadMessage>	No	Seed messages for the item's conversation.
work_item_name	string	No	User-friendly name (max 255 chars).
work_item_id	string	No	Use a specific ID (e.g. one returned by an earlier file upload).
callbacks	array<WorkItemCallback>	No	Callbacks to fire on status changes.

Request

curl -X POST 'https://{your-deployment-host}/tenants/{tenant-id}/api/v2/work-items' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "agent_id": "AGENT_ID",
    "work_item_name": "Invoice 4815",
    "payload": { "invoice_number": "4815", "amount": 1620.00 }
  }'

Returns the created Work Item.

List work items

GET /work-items

Parameters

Parameter	In	Type	Required	Description
agent_id	query	string	No	Filter by agent.
work_item_status	query	array<WorkItemStatus>	No	Filter by status (repeat for multiple).
created_by	query	string	No	Filter by the creating user.
name_search	query	string	No	Search within the work item name.
limit	query	integer	No	Page size.
offset	query	integer	No	Offset to start from.

Response — WorkItemsListResponse

{ "records": [ /* WorkItem objects */ ], "next_offset": 50 }

Use next_offset as the offset for the next page.

Get a work item

GET /work-items/{work_item_id}

Parameter	In	Type	Required	Description
work_item_id	path	string	Yes	Work item ID.
results	query	boolean	No	Include the item's results.

Returns a Work Item.

Attach files

Upload a file first, then either create the work item with the returned ID or confirm the upload onto an existing item.

Upload a file

POST /work-items/upload-file

Send as multipart/form-data with a file field. If you don't pass work_item_id, a new item ID is created and returned.

A target work item must be in DRAFT state to accept files. Uploading to a PENDING item (the state a new item lands in) returns 400. To attach files to an existing item, it has to be a draft.

Parameter	In	Type	Required	Description
work_item_id	query	string	No	Attach to an existing item; omit to create.
file	form	binary	Yes	The file to upload.

curl -X POST 'https://{your-deployment-host}/tenants/{tenant-id}/api/v2/work-items/upload-file' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -F 'file=@invoice.pdf'

Confirm a file

POST /work-items/{work_item_id}/confirm-file

Confirms a remote file upload onto a work item.

Field	Type	Required	Description
file_ref	string	Yes	Reference of the upload.
file_id	string	Yes	ID of the uploaded file.

Lifecycle actions

Continue

POST /work-items/{work_item_id}/continue

Continues a work item — for example after a NEEDS_REVIEW decision. Returns the updated Work Item.

Restart

POST /work-items/{work_item_id}/restart

Restarts processing of a work item. Returns the updated Work Item.

Cancel

POST /work-items/{work_item_id}/cancel

Cancels a work item.

Complete

POST /work-items/{work_item_id}/complete

Administratively marks a work item as COMPLETED — for example when a human reviewer resolves a NEEDS_REVIEW item without further agent work.

Handling NEEDS_REVIEW. When an item is NEEDS_REVIEW, read it with GET /work-items/{id} to see why. Then either complete it (the human decision is enough) or restart/continue it (let the agent try again with new input).

Delete

Delete one

DELETE /work-items/{work_item_id}

Deletes a work item and cleans up associated resources.

Response — DeleteWorkItemResponse

{ "work_item_id": "string", "status": "string", "warnings": [] }

Batch delete

POST /work-items/delete

Deletes multiple work items in one call.

Body

{ "work_item_ids": ["id1", "id2"] }

Response — DeleteWorkItemsResponse

{ "deleted": 2, "failures": 0 }

Callbacks

A work item can carry callbacks that fire when it reaches a given status (default NEEDS_REVIEW). The platform POSTs to your URL when the status is reached.

Field (WorkItemCallback)	Type	Description
url	string	URL to POST to when the status is reached.
on_status	string	Status that triggers the callback (default `NEEDS_REVIEW`).
signature_secret	string	Optional secret used to sign the payload; omit to leave it unsigned.

Conversations Data connections