Creates a change freeze.
const url = 'https://api.featureflip.io/api/v1/orgs/example/change-freezes';const options = { method: 'POST', headers: {Authorization: '<Authorization>', 'Content-Type': 'application/json'}, body: '{"name":"example","reason":"example","project":"example","allEnvironments":true,"environmentKeys":["example"],"environmentIds":["2489E9AD-2EE2-8E00-8EC9-32D5F69181C0"],"startsAt":"2026-04-15T12:00:00Z","endsAt":"2026-04-15T12:00:00Z","scheduledChangePolicy":"Hold"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://api.featureflip.io/api/v1/orgs/example/change-freezes \ --header 'Authorization: <Authorization>' \ --header 'Content-Type: application/json' \ --data '{ "name": "example", "reason": "example", "project": "example", "allEnvironments": true, "environmentKeys": [ "example" ], "environmentIds": [ "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0" ], "startsAt": "2026-04-15T12:00:00Z", "endsAt": "2026-04-15T12:00:00Z", "scheduledChangePolicy": "Hold" }'Requires Admin and the Business plan or above (a lower plan is a 400
PLAN_FEATURE_UNAVAILABLE). Omit startsAt to freeze now. Supports the Idempotency-Key header.
Authorizations
Section titled “ Authorizations ”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “ Path Parameters ”Request Body
Section titled “ Request Body ”Creates a change freeze. project (key or id) makes it a project window; omit it for an
organization-wide one. Omit startsAt to freeze now (then endsAt may be omitted for an
open-ended freeze); a scheduled freeze needs both. Times are UTC and must carry an offset (Z).
Name the environments with environmentKeys (a project window accepts keys too, resolved within
the project) and/or environmentIds, or set allEnvironments.
scheduledChangePolicy is Hold (the default) or Fail.
object
Allowed values: Hold, Fail.
Creates a change freeze. project (key or id) makes it a project window; omit it for an
organization-wide one. Omit startsAt to freeze now (then endsAt may be omitted for an
open-ended freeze); a scheduled freeze needs both. Times are UTC and must carry an offset (Z).
Name the environments with environmentKeys (a project window accepts keys too, resolved within
the project) and/or environmentIds, or set allEnvironments.
scheduledChangePolicy is Hold (the default) or Fail.
object
Allowed values: Hold, Fail.
Creates a change freeze. project (key or id) makes it a project window; omit it for an
organization-wide one. Omit startsAt to freeze now (then endsAt may be omitted for an
open-ended freeze); a scheduled freeze needs both. Times are UTC and must carry an offset (Z).
Name the environments with environmentKeys (a project window accepts keys too, resolved within
the project) and/or environmentIds, or set allEnvironments.
scheduledChangePolicy is Hold (the default) or Fail.
object
Allowed values: Hold, Fail.
Responses
Section titled “ Responses ”Created
A change freeze window. project is the project’s key, or null for an organization-wide window.
An organization-wide window names its environments by key (environmentKeys, matched in every project);
a project window names them by id, and returns both environmentIds and the current
environmentKeys of those environments. status is time-based only: Upcoming, Active
or Ended. enforcing is true when the window is Active and is actually in force: it has
started enforcing, or the organization’s plan includes change freezes. wontStartReason is Plan
when the window has not started enforcing and the organization’s plan no longer includes change freezes, so it
will not enforce. approvals lists the scheduled changes approved to land inside the window.
object
Allowed values: Hold, Fail.
Allowed values: Upcoming, Active, Ended.
Allowed values: Plan.
A scheduled change that a person approved to land inside a change freeze. stands is whether the approval
counts right now: false once the approver is no longer an active Owner or Admin, and the window then holds or fails
the change as if it were not approved.
object
Capability hints: which operations the authenticated caller may perform on this resource, each with allowed + optional reason. Computed from the caller’s role and the resource’s state. Injected at runtime; safe to ignore. Present only on top-level resource responses — nested occurrences (e.g. a rule inside a targeting-config response) do not carry it.
object
One entry in a resource’s _actions block: may the caller perform it, and if not, why.
object
Example
{ "scheduledChangePolicy": "Hold", "status": "Upcoming", "wontStartReason": "Plan"}Headers
Section titled “ Headers ”The maximum number of requests permitted per rate-limit window for this caller.
The number of requests remaining in the current rate-limit window.
The UTC time at which the current rate-limit window resets, as a Unix timestamp in seconds.
The request is malformed, or it carries an If-Match header, which this endpoint can’t evaluate. Send no If-Match, or *.
The frozen public-API error contract. error codes are stable snake_case strings. Wire keys
are frozen snake_case too (error, message, docs_url, fields,
retry_after) — the global camelCase naming policy would otherwise emit
docsUrl/retryAfter, breaking the published spec. !:JsonPropertyName
always wins over the policy, so these are pinned explicitly rather than relying on the
property names already being lowercase for the single-word ones.
did_you_mean, next_actions and connection_id are ADDITIVE optional keys
(null → omitted via the global DefaultIgnoreCondition = WhenWritingNull), so
pre-existing error bodies are byte-for-byte unchanged when they’re absent.
connection_id is present only on the sso_required error: the organization
requires single sign-on, and this credential didn’t come through its identity provider.
connection_id identifies which SSO connection to sign in with.
plan_limit is present only on the plan_limit_reached error: which plan cap the
request would have exceeded, so a client can branch on it without parsing message.
change_freeze is present only on the change_frozen error (#4645): the change freeze that refused the
write, so a client can show when it ends and whether the caller may break it, without parsing message.
object
object
object
The cap behind a plan_limit_reached error. resource is the capped collection
(projects, environments, flags, webhooks, members);
plan is the plan’s wire name, as GET /api/v1/orgs/{org} returns it; max is
the cap. The environment and flag caps are per project.
object
The freeze behind a change_frozen error: id and name of the window, the environment’s
environment_key, ends_at (UTC; always present, null for an open-ended window) and whether the caller’s role may
break it (can_override, with X-Freeze-Override: true and an X-Intent-Reason).
object
Example
{ "error": "not_found", "message": "Flag 'new-checkout-flw' was not found in project 'checkout'.", "docs_url": "https://featureflip.io/docs/management-api/errors/not_found", "did_you_mean": [ "new-checkout-flow" ], "next_actions": [ { "method": "GET", "path": "/api/v1/orgs/acme/projects/checkout/flags" } ]}Headers
Section titled “ Headers ”The maximum number of requests permitted per rate-limit window for this caller.
The number of requests remaining in the current rate-limit window.
The UTC time at which the current rate-limit window resets, as a Unix timestamp in seconds.
Authentication is required, or the supplied API token is invalid or expired.
The frozen public-API error contract. error codes are stable snake_case strings. Wire keys
are frozen snake_case too (error, message, docs_url, fields,
retry_after) — the global camelCase naming policy would otherwise emit
docsUrl/retryAfter, breaking the published spec. !:JsonPropertyName
always wins over the policy, so these are pinned explicitly rather than relying on the
property names already being lowercase for the single-word ones.
did_you_mean, next_actions and connection_id are ADDITIVE optional keys
(null → omitted via the global DefaultIgnoreCondition = WhenWritingNull), so
pre-existing error bodies are byte-for-byte unchanged when they’re absent.
connection_id is present only on the sso_required error: the organization
requires single sign-on, and this credential didn’t come through its identity provider.
connection_id identifies which SSO connection to sign in with.
plan_limit is present only on the plan_limit_reached error: which plan cap the
request would have exceeded, so a client can branch on it without parsing message.
change_freeze is present only on the change_frozen error (#4645): the change freeze that refused the
write, so a client can show when it ends and whether the caller may break it, without parsing message.
object
object
object
The cap behind a plan_limit_reached error. resource is the capped collection
(projects, environments, flags, webhooks, members);
plan is the plan’s wire name, as GET /api/v1/orgs/{org} returns it; max is
the cap. The environment and flag caps are per project.
object
The freeze behind a change_frozen error: id and name of the window, the environment’s
environment_key, ends_at (UTC; always present, null for an open-ended window) and whether the caller’s role may
break it (can_override, with X-Freeze-Override: true and an X-Intent-Reason).
object
Example
{ "error": "not_found", "message": "Flag 'new-checkout-flw' was not found in project 'checkout'.", "docs_url": "https://featureflip.io/docs/management-api/errors/not_found", "did_you_mean": [ "new-checkout-flow" ], "next_actions": [ { "method": "GET", "path": "/api/v1/orgs/acme/projects/checkout/flags" } ]}Headers
Section titled “ Headers ”The maximum number of requests permitted per rate-limit window for this caller.
The number of requests remaining in the current rate-limit window.
The UTC time at which the current rate-limit window resets, as a Unix timestamp in seconds.
Forbidden
The frozen public-API error contract. error codes are stable snake_case strings. Wire keys
are frozen snake_case too (error, message, docs_url, fields,
retry_after) — the global camelCase naming policy would otherwise emit
docsUrl/retryAfter, breaking the published spec. !:JsonPropertyName
always wins over the policy, so these are pinned explicitly rather than relying on the
property names already being lowercase for the single-word ones.
did_you_mean, next_actions and connection_id are ADDITIVE optional keys
(null → omitted via the global DefaultIgnoreCondition = WhenWritingNull), so
pre-existing error bodies are byte-for-byte unchanged when they’re absent.
connection_id is present only on the sso_required error: the organization
requires single sign-on, and this credential didn’t come through its identity provider.
connection_id identifies which SSO connection to sign in with.
plan_limit is present only on the plan_limit_reached error: which plan cap the
request would have exceeded, so a client can branch on it without parsing message.
change_freeze is present only on the change_frozen error (#4645): the change freeze that refused the
write, so a client can show when it ends and whether the caller may break it, without parsing message.
object
object
object
The cap behind a plan_limit_reached error. resource is the capped collection
(projects, environments, flags, webhooks, members);
plan is the plan’s wire name, as GET /api/v1/orgs/{org} returns it; max is
the cap. The environment and flag caps are per project.
object
The freeze behind a change_frozen error: id and name of the window, the environment’s
environment_key, ends_at (UTC; always present, null for an open-ended window) and whether the caller’s role may
break it (can_override, with X-Freeze-Override: true and an X-Intent-Reason).
object
Example
{ "error": "not_found", "message": "Flag 'new-checkout-flw' was not found in project 'checkout'.", "docs_url": "https://featureflip.io/docs/management-api/errors/not_found", "did_you_mean": [ "new-checkout-flow" ], "next_actions": [ { "method": "GET", "path": "/api/v1/orgs/acme/projects/checkout/flags" } ]}Headers
Section titled “ Headers ”The maximum number of requests permitted per rate-limit window for this caller.
The number of requests remaining in the current rate-limit window.
The UTC time at which the current rate-limit window resets, as a Unix timestamp in seconds.
Not Found
The frozen public-API error contract. error codes are stable snake_case strings. Wire keys
are frozen snake_case too (error, message, docs_url, fields,
retry_after) — the global camelCase naming policy would otherwise emit
docsUrl/retryAfter, breaking the published spec. !:JsonPropertyName
always wins over the policy, so these are pinned explicitly rather than relying on the
property names already being lowercase for the single-word ones.
did_you_mean, next_actions and connection_id are ADDITIVE optional keys
(null → omitted via the global DefaultIgnoreCondition = WhenWritingNull), so
pre-existing error bodies are byte-for-byte unchanged when they’re absent.
connection_id is present only on the sso_required error: the organization
requires single sign-on, and this credential didn’t come through its identity provider.
connection_id identifies which SSO connection to sign in with.
plan_limit is present only on the plan_limit_reached error: which plan cap the
request would have exceeded, so a client can branch on it without parsing message.
change_freeze is present only on the change_frozen error (#4645): the change freeze that refused the
write, so a client can show when it ends and whether the caller may break it, without parsing message.
object
object
object
The cap behind a plan_limit_reached error. resource is the capped collection
(projects, environments, flags, webhooks, members);
plan is the plan’s wire name, as GET /api/v1/orgs/{org} returns it; max is
the cap. The environment and flag caps are per project.
object
The freeze behind a change_frozen error: id and name of the window, the environment’s
environment_key, ends_at (UTC; always present, null for an open-ended window) and whether the caller’s role may
break it (can_override, with X-Freeze-Override: true and an X-Intent-Reason).
object
Example
{ "error": "not_found", "message": "Flag 'new-checkout-flw' was not found in project 'checkout'.", "docs_url": "https://featureflip.io/docs/management-api/errors/not_found", "did_you_mean": [ "new-checkout-flow" ], "next_actions": [ { "method": "GET", "path": "/api/v1/orgs/acme/projects/checkout/flags" } ]}Headers
Section titled “ Headers ”The maximum number of requests permitted per rate-limit window for this caller.
The number of requests remaining in the current rate-limit window.
The UTC time at which the current rate-limit window resets, as a Unix timestamp in seconds.
Rate limit exceeded. Retry after the interval indicated by the Retry-After header.
The frozen public-API error contract. error codes are stable snake_case strings. Wire keys
are frozen snake_case too (error, message, docs_url, fields,
retry_after) — the global camelCase naming policy would otherwise emit
docsUrl/retryAfter, breaking the published spec. !:JsonPropertyName
always wins over the policy, so these are pinned explicitly rather than relying on the
property names already being lowercase for the single-word ones.
did_you_mean, next_actions and connection_id are ADDITIVE optional keys
(null → omitted via the global DefaultIgnoreCondition = WhenWritingNull), so
pre-existing error bodies are byte-for-byte unchanged when they’re absent.
connection_id is present only on the sso_required error: the organization
requires single sign-on, and this credential didn’t come through its identity provider.
connection_id identifies which SSO connection to sign in with.
plan_limit is present only on the plan_limit_reached error: which plan cap the
request would have exceeded, so a client can branch on it without parsing message.
change_freeze is present only on the change_frozen error (#4645): the change freeze that refused the
write, so a client can show when it ends and whether the caller may break it, without parsing message.
object
object
object
The cap behind a plan_limit_reached error. resource is the capped collection
(projects, environments, flags, webhooks, members);
plan is the plan’s wire name, as GET /api/v1/orgs/{org} returns it; max is
the cap. The environment and flag caps are per project.
object
The freeze behind a change_frozen error: id and name of the window, the environment’s
environment_key, ends_at (UTC; always present, null for an open-ended window) and whether the caller’s role may
break it (can_override, with X-Freeze-Override: true and an X-Intent-Reason).
object
Example
{ "error": "not_found", "message": "Flag 'new-checkout-flw' was not found in project 'checkout'.", "docs_url": "https://featureflip.io/docs/management-api/errors/not_found", "did_you_mean": [ "new-checkout-flow" ], "next_actions": [ { "method": "GET", "path": "/api/v1/orgs/acme/projects/checkout/flags" } ]}Headers
Section titled “ Headers ”Number of seconds to wait before retrying the request.
The maximum number of requests permitted per rate-limit window for this caller.
The number of requests remaining in the current rate-limit window.
The UTC time at which the current rate-limit window resets, as a Unix timestamp in seconds.