Users#

Manage user profiles and per-user settings.

Authentication required

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

GET /v1/users#

List users in a workspace with pagination and name search.

bash

GET /v1/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.

GET /v1/users/:id#

Retrieve a single user by ID.

bash

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

Parameters#

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

Response#

Returns { data, _meta } with the result.

PATCH /v1/users/:id#

Update a user's profile information. Updatable fields: name (display name), email, jobRole (e.g. 'Head of Marketing'), avatarKey (storage key, null to remove). Only include the fields you want to change. Requests using Brandwave agent access tokens can update only the token owner's profile and cannot change email or other sign-in identity details.

bash

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

{
  "user_id": "6c9e4b21-8d05-4f7a-b3c2-1e5a9d8f4b07"
}

Parameters#

Name	Type	Required	Description
userId	`string (UUID)`	Required	User identifier to update.
name	`string`	—	Updated display name (1-255 characters).
email	`string`	—	Updated email address.
jobRole	`string \| null`	—	Updated job role (max 100 characters).
avatarKey	`string \| null`	—	Storage key for the user avatar image. Set to null to remove.

Response#

Returns { data, _meta } with the result.

GET /v1/users/:id/settings#

Retrieve a user's personal settings.

bash

GET /v1/users/:id/settings?user_id=6c9e4b21-8d05-4f7a-b3c2-1e5a9d8f4b07
Authorization: Bearer {token}

Parameters#

Name	Type	Required	Description
userId	`string (UUID)`	Required	User identifier to fetch settings for.

Response#

Returns { data, _meta } with the result.

PATCH /v1/users/:id/settings#

Create or update a user's settings, including switching the active workspace and managing UI preferences.

bash

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

{
  "user_id": "6c9e4b21-8d05-4f7a-b3c2-1e5a9d8f4b07"
}

Parameters#

Name	Type	Required	Description
userId	`string (UUID)`	Required	User identifier to update settings for.
activeWorkspaceId	`string (UUID)`	—	Workspace to set as the active workspace.
preferences	`object`	—	User UI preferences (shallow-merged into existing).

Response#

Returns { data, _meta } with the result.