Managing workspaces

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

Create a workspace

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.

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

Guides

Organization API

Endpoints

Managing workspaces

Create a workspace

All calls

In MCP

​Create a workspace

​All calls

​In MCP

​Sign-in domains

Create a workspace

All calls

In MCP

Sign-in domains