Lifecycle and code references
Ownership and dates on flags, stale and expiry status, removal advice, bulk archive, and where code uses each flag.
Concepts#
Lifecycle is computed, not stored#
Only four things are stored on a flag: its owner, expectedRemovalAt, expiresAt and permanent. Everything else on this page (the status, the findings, the removal advice) is worked out each time you ask from those fields, the flag's configuration, the evaluation history and the latest code scan. The same flag read tomorrow can be stale.
| status | Description |
|---|---|
| active | Nothing needs doing. |
| stale | At least 14 days old and, for 14 days or more, off everywhere, on for everyone everywhere, or not evaluated. |
| expiring | Expires within 14 days. |
| expired | The expiry date has passed. Nothing is switched off. |
| removal_due | The expected removal date has passed. |
| scheduled_removal | A removal date is set and still ahead. |
| permanent | Marked permanent, so it is never reported stale. |
| archived | Archived. |
When several apply, the most urgent wins in this order: archived, expired, removal due, expiring, permanent, stale, scheduled removal, active.
Removal advice#
Each flag carries a removal.verdict: blocked (code still uses it, or another flag depends on it; always wins), safe (quiet for 30 days or more and a code scan found no references), potentially_safe (quiet for 30 days or more but no repository has reported, so code is unchecked), or not_ready (still in use, too recent, or permanent).
Examples use $FLAGSWIFT_URL for your server and $SESSION for the value of the auth_session cookie; see Dashboard API.
Lifecycle fields on a flag#
Create and edit a flag with these optional fields (POST /api/flags and PATCH /api/flags/{id}). The flag object returns them too. Changes are written to the audit log as flag.updated.
| Field | Type | Description |
|---|---|---|
| owner | email | null | An email address of up to 254 characters; it is stored lower case. Defaults to the creator. null or an empty string clears it, which falls back to the creator. |
| expectedRemovalAt | ISO date | null | When the flag should be removed from code. Any date the server can parse; null clears it. |
| expiresAt | ISO date | null | After this the flag shows as expired. Nothing is switched off. |
| permanent | boolean | A permanent flag cannot have either date, checked against the flag as it will be after your change. Setting both is a 400 (A permanent flag cannot have an expiration or expected removal date. Clear the dates first.). |
curl -s -X PATCH "$FLAGSWIFT_URL/api/flags/7c1f0b2e-5a3d-4e8f-9a61-2b4d6c8e0f13" \
-b "auth_session=$SESSION" \
-H "Content-Type: application/json" \
-d '{ "owner": "dana@example.com", "expiresAt": "2026-12-01T00:00:00.000Z", "expectedRemovalAt": "2026-12-15T00:00:00.000Z" }'Lifecycle status#
List a project's flags by lifecycle#
/api/lifecycleReturns the page of items, counts for every filter (so you can show badges without extra calls), pagination, owners, collectingSince (where evaluation history starts), codeScan and the thresholds in days. There is no sort parameter: the most urgent come first, then the longest in their current state.
{
"id": "7c1f0b2e-5a3d-4e8f-9a61-2b4d6c8e0f13",
"name": "checkout-v2",
"displayName": "Checkout v2",
"type": "boolean",
"projectId": "b3a8d9c4-1e72-4f05-8c3b-6a9d0e2f4b71",
"status": "stale",
"owner": "dana@example.com",
"permanent": false,
"createdAt": "2026-01-04T09:12:00.000Z",
"lastModifiedAt": "2026-06-03T14:00:00.000Z",
"lastEvaluatedAt": null,
"evaluationsTracked": true,
"expectedRemovalAt": null,
"expiresAt": null,
"archivedAt": null,
"ageDays": 271,
"state": "off",
"stateDays": 120,
"findings": [
{
"code": "off_everywhere",
"message": "Off in every environment for 120 days."
}
],
"removal": {
"verdict": "potentially_safe",
"message": "Flag has been OFF for 120 days. Potentially safe to remove."
},
"codeReferences": {
"count": 0,
"scanned": false
}
}stateis how the flag is configured everywhere:off,on(enabled at 100% with no emergency stop) ormixed.stateDayscounts how long it has stayed that way, and is 0 when mixed.lastEvaluatedAtis null when there is no evaluation on record. CheckevaluationsTracked: false means history was not collected, so null means unknown rather than never.findings[].codeis one ofunused,off_everywhere,fully_rolled_out,expired,expiring_soon,removal_due,referenced_in_codeandprerequisite.
Authorization
flags.read
Query parameters
projectIdstringRequiredThe project.filterall | attention | stale | expiring | expired | removal_due | permanent | archivedDefault all, which leaves out archived flags. attention is stale, expiring, expired and removal due together. permanent leaves out archived flags.ownerstringOnly flags with this owner (exact match, not case sensitive). Up to 254 characters.searchstringMatches key and display name. Up to 100 characters.pageintegerFrom 1. Default 1.limitinteger1 to 100. Default 25.
Errors
- 400
Project is required,filternot one of the listed values, orlimitabove 100. - 401No valid session. Sign in again and resend the
auth_sessioncookie. - 403Your role lacks
flags.read. Also returned when a write comes from another origin, or the organization is deactivated (ORG_DEACTIVATED). - 404
Project not found.
curl -s -b "auth_session=$SESSION" \
"$FLAGSWIFT_URL/api/lifecycle?projectId=b3a8d9c4-1e72-4f05-8c3b-6a9d0e2f4b71&filter=attention&limit=25"{
"status": "success",
"message": "OK",
"data": {
"projectId": "b3a8d9c4-1e72-4f05-8c3b-6a9d0e2f4b71",
"items": [
{
"id": "7c1f0b2e-5a3d-4e8f-9a61-2b4d6c8e0f13",
"name": "checkout-v2",
"displayName": "Checkout v2",
"type": "boolean",
"projectId": "b3a8d9c4-1e72-4f05-8c3b-6a9d0e2f4b71",
"status": "stale",
"owner": "dana@example.com",
"permanent": false,
"createdAt": "2026-01-04T09:12:00.000Z",
"lastModifiedAt": "2026-06-03T14:00:00.000Z",
"lastEvaluatedAt": null,
"evaluationsTracked": true,
"expectedRemovalAt": null,
"expiresAt": null,
"archivedAt": null,
"ageDays": 271,
"state": "off",
"stateDays": 120,
"findings": [
{
"code": "off_everywhere",
"message": "Off in every environment for 120 days."
}
],
"removal": {
"verdict": "potentially_safe",
"message": "Flag has been OFF for 120 days. Potentially safe to remove."
},
"codeReferences": {
"count": 0,
"scanned": false
}
}
],
"counts": {
"all": 42,
"attention": 5,
"stale": 3,
"expiring": 1,
"expired": 1,
"removal_due": 0,
"permanent": 4,
"archived": 7
},
"pagination": {
"page": 1,
"limit": 25,
"total": 5,
"totalPages": 1,
"hasNext": false,
"hasPrev": false
},
"collectingSince": "2026-05-20T00:00:00.000Z",
"codeScan": {
"scanned": true,
"lastScannedAt": "2026-10-02T21:10:00.000Z",
"repositories": [
"acme/web"
]
},
"owners": [
"dana@example.com",
"lee@example.com"
],
"thresholds": {
"staleAfterDays": 14,
"safeAfterDays": 30,
"expiringSoonDays": 14
}
}
}One flag's lifecycle#
/api/flags/{id}/lifecycleReturns one item as above, without the flag identity fields (id, name, displayName, type, projectId).
Authorization
flags.read
Path parameters
idstring (uuid)RequiredThe flag id (not its key).
Errors
- 401No valid session. Sign in again and resend the
auth_sessioncookie. - 403Your role lacks
flags.read. Also returned when a write comes from another origin, or the organization is deactivated (ORG_DEACTIVATED). - 404
Flag not found.
curl -s -b "auth_session=$SESSION" \
"$FLAGSWIFT_URL/api/flags/7c1f0b2e-5a3d-4e8f-9a61-2b4d6c8e0f13/lifecycle"{
"status": "success",
"message": "OK",
"data": {
"status": "stale",
"owner": "dana@example.com",
"permanent": false,
"createdAt": "2026-01-04T09:12:00.000Z",
"lastModifiedAt": "2026-06-03T14:00:00.000Z",
"lastEvaluatedAt": null,
"evaluationsTracked": true,
"expectedRemovalAt": null,
"expiresAt": null,
"archivedAt": null,
"ageDays": 271,
"state": "off",
"stateDays": 120,
"findings": [
{
"code": "off_everywhere",
"message": "Off in every environment for 120 days."
}
],
"removal": {
"verdict": "potentially_safe",
"message": "Flag has been OFF for 120 days. Potentially safe to remove."
},
"codeReferences": {
"count": 0,
"scanned": false
}
}
}Archive several flags#
/api/lifecycle/archiveUp to 50 ids; repeats are ignored. Each is attempted on its own, in order, so a flag that cannot be archived (another flag needs it, it is already archived, it does not exist) does not stop the rest. The call returns 200 even when some fail: read { results, archived, failed }, where each result is { id, ok, error? }. The message is “Flags archived” when all succeed.
Authorization
flags.archive
Body
idsstring[]RequiredFlag ids, 1 to 50 (the limit is checked on the array as sent). Repeats are ignored.
Errors
- 400Malformed JSON,
Choose at least one flag, or more than 50 ids (Archive up to 50 flags at a time). - 401No valid session. Sign in again and resend the
auth_sessioncookie. - 403Your role lacks
flags.archive. Also returned when a write comes from another origin, or the organization is deactivated (ORG_DEACTIVATED).
curl -s -X POST "$FLAGSWIFT_URL/api/lifecycle/archive" \
-b "auth_session=$SESSION" \
-H "Content-Type: application/json" \
-d '{ "ids": ["7c1f0b2e-5a3d-4e8f-9a61-2b4d6c8e0f13", "e1d2c3b4-a596-4877-8695-a4b3c2d1e0f9"] }'{
"status": "success",
"message": "Some flags could not be archived",
"data": {
"results": [
{
"id": "7c1f0b2e-5a3d-4e8f-9a61-2b4d6c8e0f13",
"ok": true
},
{
"id": "e1d2c3b4-a596-4877-8695-a4b3c2d1e0f9",
"ok": false,
"error": "Cannot archive \"Express checkout\": it is a prerequisite of Upsell banner (production). Remove the dependency first."
}
],
"archived": 1,
"failed": 1
}
}Code references#
Where a flag is used#
/api/flags/{id}/code-referencesReturns { flagKey, scanned, total, lastScannedAt, repositories }. Each repository has its branch, commit, scannedAt and locations as { path, line }, repositories in name order. scanned is false until any repository has reported for the project, so zero references can be told apart from not scanned.
Authorization
flags.read
Path parameters
idstring (uuid)RequiredThe flag id (not its key).
Errors
- 401No valid session. Sign in again and resend the
auth_sessioncookie. - 403Your role lacks
flags.read. Also returned when a write comes from another origin, or the organization is deactivated (ORG_DEACTIVATED). - 404
Flag not found.
curl -s -b "auth_session=$SESSION" \
"$FLAGSWIFT_URL/api/flags/7c1f0b2e-5a3d-4e8f-9a61-2b4d6c8e0f13/code-references"{
"status": "success",
"message": "OK",
"data": {
"flagKey": "checkout-v2",
"scanned": true,
"total": 2,
"lastScannedAt": "2026-10-02T21:10:00.000Z",
"repositories": [
{
"repository": "acme/web",
"branch": "main",
"commit": "9f2c1ab",
"scannedAt": "2026-10-02T21:10:00.000Z",
"locations": [
{
"path": "src/checkout/Cart.tsx",
"line": 42
},
{
"path": "src/checkout/useCheckout.ts",
"line": 17
}
]
}
]
}
}Delete a flag that code still uses#
/api/flags/{id}?force=trueDeleting needs the flag to be archived first. Without force, deleting an archived flag that code still references is a 400. The key-authenticated report endpoints are on the Evaluation API page.
Authorization
flags.delete
Path parameters
idstring (uuid)RequiredThe flag id (not its key).
Query parameters
forcebooleanDefault false. true deletes the flag even though code references still mention it.
Errors
- 400The flag is not archived (
Archive the flag before deleting it permanently), or, withoutforce, code still references it (This flag is still used in 2 places in code. Remove those first, or delete it anyway.). - 401No valid session. Sign in again and resend the
auth_sessioncookie. - 403Your role lacks
flags.delete. Also returned when a write comes from another origin, or the organization is deactivated (ORG_DEACTIVATED). - 404
Flag not found.
curl -s -X DELETE -b "auth_session=$SESSION" \
"$FLAGSWIFT_URL/api/flags/7c1f0b2e-5a3d-4e8f-9a61-2b4d6c8e0f13?force=true"{
"status": "success",
"message": "Flag deleted successfully",
"data": null
}Reporting from CI
code_references:write scope. The bundled tools/flagswift-scan.mjs does it for you; see Flag lifecycle and cleanup.Common patterns#
Weekly cleanup#
List what needs attention, read the removal advice, archive the clear cases in one call, then delete them later once code is clean. Only flags whose removal.verdict is safe or potentially_safe are candidates; skip blocked and not_ready.
# 1. Stale flags, most urgent first. Each item carries removal.verdict.
curl -s -b "auth_session=$SESSION" \
"$FLAGSWIFT_URL/api/lifecycle?projectId=b3a8d9c4-1e72-4f05-8c3b-6a9d0e2f4b71&filter=stale&limit=100"
# 2. Archive the ones you picked (up to 50 ids per call). Check results[].ok.
curl -s -X POST "$FLAGSWIFT_URL/api/lifecycle/archive" \
-b "auth_session=$SESSION" -H "Content-Type: application/json" \
-d '{ "ids": ["7c1f0b2e-5a3d-4e8f-9a61-2b4d6c8e0f13"] }'
# 3. After the code is cleaned up, delete a flag for good.
curl -s -X DELETE -b "auth_session=$SESSION" \
"$FLAGSWIFT_URL/api/flags/7c1f0b2e-5a3d-4e8f-9a61-2b4d6c8e0f13"Hand a flag to someone else#
Change the owner with PATCH /api/flags/{id} and { "owner": "lee@example.com" }, then filter the list with owner=lee@example.com to see their flags. Sending { "owner": null } returns it to the creator.