---
title: "Create a workspace"
method: POST
path: "/workspaces"
tags: ["Workspace"]
---

# Create a workspace

`POST /workspaces`

## Request

- Base URL: `https://api.emailchaser.com/r`
- URL: `https://api.emailchaser.com/r/workspaces`
- Auth: HTTP bearer

Creates a sub-workspace under the API key's main workspace and, by default, mints a read+write API key bound to the new workspace. The key's fullKey is returned exactly once and cannot be retrieved again, and it never outlives the caller: when the calling key has an expiry, the minted key carries the same expiresAt. Must be called with a main workspace's key: keys bound to sub-workspaces are refused. API keys are included in every plan; workspaces are a Professional-plan feature.

## Request body

- ModelsCreateWorkspaceRequest
  - `generateApiKey` boolean: GenerateApiKey mints a read+write API key bound to the new workspace. Defaults to true; pass false to create the workspace only.
  - `name` string, required: Name of the new workspace. Trimmed; 1-60 characters.

## Response `201`

The created workspace and its API key

- ModelsCreateWorkspaceResponse
  - `apiKey` ModelsCreatedApiKey
    - `expiresAt` string: ExpiresAt is set when the key expires: it inherits the calling key's own expiry, so a temporary key never mints a permanent one. Null for keys minted by a non-expiring key.
    - `fullKey` string
    - `id` integer
    - `name` string
    - `scopes` string[]
  - `note` string: Note reminds integrators that fullKey is not retrievable later.
  - `workspace` ModelsWorkspaceItem
    - `createdAt` string
    - `iconUrl` string: IconURL is where the workspace's icon image can be loaded from. Empty when the workspace has none. Icons are uploaded in the app.
    - `id` integer
    - `isCurrent` boolean: IsCurrent is true for the workspace the calling API key is bound to.
    - `name` string

## Other responses

- `400`: Invalid request body or calling key is not bound to a main workspace
- `401`: Unauthorized - invalid or missing API key
- `403`: The workspace's plan does not include workspaces, or the subscription is not active
- `500`: Failed to create workspace

---

[API](https://skmtc.dev/emailchaser/apis/emailchaser-api.md) · [All operations](https://skmtc.dev/emailchaser/apis/emailchaser-api/llms.txt) · [OpenAPI document](https://skmtc.dev/emailchaser/apis/emailchaser-api/revisions/8b114990abb7?raw)