Releases
Plan a change for later, send it for review, and let the server apply it on time.
Concepts#
What a release is#
A release is a plan to change one flag in one environment. Each step sets an explicit value (enabled, rolloutPercentage or both) at a time, so applying a step twice is harmless. The kind follows from the steps and is set by the server: one step due now is a change, one step later is scheduled, and several steps are a rollout.
All times are stored and returned in UTC. timezone is kept only so the console can show the proposer's local time.
Step states#
| Status | Description |
|---|---|
| pending | Waiting for its time. |
| applied | Done. appliedAt is set. |
| failed | Gave up. error says why. A refusal (kill switch on, permission gone, flag archived) fails at once; an unexpected fault is retried up to 3 times with a growing delay, and attempts counts them. A failed step fails the release and notifies people. |
| skipped | Not run because an earlier step failed. |
| cancelled | Closed when the release was cancelled, rejected or expired. |
Lifecycle#
A release changes one flag in one environment, either in a few timed steps or as a staged rollout. Where it starts depends on who proposes it.
- If the environment requires approval, or the proposer cannot review releases (developers), it starts as
pending_approval. A reviewer approves it, moving it toscheduled, or rejects it. - Otherwise it starts
scheduled. The server runs it when due, moving throughrunningtocompletedorfailed. - Only the person who proposed a release can cancel it, while it is pending or scheduled. Anyone else gets
403; reviewers reject instead. - Unreviewed requests expire after 72 hours and end as
cancelledwith a note. - Steps run with the authority of the reviewer who approved the release, or of the proposer when no approval was needed. If that person has left the organization, the step fails.
- A step whose time is already in the past runs as soon as the release is allowed to run. Steps must be in time order and no more than a year ahead.
Reviewing your own release
ALLOW_SELF_APPROVAL=true). The reviewer's own authority is what applies the changes, so they must be allowed to change that environment: a release manager can approve production steps a developer proposed.Who needs what to propose
releases.create. When the release does not need approval, you also need the permission each step requires (toggling or rolling out, which developers lack in production). When it does need approval, the base permission is enough because the reviewer applies it.Endpoints#
Propose a release#
/api/releases{
"flagId": "FLAG_ID",
"environment": "staging",
"title": "Promo banner for the weekend",
"steps": [
{ "runAt": "2026-10-10T08:00:00Z", "changes": { "enabled": true } },
{ "runAt": "2026-10-12T08:00:00Z", "changes": { "enabled": false } }
]
}The planner checks times and the allowed changes and answers 400 with what to fix.
Authorization
releases.create
Body
flagIdstringRequiredThe flag to change.environmentstringRequiredThe environment name, as configured on the flag.titlestringRequiredA short reason, up to 200 characters. Reviewers read it.reviewerIdstringOptional, up to 100 characters. A release manager or admin (a user id) you want to review it. Only used when the release needs approval. They are emailed on their own and the release shows who was asked, but every reviewer can still approve or reject it. You cannot name yourself unless self-approval is on.timezonestringA time zone name, such as Africa/Lagos. Up to 64 characters. Display only.stepsarrayUp to 20 of{ runAt, changes: { enabled?, rolloutPercentage? } }, each applied at its time.runAtis an ISO date-time. Each step must change at least one field;rolloutPercentageis a whole number from 0 to 100. Use this orrollout. If you send both,rolloutis used.rolloutobjectA staged rollout the server expands into steps, one per percentage. Needs the fields below.rollout.startAtISO date-timeRequiredWhen the first stage runs.rollout.percentagesinteger[]Required2 to 20 whole numbers from 0 to 100, each larger than the one before.rollout.intervalMinutesnumberRequiredMinutes between stages: 1 up to 20160 (14 days).rollout.enableFirstbooleanAlso turn the flag on in the first stage, so the rollout begins when it starts.
Errors
- 400Invalid JSON (
Invalid JSON body), a missingflagId,environmentortitle, a title over 200 characters, neitherstepsnorrollout(“Add at least one step”), more than 20 steps, a step time that is not valid, out of order or more than a year ahead, a percentage outside 0 to 100, stages that do not grow, or “This flag is archived”. - 400The
reviewerIdis you (“Ask someone else to review your release”) or is not a release manager or admin of this organization (“Choose a release manager or admin from this organization”). - 401No session, or it has expired.
- 403Your role lacks
releases.create, or the release does not need approval and you cannot apply its steps (for example a developer toggling in production). Also returned when a write comes from another origin, or the organization is deactivated (ORG_DEACTIVATED). - 404
Flag not found, orEnvironment “qa” is not configured for this flag.
curl -s -b "auth_session=$SESSION" \
-X POST "$FLAGSWIFT_URL/api/releases" \
-H "Content-Type: application/json" \
-d '{
"flagId": "FLAG_ID",
"environment": "production",
"title": "Checkout redesign, ramp to everyone",
"reviewerId": "USER_ID_OF_REVIEWER",
"timezone": "Africa/Lagos",
"rollout": {
"startAt": "2026-10-05T09:00:00Z",
"percentages": [5, 25, 50, 100],
"intervalMinutes": 120,
"enableFirst": true
}
}'{
"status": "success",
"message": "Release proposed",
"data": {
"id": "3f6c1d0a-5b7e-4c92-8a1f-0d2e9b64a7c1",
"projectId": "PROJECT_ID",
"flagId": "FLAG_ID",
"flagKey": "checkout-v2",
"flagName": "Checkout v2",
"environment": "production",
"title": "Checkout redesign, ramp to everyone",
"kind": "rollout",
"status": "pending_approval",
"steps": [
{ "index": 0, "runAt": "2026-10-05T09:00:00.000Z", "changes": { "rolloutPercentage": 5, "enabled": true }, "status": "pending", "attempts": 0 },
{ "index": 1, "runAt": "2026-10-05T11:00:00.000Z", "changes": { "rolloutPercentage": 25 }, "status": "pending", "attempts": 0 },
{ "index": 2, "runAt": "2026-10-05T13:00:00.000Z", "changes": { "rolloutPercentage": 50 }, "status": "pending", "attempts": 0 },
{ "index": 3, "runAt": "2026-10-05T15:00:00.000Z", "changes": { "rolloutPercentage": 100 }, "status": "pending", "attempts": 0 }
],
"nextRunAt": "2026-10-05T09:00:00.000Z",
"requiresApproval": true,
"timezone": "Africa/Lagos",
"requestedByEmail": "dev@example.com",
"assignedReviewerEmail": "rm@example.com",
"assignedToMe": false,
"reviewedByEmail": null,
"reviewNote": null,
"reviewedAt": null,
"completedAt": null,
"createdAt": "2026-10-03T08:12:44.000Z",
"mine": true
}
}List releases#
/api/releasesNewest first, by creation time. Besides items and pagination the reply carries counts: how many releases in the whole organization are waiting for approval and how many are scheduled, regardless of your filters. It is what drives the badges in the console.
Authorization
releases.read
Query parameters
statusstringOne ofpending_approval,scheduled,running,completed,failed,rejected,cancelled, oropenfor everything not finished (pending_approval,scheduledandrunning).flagIdstringOnly this flag's releases.projectIdstringOnly releases for flags in this project.proposerstringOnly releases proposed by this member. Use the member'suserIdfrom the members list.from, toISO date-timeReleases created fromfrom(included) up toto(not included). Either may be left out.pageintegerFrom 1. Default 1.limitinteger1 to 100. Default 25.
Errors
- 400A
statusthat is not in the list, afromortothat is not a date, or apageorlimitout of range. - 401No session, or it has expired.
- 403Your role lacks
releases.read. Also returned when a write comes from another origin, or the organization is deactivated (ORG_DEACTIVATED).
curl -s -b "auth_session=$SESSION" \
"$FLAGSWIFT_URL/api/releases?status=open&projectId=PROJECT_ID&page=1&limit=25"{
"status": "success",
"message": "OK",
"data": {
"items": [
{
"id": "3f6c1d0a-5b7e-4c92-8a1f-0d2e9b64a7c1",
"flagKey": "checkout-v2",
"environment": "production",
"title": "Checkout redesign, ramp to everyone",
"kind": "rollout",
"status": "pending_approval",
"nextRunAt": "2026-10-05T09:00:00.000Z",
"requiresApproval": true,
"mine": false,
"assignedToMe": true,
"...": "same fields as Get a release"
}
],
"pagination": { "page": 1, "limit": 25, "total": 1, "totalPages": 1, "hasNext": false, "hasPrev": false },
"counts": { "pending_approval": 1, "scheduled": 3 }
}
}Get a release#
/api/releases/{id}mine says whether you proposed it and assignedToMe whether you were the reviewer asked by name. Times are ISO strings in UTC.
Authorization
releases.read
Path parameters
idstring (uuid)RequiredThe release id.
Errors
- 401No session, or it has expired.
- 403Your role lacks
releases.read. Also returned when a write comes from another origin, or the organization is deactivated (ORG_DEACTIVATED). - 404“Release not found”: no such release in your organization.
curl -s -b "auth_session=$SESSION" "$FLAGSWIFT_URL/api/releases/RELEASE_ID"{
"status": "success",
"message": "OK",
"data": {
"id": "3f6c1d0a-5b7e-4c92-8a1f-0d2e9b64a7c1",
"projectId": "PROJECT_ID",
"flagId": "FLAG_ID",
"flagKey": "checkout-v2",
"flagName": "Checkout v2",
"environment": "production",
"title": "Checkout redesign, ramp to everyone",
"kind": "rollout",
"status": "completed",
"steps": [
{ "index": 0, "runAt": "2026-10-05T09:00:00.000Z", "changes": { "rolloutPercentage": 5, "enabled": true }, "status": "applied", "attempts": 1, "appliedAt": "2026-10-05T09:00:03.000Z" },
{ "index": 1, "runAt": "2026-10-05T11:00:00.000Z", "changes": { "rolloutPercentage": 100 }, "status": "applied", "attempts": 1, "appliedAt": "2026-10-05T11:00:02.000Z" }
],
"nextRunAt": null,
"requiresApproval": true,
"timezone": "Africa/Lagos",
"requestedByEmail": "dev@example.com",
"assignedReviewerEmail": null,
"assignedToMe": false,
"reviewedByEmail": "rm@example.com",
"reviewNote": null,
"reviewedAt": "2026-10-03T09:30:10.000Z",
"completedAt": "2026-10-05T11:00:02.000Z",
"createdAt": "2026-10-03T08:12:44.000Z",
"mine": false
}
}Approve#
/api/releases/{id}/approveOptional body { "note": "..." }, up to 500 characters; a note that is too long is silently dropped, not refused. The body may be left out entirely. If it is already due it runs straight away. A release that is no longer waiting answers 409.
Authorization
releases.review
Path parameters
idstring (uuid)RequiredThe release id.
Body (optional)
notestringTrimmed, up to 500 characters. The body may be left out. A body that fails validation (such as a note over 500 characters, or invalid JSON) is ignored rather than rejected: the release is approved without a note.
Errors
- 401No session, or it has expired.
- 403You lack
releases.review, you proposed it (“Ask someone else to approve your release”), or you may not change that environment, for example a role that cannot toggle in production. Also returned when a write comes from another origin, or the organization is deactivated (ORG_DEACTIVATED). - 404No such release in your organization.
- 409“This release is no longer waiting for approval”: someone else decided it, it was cancelled, or it expired.
curl -s -b "auth_session=$SESSION" \
-X POST "$FLAGSWIFT_URL/api/releases/RELEASE_ID/approve" \
-H "Content-Type: application/json" \
-d '{ "note": "Looks good. Watch the error rate at 25%." }'{
"status": "success",
"message": "Release approved",
"data": {
"id": "3f6c1d0a-5b7e-4c92-8a1f-0d2e9b64a7c1",
"projectId": "PROJECT_ID",
"flagId": "FLAG_ID",
"flagKey": "checkout-v2",
"flagName": "Checkout v2",
"environment": "production",
"title": "Checkout redesign, ramp to everyone",
"kind": "rollout",
"status": "scheduled",
"steps": [ "... as above ..." ],
"nextRunAt": "2026-10-05T09:00:00.000Z",
"requiresApproval": true,
"timezone": "Africa/Lagos",
"requestedByEmail": "dev@example.com",
"assignedReviewerEmail": "rm@example.com",
"assignedToMe": true,
"reviewedByEmail": "rm@example.com",
"reviewNote": "Looks good. Watch the error rate at 25%.",
"reviewedAt": "2026-10-03T09:30:10.000Z",
"completedAt": null,
"createdAt": "2026-10-03T08:12:44.000Z",
"mine": false
}
}Reject#
/api/releases/{id}/rejectBody { "note": "..." } is required here, up to 500 characters: the reason, which the proposer sees. A missing reason is a 400.
Authorization
releases.review
Path parameters
idstring (uuid)RequiredThe release id.
Body
notestringRequiredThe reason, trimmed, 1 to 500 characters. The proposer sees it.
Errors
- 400“Give a reason for rejecting this release”, or a note over 500 characters, or invalid JSON.
- 401No session, or it has expired.
- 403You lack
releases.review. Also returned when a write comes from another origin, or the organization is deactivated (ORG_DEACTIVATED). - 404No such release in your organization.
- 409“This release is no longer waiting for approval”.
curl -s -b "auth_session=$SESSION" \
-X POST "$FLAGSWIFT_URL/api/releases/RELEASE_ID/reject" \
-H "Content-Type: application/json" \
-d '{ "note": "Hold until the payments incident is closed." }'{
"status": "success",
"message": "Release rejected",
"data": {
"id": "3f6c1d0a-5b7e-4c92-8a1f-0d2e9b64a7c1",
"status": "rejected",
"nextRunAt": null,
"reviewedByEmail": "rm@example.com",
"reviewNote": "Hold until the payments incident is closed.",
"reviewedAt": "2026-10-03T09:41:00.000Z",
"completedAt": "2026-10-03T09:41:00.000Z",
"...": "other fields as in Get a release; every pending step is now cancelled"
}
}Cancel#
/api/releases/{id}/cancelStops a release that has not started running, whether it is waiting for review or scheduled. Only the proposer may do it; reviewers use reject. No body is needed, and it needs only releases.read because the proposer check is what decides.
Authorization
releases.read
Path parameters
idstring (uuid)RequiredThe release id.
Errors
- 401No session, or it has expired.
- 403“Only the person who proposed this release can cancel it”. Reviewers use reject. Also returned when a write comes from another origin, or the organization is deactivated (
ORG_DEACTIVATED). - 404No such release in your organization.
- 409“This release is running or already finished”.
curl -s -b "auth_session=$SESSION" -X POST "$FLAGSWIFT_URL/api/releases/RELEASE_ID/cancel"{
"status": "success",
"message": "Release cancelled",
"data": {
"id": "3f6c1d0a-5b7e-4c92-8a1f-0d2e9b64a7c1",
"status": "cancelled",
"nextRunAt": null,
"completedAt": "2026-10-03T10:02:15.000Z",
"mine": true,
"...": "other fields as in Get a release; every pending step is now cancelled"
}
}Common patterns#
Propose, review, and watch it run#
A developer proposes a production rollout and asks a release manager by name. The release manager approves, and anyone can poll until it finishes.
# 1. Developer proposes (answers 201 with status "pending_approval"; keep data.id)
curl -s -b "auth_session=$DEV_SESSION" -X POST "$FLAGSWIFT_URL/api/releases" \
-H "Content-Type: application/json" \
-d '{"flagId":"FLAG_ID","environment":"production","title":"Ramp checkout-v2","reviewerId":"RM_USER_ID","rollout":{"startAt":"2026-10-05T09:00:00Z","percentages":[5,25,100],"intervalMinutes":60,"enableFirst":true}}'
# 2. Release manager sees what is waiting for them
curl -s -b "auth_session=$RM_SESSION" "$FLAGSWIFT_URL/api/releases?status=pending_approval"
# 3. ...and approves it
curl -s -b "auth_session=$RM_SESSION" -X POST "$FLAGSWIFT_URL/api/releases/RELEASE_ID/approve" \
-H "Content-Type: application/json" -d '{"note":"Go"}'
# 4. Check progress: steps[].status moves pending -> applied, then status becomes completed
curl -s -b "auth_session=$DEV_SESSION" "$FLAGSWIFT_URL/api/releases/RELEASE_ID"What have I proposed that is still open?#
curl -s -b "auth_session=$SESSION" \
"$FLAGSWIFT_URL/api/releases?status=open&proposer=MY_USER_ID&limit=100"Use cancel on any of them that you no longer want. A release that is already running cannot be cancelled and answers 409.