Projects and environments
Projects group flags. Environments are shared by the whole organization and give every flag its separate state.
Concepts#
How the pieces fit#
An organization has projects and environments. A project holds flags and its own API keys; segments belong to the organization (shared by every project) unless one was scoped to a single project at creation. An environment is a name shared across the organization (development, staging and production to begin with). Every flag exists in every environment, with its own on or off state in each, so creating an environment adds it, switched off, to every existing flag.
Archive, then delete#
- Archiving a project makes its flags read-only and stops its API keys working at once; nothing is deleted, and restoring brings it all back.
- Deleting is permanent and removes the project, its archived flags with their history and versions and its API keys. Organization-wide segments are kept; segments scoped to the project are deleted with it. It needs the project to be archived and to have no active flags. The audit trail is kept.
- Keys never change: a project's
keyand an environment'snameare referenced by API keys, SDK configuration and flag configuration.
Examples use $FLAGSWIFT_URL for your server and $SESSION for the value of the auth_session cookie; see Dashboard API. List calls here return a plain array in data, not { items, pagination }.
Projects#
Create a project#
/api/projects/createAuthorization
projects.create
Body
namestringRequiredTrimmed, 1 to 100 characters.keystringRequiredLetters, numbers and single hyphens, with no leading, trailing or doubled hyphen. Trimmed and stored lower case; unique in the organization. Used in the console and by project-wide API keys, and it cannot change.descriptionstringTrimmed, up to 500 characters. Default empty.colorstring | nullOne of red, orange, amber, green, teal, blue, indigo, purple, pink or gray, or null (the default) for none.
Errors
- 400Malformed JSON (
Invalid JSON body), or validation failed:Name is required,Name must be 100 characters or less,Key is required,Key may only contain letters, numbers, and hyphens,Pick a colour from the list. - 401No valid session. Sign in again and resend the
auth_sessioncookie. - 403Your role lacks
projects.create(developers do not hold it). Also returned when a write comes from another origin, or the organization is deactivated (ORG_DEACTIVATED). - 409
A project with this key already exists. Keys are compared lower case within the organization.
curl -s -X POST "$FLAGSWIFT_URL/api/projects/create" \
-b "auth_session=$SESSION" \
-H "Content-Type: application/json" \
-d '{ "name": "Web app", "key": "web-app", "description": "Customer-facing site", "color": "blue" }'{
"status": "success",
"message": "Project created successfully",
"data": {
"id": "b3a8d9c4-1e72-4f05-8c3b-6a9d0e2f4b71",
"name": "Web app",
"key": "web-app",
"description": "Customer-facing site",
"color": "blue",
"archivedAt": null,
"createdAt": "2026-09-01T10:00:00.000Z",
"pinned": false
}
}List projects#
/api/projectsReturns every matching project as an array (there is no paging), with the projects you pinned first and the rest in stored order. usage is { flags, archivedFlags, apiKeys }: flags that are not archived, archived flags, and API keys that are not revoked.
Authorization
projects.read
Query parameters
archivedactive | archived | allWhich projects to return. Default active.usagetrue | falseWith true each project includes its counts of flags and keys. Default false.
Errors
- 400
archivedorusageis not one of the listed values. - 401No valid session. Sign in again and resend the
auth_sessioncookie. - 403Your role lacks
projects.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/projects?usage=true&archived=all"{
"status": "success",
"message": "Projects fetched successfully",
"data": [
{
"id": "b3a8d9c4-1e72-4f05-8c3b-6a9d0e2f4b71",
"name": "Web app",
"key": "web-app",
"description": "Customer-facing site",
"color": "blue",
"archivedAt": null,
"createdAt": "2026-09-01T10:00:00.000Z",
"pinned": true,
"usage": {
"flags": 18,
"archivedFlags": 4,
"apiKeys": 3
}
},
{
"id": "c7d6e5f4-a3b2-4c1d-8e9f-0a1b2c3d4e5f",
"name": "Mobile",
"key": "mobile",
"description": "",
"color": null,
"archivedAt": "2026-09-20T12:00:00.000Z",
"createdAt": "2026-09-01T10:00:00.000Z",
"pinned": false,
"usage": {
"flags": 0,
"archivedFlags": 6,
"apiKeys": 0
}
}
]
}Get a project#
/api/projects/{id}Includes its usage counts. pinned is always false here; it is only filled in on the list.
Authorization
projects.read
Path parameters
idstring (uuid)RequiredThe project id.
Errors
- 401No valid session. Sign in again and resend the
auth_sessioncookie. - 403Your role lacks
projects.read. Also returned when a write comes from another origin, or the organization is deactivated (ORG_DEACTIVATED). - 404
Project not found: no such project in your organization, or it was deleted.
curl -s -b "auth_session=$SESSION" \
"$FLAGSWIFT_URL/api/projects/b3a8d9c4-1e72-4f05-8c3b-6a9d0e2f4b71"{
"status": "success",
"message": "OK",
"data": {
"id": "b3a8d9c4-1e72-4f05-8c3b-6a9d0e2f4b71",
"name": "Web app",
"key": "web-app",
"description": "Customer-facing site",
"color": "blue",
"archivedAt": null,
"createdAt": "2026-09-01T10:00:00.000Z",
"pinned": false,
"usage": {
"flags": 18,
"archivedFlags": 4,
"apiKeys": 3
}
}
}Edit a project#
/api/projects/{id}Any of name, description, color; send at least one. color can be null to clear it. The key cannot change and is ignored if sent. Sending values identical to the current ones succeeds without writing an audit entry.
Authorization
projects.update
Path parameters
idstring (uuid)RequiredThe project id.
Body
namestringTrimmed, 1 to 100 characters.descriptionstringTrimmed, up to 500 characters.colorstring | nullA colour from the create list, or null to clear it.
Errors
- 400Malformed JSON (
Invalid JSON body), orNothing to update(an empty body), a validation message (Name is requiredfor a blank name,Pick a colour from the list), orThis project is archived. Restore the project to edit it. - 401No valid session. Sign in again and resend the
auth_sessioncookie. - 403Your role lacks
projects.update. Also returned when a write comes from another origin, or the organization is deactivated (ORG_DEACTIVATED). - 404
Project not found: no such project in your organization, or it was deleted.
curl -s -X PATCH "$FLAGSWIFT_URL/api/projects/b3a8d9c4-1e72-4f05-8c3b-6a9d0e2f4b71" \
-b "auth_session=$SESSION" \
-H "Content-Type: application/json" \
-d '{ "name": "Web application", "color": null }'{
"status": "success",
"message": "Project updated successfully",
"data": {
"id": "b3a8d9c4-1e72-4f05-8c3b-6a9d0e2f4b71",
"name": "Web application",
"key": "web-app",
"description": "Customer-facing site",
"color": null,
"archivedAt": null,
"createdAt": "2026-09-01T10:00:00.000Z",
"pinned": false
}
}Archive or restore#
/api/projects/{id}/archivePOST /api/projects/{id}/restore brings it back, with the same permission and a Project restored message. Only admins hold projects.archive; release managers and developers do not. While a project is archived its flags and segments cannot be changed (400) and its API keys stop working.
Authorization
projects.archive
Path parameters
idstring (uuid)RequiredThe project id.
Errors
- 400
This project is already archived(for restore:This project is not archived). - 401No valid session. Sign in again and resend the
auth_sessioncookie. - 403Your role lacks
projects.archive. Only admins hold it. Also returned when a write comes from another origin, or the organization is deactivated (ORG_DEACTIVATED). - 404
Project not found: no such project in your organization, or it was deleted.
curl -s -X POST -b "auth_session=$SESSION" \
"$FLAGSWIFT_URL/api/projects/b3a8d9c4-1e72-4f05-8c3b-6a9d0e2f4b71/archive"{
"status": "success",
"message": "Project archived",
"data": {
"id": "b3a8d9c4-1e72-4f05-8c3b-6a9d0e2f4b71",
"name": "Web app",
"key": "web-app",
"description": "Customer-facing site",
"color": "blue",
"archivedAt": "2026-10-03T09:00:00.000Z",
"createdAt": "2026-09-01T10:00:00.000Z",
"pinned": false
}
}Delete a project#
/api/projects/{id}Permanent. The project must be archived and hold no active flags. It removes the project's archived flags with their history and versions, its API keys and the segments scoped to it (organization-wide segments are kept), its evaluation counts and alert rules, and everyone's pins on them. Archive instead unless you are sure.
Authorization
projects.delete
Path parameters
idstring (uuid)RequiredThe project id.
Errors
- 400
Archive the project before deleting it permanently. - 401No valid session. Sign in again and resend the
auth_sessioncookie. - 403Your role lacks
projects.delete(admins hold it). Also returned when a write comes from another origin, or the organization is deactivated (ORG_DEACTIVATED). - 404
Project not found: no such project in your organization, or it was deleted. - 409Active flags remain (
This project still has 3 active flags. Archive them, or archive the project instead.). Archive the flags first, for example with the bulk archive on the Lifecycle page.
curl -s -X DELETE -b "auth_session=$SESSION" \
"$FLAGSWIFT_URL/api/projects/b3a8d9c4-1e72-4f05-8c3b-6a9d0e2f4b71"{
"status": "success",
"message": "Project deleted successfully",
"data": null
}Pin for yourself#
/api/projects/{id}/marksBody { "kind": "pin", "value": true }. At most 3 projects can be pinned, and pins are personal. Send false to unpin; repeating a request changes nothing.
Authorization
projects.read
Path parameters
idstring (uuid)RequiredThe project id.
Body
kind"pin"RequiredThe only kind there is.valuebooleanRequiredtrue to pin, false to unpin.
Errors
- 400Malformed JSON (
Invalid JSON body), orKind is required,Kind must be pin,Value is required, orYou can pin at most 3 projects. Remove one first. - 401No valid session. Sign in again and resend the
auth_sessioncookie. - 403Your role lacks
projects.read. Also returned when a write comes from another origin, or the organization is deactivated (ORG_DEACTIVATED). - 404
Project not found: no such project in your organization, or it was deleted.
curl -s -X PUT "$FLAGSWIFT_URL/api/projects/b3a8d9c4-1e72-4f05-8c3b-6a9d0e2f4b71/marks" \
-b "auth_session=$SESSION" \
-H "Content-Type: application/json" \
-d '{ "kind": "pin", "value": true }'{
"status": "success",
"message": "Saved",
"data": {
"pinned": true
}
}Environments#
Environments belong to the organization, not a project, so production means the same thing everywhere. Marking one as production withdraws toggling, rollouts, targeting and the kill switch from developers there, and requiring approval sends every change through a release. The three defaults (development, staging, production) can be renamed in display and reordered but not removed, and production is always a production environment.
Create an environment#
/api/environmentsThe new environment is added, off at 100%, to every existing flag in the organization. It is placed last in the order.
Authorization
environments.create
Body
namestringRequiredTrimmed and lower-cased; 1 to 50 characters of letters, numbers, hyphens and underscores, with no doubled or edge separators (^[a-z0-9]+([-_][a-z0-9]+)*$). Unique in the organization. It is what keys and SDKs use, so it cannot change.displayNamestringRequiredTrimmed, 1 to 50 characters.isProductionbooleanDefault false.
Errors
- 400Malformed JSON (
Invalid JSON body), orName may only contain lowercase letters, numbers, hyphens and underscores,Name is required,Display name is required, or a name or display name over 50 characters. - 401No valid session. Sign in again and resend the
auth_sessioncookie. - 403Your role lacks
environments.create. Also returned when a write comes from another origin, or the organization is deactivated (ORG_DEACTIVATED). - 409
An environment with this name already exists.
curl -s -X POST "$FLAGSWIFT_URL/api/environments" \
-b "auth_session=$SESSION" \
-H "Content-Type: application/json" \
-d '{ "name": "qa", "displayName": "QA", "isProduction": false }'{
"status": "success",
"message": "Environment created successfully",
"data": {
"id": "9e8d7c6b-5a49-4382-b1a0-f9e8d7c6b5a4",
"name": "qa",
"displayName": "QA",
"order": 3,
"isDefault": false,
"isProduction": false,
"requiresApproval": false
}
}List environments#
/api/environmentsA plain array in display order, with no paging. An organization that has none yet gets the three defaults on first use.
Authorization
environments.read
Errors
- 401No valid session. Sign in again and resend the
auth_sessioncookie. - 403Your role lacks
environments.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/environments"{
"status": "success",
"message": "OK",
"data": [
{
"id": "11111111-2222-4333-8444-555555555551",
"name": "development",
"displayName": "Development",
"order": 0,
"isDefault": true,
"isProduction": false,
"requiresApproval": false
},
{
"id": "11111111-2222-4333-8444-555555555552",
"name": "staging",
"displayName": "Staging",
"order": 1,
"isDefault": true,
"isProduction": false,
"requiresApproval": false
},
{
"id": "11111111-2222-4333-8444-555555555553",
"name": "production",
"displayName": "Production",
"order": 2,
"isDefault": true,
"isProduction": true,
"requiresApproval": true
}
]
}Get one, with usage#
/api/environments/{id}usage is how many flags have a configuration here and how many of those are on, which is what a removal would touch.
Authorization
environments.read
Path parameters
idstring (uuid)RequiredThe environment id (not its name).
Errors
- 401No valid session. Sign in again and resend the
auth_sessioncookie. - 403Your role lacks
environments.read. Also returned when a write comes from another origin, or the organization is deactivated (ORG_DEACTIVATED). - 404
Environment not found.
curl -s -b "auth_session=$SESSION" \
"$FLAGSWIFT_URL/api/environments/9e8d7c6b-5a49-4382-b1a0-f9e8d7c6b5a4"{
"status": "success",
"message": "OK",
"data": {
"id": "9e8d7c6b-5a49-4382-b1a0-f9e8d7c6b5a4",
"name": "qa",
"displayName": "QA",
"order": 3,
"isDefault": false,
"isProduction": false,
"requiresApproval": false,
"usage": {
"flagCount": 22,
"enabledCount": 5
}
}
}Edit an environment#
/api/environments/{id}Authorization
environments.update
Path parameters
idstring (uuid)RequiredThe environment id (not its name).
Body
displayNamestringRequiredTrimmed, 1 to 50 characters. Required on every edit, even when only changing a flag below.isProductionbooleanProduction restrictions apply to developers. Left as it is when omitted. Cannot be turned off for production.requiresApprovalbooleanDirect changes are refused with403; changes go through a release. Left as it is when omitted.
Errors
- 400Malformed JSON (
Invalid JSON body), orDisplay name is requiredor over 50 characters. - 401No valid session. Sign in again and resend the
auth_sessioncookie. - 403Your role lacks
environments.update, or you tried to turnisProductionoff forproduction(The production environment cannot be downgraded). Also returned when a write comes from another origin, or the organization is deactivated (ORG_DEACTIVATED). - 404
Environment not found.
curl -s -X PATCH "$FLAGSWIFT_URL/api/environments/9e8d7c6b-5a49-4382-b1a0-f9e8d7c6b5a4" \
-b "auth_session=$SESSION" \
-H "Content-Type: application/json" \
-d '{ "displayName": "QA", "requiresApproval": true }'{
"status": "success",
"message": "Environment updated successfully",
"data": {
"id": "9e8d7c6b-5a49-4382-b1a0-f9e8d7c6b5a4",
"name": "qa",
"displayName": "QA",
"order": 3,
"isDefault": false,
"isProduction": false,
"requiresApproval": true
}
}Reorder#
/api/environments/orderBody { "ids": ["...", "..."] }, in the order you want them shown. Send every environment id exactly once; a missing, extra or repeated id is a conflict. Returns the full list in the new order.
Authorization
environments.update
Body
idsstring[]RequiredEvery environment id of the organization exactly once, in the order to show them. At least one.
Errors
- 400Malformed JSON (
Invalid JSON body), orAt least one environment is required, orEnvironment order is required. - 401No valid session. Sign in again and resend the
auth_sessioncookie. - 403Your role lacks
environments.update. Also returned when a write comes from another origin, or the organization is deactivated (ORG_DEACTIVATED). - 409The ids are not exactly the organization's environments, each once (
Environments have changed. Refresh the page and try again). List them again and resend.
curl -s -X PUT "$FLAGSWIFT_URL/api/environments/order" \
-b "auth_session=$SESSION" \
-H "Content-Type: application/json" \
-d '{ "ids": ["11111111-2222-4333-8444-555555555551", "11111111-2222-4333-8444-555555555552", "9e8d7c6b-5a49-4382-b1a0-f9e8d7c6b5a4", "11111111-2222-4333-8444-555555555553"] }'{
"status": "success",
"message": "Environment order updated",
"data": [
{
"id": "11111111-2222-4333-8444-555555555551",
"name": "development",
"displayName": "Development",
"order": 0,
"isDefault": true,
"isProduction": false,
"requiresApproval": false
},
{
"id": "11111111-2222-4333-8444-555555555552",
"name": "staging",
"displayName": "Staging",
"order": 1,
"isDefault": true,
"isProduction": false,
"requiresApproval": false
},
{
"id": "9e8d7c6b-5a49-4382-b1a0-f9e8d7c6b5a4",
"name": "qa",
"displayName": "QA",
"order": 2,
"isDefault": false,
"isProduction": false,
"requiresApproval": false
},
{
"id": "11111111-2222-4333-8444-555555555553",
"name": "production",
"displayName": "Production",
"order": 3,
"isDefault": true,
"isProduction": true,
"requiresApproval": false
}
]
}Delete#
/api/environments/{id}Permanent. The environment's configuration is stripped from every flag and its change history is deleted. Check usage with the get call first.
Authorization
environments.delete
Path parameters
idstring (uuid)RequiredThe environment id (not its name).
Errors
- 401No valid session. Sign in again and resend the
auth_sessioncookie. - 403Your role lacks
environments.delete, or it is a default environment (Default environments cannot be removed). Also returned when a write comes from another origin, or the organization is deactivated (ORG_DEACTIVATED). - 404
Environment not found.
curl -s -X DELETE -b "auth_session=$SESSION" \
"$FLAGSWIFT_URL/api/environments/9e8d7c6b-5a49-4382-b1a0-f9e8d7c6b5a4"{
"status": "success",
"message": "Environment removed successfully",
"data": null
}Names are permanent
Common patterns#
Wind a project down#
Archive its flags, archive the project, and delete it only when you are sure. Each step can be stopped, and everything before the delete can be undone.
# 1. See what it holds. usage.flags must reach 0 before it can be deleted.
curl -s -b "auth_session=$SESSION" "$FLAGSWIFT_URL/api/projects/b3a8d9c4-1e72-4f05-8c3b-6a9d0e2f4b71"
# 2. Archive its active flags (up to 50 ids per call; see the Lifecycle page).
curl -s -X POST "$FLAGSWIFT_URL/api/lifecycle/archive" \
-b "auth_session=$SESSION" -H "Content-Type: application/json" \
-d '{ "ids": ["FLAG_ID", "FLAG_ID"] }'
# 3. Archive the project. Its keys stop working; POST .../restore undoes this.
curl -s -X POST -b "auth_session=$SESSION" "$FLAGSWIFT_URL/api/projects/b3a8d9c4-1e72-4f05-8c3b-6a9d0e2f4b71/archive"
# 4. Permanently delete it.
curl -s -X DELETE -b "auth_session=$SESSION" "$FLAGSWIFT_URL/api/projects/b3a8d9c4-1e72-4f05-8c3b-6a9d0e2f4b71"Add an environment that needs approval#
curl -s -X POST "$FLAGSWIFT_URL/api/environments" \
-b "auth_session=$SESSION" -H "Content-Type: application/json" \
-d '{ "name": "pre-prod", "displayName": "Pre-prod", "isProduction": true }'
# Use the returned id. displayName is required on every edit.
curl -s -X PATCH "$FLAGSWIFT_URL/api/environments/ENVIRONMENT_ID" \
-b "auth_session=$SESSION" -H "Content-Type: application/json" \
-d '{ "displayName": "Pre-prod", "requiresApproval": true }'From then on, direct toggles and rollout edits there are refused with 403; changes go through a release. Rollbacks and the emergency stop still work directly.