Scheduled changes and change requests
Both hold a change for later: a schedule until a time, a request until a reviewer approves it. Each is validated when you create it, so a typo fails now, not at 03:00.
Schedule a change
POST/v1/admin/projects/{project}/environments/{env}/flags/{flag}/schedule
Auth: Personal access token or dashboard session, role writer or higher.
Saves a change for a node's scheduler to apply at executeAt, checked every 15 seconds. A change more than an hour late (SCHEDULER_GRACE_MS) is marked failed instead of applied, so a 09:00 launch never fires at 15:00.
Path parameters
| Name | Type | Description |
|---|---|---|
project | string | Project key. |
env | string | Environment key. |
flag | string | Flag key. |
Body
| Field | Type | Required | Description |
|---|---|---|---|
patch | object | yes | The same fields as PATCH a flag's configuration, without expectedVersion. |
executeAt | string | yes | ISO 8601 date-time in the future. |
comment | string | no |
Responses
{
"id": "c4d5e6f7-a8b9-4c0d-9e1f-2a3b4c5d6e7f",
"executeAt": "2026-11-27T09:00:00.000Z"
}
{
"error": "INVALID_BODY",
"message": "executeAt: Invalid ISO datetime"
}
{
"error": "EXECUTE_AT_IN_PAST",
"message": "executeAt must be in the future"
}
{
"error": "NOT_FOUND",
"message": "no such flag in that environment"
}
Common errors (401, 403, 400, 409, 422, 413, 500)
{
"error": "MISSING_TOKEN",
"message": "an access token is required"
}
{
"error": "TOKEN_REJECTED",
"message": "access token rejected"
}
{
"error": "SESSION_REJECTED",
"message": "session expired or rejected"
}
{
"error": "CSRF_HEADER_REQUIRED",
"message": "x-featurekit-csrf is required for cookie auth"
}
{
"error": "INSUFFICIENT_ROLE",
"message": "requires writer or higher"
}
{
"error": "INVALID_IDEMPOTENCY_KEY",
"message": "Idempotency-Key must be at most 200 characters of [A-Za-z0-9._:-]"
}
{
"error": "IDEMPOTENCY_IN_FLIGHT",
"message": "a request with this Idempotency-Key is still being processed"
}
{
"error": "IDEMPOTENCY_KEY_REUSED",
"message": "this Idempotency-Key was already used for a different request body"
}
{
"error": "INVALID_JSON",
"message": "request body is not valid JSON"
}
{
"error": "PAYLOAD_TOO_LARGE",
"message": "body exceeds 524288 bytes"
}
{
"error": "INTERNAL_ERROR"
}
Example
curl -X POST http://127.0.0.1:3000/v1/admin/projects/acme/environments/production/flags/bf-banner/schedule \
-H "Authorization: Bearer $FEATUREKIT_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"patch": { "enabled": true },
"executeAt": "2026-11-27T09:00:00Z",
"comment": "Black Friday banner"
}'
List scheduled changes
GET/v1/admin/projects/{project}/environments/{env}/flags/{flag}/schedule
Auth: Personal access token or dashboard session, role reader or higher.
Up to 100, soonest first, including ones already applied or failed.
Path parameters
| Name | Type | Description |
|---|---|---|
project | string | Project key. |
env | string | Environment key. |
flag | string | Flag key. |
Responses
{
"scheduled": [
{
"id": "c4d5e6f7-a8b9-4c0d-9e1f-2a3b4c5d6e7f",
"executeAt": "2026-11-27T09:00:00.000Z",
"executedAt": null,
"failedReason": null
}
]
}
{
"error": "NOT_FOUND",
"message": "no such flag in that environment"
}
Common errors (401, 500)
{
"error": "MISSING_TOKEN",
"message": "an access token is required"
}
{
"error": "TOKEN_REJECTED",
"message": "access token rejected"
}
{
"error": "SESSION_REJECTED",
"message": "session expired or rejected"
}
{
"error": "INTERNAL_ERROR"
}
Example
curl http://127.0.0.1:3000/v1/admin/projects/acme/environments/production/flags/bf-banner/schedule -H "Authorization: Bearer $FEATUREKIT_TOKEN"
Cancel a scheduled change
DELETE/v1/admin/projects/{project}/environments/{env}/flags/{flag}/schedule/{scheduleId}
Auth: Personal access token or dashboard session, role writer or higher.
Cancels a change that hasn't run yet.
Path parameters
| Name | Type | Description |
|---|---|---|
project | string | Project key. |
env | string | Environment key. |
flag | string | Flag key. |
scheduleId | string | From the list above. |
Responses
{
"cancelled": true
}
{
"error": "NOT_FOUND",
"message": "no such pending scheduled change"
}
Common errors (401, 403, 400, 409, 422, 500)
{
"error": "MISSING_TOKEN",
"message": "an access token is required"
}
{
"error": "TOKEN_REJECTED",
"message": "access token rejected"
}
{
"error": "SESSION_REJECTED",
"message": "session expired or rejected"
}
{
"error": "CSRF_HEADER_REQUIRED",
"message": "x-featurekit-csrf is required for cookie auth"
}
{
"error": "INSUFFICIENT_ROLE",
"message": "requires writer or higher"
}
{
"error": "INVALID_IDEMPOTENCY_KEY",
"message": "Idempotency-Key must be at most 200 characters of [A-Za-z0-9._:-]"
}
{
"error": "IDEMPOTENCY_IN_FLIGHT",
"message": "a request with this Idempotency-Key is still being processed"
}
{
"error": "IDEMPOTENCY_KEY_REUSED",
"message": "this Idempotency-Key was already used for a different request body"
}
{
"error": "INTERNAL_ERROR"
}
Example
curl -X DELETE http://127.0.0.1:3000/v1/admin/projects/acme/environments/production/flags/bf-banner/schedule/c4d5e6f7-a8b9-4c0d-9e1f-2a3b4c5d6e7f -H "Authorization: Bearer $FEATUREKIT_TOKEN"
Raise a change request
POST/v1/admin/projects/{project}/environments/{env}/flags/{flag}/requests
Auth: Personal access token or dashboard session, role reader or higher.
Proposes a change without applying it. Readers can raise one, which is how someone without write access asks for a change. A writer other than you then approves or rejects it.
Path parameters
| Name | Type | Description |
|---|---|---|
project | string | Project key. |
env | string | Environment key. |
flag | string | Flag key. |
Body
| Field | Type | Required | Description |
|---|---|---|---|
patch | object | yes | The same fields as PATCH a flag's configuration, without expectedVersion. |
comment | string | no | Why, for the reviewer. |
Responses
{
"id": "d5e6f7a8-b9c0-4d1e-8f2a-3b4c5d6e7f80",
"status": "pending"
}
{
"error": "NOT_FOUND",
"message": "no such flag in that environment"
}
Common errors (401, 403, 400, 409, 422, 413, 500)
{
"error": "MISSING_TOKEN",
"message": "an access token is required"
}
{
"error": "TOKEN_REJECTED",
"message": "access token rejected"
}
{
"error": "SESSION_REJECTED",
"message": "session expired or rejected"
}
{
"error": "CSRF_HEADER_REQUIRED",
"message": "x-featurekit-csrf is required for cookie auth"
}
{
"error": "INVALID_IDEMPOTENCY_KEY",
"message": "Idempotency-Key must be at most 200 characters of [A-Za-z0-9._:-]"
}
{
"error": "IDEMPOTENCY_IN_FLIGHT",
"message": "a request with this Idempotency-Key is still being processed"
}
{
"error": "IDEMPOTENCY_KEY_REUSED",
"message": "this Idempotency-Key was already used for a different request body"
}
{
"error": "INVALID_JSON",
"message": "request body is not valid JSON"
}
{
"error": "PAYLOAD_TOO_LARGE",
"message": "body exceeds 524288 bytes"
}
{
"error": "INTERNAL_ERROR"
}
Example
curl -X POST http://127.0.0.1:3000/v1/admin/projects/acme/environments/production/flags/new-checkout/requests \
-H "Authorization: Bearer $FEATUREKIT_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "patch": { "enabled": true }, "comment": "ready for 10% after QA sign-off" }'
List change requests
GET/v1/admin/projects/{project}/environments/{env}/flags/{flag}/requests
Auth: Personal access token or dashboard session, role reader or higher.
Path parameters
| Name | Type | Description |
|---|---|---|
project | string | Project key. |
env | string | Environment key. |
flag | string | Flag key. |
Responses
{
"requests": [
{
"id": "d5e6f7a8-b9c0-4d1e-8f2a-3b4c5d6e7f80",
"status": "pending",
"requestedBy": "5d1f0c2a-8b3e-4f6a-9c7d-2e1b0a9f8e7d",
"reviewedBy": null,
"createdAt": "2026-11-18T09:12:44.318Z"
}
]
}
{
"error": "NOT_FOUND",
"message": "no such flag in that environment"
}
Common errors (401, 500)
{
"error": "MISSING_TOKEN",
"message": "an access token is required"
}
{
"error": "TOKEN_REJECTED",
"message": "access token rejected"
}
{
"error": "SESSION_REJECTED",
"message": "session expired or rejected"
}
{
"error": "INTERNAL_ERROR"
}
Example
curl http://127.0.0.1:3000/v1/admin/projects/acme/environments/production/flags/new-checkout/requests -H "Authorization: Bearer $FEATUREKIT_TOKEN"
Approve a change request
POST/v1/admin/projects/{project}/environments/{env}/flags/{flag}/requests/{requestId}/approve
Auth: Personal access token or dashboard session, role writer or higher.
Applies the requested change and audits it as flag.change_request_approved. The person who raised it can't approve it.
Path parameters
| Name | Type | Description |
|---|---|---|
project | string | Project key. |
env | string | Environment key. |
flag | string | Flag key. |
requestId | string | From the list above. |
Responses
{
"applied": true,
"version": 416
}
{
"error": "NOT_FOUND",
"message": "no such change request"
}
{
"error": "CHANGE_REQUEST_REJECTED",
"message": "change request is already approved"
}
{
"error": "CHANGE_REQUEST_REJECTED",
"message": "a change request cannot be approved by the person who raised it"
}
{
"error": "CHANGE_REQUEST_REJECTED",
"message": "the requested change is no longer valid: …"
}
Common errors (401, 403, 400, 409, 422, 500)
{
"error": "MISSING_TOKEN",
"message": "an access token is required"
}
{
"error": "TOKEN_REJECTED",
"message": "access token rejected"
}
{
"error": "SESSION_REJECTED",
"message": "session expired or rejected"
}
{
"error": "CSRF_HEADER_REQUIRED",
"message": "x-featurekit-csrf is required for cookie auth"
}
{
"error": "INSUFFICIENT_ROLE",
"message": "requires writer or higher"
}
{
"error": "INVALID_IDEMPOTENCY_KEY",
"message": "Idempotency-Key must be at most 200 characters of [A-Za-z0-9._:-]"
}
{
"error": "IDEMPOTENCY_IN_FLIGHT",
"message": "a request with this Idempotency-Key is still being processed"
}
{
"error": "IDEMPOTENCY_KEY_REUSED",
"message": "this Idempotency-Key was already used for a different request body"
}
{
"error": "INTERNAL_ERROR"
}
Example
curl -X POST http://127.0.0.1:3000/v1/admin/projects/acme/environments/production/flags/new-checkout/requests/d5e6f7a8-b9c0-4d1e-8f2a-3b4c5d6e7f80/approve -H "Authorization: Bearer $FEATUREKIT_TOKEN"
Reject a change request
POST/v1/admin/projects/{project}/environments/{env}/flags/{flag}/requests/{requestId}/reject
Auth: Personal access token or dashboard session, role writer or higher.
Path parameters
| Name | Type | Description |
|---|---|---|
project | string | Project key. |
env | string | Environment key. |
flag | string | Flag key. |
requestId | string | From the list above. |
Body
| Field | Type | Required | Description |
|---|---|---|---|
comment | string | no | Why, for the requester. |
Responses
{
"status": "rejected"
}
{
"error": "NOT_FOUND",
"message": "no such pending change request"
}
Common errors (401, 403, 400, 409, 422, 413, 500)
{
"error": "MISSING_TOKEN",
"message": "an access token is required"
}
{
"error": "TOKEN_REJECTED",
"message": "access token rejected"
}
{
"error": "SESSION_REJECTED",
"message": "session expired or rejected"
}
{
"error": "CSRF_HEADER_REQUIRED",
"message": "x-featurekit-csrf is required for cookie auth"
}
{
"error": "INSUFFICIENT_ROLE",
"message": "requires writer or higher"
}
{
"error": "INVALID_IDEMPOTENCY_KEY",
"message": "Idempotency-Key must be at most 200 characters of [A-Za-z0-9._:-]"
}
{
"error": "IDEMPOTENCY_IN_FLIGHT",
"message": "a request with this Idempotency-Key is still being processed"
}
{
"error": "IDEMPOTENCY_KEY_REUSED",
"message": "this Idempotency-Key was already used for a different request body"
}
{
"error": "INVALID_JSON",
"message": "request body is not valid JSON"
}
{
"error": "PAYLOAD_TOO_LARGE",
"message": "body exceeds 4096 bytes"
}
{
"error": "INTERNAL_ERROR"
}
Example
curl -X POST http://127.0.0.1:3000/v1/admin/projects/acme/environments/production/flags/new-checkout/requests/d5e6f7a8-b9c0-4d1e-8f2a-3b4c5d6e7f80/reject \
-H "Authorization: Bearer $FEATUREKIT_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "comment": "wait for the payments fix" }'