Create a workspace

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-99); 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.

POST /workspaces

Create a workspace

cURL

curl --request POST \
  --url https://app.timelines.ai/partner/api/v1/workspaces \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-TL-Partner-Id: <x-tl-partner-id>' \
  --data '
{
  "display_name": "my-first-workspace (must contain only letters, digits and dash)",
  "seats_purchased": 3
}
'

201

{
  "workspace_id": "ws_1234567890abcdef",
  "display_name": "my-first-workspace",
  "plan_id": 1,
  "seats_total": 3,
  "seats_available": 2,
  "updated_at": "2024-01-01T12:00:00Z",
  "owner_user_id": 42,
  "group_id": 7,
  "created_at": "2024-01-01T10:00:00Z",
  "suspended_members": [
    {
      "user_id": 123,
      "whatsapp_account_id": 1092930,
      "phone_numbers": [
        "[phone]"
      ]
    }
  ]
}

Authorizations

Authorization · string · header · required

JWT bearer authentication. The token payload must include partner_id, nbf (not-before) and exp (expiry) claims. All Partner API requests must be authenticated with Authorization: Bearer .

Headers

X-TL-Partner-Id · string · required

The unique identifier for the partner.

Body

application/json

Workspace creation request payload

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

Required string length: 1 - 30

Example:

"my-first-workspace (must contain only letters, digits and dash)"

seats_purchased · integer · default: 1 · required

Number of workspace seats

Required range: 1 <= x <= 99

Example:

3

Response

201

application/json

Workspace created

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

Example:

"ws_1234567890abcdef"

display_name · string · required

Workspace display name

Example:

"my-first-workspace"

plan_id · integer · required

Workspace plan type

Example:

1

seats_total · integer · required

Total number of seats in the workspace

Example:

3

seats_available · integer · required

Number of available seats in the workspace

Example:

2

updated_at · string<date-time>

Timestamp of the last update

Example:

"2024-01-01T12:00:00Z"

owner_user_id · integer

User ID of the workspace owner

Example:

42

group_id · integer

Group ID associated with the workspace

Example:

7

created_at · string<date-time>

Timestamp of workspace creation

Example:

"2024-01-01T10:00:00Z"

suspended_members · object[]

array of suspended user IDs

Show child attributes