Workspaces#

Manage workspaces, team members, invitations, and workspace-level settings.

Authentication required

All endpoints require a Bearer token in the Authorization header. See the Authentication guide for setup instructions.

GET /v1/workspaces#

List workspaces the current user belongs to, with membership details.

bash

GET /v1/workspaces?page_index=0&page_size=25&user_id=6c9e4b21-8d05-4f7a-b3c2-1e5a9d8f4b07
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
pageIndex	`integer`	Required	Zero-based page index for pagination.
pageSize	`integer`	Required	Number of items per page (1-100).
userId	`string (UUID)`	Required	User identifier to list workspaces for.

Response#

Returns { items, totalCount, facets, _meta } with paginated results.

GET /v1/workspaces/:id#

Retrieve a single workspace by ID.

bash

GET /v1/workspaces/:id
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
id	`string (UUID)`	Required	Workspace identifier.

Response#

Returns { data, _meta } with the result.

POST /v1/workspaces#

Create a workspace with a name, timezone, and currency, then assign the requesting user as owner.

bash

POST /v1/workspaces
Authorization: Bearer {token}
Content-Type: application/json

{
  "user_id": "6c9e4b21-8d05-4f7a-b3c2-1e5a9d8f4b07",
  "name": "My Campaign"
}

Parameters#

Name	Type	Required	Description
userId	`string (UUID)`	Required	User identifier of the workspace owner.
organizationId	`string (UUID)`	—	Organization to add the workspace to. Defaults to the first organization the user owns or administers.
name	`string`	Required	Workspace name, usually the brand.
ianaTimezone	`'UTC' \| 'America/New_York' \| 'America/Chicago' \| 'America/Denver' \| 'America/Los_Angeles' \| 'America/Anchorage' \| 'Pacific/Honolulu' \| 'America/Toronto' \| 'America/Vancouver' \| 'Europe/London' \| 'Europe/Paris' \| 'Europe/Berlin' \| 'Australia/Sydney' \| 'Australia/Melbourne' \| 'Pacific/Auckland' \| 'Asia/Tokyo' \| 'Asia/Singapore' \| null`	—	IANA timezone identifier.
currency	`'USD' \| 'CAD' \| 'GBP' \| 'EUR' \| 'AUD' \| 'NZD' \| 'JPY' \| 'SGD'`	—	ISO 4217 currency code.

Response#

Returns { data, _meta } with the result.

PATCH /v1/workspaces/:id#

Update a workspace's name, avatar, timezone, currency, or country.

Owner only

bash

PATCH /v1/workspaces/:id
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
id	`string (UUID)`	Required	Workspace identifier to update.
name	`string`	—	Updated workspace name (1-255 characters).
avatarKey	`string \| null`	—	Storage key for the workspace avatar image. Set to null to remove.
ianaTimezone	`'UTC' \| 'America/New_York' \| 'America/Chicago' \| 'America/Denver' \| 'America/Los_Angeles' \| 'America/Anchorage' \| 'Pacific/Honolulu' \| 'America/Toronto' \| 'America/Vancouver' \| 'Europe/London' \| 'Europe/Paris' \| 'Europe/Berlin' \| 'Australia/Sydney' \| 'Australia/Melbourne' \| 'Pacific/Auckland' \| 'Asia/Tokyo' \| 'Asia/Singapore' \| null`	—	Updated IANA timezone.
currency	`'USD' \| 'CAD' \| 'GBP' \| 'EUR' \| 'AUD' \| 'NZD' \| 'JPY' \| 'SGD'`	—	Updated currency code.

Response#

Returns { data, _meta } with the result.

DELETE /v1/workspaces/:id#

Delete a workspace by marking it deleted rather than permanently erasing its records. Requires workspace-owner permissions. Requests using Brandwave agent access tokens are rejected.

Owner only

bash

DELETE /v1/workspaces/:id
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
id	`string (UUID)`	Required	Workspace identifier to delete.

Response#

Returns { data, _meta } with the result.

Destructive action

Deleting a workspace removes access to its workspace and associated data. This operation marks the workspace deleted rather than permanently erasing its records.

GET /v1/workspaces/:id/users#

List users in a workspace with pagination and search.

bash

GET /v1/workspaces/:id/users?page_index=0&page_size=25&workspace_id=1c7743a8-6410-4a9e-9f3b-2c1d5e8a4b01
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
pageIndex	`integer`	Required	Zero-based page index for pagination.
pageSize	`integer`	Required	Number of items per page (1-100).
workspaceId	`string (UUID)`	Required	Workspace identifier.
searchTerm	`string`	—	Free-text search term to filter results (max 200 characters).
sortBy	`string`	—	Column name to sort by.
sortDirection	`'asc' \| 'desc'`	—	Sort direction: ascending or descending.

Response#

Returns { items, totalCount, facets, _meta } with paginated results.

POST /v1/workspaces/:id/users#

Add any existing Brandwave user account as a pending workspace member with the specified role. Requires workspace-owner permissions. Workspace details and stored aggregate marketing metrics become visible in the recipient's workspace list while pending; acceptance grants role-based workspace access. Does not create an account or send an email.

Owner only

bash

POST /v1/workspaces/:id/users
Authorization: Bearer {token}
Content-Type: application/json

{
  "workspace_id": "1c7743a8-6410-4a9e-9f3b-2c1d5e8a4b01",
  "user_id": "6c9e4b21-8d05-4f7a-b3c2-1e5a9d8f4b07",
  "role": "member"
}

Parameters#

Name	Type	Required	Description
workspaceId	`string (UUID)`	Required	Workspace identifier.
userId	`string (UUID)`	Required	User identifier to add.
role	`'owner' \| 'member' \| 'viewer'`	Required	Role to assign (owner, member, or viewer).

Response#

Returns { data, _meta } with the result.

PATCH /v1/workspaces/:id/users/:userId#

Update the role on an existing workspace membership or pending invitation. Requires workspace-owner permissions; cannot change your own role. Does not add a new membership or send a notification.

Owner only

bash

PATCH /v1/workspaces/:id/users/:userId
Authorization: Bearer {token}
Content-Type: application/json

{
  "workspace_id": "1c7743a8-6410-4a9e-9f3b-2c1d5e8a4b01",
  "role": "member"
}

Parameters#

Name	Type	Required	Description
workspaceId	`string (UUID)`	Required	Workspace identifier.
userId	`string (UUID)`	Required	User identifier whose role is being changed.
role	`'owner' \| 'member' \| 'viewer'`	Required	New role to assign (owner, member, or viewer).

Response#

Returns { data, _meta } with the result.

DELETE /v1/workspaces/:id/users/:userId#

Remove an existing workspace membership or pending invitation by marking it deleted. Requires workspace-owner permissions; cannot remove yourself. Does not delete the user account or send a notification.

Owner only

bash

DELETE /v1/workspaces/:id/users/:userId
Authorization: Bearer {token}
Content-Type: application/json

{
  "workspace_id": "1c7743a8-6410-4a9e-9f3b-2c1d5e8a4b01"
}

Parameters#

Name	Type	Required	Description
workspaceId	`string (UUID)`	Required	Workspace identifier.
userId	`string (UUID)`	Required	User identifier to remove.

Response#

Returns { data, _meta } with the result.

POST /v1/workspaces/:id/invites#

Invite a user to a workspace by email.

Owner only

bash

POST /v1/workspaces/:id/invites
Authorization: Bearer {token}
Content-Type: application/json

{
  "email": "user@example.com",
  "workspace_id": "1c7743a8-6410-4a9e-9f3b-2c1d5e8a4b01",
  "role": "member"
}

Parameters#

Name	Type	Required	Description
email	`string`	Required	Email address to send the invite to.
workspaceId	`string (UUID)`	Required	Workspace identifier.
role	`'owner' \| 'member' \| 'viewer'`	Required	Role to assign to the invited user (owner, member, or viewer).

Response#

Returns { data, _meta } with the result.

Authorization required

Only workspace owners can invite new members.