Partially update tenant settings

PATCH

/v1/tenants/{tenant_id}/settings

const url = 'http://localhost:8080/v1/tenants/org-123/settings';
const options = {
  method: 'PATCH',
  headers: {
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/merge-patch+json'
  },
  body: '{ "target_language": "de-DE" }'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request PATCH \
  --url http://localhost:8080/v1/tenants/org-123/settings \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/merge-patch+json' \
  --data '{ "target_language": "de-DE" }'

Partially updates the enrichment settings for the specified tenant_id using RFC 7396 JSON Merge Patch semantics (media type application/merge-patch+json; application/json is also accepted). For each member: a value sets that setting, JSON null removes it (e.g. {"target_language": null} clears the target language), and an omitted member is left unchanged. The tenant_id is taken from the path, so a request can only ever modify its own tenant’s settings. target_language is normalized to a canonical BCP-47 locale (e.g. “en-us” becomes “en-US”); an empty string is rejected (send null to remove it). While a tenant data purge runs for the same tenant_id, this write is rejected with HTTP 409 (code tenant_write_conflict) and may be retried.

Authorizations

ApiKeyAuth

Parameters

Path Parameters

tenant_id

required

string

>= 1 characters <= 255 characters /^[^\x00]*$/

Example

org-123

Tenant ID whose settings should be updated. Empty strings and NULL bytes are not allowed.

Request Body^required

RFC 7396 JSON Merge Patch for a tenant’s enrichment settings. For each member: a value sets the setting, JSON null removes it, and an omitted member is left unchanged.

object

target_language

Target BCP-47 locale to translate into; normalized to a canonical form (e.g. “en-us” becomes “en-US”). Send null to remove it; omit to leave it unchanged. An empty string is rejected.

string | null

<= 35 characters

sentiment_enabled

Enable or disable sentiment enrichment. Send null to restore the default (enabled); omit to leave it unchanged.

boolean | null

emotions_enabled

Enable or disable emotion enrichment. Send null to restore the default (enabled); omit to leave it unchanged.

boolean | null

Examples

set

Set the target language (other settings untouched)

{
  "target_language": "de-DE"
}

RFC 7396 JSON Merge Patch for a tenant’s enrichment settings. For each member: a value sets the setting, JSON null removes it, and an omitted member is left unchanged.

object

target_language

Target BCP-47 locale to translate into; normalized to a canonical form (e.g. “en-us” becomes “en-US”). Send null to remove it; omit to leave it unchanged. An empty string is rejected.

string | null

<= 35 characters

Example

de-DE

sentiment_enabled

Enable or disable sentiment enrichment. Send null to restore the default (enabled); omit to leave it unchanged.

boolean | null

Example

false

emotions_enabled

Enable or disable emotion enrichment. Send null to restore the default (enabled); omit to leave it unchanged.

boolean | null

Example

false

Responses

200

Updated tenant settings

application/json

object

tenant_id

required

Tenant ID the settings belong to

string

>= 1 characters <= 255 characters /^[^\x00]*$/

settings

required

Tenant-scoped enrichment configuration. Fields are optional; absent fields use server defaults.

object

target_language

Normalized BCP-47 locale (e.g. “en-US”) that language enrichment translates feedback records and topic labels into. Absent or empty means not configured.

string

<= 35 characters

sentiment_enabled

Per-directory switch for sentiment enrichment. Absent means the default (enabled), so a tenant is enriched unless it has explicitly set this to false. The deployment-level sentiment provider/model gate applies on top of this.

boolean

emotions_enabled

Per-directory switch for emotion enrichment. Absent means the default (enabled), so a tenant is enriched unless it has explicitly set this to false. The deployment-level emotions provider/model gate applies on top of this.

boolean

Examples

success

Settings after the partial update

{
  "tenant_id": "org-123",
  "settings": {
    "target_language": "de-DE"
  }
}

400

Bad Request (e.g. invalid tenant_id or target_language)

application/problem+json

RFC 9457 problem details (application/problem+json). Branch on the stable code member rather than on title or type.

object

code

required

Stable, machine-readable error code; the primary value to branch on. service_unavailable indicates a feature or dependency is temporarily unavailable and the request may be retried later. tenant_write_conflict indicates the write conflicted with an in-progress tenant data purge (or vice versa) and may be retried later unchanged. All other codes are terminal until the request itself is changed.

string

Allowed values: validation bad_request unauthorized forbidden not_found conflict tenant_write_conflict method_not_allowed content_too_large service_unavailable internal_server_error

detail

A human-readable explanation specific to this occurrence of the problem.

string

details

Optional structured context for this problem, e.g. resource_type on a 404.

object

key

additional properties

any

instance

A URI reference (typically the request path) identifying the specific occurrence of the problem.

string

invalid_params

Field-level validation failures (RFC 9457 “invalid_params” extension). Present on validation errors.

Array<object>

<= 100 items

A single invalid request parameter (RFC 9457 “invalid_params” extension member).

object

name

required

Dotted path to the offending request field, e.g. ‘field_type’ or ‘items[0].field_type’.

string

reason

required

Human- and agent-readable explanation of why the value is invalid, naming allowed values or constraints where applicable so the request can be corrected without guessing.

string

request_id

required

Identifier for this request, also returned in the X-Request-ID response header; include it when reporting a problem.

string

status

required

HTTP status code

integer format: int64

title

required

A short, human-readable summary of the problem type. This value should not change between occurrences of the error.

string

type

A URI reference identifying the problem type.

string format: uri

Example

{
  "code": "validation",
  "detail": "One or more request parameters are invalid",
  "instance": "/v1/feedback-records",
  "invalid_params": [
    {
      "name": "field_type",
      "reason": "must be one of: text, categorical, nps, csat, ces, rating, number, boolean, date"
    }
  ],
  "request_id": "0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
  "status": 400,
  "title": "Bad Request",
  "type": "https://hub.formbricks.com/problems/bad-request"
}

409

Conflict – a tenant data purge for the same tenant_id is in progress (code tenant_write_conflict). No settings were written; retry later.

application/problem+json

RFC 9457 problem details (application/problem+json). Branch on the stable code member rather than on title or type.

object

code

required

string

Allowed values: validation bad_request unauthorized forbidden not_found conflict tenant_write_conflict method_not_allowed content_too_large service_unavailable internal_server_error

detail

A human-readable explanation specific to this occurrence of the problem.

string

details

Optional structured context for this problem, e.g. resource_type on a 404.

object

key

additional properties

any

instance

A URI reference (typically the request path) identifying the specific occurrence of the problem.

string

invalid_params

Field-level validation failures (RFC 9457 “invalid_params” extension). Present on validation errors.

Array<object>

<= 100 items

A single invalid request parameter (RFC 9457 “invalid_params” extension member).

object

name

required

Dotted path to the offending request field, e.g. ‘field_type’ or ‘items[0].field_type’.

string

reason

required

Human- and agent-readable explanation of why the value is invalid, naming allowed values or constraints where applicable so the request can be corrected without guessing.

string

request_id

required

Identifier for this request, also returned in the X-Request-ID response header; include it when reporting a problem.

string

status

required

HTTP status code

integer format: int64

title

required

A short, human-readable summary of the problem type. This value should not change between occurrences of the error.

string

type

A URI reference identifying the problem type.

string format: uri

Example

{
  "code": "validation",
  "detail": "One or more request parameters are invalid",
  "instance": "/v1/feedback-records",
  "invalid_params": [
    {
      "name": "field_type",
      "reason": "must be one of: text, categorical, nps, csat, ces, rating, number, boolean, date"
    }
  ],
  "request_id": "0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
  "status": 400,
  "title": "Bad Request",
  "type": "https://hub.formbricks.com/problems/bad-request"
}

413

Request body exceeds the maximum allowed size.

application/problem+json

RFC 9457 problem details (application/problem+json). Branch on the stable code member rather than on title or type.

object

code

required

string

Allowed values: validation bad_request unauthorized forbidden not_found conflict tenant_write_conflict method_not_allowed content_too_large service_unavailable internal_server_error

detail

A human-readable explanation specific to this occurrence of the problem.

string

details

Optional structured context for this problem, e.g. resource_type on a 404.

object

key

additional properties

any

instance

A URI reference (typically the request path) identifying the specific occurrence of the problem.

string

invalid_params

Field-level validation failures (RFC 9457 “invalid_params” extension). Present on validation errors.

Array<object>

<= 100 items

A single invalid request parameter (RFC 9457 “invalid_params” extension member).

object

name

required

Dotted path to the offending request field, e.g. ‘field_type’ or ‘items[0].field_type’.

string

reason

required

Human- and agent-readable explanation of why the value is invalid, naming allowed values or constraints where applicable so the request can be corrected without guessing.

string

request_id

required

Identifier for this request, also returned in the X-Request-ID response header; include it when reporting a problem.

string

status

required

HTTP status code

integer format: int64

title

required

A short, human-readable summary of the problem type. This value should not change between occurrences of the error.

string

type

A URI reference identifying the problem type.

string format: uri

Example

{
  "code": "validation",
  "detail": "One or more request parameters are invalid",
  "instance": "/v1/feedback-records",
  "invalid_params": [
    {
      "name": "field_type",
      "reason": "must be one of: text, categorical, nps, csat, ces, rating, number, boolean, date"
    }
  ],
  "request_id": "0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
  "status": 400,
  "title": "Bad Request",
  "type": "https://hub.formbricks.com/problems/bad-request"
}

default

Error

application/problem+json

RFC 9457 problem details (application/problem+json). Branch on the stable code member rather than on title or type.

object

code

required

string

Allowed values: validation bad_request unauthorized forbidden not_found conflict tenant_write_conflict method_not_allowed content_too_large service_unavailable internal_server_error

detail

A human-readable explanation specific to this occurrence of the problem.

string

details

Optional structured context for this problem, e.g. resource_type on a 404.

object

key

additional properties

any

instance

A URI reference (typically the request path) identifying the specific occurrence of the problem.

string

invalid_params

Field-level validation failures (RFC 9457 “invalid_params” extension). Present on validation errors.

Array<object>

<= 100 items

A single invalid request parameter (RFC 9457 “invalid_params” extension member).

object

name

required

Dotted path to the offending request field, e.g. ‘field_type’ or ‘items[0].field_type’.

string

reason

required

Human- and agent-readable explanation of why the value is invalid, naming allowed values or constraints where applicable so the request can be corrected without guessing.

string

request_id

required

Identifier for this request, also returned in the X-Request-ID response header; include it when reporting a problem.

string

status

required

HTTP status code

integer format: int64

title

required

A short, human-readable summary of the problem type. This value should not change between occurrences of the error.

string

type

A URI reference identifying the problem type.

string format: uri

Example

{
  "code": "validation",
  "detail": "One or more request parameters are invalid",
  "instance": "/v1/feedback-records",
  "invalid_params": [
    {
      "name": "field_type",
      "reason": "must be one of: text, categorical, nps, csat, ces, rating, number, boolean, date"
    }
  ],
  "request_id": "0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
  "status": 400,
  "title": "Bad Request",
  "type": "https://hub.formbricks.com/problems/bad-request"
}

Partially update tenant settings

Authorizations

Parameters

Path Parameters

Example

Request Bodyrequired

Examples

Example

Example

Example

Responses

200

Examples

400

Example

409

Example

413

Example

default

Example

Request Body^required