Organization settings configuration

Organization settings apply to every Team, Schedule, and user inside a single Organization. They cover defaults that propagate to other resources (locale, timezone), governance options (MFA, SSO, email domain), how long each category of data is kept, and the limits that bound Buddy's autonomous work.

These settings can only be changed by an Organization owner or admin. Some of them, including SSO requirement and email domain restriction, are gated by plan and are rejected when the Organization's plan does not include the feature.

What this document covers

This page describes the Organization configuration document — the JSON you edit in the Organization configuration editor (GET / PUT /api/v1/organizations/{id}/config). The document is a fixed set of keys, and a PUT that carries a fixed key the document does not define is rejected as an unknown field. The keys inside notifications are notification type names rather than fixed fields, and they are checked against the list of known types: an unrecognized type name is rejected as well (see Validation rules).

Three groups of Organization-level settings are deliberately not part of this document, so sending them here fails:

The Buddy autonomy limits described below (auto_continuation_max_turns, auto_continuation_max_credits, auto_continuation_mode, tool_record_max_per_conversation) are stored inside ai_settings internally, but this document exposes them as top-level keys — write them at the top level, never nested under ai_settings.

Because a PUT replaces the whole document, do not assemble a document from this page alone — always start from what GET /api/v1/organizations/{id}/config returns, or any key this page omits will be cleared.

Update semantics

The configuration document is declarative: a PUT replaces the stored configuration instead of patching it. Start from the document returned by GET /api/v1/organizations/{id}/config, edit the keys you want to change, and send the whole document back.

• Omitting a boolean (require_mfa, mfa_step_up_enabled, allow_member_leave, sso_step_up_enabled) applies false, and omitting an array (allowed_email_domains, required_sso_providers) clears it. For these keys, omission is not "keep the current value".
• The Default column in the tables below is the value a newly created Organization starts with — it is not the value applied when you omit the key. For most booleans the two coincide (false), but allow_member_leave starts as true, so omitting it in a PUT sets it to false and turns member self-removal off.
• Omitting one of the numeric Buddy limits applies 0, which means "follow the system default".
• Omitting name, default_locale, default_timezone, or description keeps the currently stored value.
• The data_retention and notifications sections must always be present in full (see below).

The examples at the end of this page show only the keys being changed so that each example stays readable; they are not complete documents.

Which fields your plan can change

Several settings on this page are gated by plan, and the gate is not visible in the configuration JSON itself. GET /api/v1/organizations/{id}/config therefore also returns field_availability: a map from field path to what your current plan allows for it. The configuration editor uses it to mark those fields instead of hiding them, and you can read it directly when you drive the API yourself.

{
  "content": "{ ... the configuration document ... }",
  "field_availability": {
    "data_retention.audit_logs": {
      "settable": false,
      "reason": "custom_retention_not_allowed",
      "clearable": true,
      "unchanged_allowed": true
    }
  }
}

• settable — whether a new value can be saved for that field on your current plan.
• reason — why not, using the same error code the PUT would return, so you can map it to the same message. Absent when settable is true.
• clearable — whether the field can still be reset to the plan default (null for a retention category, an empty list for an array). This stays true even when settable is false, which is how an Organization that moved to a smaller plan clears values it set earlier.
• unchanged_allowed — whether sending the stored value back unchanged is accepted. It is true for data_retention and required_sso_providers, and false for allowed_email_domains, which is validated whenever the list is non-empty.

Fields that are not gated by plan do not appear in the map. The map is omitted entirely if the plan cannot be resolved for the request; the PUT validation is unaffected either way.

Profile fields

These describe the Organization itself.

default_locale only affects content where no per-user preference applies. Account-level notifications (password reset, lockouts) follow the recipient user's preferred locale, not this value.

Membership and access fields

These control who can join the Organization and how.

Data retention

The data_retention section controls how long each category of data is kept inside the Organization. Every key holds either null (use the plan's default retention) or a number of days (custom retention).

Warning: shortening a retention period irreversibly deletes existing data older than the new window on the next daily cleanup run. Review the diff carefully before saving.

Unlike other fields, the data_retention section and all six keys must be present in every update: omitting them is rejected instead of silently reverting to defaults, because a silent revert could trigger unintended data deletion. Use explicit null to return a category to the plan default.

Setting any custom (non-null) value requires the Business plan or higher. Every category accepts values between 7 and 36500 days, and every category additionally has a plan-specific upper limit where one is defined for your plan; values above that limit are rejected. For values equal to the currently saved ones, the plan-based checks (Business+ gate and plan cap) are skipped (so a plan downgrade never blocks editing unrelated settings; the absolute 7-36500 range is still validated whenever a value is non-null), and null is always accepted (clearing a custom value works on every plan).

Buddy autonomy limits

These bound how far Buddy may carry an investigation on its own before it stops and asks you. They do not turn AI features on or off — the AI master switch (ai_enabled) and the per-feature settings are not part of this document (see What this document covers above).

With on-demand charging enabled, auto_continuation_max_turns, auto_continuation_max_credits, and tool_record_max_per_conversation are the primary guard against unexpected spend, since the credit balance alone no longer acts as a hard stop.

When any of these limits is reached, Buddy stops the automatic continuation and tells you that a limit was reached — this is a normal stop, not a failure. Resuming (pressing Resume or saying "continue") starts a fresh turn and resets the counters, so you can keep going without changing the limits. In other words, these limits control how often you are asked to confirm, not a hard cap on the total amount of work.

auto_continuation_mode controls how much supervision Buddy's autonomous tasks require. In every mode, actions that write outside the conversation — saving a Runbook or Postmortem, applying configuration changes, or changing production systems — always require human approval; the mode only changes how autonomously Buddy may investigate (read and diagnose). There is no mode that bypasses write approval. Note: enforcement of plan gating and per-step confirmation is being rolled out progressively; until fully enabled, investigation reads run without confirmation and writes always require approval regardless of the configured mode.

Notifications

notifications holds the Organization-wide notification policy, keyed by notification type (for example critical_incident, document_created, org_config_changed, credit_stopped).

Because the object replaces the stored policy as a whole, dropping a type would silently reset it — so a PUT that leaves out any known type is rejected instead (notifications_required), the same way data_retention requires all of its keys. Start from the object returned by GET /api/v1/organizations/{id}/config, which always lists every known type, edit the entries you want to change, and send the whole object back. Inside an entry, an omitted key is read as its empty value (false for the booleans, "" for force_email_target), so write all three keys; sending null in place of an entry is read the same way.

Configuration-change and billing notifications (org_config_changed, webhook_config_changed, routing_rule_changed, mcp_connection_changed, transformation_rule_changed, team_config_changed, schedule_config_changed, bundle_settings_changed, and the credit balance / on-demand charge notifications) start with force_email_target: "owner" when the Organization is created, so that owners are not silently cut out of billing- and audit-relevant events.

These types cannot be released from forced email: force_email_target: "" on any of them is rejected (invalid_force_email_target), and so is leaving them out of the object. You can only widen the target from "owner" to "owner_and_admin".

Individual users can still turn a notification type off for themselves. The Organization policy sets the upper bound, and force_email_target is the one exception that overrides an individual preference.

Validation rules

• slug, ai_enabled, and ai_settings are not part of this document. A PUT that carries them — or any other fixed key the document does not define, at the top level or nested — is rejected as an unknown field, and the whole update fails. The keys inside notifications are checked separately against the list of known notification types: a misspelled or retired type name is rejected (invalid_notification_type). Copy type names from the document returned by GET /api/v1/organizations/{id}/config.
• name, when provided, must be 100 characters or less; description must be 500 characters or less.
• default_locale, when provided, must be en or ja.
• default_timezone, when provided, must be a valid IANA timezone (e.g. Asia/Tokyo).
• allowed_email_domains, when non-empty, requires a plan that includes domain restriction. Submitting it on a plan that does not is rejected even when the list is unchanged, so an Organization that moved to a smaller plan has to send an empty list before any other change to this document goes through. If any existing member has an email outside the listed domains, the change is rejected and the conflicting members are returned in the response.
• required_sso_providers recognizes only google and github: any other value is dropped and duplicates are collapsed, so what you read back is the filtered list. Adding or changing providers on a plan that does not include required SSO is rejected; sending the stored list back unchanged, and clearing it to an empty list, are accepted on every plan.
• mfa_step_up_enabled has no effect unless require_mfa is also true. Likewise, sso_step_up_enabled has no effect unless required_sso_providers is non-empty.
• The data_retention section and all six keys (alerts, learning, documents, chat, audit_logs, config_history) must be present; omitting any of them is rejected. Each value must be null or an integer between 7 and 36500, and every category is additionally validated against the plan-specific limit for that category where one is defined for your plan. Setting a new custom value requires the Business plan or higher (null and unchanged values are accepted on every plan). audit_logs additionally requires a plan that includes audit logs.
• The notifications section must be present and must list every known notification type; omitting the section or any type is rejected (notifications_required). Each entry's force_email_target must be "", "owner", or "owner_and_admin", and the administrative types listed above cannot use "" (invalid_force_email_target).
• auto_continuation_max_turns must be 0 (system default) or an integer between 1 and 50. auto_continuation_max_credits must be 0 (system default) or between 1 and 500. Out-of-range values are rejected.
• auto_continuation_mode must be "" (empty string or omitted = system default ask) or one of plan, ask, auto. Any other value is rejected.
• tool_record_max_per_conversation must be 0 (system default) or an integer between 10 and 1000. Out-of-range values are rejected.

Examples

Each example shows only the keys being changed. Because a PUT replaces the stored configuration (see Update semantics above), apply these edits to the document returned by GET /api/v1/organizations/{id}/config and send the complete document back.

Defaults for a new Organization based in Japan:

{
  "default_locale": "ja",
  "default_timezone": "Asia/Tokyo",
  "allow_member_leave": true,
  "require_mfa": false
}

Tighten membership to a single email domain and require MFA:

{
  "allowed_email_domains": ["example.com"],
  "require_mfa": true,
  "mfa_step_up_enabled": true,
  "allow_member_leave": false
}

Require SSO via Google and re-prompt at most once a day:

{
  "required_sso_providers": ["google"],
  "sso_step_up_enabled": true,
  "require_mfa": true
}

Keep alert data for one year and leave every other category on the plan default (requires the Business plan or higher; all six keys must be present):

{
  "data_retention": {
    "alerts": 365,
    "learning": null,
    "documents": null,
    "chat": null,
    "audit_logs": null,
    "config_history": null
  }
}

Allow deeper autonomous investigations (raise the auto-continuation limits from the defaults):

{
  "auto_continuation_max_turns": 20,
  "auto_continuation_max_credits": 100
}

Stop sending document notifications by push, and force configuration-change emails to owners and admins. The notifications object below is abridged for readability and cannot be sent as-is — it omits the other known types, and a PUT missing any of them is rejected. Take the notifications object from GET /api/v1/organizations/{id}/config and edit only the entries you want to change:

{
  "notifications": {
    "document_created": { "push": false, "email": true,  "force_email_target": "" },
    "document_updated": { "push": false, "email": true,  "force_email_target": "" },
    "org_config_changed": { "push": true, "email": true, "force_email_target": "owner_and_admin" }
  }
}

Related

• Team — Teams live inside an Organization and inherit its locale and timezone defaults.
• Schedule — Schedule timezone falls back to default_timezone.
• Tags and labels — the tag and label masters are scoped per Organization.