Skip to content
FlagSwiftDocs

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#

Values for steps[].status
StatusDescription
pendingWaiting for its time.
appliedDone. appliedAt is set.
failedGave 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.
skippedNot run because an earlier step failed.
cancelledClosed 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 to scheduled, or rejects it.
  • Otherwise it starts scheduled. The server runs it when due, moving through running to completed or failed.
  • 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 cancelled with 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

A reviewer cannot approve what they proposed, unless the organization allows self-approval (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

Proposing needs 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#

POST/api/releases
Explicit steps instead: turn on, later turn off
{
  "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

  • flagIdstringRequired

    The flag to change.
  • environmentstringRequired

    The environment name, as configured on the flag.
  • titlestringRequired

    A short reason, up to 200 characters. Reviewers read it.
  • reviewerIdstring

    Optional, 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.
  • timezonestring

    A time zone name, such as Africa/Lagos. Up to 64 characters. Display only.
  • stepsarray

    Up to 20 of { runAt, changes: { enabled?, rolloutPercentage? } }, each applied at its time. runAt is an ISO date-time. Each step must change at least one field; rolloutPercentage is a whole number from 0 to 100. Use this or rollout. If you send both, rollout is used.
  • rolloutobject

    A staged rollout the server expands into steps, one per percentage. Needs the fields below.
  • rollout.startAtISO date-timeRequired

    When the first stage runs.
  • rollout.percentagesinteger[]Required

    2 to 20 whole numbers from 0 to 100, each larger than the one before.
  • rollout.intervalMinutesnumberRequired

    Minutes between stages: 1 up to 20160 (14 days).
  • rollout.enableFirstboolean

    Also turn the flag on in the first stage, so the rollout begins when it starts.

Errors

  • 400Invalid JSON (Invalid JSON body), a missing flagId, environment or title, a title over 200 characters, neither steps nor rollout (“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 reviewerId is 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).
  • 404Flag not found, or Environment “qa” is not configured for this flag.
Request
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
    }
  }'
201Created
{
  "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#

GET/api/releases

Newest 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

  • statusstring

    One of pending_approval, scheduled, running, completed, failed, rejected, cancelled, or open for everything not finished (pending_approval, scheduled and running).
  • flagIdstring

    Only this flag's releases.
  • projectIdstring

    Only releases for flags in this project.
  • proposerstring

    Only releases proposed by this member. Use the member's userId from the members list.
  • from, toISO date-time

    Releases created from from (included) up to to (not included). Either may be left out.
  • pageinteger

    From 1. Default 1.
  • limitinteger

    1 to 100. Default 25.

Errors

  • 400A status that is not in the list, a from or to that is not a date, or a page or limit out 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).
Request
curl -s -b "auth_session=$SESSION" \
  "$FLAGSWIFT_URL/api/releases?status=open&projectId=PROJECT_ID&page=1&limit=25"
200OK
{
  "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#

GET/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)Required

    The 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.
Request
curl -s -b "auth_session=$SESSION" "$FLAGSWIFT_URL/api/releases/RELEASE_ID"
200OK
{
  "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#

POST/api/releases/{id}/approve

Optional 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)Required

    The release id.

Body (optional)

  • notestring

    Trimmed, 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.
Request
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%." }'
200OK
{
  "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#

POST/api/releases/{id}/reject

Body { "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)Required

    The release id.

Body

  • notestringRequired

    The 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”.
Request
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." }'
200OK
{
  "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#

POST/api/releases/{id}/cancel

Stops 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)Required

    The 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”.
Request
curl -s -b "auth_session=$SESSION" -X POST "$FLAGSWIFT_URL/api/releases/RELEASE_ID/cancel"
200OK
{
  "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.

bash
# 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?#

bash
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.