Skip to main content
PUT
Update organization settings

Authorizations

Authorization
string
header
required

JWT Bearer token authentication. Include your access token in the Authorization header as: Bearer YOUR_ACCESS_TOKEN

Example:

Body

application/json

Request model for the self-service PUT /organizations/settings endpoint.

Deliberately a NARROW subset of OrganizationSettings: it exposes only the fields an org admin sets themselves (worker_landing_page via the worker-entry config, security via the SSO/MFA toggles, model_region via the data-residency control) and OMITS every backoffice-only field — max_concurrent_executions, payment_method, enabled_capabilities AND auto_calibration — each of which has its own /admin/organizations/{id}/… endpoint. Modelling the restriction structurally — rather than value-guarding each field in the handler — closes the presence-vs-value hole where a body of {"enabled_capabilities": null} slipped past an is not None guard and cleared a backoffice override. extra="forbid" makes any attempt to send a backoffice-only (or unknown) field a 422 rather than a silent drop.

model_region
enum<string> | null

Where AI model inference may run: 'global' (default) or 'eu'. 'eu' region-tags every model call and refuses a model with no EU deployment rather than falling back.

Available options:
global,
eu
security
OrganizationSecuritySettings · object

Security-related settings such as strict SSO enforcement.

worker_landing_page
enum<string>
default:hub

Landing page configuration: 'hub', 'assigned_flow_data_tab', or 'assigned_flow_work_tab'

Available options:
hub,
assigned_flow_data_tab,
assigned_flow_work_tab

Response

Settings updated successfully

Organization response model.

created_at
string<date-time>
required
id
string<uuid>
required
is_active
boolean
required
read-only

Whether the organization is active, i.e. status == 'active'. Active organizations allow user logins and flow executions. Inactive organizations are read-only; users cannot log in. Set via PUT /admin/organizations/{id} or PATCH /deactivate endpoint.

modified_by
string
required
name
string
required

Organization display name. Unique across the platform. Used in UI, reports, and organization selection. Can be updated via PUT /admin/organizations/{id}

Examples:

"Acme Corporation"

"Engineering Team"

period_end
string<date>
required

End date of current billing period. Credits are reset when period_end is reached. Format: ISO 8601 date (e.g., '2025-02-01').

Example:

"2025-02-01"

period_start
string<date>
required

Start date of current billing period. Monthly credits reset at the beginning of each period. Format: ISO 8601 date (e.g., '2025-01-01').

Example:

"2025-01-01"

tier
enum<string>
required

Organization tier determining monthly credit allowance. Free: 25,000 credits/month, Growth: 100,000 credits/month, Enterprise: 500,000 credits/month. Can be changed via POST /admin/organizations/{id}/tier

Available options:
free,
growth,
enterprise
Examples:

"free"

"growth"

"enterprise"

updated_at
string<date-time>
required
account_stage
enum<string>
default:promoted

RESOLVED trial-first account stage (FLO-2652): the stored settings.account_state.stage when present, otherwise 'promoted'. Populated from the Organization.account_stage ORM property. 'trial' = one-off bounded allowance, never refreshed; 'promoted' = the ordinary free tier; 'suspended' = blocked from spending.

Available options:
trial,
promoted,
suspended
deletion_requested_at
string<date-time> | null

When a deletion request was accepted (FLO-2215). Null if none. Read-only.

deletion_scheduled_for
string<date-time> | null

Calendar boundary after which the purge runs (FLO-2215): deletion_requested_at + 30 days. Null if no deletion is in flight. Read-only. Never exposed to a locked-out user — the blocking screen shows no date.

enabled_capabilities
enum<string>[]

RESOLVED effective side-panel capabilities for this org (FLO-2318, replacement model): the backoffice setting stored in settings.enabled_capabilities when present (including an explicit []), otherwise the tier default. This is the read/display surface — the raw stored setting lives in settings.enabled_capabilities and is written via PATCH /admin/organizations/{id}/capabilities (granted_capabilities). Populated from the Organization.enabled_capabilities ORM property on every response path. Values: 'chat', 'flows'.

Product surfaces a side-panel can expose (FLO-2318).

chat = the enterprise Chat agent surface; flows = the self-service Flows surface. An org's effective set is the stored backoffice setting when one exists (replacement model), otherwise the tier default (see resolve_enabled_capabilities). Stored as string values in the Organization.settings JSONB under enabled_capabilities.

Available options:
chat,
flows,
org_self_deletion
pending_downgrade_at
string<date-time> | null

When a scheduled downgrade takes effect (FLO-2289). Null if none.

pending_downgrade_tier
enum<string> | null

Tier this org is scheduled to downgrade to (FLO-2289), applied at pending_downgrade_at.

Available options:
free,
growth,
enterprise
settings
OrganizationSettings · object | null

Organization settings including worker landing page configuration

status
enum<string>
default:active

Raw lifecycle status (FLO-2215). is_active only tells 'active' from everything else, which cannot distinguish 'inactive' from 'pending_deletion' or 'deleted' — read this field when the difference matters (backoffice deletion tab, auth enforcement).

Available options:
active,
inactive,
pending_deletion,
deleted