Create Workspace
Create a new workspace with the authenticated user as the owner.
The new workspace is a sub-workspace of your master workspace (parentWorkspaceId is set to the master). It uses your master workspace's plan tier, and if the master is white-labelled (agency mode) it inherits the master's branding.
Creating workspaces is subject to your plan's workspace limit (see the errors below).
Headers
x-workspace-idstringrequiredThe _id of any workspace you're a member of. Required by the API-key auth check. It doesn't affect where the new workspace is created.
Request Body
namestringrequiredThe name of the workspace (for example "Marketing Team Workspace").
initialsstringrequiredInitials shown for the workspace (for example "MT").
Any other fields are ignored.
Response
The new workspace object, including:
_idstringThe new workspace's ID.
namestringThe workspace name.
initialsstringThe workspace initials.
parentWorkspaceIdstringYour master workspace's ID.
teamMembersarrayThe workspace's team members, starting with you as the owner.
createdAtstringWhen the workspace was created (ISO 8601).
updatedAtstringWhen the workspace was last updated (ISO 8601).
Studio plan: paying for an extra workspace
On a Studio plan, creating a workspace past the plan's included number returns 402. For API-key requests, the response includes a Stripe Checkout link:
{
"error": "Your current plan is limited to <limit> workspaces. Please upgrade to create more.",
"requiresPayment": true,
"isStudioPlan": true,
"sessionId": "cs_live_...",
"sessionUrl": "https://checkout.stripe.com/c/pay/cs_live_...",
"message": "Your Studio plan workspace limit has been reached. ..."
}
Send the user to sessionUrl. The workspace is created automatically, with the name and initials you sent, once payment succeeds. It is not created by this request.
Errors
| Status | Body | When |
|---|---|---|
402 | {"error": "...", "requiresPayment": true, "isStudioPlan": true, ...} | Studio plan over its included workspaces (see above) |
403 | {"error": "Please subscribe to a plan to create workspaces", "subscriptionCanceled": true} | Your subscription is cancelled |
423 | {"error": "...", "code": "WORKSPACE_CHANGE_IN_PROGRESS"} | Another workspace create or restore for your account is still running. Retry shortly |
500 | {"error": "..."} | Unexpected server error |
{
"name": "Marketing Team Workspace",
"initials": "MT"
}Last updated on