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. To create Work Items on a recurring cadence instead, see Schedules.

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}/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 */ ], "total_count": 120, "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}/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 Schedules