Work Items API

Work items are the core unit of work in OpenIndex. The hierarchy is project → task → sub_task. Each item belongs to a domain and has a domain-scoped key (e.g. OPS-42). Sub-task keys inherit from the parent task with a suffix (e.g. OPS-42.1). All work item endpoints require a Bearer token. See API Authentication.

Browse and create

List work items

GET /browse
Authorization: Bearer <your-pat>

string

Filter by work item type: project, task, or sub_task.

string

Filter by domain ID.

string

Filter by status value.

string

Full-text search across title and description.

Create a work item

POST /browse
Authorization: Bearer <your-pat>
Content-Type: application/json

string

required

Work item type: project, task, or sub_task.

string

required

Work item title.

string

required

ID of the domain to create the item in.

string

Key of the parent work item. Required for sub_task; optional for task (creates under a project).

string

Workflow to assign. If omitted, the domain default workflow is used.

string

Markdown-formatted description.

string

Initial status. Must be a valid status for the assigned workflow.

string

Priority level (e.g. low, medium, high, critical).

string

Target agent or executor ID for agent-dispatched items.

curl --request POST \
  --url https://your-deployment.convex.site/browse \
  --header 'Authorization: Bearer oi_pat_...' \
  --header 'Content-Type: application/json' \
  --data '{
    "kind": "task",
    "title": "Investigate performance regression",
    "domainId": "domain_abc123",
    "workflowId": "wf_xyz456",
    "priority": "high"
  }'

{
  "key": "OPS-43",
  "kind": "task",
  "title": "Investigate performance regression",
  "status": "todo",
  "priority": "high",
  "domainId": "domain_abc123",
  "workflowId": "wf_xyz456",
  "createdAt": "2026-03-31T10:00:00Z"
}

Agent work queue

GET /browse/queue
Authorization: Bearer <your-pat>

Returns work items eligible for agent pickup — items in agent-required workflow stages that are not currently claimed.

Get a work item

GET /browse/:key
Authorization: Bearer <your-pat>

Returns full details for the work item with the given key (e.g. GET /browse/OPS-42).

Update a work item

PATCH /browse/:key
Authorization: Bearer <your-pat>
Content-Type: application/json

Send only the fields you want to update. Updatable fields include title, description, priority, status, and executionTarget.

Delete a work item

DELETE /browse/:key
Authorization: Bearer <your-pat>

Permanently deletes the work item. This action is permission-checked and cannot be undone.

Workflow transitions

List available transitions

GET /browse/:key/transitions
Authorization: Bearer <your-pat>

Returns the status transitions available for the work item from its current state.

Claim for agent execution

POST /browse/:key/claim
Authorization: Bearer <your-pat>
Content-Type: application/json

string

required

The status to transition the item to when claiming.

string

required

ID of the agent claiming the item.

Complete a work item

POST /browse/:key/complete
Authorization: Bearer <your-pat>
Content-Type: application/json

string

required

The completion status to transition to.

string

required

ID of the agent completing the item.

Advance a stage gate

POST /browse/:key/stage-gates/:gateKey/progress
Authorization: Bearer <your-pat>
Content-Type: application/json

Advances the specified stage gate. Stage gates are defined in the workflow and must be progressed in order before a status transition can occur.

Get agent execution context

GET /browse/:key/agent-context
Authorization: Bearer <your-pat>

Returns the full execution context for the agent operating on this work item, including workflow state, stage gates, custom field values, and conversation history.

Comments

List comments

GET /browse/:key/comments
Authorization: Bearer <your-pat>

Add a comment

POST /browse/:key/comments
Authorization: Bearer <your-pat>
Content-Type: application/json

string

required

Comment text. Supports Markdown.

Update a comment

PATCH /browse/:key/comments/:commentId
Authorization: Bearer <your-pat>
Content-Type: application/json

Delete a comment

DELETE /browse/:key/comments/:commentId
Authorization: Bearer <your-pat>

Attachments

List attachments

GET /browse/:key/attachments
Authorization: Bearer <your-pat>

Upload an attachment

Uploading a file is a two-step process:

Initiate the upload

POST /browse/:key/attachments/initiate
Authorization: Bearer <your-pat>
Content-Type: application/json

{
  "filename": "report.pdf",
  "contentType": "application/pdf",
  "size": 204800
}

Returns an upload URL and attachment ID.

Complete the upload

After uploading to the returned URL, confirm the upload:

POST /browse/:key/attachments/:attachmentId/complete
Authorization: Bearer <your-pat>

Download an attachment

GET /browse/:key/attachments/:attachmentId/download
Authorization: Bearer <your-pat>

Returns a signed download URL.

Delete an attachment

DELETE /browse/:key/attachments/:attachmentId
Authorization: Bearer <your-pat>

Dependencies

# List dependencies
GET /browse/:key/dependencies

# Add a dependency
POST /browse/:key/dependencies

# Remove a dependency
DELETE /browse/:key/dependencies/:dependencyId

Custom fields

# Get custom field values for a work item
GET /browse/:key/custom-fields

# Set or update a custom field value
POST /browse/:key/custom-fields

Custom fields are defined on the workflow. Values must conform to the field type defined in the workflow.

Hierarchy

GET /browse/:key/hierarchy
Authorization: Bearer <your-pat>

Returns the full parent/child hierarchy for the work item: its parent project or task, and any child tasks or sub-tasks.

Conversation

# Get the conversation thread for a work item
GET /browse/:key/conversation

# Send an outbound email reply in the conversation
POST /browse/:key/conversation/send

Work item conversations link inbound and outbound email to the item’s thread. See the Email API for how to configure the mailboxes and routing rules that route inbound email to work items.

Spawn an internal sub-item

POST /browse/:key/spawn-internal
Authorization: Bearer <your-pat>
Content-Type: application/json

Creates a child work item (sub-task) under the given key within the same domain. The created item inherits the domain and workflow of its parent unless overridden.

Overview

Work Items

Integrations

Browse and create

List work items

Create a work item

Agent work queue

Get a work item

Update a work item

Delete a work item

Workflow transitions

List available transitions

Claim for agent execution

Complete a work item

Advance a stage gate

Get agent execution context

Comments

List comments

Add a comment

Update a comment

Delete a comment

Attachments

List attachments

Upload an attachment

Download an attachment

Delete an attachment

Categories

Dependencies

Custom fields

Hierarchy

Conversation

Spawn an internal sub-item

​Browse and create

​List work items

​Create a work item

​Agent work queue

​Get a work item

​Update a work item

​Delete a work item

​Workflow transitions

​List available transitions

​Claim for agent execution

​Complete a work item

​Advance a stage gate

​Get agent execution context

​Comments

​List comments

​Add a comment

​Update a comment

​Delete a comment

​Attachments

​List attachments

​Upload an attachment

​Download an attachment

​Delete an attachment

​Categories

​Dependencies

​Custom fields

​Hierarchy

​Conversation

​Spawn an internal sub-item

Browse and create

List work items

Create a work item

Agent work queue

Get a work item

Update a work item

Delete a work item

Workflow transitions

List available transitions

Claim for agent execution

Complete a work item

Advance a stage gate

Get agent execution context

Comments

List comments

Add a comment

Update a comment

Delete a comment

Attachments

List attachments

Upload an attachment

Download an attachment

Delete an attachment

Categories

Dependencies

Custom fields

Hierarchy

Conversation

Spawn an internal sub-item