Organisation
Every call needs Authorization: Bearer <key>. 4 calls:
- Get the organisation:
GET /v1/org - Update the organisation:
PATCH /v1/org - List the organisation's workspaces:
GET /v1/workspaces - Create a workspace:
POST /v1/workspaces
Get the organisation
GET /v1/org
Headers
| Name | Type | Required | Description |
|---|---|---|---|
x-workspace-id | string | No | Workspace for session (JWT) callers. API keys carry their own workspace. |
Response 200
| Field | Type | Description |
|---|---|---|
created_at | string (date-time) | ISO 8601 timestamp. |
id | string | Organisation id (org_...). |
logo_url | string or null | |
name | string | |
plan | enum | One of: pilot, growth, enterprise. |
sandbox_enabled | boolean | |
slug | string | |
status | enum | One of: onboarding, live, paused, suspended, offboarded. |
timezone | string | IANA time zone. Up to 64 characters. |
Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500. See errors for the shape and codes.
Update the organisation
PATCH /v1/org
Headers
| Name | Type | Required | Description |
|---|---|---|---|
x-workspace-id | string | No | Workspace for session (JWT) callers. API keys carry their own workspace. |
idempotency-key | string | No | Makes the write safe to retry for 24 hours. 1 to 255 printable characters. Keys starting with outreach:, workflow: or agent: are reserved for messages bubbl3 sends itself and are refused with 400. Up to 255 characters. |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
logo_url | string (uri) or null | No | HTTPS URL. Up to 2048 characters. |
name | string | No | Up to 120 characters. |
sandbox_enabled | boolean | No | |
timezone | string | No | IANA time zone. Up to 64 characters. |
Response 200
| Field | Type | Description |
|---|---|---|
created_at | string (date-time) | ISO 8601 timestamp. |
id | string | Organisation id (org_...). |
logo_url | string or null | |
name | string | |
plan | enum | One of: pilot, growth, enterprise. |
sandbox_enabled | boolean | |
slug | string | |
status | enum | One of: onboarding, live, paused, suspended, offboarded. |
timezone | string | IANA time zone. Up to 64 characters. |
Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500. See errors for the shape and codes.
List the organisation's workspaces
GET /v1/workspaces
Headers
| Name | Type | Required | Description |
|---|---|---|---|
x-workspace-id | string | No | Workspace for session (JWT) callers. API keys carry their own workspace. |
Response 200
| Field | Type | Description |
|---|---|---|
data | object[] | |
data[].created_at | string (date-time) | ISO 8601 timestamp. |
data[].id | string | Workspace id (ws_...). |
data[].is_default | boolean | |
data[].name | string | |
data[].org_id | string | Organisation id (org_...). |
Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500. See errors for the shape and codes.
Create a workspace
POST /v1/workspaces
The caller becomes the owner of the new workspace.
Headers
| Name | Type | Required | Description |
|---|---|---|---|
x-workspace-id | string | No | Workspace for session (JWT) callers. API keys carry their own workspace. |
idempotency-key | string | No | Makes the write safe to retry for 24 hours. 1 to 255 printable characters. Keys starting with outreach:, workflow: or agent: are reserved for messages bubbl3 sends itself and are refused with 400. Up to 255 characters. |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Up to 80 characters. |
Response 201
| Field | Type | Description |
|---|---|---|
created_at | string (date-time) | ISO 8601 timestamp. |
id | string | Workspace id (ws_...). |
is_default | boolean | |
name | string | |
org_id | string | Organisation id (org_...). |
Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500. See errors for the shape and codes.