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

> Create and manage domains and domain membership via the OpenIndex API.

Domains are the top-level organizational boundary in OpenIndex. Each domain owns its own work items, workflows, categories, and mailboxes. Membership is role-based: `owner`, `admin`, `member`, or `viewer`.

All domain endpoints require a Bearer token. See [API Authentication](/api/authentication).

## Domains

### List domains

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

Returns all domains the authenticated user is a member of.

### Create a domain

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

<ParamField path="body.name" type="string" required>
  Display name for the domain.
</ParamField>

<ParamField path="body.key" type="string" required>
  Short uppercase key used as the prefix for work item keys (e.g. `OPS` produces keys like `OPS-1`). Must be unique across the instance.
</ParamField>

<ParamField path="body.description" type="string">
  Optional description.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://your-deployment.convex.site/domains \
    --header 'Authorization: Bearer oi_pat_...' \
    --header 'Content-Type: application/json' \
    --data '{
      "name": "Operations",
      "key": "OPS",
      "description": "Internal operations team"
    }'
  ```

  ```json Response theme={null}
  {
    "id": "domain_abc123",
    "name": "Operations",
    "key": "OPS",
    "description": "Internal operations team",
    "createdAt": "2026-03-31T10:00:00Z"
  }
  ```
</CodeGroup>

### Get a domain

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

### Update a domain

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

You can update `name` and `description`. The domain `key` cannot be changed after creation.

## Deleting a domain

Deleting a domain cascades to all work items, workflows, and memberships in that domain. Because this is destructive, OpenIndex requires a two-step delete flow.

### Step 1: Preview the deletion

```bash theme={null}
GET /domains/:id/delete-preview
Authorization: Bearer <your-pat>
```

Returns a summary of all resources that will be deleted, including work item counts, workflow counts, and member counts.

<Warning>
  Always run the delete preview before deleting a domain. Review the impact before proceeding.
</Warning>

### Step 2: Confirm and delete

```bash theme={null}
DELETE /domains/:id?confirmCascade=true
Authorization: Bearer <your-pat>
```

The `confirmCascade=true` query parameter is required. Requests without it are rejected. The deletion is permanent and cannot be undone.

## Domain membership

Members have one of four roles:

| Role     | Access                                                                      |
| -------- | --------------------------------------------------------------------------- |
| `owner`  | Full access including deleting the domain and managing all members.         |
| `admin`  | Manage work items, workflows, members (except owners), and domain settings. |
| `member` | Create and update work items. Cannot manage domain settings or membership.  |
| `viewer` | Read-only access to all domain resources.                                   |

### List members

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

### Add a member

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

<ParamField path="body.userId" type="string" required>
  ID of the user to add.
</ParamField>

<ParamField path="body.role" type="string" required>
  Role to assign: `admin`, `member`, or `viewer`.
</ParamField>

### Update a member's role

```bash theme={null}
PATCH /domains/:domainId/members/:memberId
Authorization: Bearer <your-pat>
Content-Type: application/json
```

<ParamField path="body.role" type="string" required>
  New role: `admin`, `member`, or `viewer`.
</ParamField>

### Remove a member

```bash theme={null}
DELETE /domains/:domainId/members/:memberId
Authorization: Bearer <your-pat>
```

Removes the member from the domain. Their work items remain assigned but they lose access.