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

# Create a workspace

`POST /workspaces`

Creates a new partner-managed workspace and automatically provisions an Owner user. The workspace_id identifier is derived from the requested display_name (lowercase, alphanumeric and dashes, up to 30 characters). The workspace is created on the calling partner's plan and linked to that partner for ownership and billing-eligibility checks. An Owner user is created with a non-login, system-managed email of the form `<user_id>-<workspace-id>@partners.timelines.ai` and added to the default workspace group. Seats are allocated according to seats_purchased (1-999); the Owner consumes one seat and the remaining seats become available for additional agents. On success the response returns workspace metadata, seat counters and the newly created owner_user_id. Conflicts on identifier generation (duplicate workspace_id) are reported with a 409 WorkspaceCreationFailed error.

## Headers

- `X-TL-Partner-Id` string, required

## Request body

- PartnerAPIWorkspaceCreateRequest — Request payload for creating a new partner-managed workspace. Partners supply a human-friendly display_name and the initial number of purchased seats. The server derives the internal workspace_id identifier from display_name and provisions the workspace on the partner’s plan with the requested seats.
  - `display_name` string, required — Workspace display name
  - `seats_purchased` integer, required — Number of workspace seats

## Response `201`

Workspace created

- PartnerAPIWorkspaceResponse — Representation of a partner-managed workspace returned after creation or update. It includes the stable workspace_id, display_name, linked plan_id, seat allocation and utilization, audit timestamps, the default group identifier, the automatically generated Owner user, and any suspended members that resulted from a seat downgrade.
  - `workspace_id` string, required — Unique identifier for the workspace
  - `display_name` string, required — Workspace display name
  - `plan_id` integer, required — Workspace plan type
  - `seats_total` integer, required — Total number of seats in the workspace
  - `seats_available` integer, required — Number of available seats in the workspace
  - `updated_at` string, date-time — Timestamp of the last update
  - `owner_user_id` integer — User ID of the workspace owner
  - `group_id` integer — Group ID associated with the workspace
  - `created_at` string, date-time — Timestamp of workspace creation
  - `suspended_members` SuspendedMember[] — array of suspended user IDs
    - `user_id` integer, required — ID of the suspended user
    - `whatsapp_account_id` integer — ID of the WhatsApp account associated with the suspended user
    - `phone_numbers` string[] — List of phone numbers associated with the suspended user

## Other responses

- `409` — Workspace with this name already exists

## Changes

- **2026-07-01** `3b25460ca964` — 1 info
  - the `display_name` request property's maxLength was increased from `30` to `100`
- **2026-02-25** `620de7c48b91` — 1 info
  - the `seats_purchased` request property's max was increased from `99.00` to `999.00`
- **2026-02-10** `e194e97d18e1` — 1 info
  - endpoint added
- **2026-02-10** `e609fc1e2ea3` — 1 breaking
  - api path removed without deprecation

[Change history](https://skmtc.dev/initechsoftware/apis/partner-api/changes/workspaces/post.md)

---

[API](https://skmtc.dev/initechsoftware/apis/partner-api.md) · [All operations](https://skmtc.dev/initechsoftware/apis/partner-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/initechsoftware/partner-api/revisions/f5ac60374320/schema)