/v1/workspaces/{workspace_id}/settings/{setting_id}/values/{environment_id}/scheduled-changesAuthSchedule a change
Schedules a value write for `run_at` (to within about 30 seconds): a `patch` (turn a flag on at 09:00) applies to whatever the value is then; a `replace` applies only if the value is still at `version`. Where the environment needs approval for the caller this answers 409 `APPROVAL_REQUIRED`: propose a change request and schedule it once approved.
Path parameters
setting_id*string · uuidId of the setting.
environment_id*string · uuidId of an environment of the same project.
workspace_id*string · uuidId of the workspace.
Headers
Idempotency-KeystringIdempotency key (1-256 characters, `[A-Za-z0-9._:-]`). A retry with the same key and body returns the first response for 24 h.
Request body
run_at*string · date-timeWhen to apply it (UTC, ISO 8601), in the future and within a year.
Example: "2026-11-20T09:00:00.000Z"
operation*enum (2)`patch`: `value`, `percentage_attribute` and/or `clear_rules`, applied to whatever the value is at `run_at` (turn a flag on at 09:00). `replace`: the whole targeting, applied only if the value is still at `version`.
Example: "patch"
versioninteger`replace` only: the `version` you read.
Example: 7
notestringA note for reviewers and the history (at most 500 characters). Required where the environment has `require_note`.
Example: "Roll out the new checkout to everyone (FLAG-142)"
valueobjectA value of the setting's type: `boolean` true/false, `string`, `integer` / `number`, or for `json` a string holding JSON text.
Example: true
rulesarray`replace` only: the rules.
percentagesarray`replace` only: the flag-level split.
percentage_attributestringThe attribute splits hash; null for `identifier`.
clear_rulesboolean`patch` only: serve `value` to everyone (drop rules and splits).
Example: false
Response · 201 The pending scheduled change.
id*string · uuidId of the scheduled change.
workspace_id*string · uuidThe workspace.
project_id*string · uuidThe project.
config_id*string · uuidThe config.
setting_id*string · uuidThe setting.
setting_key*stringThe setting's key.
Example: "new_checkout"
environment_id*string · uuidThe environment.
environment_key*stringThe environment's key.
Example: "production"
operation*object`patch` applies its edits to whatever the value is at `run_at`; `replace` (and an approved change request) applies only if the value is still at `base_version`, else it fails.
Example: "patch"
payload*objectWhat will be written: the patch fields (`value`, `percentage_attribute`, `clear_rules`) or the whole targeting.
base_version*integer`replace` only: the `version` the change must still find.
Example: 7
change_request_id*string · uuidThe approved change request this applies.
run_at*string · date-timeWhen it runs (to within about 30 seconds).
status*objectState.
Example: "pending"
note*stringThe note the history entry gets.
Example: "Launch at 09:00"
created_by*objectWho scheduled it.
applied_change_id*string · uuidThe history entry it wrote.
executed_at*string · date-timeWhen it ran.
last_error*objectWhy it failed.
created_at*string · date-timeWhen it was scheduled.
updated_at*string · date-timeWhen it last changed state.
Example
Request
POST https://api.flags.productcraft.co/v1/workspaces/{workspace_id}/settings/{setting_id}/values/{environment_id}/scheduled-changes
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json
{
"run_at": "2026-11-20T09:00:00.000Z",
"operation": "patch",
"version": 7,
"note": "Roll out the new checkout to everyone (FLAG-142)",
"value": true,
"rules": [
{}
],
"percentages": [
{}
],
"percentage_attribute": "string",
"clear_rules": false
}import { Flags } from "@productcraft/flags";
// Reads PRODUCTCRAFT_API_KEY from the environment
const flags = new Flags();
const scheduledChange = await flags.settings.values.scheduledChanges.create("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f", "3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f", { operation: "patch", run_at: "2026-11-20T09:00:00.000Z" });flags.settings.values.scheduledChanges.create(settingId, environmentId, params, options?): Flags.ScheduledChange
Response
{
"id": "00000000-0000-0000-0000-000000000000",
"workspace_id": "00000000-0000-0000-0000-000000000000",
"project_id": "00000000-0000-0000-0000-000000000000",
"config_id": "00000000-0000-0000-0000-000000000000",
"setting_id": "00000000-0000-0000-0000-000000000000",
"setting_key": "new_checkout",
"environment_id": "00000000-0000-0000-0000-000000000000",
"environment_key": "production",
"operation": "patch",
"payload": {},
"base_version": 7,
"change_request_id": "00000000-0000-0000-0000-000000000000",
"run_at": "2026-01-01T00:00:00.000Z",
"status": "pending",
"note": "Launch at 09:00",
"created_by": {},
"applied_change_id": "00000000-0000-0000-0000-000000000000",
"executed_at": "2026-01-01T00:00:00.000Z",
"last_error": {},
"created_at": "2026-01-01T00:00:00.000Z",
"updated_at": "2026-01-01T00:00:00.000Z"
}