Flags API reference

Flags API · Change-Requests

post/v1/workspaces/{workspace_id}/change-requests/{change_request_id}/scheduleAuth

Schedule a change request

Applies an approved `value` request at `run_at` (status `scheduled`). If the value moved by then the request becomes `failed`: rebase it. Cancel the schedule by cancelling the scheduled change or the request.

Path parameters

change_request_id*string · uuid

Id of the change request.

workspace_id*string · uuid

Id of the workspace.

Request body

run_at*string · date-time

When to apply the approved change (UTC, ISO 8601), in the future and within a year.

Example: "2026-11-20T09:00:00.000Z"

Response · 200 The scheduled change request (`scheduled_change_id`).

id*string · uuid

Id of the change request.

workspace_id*string · uuid

The workspace.

project_id*string · uuid

The project.

config_id*string · uuid

The config.

setting_id*string · uuid

The setting the change is for.

setting_key*string

The setting's key.

Example: "new_checkout"

environment_id*string · uuid

The environment the change is for.

environment_key*string

The environment's key.

Example: "production"

kind*object

`value`: a new value and targeting. `ramp`: a timed percentage rollout, started when applied.

Example: "value"

status*object

`pending` until it has `required_approvals` approvals (`approved`); `scheduled` when an approved request waits for its `run_at`; `applied`; `rejected` by a reviewer; `cancelled` by its author or a reviewer; `failed` when a scheduled apply found the value changed (rebase it).

Example: "pending"

base_version*integer

The value's `version` the proposal was made against.

Example: 7

current_version*integer

The value's `version` now.

Example: 7

stale*boolean

True when the value changed since the proposal (`current_version` ≠ `base_version`) while the request is still open: rebase or recreate it before applying.

Example: false

before*object

What the environment served when the change was proposed: `value`, `rules`, `percentages`, `percentage_attribute`. Confidential lists show as counts.

after*object

What it will serve once applied (same shape), or for a `ramp` the ramp `{value, steps}`.

diff*array

JSON Patch (RFC 6902) from `before` to `after`.

summary*array

The change in words ("value false → true", "rule 2 percentage 10 → 25").

Example: ["value false → true"]

note*string

The author's note.

Example: "Turn on for everyone"

required_approvals*integer

Approvals needed (from the environment when it was proposed).

Example: 1

approvals*integer

Approvals so far.

Example: 0

reviews*array

Every decision, oldest first.

author*object

Who proposed it (and for whom, when an agent did).

applied_change_id*string · uuid

The history entry the apply wrote.

applied_at*string · date-time

When it was applied.

scheduled_change_id*string · uuid

The scheduled change that will apply it.

last_error*object

Why the last scheduled apply failed.

created_at*string · date-time

When it was proposed.

updated_at*string · date-time

When it last changed state.

Example

Request

POST https://api.flags.productcraft.co/v1/workspaces/{workspace_id}/change-requests/{change_request_id}/schedule
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "run_at": "2026-11-20T09:00:00.000Z"
}

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",
  "kind": "value",
  "status": "pending",
  "base_version": 7,
  "current_version": 7,
  "stale": false,
  "before": {},
  "after": {},
  "diff": [
    {
      "op": {},
      "path": "/rules/1/percentages/0/percentage",
      "value": 25
    }
  ],
  "summary": [
    "value false → true"
  ],
  "note": "Turn on for everyone",
  "required_approvals": 1,
  "approvals": 0,
  "reviews": [
    {
      "reviewer_id": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f7a8b9",
      "reviewer_label": "ada@example.com",
      "decision": "approved",
      "note": "Looks good",
      "created_at": "2026-01-01T00:00:00.000Z"
    }
  ],
  "author": {},
  "applied_change_id": "00000000-0000-0000-0000-000000000000",
  "applied_at": "2026-01-01T00:00:00.000Z",
  "scheduled_change_id": "00000000-0000-0000-0000-000000000000",
  "last_error": {},
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}