Skip to content
oHallo Developers

Create a workspace

POST
/api/workspaces

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

Section titled “Authorizations ”

Request Body

Section titled “Request Body ”
object
brandId
required

The brand this workspace operates under. List brands with GET /api/brands, or create one with POST /api/brands.

string format: uuid
Example
b1a2c3d4-5678-4abc-8ef0-1234567890ab
name
required

Display name of the workspace.

string
>= 1 characters
Example
Support
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
Example Company
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
legalAddress

Structured legal address of the operating entity. Rendered into the composed email company block.

object
street
string | null
<= 200 characters
buildingNumber
string | null
<= 50 characters
postalCode
string | null
<= 20 characters
city
string | null
<= 100 characters
country
string | null
<= 2 characters
supportEmail

Public support email address for this workspace.

string format: email
Example
support@example.com
supportPhone

Public support phone number for this workspace.

string
<= 50 characters
websiteUrl

The workspace’s public website. The onboarding read starts from this site.

string format: uri
<= 1000 characters
Example
https://www.example.com
voiceGreetings

The spoken greeting per language, each confirmed in its own language. Each language appears at most once. A greeting without a valid confirmation is replaced at call time by the standard opening line in its language.

Array<object>
<= 23 items

One language’s spoken greeting as a request writes it.

object
language
required

The language of the greeting: one of the brand’s supported languages, or the workspace’s operating language. Any other language is refused with 422 and code greeting_language_not_supported.

string
greeting

The greeting text. Send null or an empty text to clear the language’s greeting. Leave it out to confirm the stored text with attested.

string | null
<= 2000 characters
attested

EU AI Act Article 50 confirmation that the greeting tells callers they are speaking with an AI assistant. A new or changed greeting is refused with 422 and code greeting_attestation_required unless this is true, and refused with code greeting_must_mention_ai when the wording does not mention the assistant in this language. An unchanged greeting needs no flag. The server records who confirmed, when, and in which language.

boolean
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
UTC
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
signatureAdditionalHtml

Optional lines appended below the composed company block. Rendered as written.

string

Responses

Section titled “ Responses ”

201

Section titled “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
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

403

Section titled “403 ”

The caller may not create workspaces here. People need the owner or admin role. An API key restricted to a workspace receives code: "key_lock".

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"
]

404

Section titled “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"
]

422

Section titled “422 ”

Validation error. One or more required fields are missing or invalid. A greeting that cannot be saved answers with code and language: greeting_required (a confirmation with no greeting to confirm), greeting_attestation_required (a new or changed greeting without its confirmation), greeting_must_mention_ai (the wording does not mention the assistant in that language) or greeting_language_not_supported (a language that is neither one of the brand’s supported languages nor the operating language). Nothing was written.

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"
]
language

With a greeting code: the language of the greeting that was refused.

string
Example
en

Looking for the product? Visit ohallo.ai  ·  Help Centre  ·  Contact

Copyright 2026 oHallo. All rights reserved.