Skip to main content
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>
​
query.kind
string
Filter by work item type: project, task, or sub_task.
​
query.domainId
string
Filter by domain ID.
​
query.status
string
Filter by status value.
​
query.search
string
Full-text search across title and description.

​
Create a work item

POST /browse
Authorization: Bearer <your-pat>
Content-Type: application/json
​
body.kind
string
required
Work item type: project, task, or sub_task.
​
body.title
string
required
Work item title.
​
body.domainId
string
required
ID of the domain to create the item in.
​
body.parentKey
string
Key of the parent work item. Required for sub_task; optional for task (creates under a project).
​
body.workflowId
string
Workflow to assign. If omitted, the domain default workflow is used.
​
body.description
string
Markdown-formatted description.
​
body.status
string
Initial status. Must be a valid status for the assigned workflow.
​
body.priority
string
Priority level (e.g. low, medium, high, critical).
​
body.executionTarget
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"
  }'

​
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
​
body.toStatus
string
required
The status to transition the item to when claiming.
​
body.agentId
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
​
body.toStatus
string
required
The completion status to transition to.
​
body.agentId
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
​
body.body
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:
1

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.
2

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>

​
Categories

# List categories assigned to a work item
GET /browse/:key/categories

# Assign a category
POST /browse/:key/categories

# Remove a category
DELETE /browse/:key/categories/:categoryId
Categories are domain-scoped labels. You can assign multiple categories to a single work item.

​
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.