Skip to content

Edits a change freeze.

PATCH
/api/v1/orgs/{org}/change-freezes/{id}
curl --request PATCH \
--url https://api.featureflip.io/api/v1/orgs/example/change-freezes/example \
--header 'Authorization: <Authorization>' \
--header 'Content-Type: application/json' \
--data '{ "name": "example", "reason": "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. A field left out is unchanged. An ended window cannot be edited and the start of an active window cannot move (400). Below the Business plan a window can only be renamed, have its reason edited, or end sooner; anything else is a 400 PLAN_FEATURE_UNAVAILABLE.

org
required
string
id
required
string
If-Match
string

Optional. The ETag from a GET of this resource. The write applies only if the resource still has that ETag, meaning nothing in its body has changed since; otherwise 412 precondition_failed. * or no header applies the write unconditionally.

Edits a change freeze; a field left out is left as it was. An ended window cannot be edited, and the start of an active window cannot move. Send If-Match with the ETag from the last read to guard against a concurrent edit.

object
name
string
nullable
reason
string
nullable
allEnvironments
boolean
nullable
environmentKeys
Array<string>
nullable
environmentIds
Array<string>
nullable
startsAt
string format: date-time
nullable
endsAt
string format: date-time
nullable
scheduledChangePolicy

Allowed values: Hold, Fail.

string
nullable
Allowed values: Hold Fail

OK

Media type application/json

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
id
required
string format: uuid
project
string
nullable
name
required
string
reason
required
string
allEnvironments
required
boolean
environmentKeys
required
Array<string>
environmentIds
required
Array<string>
startsAt
required
string format: date-time
endsAt
string format: date-time
nullable
endedAt
string format: date-time
nullable
scheduledChangePolicy
required

Allowed values: Hold, Fail.

string
Allowed values: Hold Fail
status
required

Allowed values: Upcoming, Active, Ended.

string
Allowed values: Upcoming Active Ended
enforcing
required
boolean
wontStartReason

Allowed values: Plan.

string
nullable
Allowed values: Plan
approvals
required
Array<object>

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
scheduledChangeId
required
string format: uuid
flagId
required
string format: uuid
flagKey
string
nullable
environmentId
required
string format: uuid
scheduledAtUtc
required
string format: date-time
reason
required
string
approvedByEmail
required
string
approvedAt
required
string format: date-time
stands
required
boolean
createdByEmail
required
string
_actions

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
key
additional properties

One entry in a resource’s _actions block: may the caller perform it, and if not, why.

object
allowed
boolean
reason
string
nullable

Example

{
"scheduledChangePolicy": "Hold",
"status": "Upcoming",
"wontStartReason": "Plan"
}
ETag
string

Strong ETag of the resource’s whole body as sent to this caller: it changes whenever anything in the body does. Send it back as If-Match on a PUT.

X-RateLimit-Limit
integer

The maximum number of requests permitted per rate-limit window for this caller.

X-RateLimit-Remaining
integer

The number of requests remaining in the current rate-limit window.

X-RateLimit-Reset
integer

The UTC time at which the current rate-limit window resets, as a Unix timestamp in seconds.

Bad Request

Media type application/json

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
error
required
string
message
required
string
docs_url
required
string
fields
object
key
additional properties
Array<string>
retry_after
integer format: int32
nullable
did_you_mean
Array<string>
nullable
next_actions
Array<object>
nullable
object
method
required
string
path
required
string
connection_id
string format: uuid
nullable
plan_limit

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
resource
required
string
plan
required
string
max
required
integer format: int32
change_freeze

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
id
required
string format: uuid
name
required
string
environment_key
required
string
ends_at
string format: date-time
nullable
can_override
required
boolean

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"
}
]
}
X-RateLimit-Limit
integer

The maximum number of requests permitted per rate-limit window for this caller.

X-RateLimit-Remaining
integer

The number of requests remaining in the current rate-limit window.

X-RateLimit-Reset
integer

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.

Media type application/json

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
error
required
string
message
required
string
docs_url
required
string
fields
object
key
additional properties
Array<string>
retry_after
integer format: int32
nullable
did_you_mean
Array<string>
nullable
next_actions
Array<object>
nullable
object
method
required
string
path
required
string
connection_id
string format: uuid
nullable
plan_limit

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
resource
required
string
plan
required
string
max
required
integer format: int32
change_freeze

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
id
required
string format: uuid
name
required
string
environment_key
required
string
ends_at
string format: date-time
nullable
can_override
required
boolean

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"
}
]
}
X-RateLimit-Limit
integer

The maximum number of requests permitted per rate-limit window for this caller.

X-RateLimit-Remaining
integer

The number of requests remaining in the current rate-limit window.

X-RateLimit-Reset
integer

The UTC time at which the current rate-limit window resets, as a Unix timestamp in seconds.

Forbidden

Media type application/json

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
error
required
string
message
required
string
docs_url
required
string
fields
object
key
additional properties
Array<string>
retry_after
integer format: int32
nullable
did_you_mean
Array<string>
nullable
next_actions
Array<object>
nullable
object
method
required
string
path
required
string
connection_id
string format: uuid
nullable
plan_limit

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
resource
required
string
plan
required
string
max
required
integer format: int32
change_freeze

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
id
required
string format: uuid
name
required
string
environment_key
required
string
ends_at
string format: date-time
nullable
can_override
required
boolean

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"
}
]
}
X-RateLimit-Limit
integer

The maximum number of requests permitted per rate-limit window for this caller.

X-RateLimit-Remaining
integer

The number of requests remaining in the current rate-limit window.

X-RateLimit-Reset
integer

The UTC time at which the current rate-limit window resets, as a Unix timestamp in seconds.

Not Found

Media type application/json

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
error
required
string
message
required
string
docs_url
required
string
fields
object
key
additional properties
Array<string>
retry_after
integer format: int32
nullable
did_you_mean
Array<string>
nullable
next_actions
Array<object>
nullable
object
method
required
string
path
required
string
connection_id
string format: uuid
nullable
plan_limit

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
resource
required
string
plan
required
string
max
required
integer format: int32
change_freeze

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
id
required
string format: uuid
name
required
string
environment_key
required
string
ends_at
string format: date-time
nullable
can_override
required
boolean

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"
}
]
}
X-RateLimit-Limit
integer

The maximum number of requests permitted per rate-limit window for this caller.

X-RateLimit-Remaining
integer

The number of requests remaining in the current rate-limit window.

X-RateLimit-Reset
integer

The UTC time at which the current rate-limit window resets, as a Unix timestamp in seconds.

The resource changed since the If-Match ETag.

Media type application/json

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
error
required
string
message
required
string
docs_url
required
string
fields
object
key
additional properties
Array<string>
retry_after
integer format: int32
nullable
did_you_mean
Array<string>
nullable
next_actions
Array<object>
nullable
object
method
required
string
path
required
string
connection_id
string format: uuid
nullable
plan_limit

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
resource
required
string
plan
required
string
max
required
integer format: int32
change_freeze

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
id
required
string format: uuid
name
required
string
environment_key
required
string
ends_at
string format: date-time
nullable
can_override
required
boolean

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"
}
]
}
X-RateLimit-Limit
integer

The maximum number of requests permitted per rate-limit window for this caller.

X-RateLimit-Remaining
integer

The number of requests remaining in the current rate-limit window.

X-RateLimit-Reset
integer

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.

Media type application/json

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
error
required
string
message
required
string
docs_url
required
string
fields
object
key
additional properties
Array<string>
retry_after
integer format: int32
nullable
did_you_mean
Array<string>
nullable
next_actions
Array<object>
nullable
object
method
required
string
path
required
string
connection_id
string format: uuid
nullable
plan_limit

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
resource
required
string
plan
required
string
max
required
integer format: int32
change_freeze

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
id
required
string format: uuid
name
required
string
environment_key
required
string
ends_at
string format: date-time
nullable
can_override
required
boolean

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"
}
]
}
Retry-After
integer

Number of seconds to wait before retrying the request.

X-RateLimit-Limit
integer

The maximum number of requests permitted per rate-limit window for this caller.

X-RateLimit-Remaining
integer

The number of requests remaining in the current rate-limit window.

X-RateLimit-Reset
integer

The UTC time at which the current rate-limit window resets, as a Unix timestamp in seconds.