List a brand's workspaces

GET

/api/brands/{brandId}/workspaces

• Production

Lists the workspaces of a brand that are within the caller’s reach. Requires the brands:read and workspaces:read scopes.

Authorizations

• bearerAuth

Parameters

Path Parameters

brandId

required

string format: uuid

The unique identifier of the brand.

Responses

200

The workspaces.

Array<object>

A workspace is an operational unit within a brand, typically representing a region, business unit, or product line. Conversations, knowledge base entries, policies, and channels are all scoped to a workspace.

object

id

required

Unique identifier for the workspace.

string format: uuid

Example

w1a2b3c4-5678-9abc-def0-1234567890ab

tenantId

required

The tenant this workspace belongs to.

string format: uuid

Example

a0b1c2d3-4567-89ab-cdef-0123456789ab

brandId

required

The brand this workspace operates under. Determines tone, sender identity, and email templates.

string format: uuid

Example

b1a2c3d4-5678-9abc-def0-1234567890ab

name

required

Display name of the workspace.

string

Example

Support

country

required

ISO 3166-1 alpha-2 country code for this workspace’s primary operating region. Affects currency defaults and compliance.

string

Example

DE

operatingLanguage

required

The primary language the AI uses when communicating in this workspace. ISO 639-1 code.

string

Example

de

operatingLanguageSetAt

When the operating language was last chosen, by a create or an update that carries operatingLanguage. Null when no choice is recorded.

string | null format: date-time

Example

2026-01-20T10:00:00.000Z

currency

required

ISO 4217 currency code used for financial references in this workspace.

string

Example

EUR

workspaceInstructions

Free-text instructions specific to this workspace. These are combined with brand instructions to guide the AI. Use for workspace-specific rules like regional regulations or product-specific guidance.

string | null

Example

All prices must include VAT. Refer customers to the Returns policy.

createdAt

required

Timestamp when the workspace was created.

string format: date-time

Example

2026-01-20T10:00:00.000Z

updatedAt

required

Timestamp when the workspace was last updated.

string format: date-time

Example

2026-03-01T16:45:00.000Z

customerType

Whether this workspace handles business-to-business or business-to-consumer conversations. Affects contact resolution, account enrichment, and AI behavior.

string

Allowed values: b2b b2c mixed

Example

b2b

websiteUrl

The workspace’s public website. The onboarding read starts from this site and derives the origin from it: lowercase host, path and query dropped, https first.

string | null format: uri

<= 1000 characters

Example

https://www.example.com

signatureAdditionalHtml

Optional lines appended below the company block composed from the workspace’s legal entity (social links, awards, disclaimers). Rendered as written.

string | null

voiceGreetings

The spoken greeting per language, one entry for each language that has a greeting. Each greeting carries its own EU AI Act Article 50 confirmation, checked in its language.

Array<object>

One language’s spoken greeting on a workspace, with the state of its EU AI Act Article 50 confirmation.

object

language

required

The language the greeting is spoken in.

string

Example

en

greeting

required

The greeting text.

string

<= 2000 characters

Example

Thank you for calling Example Company. You are speaking with an AI assistant. How can I help?

attestationValid

required

Whether the confirmation covers this exact text, in this language. A greeting is spoken only while this is true; otherwise callers hear the standard opening line in this language.

boolean

attestedAt

required

When the greeting was confirmed. Null while the confirmation does not cover the greeting.

string | null format: date-time

404

No brand with this ID is within the caller’s reach.

Standard error response returned by all endpoints on failure.

object

error

required

A human-readable error message describing what went wrong.

string

Example

Conversation not found

code

A machine-readable reason on some refusals, for example ‘key_lock’ when an API key’s brand or workspace restriction does not cover the action.

string

Example

key_lock

missing_scopes

On a 403 for an API key without a scope the endpoint requires: the scopes the key lacks.

Array<string>

Example

[
  "mcp:write"
]

entryId

On a 409 with code duplicate_question or duplicate_rule_text: the knowledge base entry or policy that already holds the question or rule text.

string format: uuid

Example

11223344-5566-4788-99aa-bbccddeeff00

connectionId

On a 422 about one MCP connection a request names, from an assignment or an agent create or update (a connection that does not exist, one listed twice, or one that does not declare a tool named): the connection, as the request named it.

string

undeclaredTools

On the same 422: the tool names the connection does not declare.

Array<string>

Example

[
  "get_orders"
]

declaredTools

On the same 422: the tools the connection declares.

Array<string>

Example

[
  "get_order",
  "search_orders"
]