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

# Create a workspace

`POST /workspaces`

## Request

- Base URL: `https://www.happyscribe.com/api/v1`
- URL: `https://www.happyscribe.com/api/v1/workspaces`
- Auth: API key in header `Authorization`

Creates a workspace with the caller as its owner. The new workspace starts
on the free plan.

## Request body

- object
  - `name` string, required: Name of the workspace.
  - `metadata` union: Merged into the object's metadata: the keys you send are added or overwritten and the others kept. `""` as a value removes that key; `metadata: ""` removes every key. Numbers and booleans are stored as their text; objects, arrays and `null` are refused.
    - object
    - ''

## Response `201`

The created workspace.

- Workspace
  - `id` string: Workspace ID, beginning with `wks_`. Treat it as an opaque string.
  - `name` string: The workspace name, shown to its members in HappyScribe.
  - `role` 'owner' | 'admin' | 'member' | 'guest': The authenticated user's role in this workspace. - `owner`: owns the workspace. - `admin`: manages the workspace. - `member`: records and reads their own meetings. - `guest`: sees only what is shared with them.
  - `created_at` string, date-time: When it was created, in ISO 8601.
  - `updated_at` string, date-time: When it last changed, in ISO 8601.
  - `owner_email` string: (staff only) Email address of the workspace owner.
  - `members_count` integer: (staff only) Number of members, excluding guests and deleted users.
  - `is_human_transcription_allowed` boolean: (staff only) Whether the workspace may order human transcription.
  - `is_human_translation_allowed` boolean: (staff only) Whether the workspace may order human translation.
  - `email_domains` string[]: (staff only) Domains that auto-join the workspace at sign-up.
  - `idp_company_names` string[]: (staff only) IdP company names configured for SSO.
  - `currency` string: (staff only) Billing currency code, e.g. `usd`, `eur`, `gbp`.
  - `metadata` Metadata: Your own key-value pairs, for your ids and context. HappyScribe stores them, returns them on the object and in every webhook that carries it, and never acts on them. Up to 50 keys of up to 40 characters (no square brackets), values up to 500 characters. See [metadata](/meetingkit/setup#a-workspace-per-customer).

## Other responses

- `401`: Your API key is missing (`missing_api_key`) or wrong (`invalid_api_key`), or it may not access this resource (`unauthorized`).
- `403`: The caller may not create workspaces — SSO users without a staff membership, and members of a workspace whose administrators restrict it, cannot create workspaces. Code `workspace_creation_not_allowed`.
- `422`: Invalid `name`: missing, blank, longer than 100 characters, containing control characters, or shaped like a URL or path (names containing `://`, or both a `.` and a `/`, are rejected).
- `429`: The caller created too many workspaces in the last 24 hours (archived ones count). Retry after the number of seconds in `Retry-After`. Code `workspace_creation_rate_limited`.

---

[API](https://skmtc.dev/happyscribe/apis/happyscribe-api.md) - [All operations](https://skmtc.dev/happyscribe/apis/happyscribe-api/llms.txt) - [OpenAPI document](https://skmtc.dev/happyscribe/apis/happyscribe-api/revisions/1281bd968c3d?raw)