Star
API reference

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

NameTypeDescription
projectstringProject key.
envstringEnvironment key.
flagstringFlag key.

Body

FieldTypeRequiredDescription
patchobjectyesThe same fields as PATCH a flag's configuration, without expectedVersion.
executeAtstringyesISO 8601 date-time in the future.
commentstringno

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

NameTypeDescription
projectstringProject key.
envstringEnvironment key.
flagstringFlag 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

NameTypeDescription
projectstringProject key.
envstringEnvironment key.
flagstringFlag key.
scheduleIdstringFrom 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

NameTypeDescription
projectstringProject key.
envstringEnvironment key.
flagstringFlag key.

Body

FieldTypeRequiredDescription
patchobjectyesThe same fields as PATCH a flag's configuration, without expectedVersion.
commentstringnoWhy, 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

NameTypeDescription
projectstringProject key.
envstringEnvironment key.
flagstringFlag 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

NameTypeDescription
projectstringProject key.
envstringEnvironment key.
flagstringFlag key.
requestIdstringFrom 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

NameTypeDescription
projectstringProject key.
envstringEnvironment key.
flagstringFlag key.
requestIdstringFrom the list above.

Body

FieldTypeRequiredDescription
commentstringnoWhy, 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" }'