Skip to content
oHallo Developers

Update a workspace

PATCH
/api/workspaces/{workspaceId}

Updates a workspace. Only the fields you include are changed; omitted fields are left untouched. Several fields accept an explicit null to clear a previously set value. The brand a workspace belongs to cannot be changed.

Authorizations

Section titled “Authorizations ”

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “Path Parameters ”
workspaceId
required
string format: uuid

The unique identifier of the workspace to update.

Request Body

Section titled “Request Body ”
object
name

Updated display name.

string
>= 1 characters
Example
Support
country

Updated ISO 3166-1 alpha-2 country code.

string
>= 2 characters <= 2 characters
Example
AT
operatingLanguage

Updated operating language. Must be enabled and permitted by the brand.

string
>= 2 characters <= 35 characters
Example
de
currency

Updated ISO 4217 currency code.

string
>= 3 characters <= 3 characters
Example
EUR
legalName

Updated legal name.

string
>= 1 characters
Example
Example Company
status

Updated lifecycle status.

string
Allowed values: active inactive archived
Example
active
customerType

Updated customer type.

string
Allowed values: b2b b2c mixed
Example
b2b
companyNumber

Updated company registration number. Send null to clear.

string | null
<= 50 characters
legalAddress

Updated legal address. Send null to clear.

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

Updated support email. Send null to clear.

string | null format: email
Example
support@example.com
supportPhone

Updated support phone. Send null to clear.

string | null
<= 50 characters
websiteUrl

Updated public website. Send null to clear.

string | null format: uri
<= 1000 characters
Example
https://www.example.com
escalationAlertEmail

Address that receives an alert when a conversation is handed to a person outside the workspace opening hours. Send null to clear. An address one of this account’s own email channels receives on is refused with 422, because alerting to it would feed the alert back into the inbound pipeline.

string | null format: email
Example
sales@example.com
escalationAlertEnabled

Whether out-of-hours alerts are sent to escalationAlertEmail. Any value other than true means alerts stay off, which is the default for every workspace.

boolean | null
voiceGreetings

Greetings to write, one entry per language, each confirmed in its own language. Languages left out keep their greeting. Each language appears at most once.

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

Updated workspace instructions. Send null to clear.

string | null
learningLoopConfig

Learning-loop configuration for this workspace.

object
enabled
required

Whether the learning loop is enabled.

boolean
Example
true
humanOnlyFilter
required

Whether to restrict learning to human-managed conversations.

boolean
Example
true
agentFollowUpConfig

Automated follow-up configuration for this workspace.

object
enabled
required

Whether automated follow-ups are enabled.

boolean
Example
true
maxPerConversation
required

Maximum follow-ups per conversation.

integer
>= 1 <= 20
Example
3
maxHorizonHours
required

Maximum horizon in hours for a follow-up.

integer
>= 1 <= 8760
Example
168
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. Send null to clear.

string | null

Responses

Section titled “ Responses ”

200

Section titled “200 ”

The workspace was updated.

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 change this workspace. People need the owner or admin role.

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 workspace exists with the given ID in the authenticated tenant.

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.