Skip to main content
Every piece of work in OpenIndex lives in a four-level hierarchy. Understanding this structure helps you create, organize, and act on work correctly — whether you’re a human configuring a domain or an agent executing tasks.

​
The hierarchy

Domain
└── Project
    └── Task
        └── Sub-task

Domain

The top-level operational boundary. Owns workflows, members, categories, mailboxes, and all work items beneath it.

Project

A container for a larger objective inside a domain. Groups related tasks under a single trackable item.

Task

The standard executable work item under a project. Tasks are what humans and agents actually do.

Sub-task

A granular executable unit under a task. Sub-tasks let you break a task into independently trackable steps.

​
Work item kinds

Every work item has a kind field that identifies its level in the hierarchy:
KindDescription
projectContainer for a larger objective
taskStandard executable work item under a project
sub_taskGranular executable work item under a task

​
Work item keys

Work item keys are domain-scoped and sequential. When you create a work item in a domain with the key OPS, the platform assigns keys like OPS-1, OPS-2, OPS-123. Sub-task keys extend their parent task key with an ordinal suffix:
ItemKey
TaskABC-123
First sub-taskABC-123.1
Second sub-taskABC-123.2
Tasks can only move within the same domain. You cannot reassign a task from one domain to another — keys are permanently scoped to the domain where the item was created.

​
Work item fields

Every work item shares a common set of fields:
FieldDescription
titleShort label for the work item
descriptionFree-text detail about the work
statusCurrent workflow status (e.g., todo, in_progress, done)
priorityRelative urgency of the item
execution_targetWho should execute this item: human, agent, or either
assigneeThe user currently assigned to the item
ownerThe user who owns the item
scheduleOptional date or datetime range for when work is planned
The execution_target field is particularly important for agent workflows. When an agent calls oi queue list, only items with execution_target set to agent or either appear in the available bucket.

​
Categories

Categories are domain-scoped labels you attach to work items for organization and filtering. A work item can have multiple categories. You manage categories on a work item through the /browse/:key/categories endpoint: 
GET  /browse/:key/categories
POST /browse/:key/categories
DELETE /browse/:key/categories/:categoryId

​
Dependencies

Work items can depend on other work items. Dependencies let you express ordering and blocking relationships across your backlog. 
GET    /browse/:key/dependencies
POST   /browse/:key/dependencies
DELETE /browse/:key/dependencies/:dependencyId

​
Comments

Comments on work items support two visibility levels:
VisibilityDescription
internalVisible only to domain members (default)
externalIncluded in outbound email threads for external collaborators
oi work-item comment create ABC-123 --body "Investigation complete." --visibility internal

​
Attachments

You can attach files or link external URLs to any work item. File uploads go through a two-step initiate/complete flow; URL attachments are added directly. 
oi work-item attachment upload ABC-123 --file ./report.pdf
oi work-item attachment link  ABC-123 --url https://example.com/doc

​
Custom fields

Workflows can define additional fields that are required when a work item transitions through specific stage gates. These custom fields are stored per work item and keyed to the workflow definition. 
oi work-item custom-fields get ABC-123
oi work-item custom-fields update ABC-123 --values-json '{"acceptance_criteria": "All tests pass"}'
Use oi work-item agent-context ABC-123 to see which custom fields are required before you can advance through the next stage gate. The response includes requiredFields for the current transition.

​
Audit history

Every mutation to a work item — status changes, field updates, comments, assignments — is recorded in the audit log. You can retrieve and export the history for any item: 
oi work-item audit list ABC-123
oi work-item audit export ABC-123 --format json --output ./audit.json
The audit log includes correlation IDs, making it easy to trace a sequence of related changes.