Sign inGet Started
Get started
Guides
API Reference
SDKs
CLI
Knowledge Base
Changelog

Create a workspace

Create a workspace in your organization with POST /v1/organization/workspaces. Use this request when your integration provisions workspaces for separate teams or applications.

Prepare access

Before your integration can create workspaces:

  1. Contact your Bird representative to enable organization master keys and confirm your organization's workspace limit. The limit is the total number of workspaces the organization can hold. For example, a limit of five with two existing workspaces leaves three available slots.
  2. Have an organization owner or administrator create a key using the Organization master keys guide. This works with one workspace once your organization has a master key allowance.
  3. Load the key into BIRD_MASTER_KEY from your secret manager. Set BIRD_API_URL to https://eu1.platform.bird.com for a bm_eu1_ key, or https://us1.platform.bird.com for a bm_us1_ key.

Workspace creation requires organization-level workspace write access (org:workspaces:write), which a master key includes. A workspace API key cannot make this organization request. The master key identifies the organization. Omit X-Organization-Id and X-Workspace-Id.

Create the workspace

Send a JSON object containing name. The name must be 3–100 characters and include a letter or number. Leading and trailing whitespace is removed, and repeated whitespace is collapsed. Additional body fields are not accepted.

Choose an Idempotency-Key for this provisioning operation and keep it for retries. Replace YOUR_PROVISIONING_ID with an identifier from your application. Use a different value for each new workspace.

Code example
curl -X POST "$BIRD_API_URL/v1/organization/workspaces" \
  -H "Authorization: Bearer $BIRD_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: create-workspace/YOUR_PROVISIONING_ID" \
  -d '{"name":"Production"}'

The API returns 201 Created with the workspace object:

Code example
{
  "created_at": "2026-10-16T08:41:57.436537049Z",
  "id": "ws_01m51y01dwf0v907kfpc1k1bcq",
  "name": "Production",
  "notification_emails": {
    "operational": []
  },
  "organization_id": "org_01m51xw64pf4bb28sjztpk7ttt",
  "updated_at": "2026-10-16T08:41:57.436537049Z"
}

Save the returned id. To make product requests in the new workspace with the same master key, send that ID in X-Workspace-Id. See Make a workspace request.

Retry a creation request

The Idempotency-Key header is optional, but requests without it have no deduplication. Retry with the same key, method, URL, and body. A retained response is replayed with the original status and body and an Idempotency-Replay: true header. Keys for this endpoint are scoped to the organization.

Follow the retention window and retry guidance in Idempotency. After the retained response expires, the same request can create another workspace. If creation succeeds but its response cannot be retained, a retry can also create another workspace. Keep the returned workspace ID in your application's provisioning record.

Troubleshoot creation

ResponseWhat to check
422, E01001Send the required name field and check its length and content. Remove additional body fields. In each details entry, param is name for an invalid name, or body for a missing or extra field, which message then names.
401, E02072Check that the key was copied whole, including its bm_ prefix, and that BIRD_API_URL is the host for the key's region.
401, E02036The key has expired, for example after a rotation grace period ended. Use the replacement key.
401, E02002The key has been revoked. Create or rotate a master key.
403Use a master key for the intended organization with organization workspace write access.
422, E10014The organization has reached its workspace limit. Ask your Bird representative to raise the total limit.
409, E01004A request with the same idempotency key is in progress. Wait briefly, then retry the same request.
409, E01005The idempotency key was used for a different request. Use a new key for a new provisioning operation.
503, E01033Idempotency protection is unavailable and this attempt did not execute. Retry with backoff using the same key and request.

Workspaces awaiting permanent deletion still count toward the workspace limit. Deleting a workspace does not immediately free a slot.

Next steps