Create a workspace

POST

/api/workspaces

Production

Creates a new workspace under a brand. The operating language must be one of the enabled languages and permitted by the brand. The full workspace record is returned.

Authorizations

bearerAuth

Request Body

object

brandId

required

The brand this workspace operates under.

string format: uuid

Example

b1a2c3d4-5678-9abc-def0-1234567890ab

name

required

Display name of the workspace.

string

>= 1 characters

Example

DACH Region

country

required

ISO 3166-1 alpha-2 country code for the workspace’s primary operating region.

string

>= 2 characters <= 2 characters

Example

DE

operatingLanguage

required

The primary language the assistant uses in this workspace. Must be one of the enabled languages and permitted by the brand.

string

>= 2 characters <= 35 characters

Example

de

currency

required

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

string

>= 3 characters <= 3 characters

Example

EUR

legalName

required

The registered legal name of the entity operating this workspace.

string

>= 1 characters

Example

Acme DACH GmbH

status

Lifecycle status of the workspace. Defaults to ‘active’ when omitted.

string

Allowed values: active inactive archived

Example

active

customerType

Whether this workspace handles business-to-business, business-to-consumer, or mixed conversations. Defaults to ‘b2b’ when omitted.

string

Allowed values: b2b b2c mixed

Example

b2b

companyNumber

Company registration number.

string

<= 50 characters

Example

HRB 12345

vatNumber

VAT registration number.

string

<= 50 characters

Example

DE123456789

legalAddress

Structured legal address of the operating entity.

object

key

additional properties

Example

{
  "street": "Beispielstrasse 1",
  "city": "Berlin",
  "postalCode": "10115",
  "country": "DE"
}

supportEmail

Public support email address for this workspace.

string format: email

Example

support@acme.example

supportPhone

Public support phone number for this workspace.

string

<= 50 characters

Example

+49 30 1234567

websiteUrl

Public website URL for the operating entity.

string format: uri

Example

https://acme.example

emailSignatureHtml

Workspace-level HTML email signature. Overrides the brand-level signature when set.

string

Example

<p>Freundliche Gruesse</p>

emailSignatureText

Workspace-level plain-text email signature. Overrides the brand-level signature when set.

string

Example

Freundliche Gruesse

voiceGreeting

The spoken greeting used at the start of a voice call in this workspace.

string

<= 2000 characters

Example

Thank you for calling Acme. How can I help?

workspaceInstructions

Free-text instructions specific to this workspace, combined with brand instructions to guide the assistant.

string

Example

All prices must include VAT.

openingHours

The workspace opening hours. When any ranges are provided, a timezone is required.

object

timezone

IANA timezone identifier for the opening hours.

string

>= 1 characters <= 50 characters

Example

Europe/Berlin

hours

required

The opening-hour ranges. Defaults to an empty list.

Array<object>

object

days

required

The days this range applies to.

Array<string>

>= 1 items

Allowed values: sun mon tue wed thu fri sat

Example

[
  "mon",
  "tue",
  "wed",
  "thu",
  "fri"
]

open

required

Opening time in 24-hour HH:MM format.

string

Example

09:00

close

required

Closing time in 24-hour HH:MM format.

string

Example

17:00

Responses

201

The workspace was created.

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

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

DACH Region

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

currency

required

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

string

Example

EUR

workspaceType

required

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

Example

b2b

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 German returns policy for DACH orders.

emailSignatureHtml

Workspace-level HTML email signature. Overrides the brand-level signature when set.

string | null

Example

<p>Freundliche Gruesse,<br>Ihr Acme DACH Team</p>

emailSignatureText

Workspace-level plain-text email signature. Overrides the brand-level signature when set.

string | null

Example

Freundliche Gruesse,
Ihr Acme DACH Team

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

422

Validation error. One or more required fields are missing or invalid.

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