> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orca.0-9.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Work Items API

> Create, read, update, and manage work items via the OpenIndex 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](/api/authentication).

## Browse and create

### List work items

```bash theme={null}
GET /browse
Authorization: Bearer <your-pat>
```

<ParamField path="query.kind" type="string">
  Filter by work item type: `project`, `task`, or `sub_task`.
</ParamField>

<ParamField path="query.domainId" type="string">
  Filter by domain ID.
</ParamField>

<ParamField path="query.status" type="string">
  Filter by status value.
</ParamField>

<ParamField path="query.search" type="string">
  Full-text search across title and description.
</ParamField>

### Create a work item

```bash theme={null}
POST /browse
Authorization: Bearer <your-pat>
Content-Type: application/json
```

<ParamField path="body.kind" type="string" required>
  Work item type: `project`, `task`, or `sub_task`.
</ParamField>

<ParamField path="body.title" type="string" required>
  Work item title.
</ParamField>

<ParamField path="body.domainId" type="string" required>
  ID of the domain to create the item in.
</ParamField>

<ParamField path="body.parentKey" type="string">
  Key of the parent work item. Required for `sub_task`; optional for `task` (creates under a project).
</ParamField>

<ParamField path="body.workflowId" type="string">
  Workflow to assign. If omitted, the domain default workflow is used.
</ParamField>

<ParamField path="body.description" type="string">
  Markdown-formatted description.
</ParamField>

<ParamField path="body.status" type="string">
  Initial status. Must be a valid status for the assigned workflow.
</ParamField>

<ParamField path="body.priority" type="string">
  Priority level (e.g. `low`, `medium`, `high`, `critical`).
</ParamField>

<ParamField path="body.executionTarget" type="string">
  Target agent or executor ID for agent-dispatched items.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  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"
    }'
  ```

  ```json Response theme={null}
  {
    "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"
  }
  ```
</CodeGroup>

### Agent work queue

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
POST /browse/:key/claim
Authorization: Bearer <your-pat>
Content-Type: application/json
```

<ParamField path="body.toStatus" type="string" required>
  The status to transition the item to when claiming.
</ParamField>

<ParamField path="body.agentId" type="string" required>
  ID of the agent claiming the item.
</ParamField>

### Complete a work item

```bash theme={null}
POST /browse/:key/complete
Authorization: Bearer <your-pat>
Content-Type: application/json
```

<ParamField path="body.toStatus" type="string" required>
  The completion status to transition to.
</ParamField>

<ParamField path="body.agentId" type="string" required>
  ID of the agent completing the item.
</ParamField>

### Advance a stage gate

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
GET /browse/:key/comments
Authorization: Bearer <your-pat>
```

### Add a comment

```bash theme={null}
POST /browse/:key/comments
Authorization: Bearer <your-pat>
Content-Type: application/json
```

<ParamField path="body.body" type="string" required>
  Comment text. Supports Markdown.
</ParamField>

### Update a comment

```bash theme={null}
PATCH /browse/:key/comments/:commentId
Authorization: Bearer <your-pat>
Content-Type: application/json
```

### Delete a comment

```bash theme={null}
DELETE /browse/:key/comments/:commentId
Authorization: Bearer <your-pat>
```

## Attachments

### List attachments

```bash theme={null}
GET /browse/:key/attachments
Authorization: Bearer <your-pat>
```

### Upload an attachment

Uploading a file is a two-step process:

<Steps>
  <Step title="Initiate the upload">
    ```bash theme={null}
    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.
  </Step>

  <Step title="Complete the upload">
    After uploading to the returned URL, confirm the upload:

    ```bash theme={null}
    POST /browse/:key/attachments/:attachmentId/complete
    Authorization: Bearer <your-pat>
    ```
  </Step>
</Steps>

### Download an attachment

```bash theme={null}
GET /browse/:key/attachments/:attachmentId/download
Authorization: Bearer <your-pat>
```

Returns a signed download URL.

### Delete an attachment

```bash theme={null}
DELETE /browse/:key/attachments/:attachmentId
Authorization: Bearer <your-pat>
```

## Categories

```bash theme={null}
# 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

```bash theme={null}
# List dependencies
GET /browse/:key/dependencies

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

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

## Custom fields

```bash theme={null}
# 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

```bash theme={null}
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

```bash theme={null}
# 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](/api/email) for how to configure the mailboxes and routing rules that route inbound email to work items.

## Spawn an internal sub-item

```bash theme={null}
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.