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

# Domains

> Domains are the top-level organizational boundary in OpenIndex — they contain members, workflows, and work items.

A domain is the top-level container for all work in OpenIndex. Everything you create — work items, workflows, categories, mailboxes — belongs to a domain. You organize your teams and operational areas by creating and managing domains.

## Personal domains and shared domains

OpenIndex distinguishes between two kinds of domains:

| Type                | Description                                                                                                                                                          |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Personal domain** | Automatically created for each user. Identified by the special `ME` key in the CLI. Use it for personal tasks, drafts, and workflows that aren't shared with a team. |
| **Shared domain**   | Explicitly created and shared with other users. This is the standard type for team operations.                                                                       |

When you run `oi queue list` or `oi settings domain workflows list --domain ME`, you're targeting your personal domain.

## Domain keys

Each domain has a short alphanumeric key you choose at creation time. The key is used to prefix all work item identifiers in that domain:

```
OPS-1, OPS-2, OPS-123
```

Sub-task keys extend the parent task key:

```
OPS-123.1, OPS-123.2
```

Choose a key that is short and meaningful — it appears on every work item in the domain and cannot be changed after creation.

## Membership roles

Domains support four membership roles with different permission levels:

<AccordionGroup>
  <Accordion title="Owner">
    Full control over the domain, including deleting it. Each domain has exactly one owner. Owners can transfer ownership and manage all members.
  </Accordion>

  <Accordion title="Admin">
    Can manage domain settings, invite and remove members, configure workflows, and create or delete work items. Cannot delete the domain itself.
  </Accordion>

  <Accordion title="Member">
    Can create and update work items, add comments, and manage their own assignments. Cannot change domain settings or manage other members.
  </Accordion>

  <Accordion title="Viewer">
    Read-only access to the domain's work items and workflows. Cannot create or modify any content.
  </Accordion>
</AccordionGroup>

## What you can do in a domain

<CardGroup cols={2}>
  <Card title="Manage workflows" icon="diagram-project">
    Assign workflows to the domain and define the statuses, stages, stage gates, and custom fields that govern work progression.
  </Card>

  <Card title="Create work items" icon="plus">
    Create projects, tasks, and sub-tasks. All work items are keyed with the domain prefix and tracked in a single canonical model.
  </Card>

  <Card title="Invite members" icon="user-plus">
    Add users to the domain with a specific role. Update or revoke membership at any time.
  </Card>

  <Card title="Configure categories" icon="tag">
    Define domain-scoped labels to organize and filter work items. Categories are applied to individual work items and can be used to group related work.
  </Card>
</CardGroup>

## Domain API

### Create a domain

```bash theme={null}
POST /domains
```

```json theme={null}
{
  "key": "OPS",
  "name": "Operations"
}
```

Or with the CLI:

```bash theme={null}
oi settings domain create --key OPS --name "Operations"
```

### Read and update a domain

```bash theme={null}
GET   /domains/:id
PATCH /domains/:id
```

```bash theme={null}
oi settings domain list
oi settings domain get OPS
```

### Manage members

<Tabs>
  <Tab title="API">
    ```bash theme={null}
    GET    /domains/:id/members
    POST   /domains/:id/members
    PATCH  /domains/:domainId/members/:memberId
    DELETE /domains/:domainId/members/:memberId
    ```
  </Tab>

  <Tab title="CLI">
    ```bash theme={null}
    oi settings domain members list --domain OPS
    ```
  </Tab>
</Tabs>

When you invite a member via `POST /domains/:id/members`, provide the user ID and role. Use `PATCH` to change a member's role later, and `DELETE` to remove them.

### Categories

Categories are managed on the domain work item:

```bash theme={null}
GET    /domains/:id/categories
GET    /browse/:key/categories
POST   /browse/:key/categories
DELETE /browse/:key/categories/:categoryId
```

## Deletion safety

Domain deletion is a two-step process to prevent accidental data loss:

<Steps>
  <Step title="Preview the delete">
    Call `GET /domains/:id/delete-preview` to see what will be removed. The response lists all dependent resources — work items, workflows, members, mailboxes — before any data is touched.

    ```bash theme={null}
    oi settings domain delete-preview OPS
    ```
  </Step>

  <Step title="Confirm cascade deletion">
    If you want to proceed, call `DELETE /domains/:id?confirmCascade=true`. The `confirmCascade` query parameter is required. Without it, the delete request is rejected.

    ```bash theme={null}
    DELETE /domains/:id?confirmCascade=true
    ```
  </Step>
</Steps>

<Warning>
  Domain deletion is permanent and cascades to all work items, workflows, categories, and mailboxes in the domain. Always review the delete preview before confirming.
</Warning>