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.

GET /v1/workspaces/metrics#

Fetch workspace-level metrics including total expenses, impressions, social engagement, delivery coverage, and denominator-aware CPM and Social CPE.

bash

GET /v1/workspaces/metrics?workspace_id=1c7743a8-6410-4a9e-9f3b-2c1d5e8a4b01
Authorization: Bearer {token}

Parameters#

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

Response#

Returns { data, _meta } with the result.

GET /v1/workspaces/metrics/history#

Fetch workspace metrics over time with a configurable lookback window.

bash

GET /v1/workspaces/metrics/history?workspace_id=1c7743a8-6410-4a9e-9f3b-2c1d5e8a4b01
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
workspaceId	`string (UUID)`	Required	Workspace identifier.
daysBack	`integer`	—	Number of days of history to return (1-365).

Response#

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

GET /v1/workspaces/todos#

List what needs doing in a workspace right now: promo codes and tagged links to link to marketing, customer answers to group, ended campaigns with no learnings written up, and results to choose once analytics is connected. Each item clears itself once done.

bash

GET /v1/workspaces/todos?workspace_id=1c7743a8-6410-4a9e-9f3b-2c1d5e8a4b01
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
workspaceId	`string (UUID)`	Required	Workspace whose waiting housekeeping should be listed.

Response#

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