Skip to main content
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.

​
Domains

​
List domains

GET /domains
Authorization: Bearer <your-pat>
Returns all domains the authenticated user is a member of.

​
Create a domain

POST /domains
Authorization: Bearer <your-pat>
Content-Type: application/json
​
body.name
string
required
Display name for the domain.
​
body.key
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.
​
body.description
string
Optional description.
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"
  }'

​
Get a domain

GET /domains/:id
Authorization: Bearer <your-pat>

​
Update a domain

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

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.
Always run the delete preview before deleting a domain. Review the impact before proceeding.

​
Step 2: Confirm and delete

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:
RoleAccess
ownerFull access including deleting the domain and managing all members.
adminManage work items, workflows, members (except owners), and domain settings.
memberCreate and update work items. Cannot manage domain settings or membership.
viewerRead-only access to all domain resources.

​
List members

GET /domains/:id/members
Authorization: Bearer <your-pat>

​
Add a member

POST /domains/:id/members
Authorization: Bearer <your-pat>
Content-Type: application/json
​
body.userId
string
required
ID of the user to add.
​
body.role
string
required
Role to assign: admin, member, or viewer.

​
Update a member’s role

PATCH /domains/:domainId/members/:memberId
Authorization: Bearer <your-pat>
Content-Type: application/json
​
body.role
string
required
New role: admin, member, or viewer.

​
Remove a member

DELETE /domains/:domainId/members/:memberId
Authorization: Bearer <your-pat>
Removes the member from the domain. Their work items remain assigned but they lose access.