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

# Managing workspaces

> Create, rename, suspend, resume and delete the workspaces of your organization

You create one workspace for each of your clients. These calls need the `tenants:write`
scope, except the two reads.

## Create a workspace

```bash theme={null}
curl -X POST https://api.clustr-ai.com/api/org/v1/tenants \
  -H "Authorization: Bearer $CLUSTR_ORG_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme", "externalId": "client-1234" }'
```

| Field | Meaning |
| - | - |
| `name` | The workspace's name. Required. |
| `externalId` | Your own id for the client. Unique in your organization. A second workspace with the same `externalId` answers `409`. |

The answer is `201` with the workspace in `data`: `id`, `name`, `externalId`,
`suspendedAt` and `createdAt`. Its `id` and your `externalId` both work in
[`X-Clustr-Tenant`](https://docs.clustr-ai.com/enterprise/working-in-a-workspace).

## All calls

| Call | What it does |
| - | - |
| `GET /api/org/v1/tenants` | List your workspaces. `limit` (default 100, at most 500) and `offset` page the list. |
| `POST /api/org/v1/tenants` | Create a workspace. |
| `GET /api/org/v1/tenants/{tenantID}` | Read one workspace. |
| `PATCH /api/org/v1/tenants/{tenantID}` | Change `name` or `externalId`. |
| `POST /api/org/v1/tenants/{tenantID}/suspend` | Stop new jobs and writes. Reads still work. |
| `POST /api/org/v1/tenants/{tenantID}/resume` | Undo a suspend. |
| `DELETE /api/org/v1/tenants/{tenantID}` | Delete the workspace. Your organization and keys stay. |

A delete cannot be undone. A `tenant.deleted` [webhook](https://docs.clustr-ai.com/enterprise/webhooks.md) is sent. Your default workspace, the one your team signs in to, cannot be deleted: the call answers `409`.

## In MCP

Organization admins have the same operations as tools: `org_list_tenants`,
`org_create_tenant`, `org_get_tenant`, `org_update_tenant`, `org_suspend_tenant`,
`org_resume_tenant` and `org_delete_tenant`. They take the workspace as `id` or
`external_id`.

## Sign-in domains

Organization admins can let people join by email domain, through the app or MCP.
`org_get_sign_in_settings` lists the domains and their status. `org_add_domain` starts
verification and returns the DNS `TXT` record to publish. `org_verify_domain` checks it.
Once a domain is verified, anyone who signs in with an email on it joins the
organization. `org_remove_domain` takes a domain off.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.