Skip to content
FlagSwiftDocs

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 key and an environment's name are 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#

POST/api/projects/create

Authorization

projects.create

Body

  • namestringRequired

    Trimmed, 1 to 100 characters.
  • keystringRequired

    Letters, 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.
  • descriptionstring

    Trimmed, up to 500 characters. Default empty.
  • colorstring | null

    One 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_session cookie.
  • 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).
  • 409A project with this key already exists. Keys are compared lower case within the organization.
Request
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" }'
201Created
{
  "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#

GET/api/projects

Returns 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 | all

    Which projects to return. Default active.
  • usagetrue | false

    With true each project includes its counts of flags and keys. Default false.

Errors

  • 400archived or usage is not one of the listed values.
  • 401No valid session. Sign in again and resend the auth_session cookie.
  • 403Your role lacks projects.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/projects?usage=true&archived=all"
200OK
{
  "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#

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

    The project id.

Errors

  • 401No valid session. Sign in again and resend the auth_session cookie.
  • 403Your role lacks projects.read. Also returned when a write comes from another origin, or the organization is deactivated (ORG_DEACTIVATED).
  • 404Project not found: no such project in your organization, or it was deleted.
Request
curl -s -b "auth_session=$SESSION" \
  "$FLAGSWIFT_URL/api/projects/b3a8d9c4-1e72-4f05-8c3b-6a9d0e2f4b71"
200OK
{
  "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#

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

    The project id.

Body

  • namestring

    Trimmed, 1 to 100 characters.
  • descriptionstring

    Trimmed, up to 500 characters.
  • colorstring | null

    A colour from the create list, or null to clear it.

Errors

  • 400Malformed JSON (Invalid JSON body), or Nothing to update (an empty body), a validation message (Name is required for a blank name, Pick a colour from the list), or This project is archived. Restore the project to edit it.
  • 401No valid session. Sign in again and resend the auth_session cookie.
  • 403Your role lacks projects.update. Also returned when a write comes from another origin, or the organization is deactivated (ORG_DEACTIVATED).
  • 404Project not found: no such project in your organization, or it was deleted.
Request
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 }'
200OK
{
  "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#

POST/api/projects/{id}/archive

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

    The project id.

Errors

  • 400This project is already archived (for restore: This project is not archived).
  • 401No valid session. Sign in again and resend the auth_session cookie.
  • 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).
  • 404Project not found: no such project in your organization, or it was deleted.
Request
curl -s -X POST -b "auth_session=$SESSION" \
  "$FLAGSWIFT_URL/api/projects/b3a8d9c4-1e72-4f05-8c3b-6a9d0e2f4b71/archive"
200OK
{
  "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#

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

    The project id.

Errors

  • 400Archive the project before deleting it permanently.
  • 401No valid session. Sign in again and resend the auth_session cookie.
  • 403Your role lacks projects.delete (admins hold it). Also returned when a write comes from another origin, or the organization is deactivated (ORG_DEACTIVATED).
  • 404Project 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.
Request
curl -s -X DELETE -b "auth_session=$SESSION" \
  "$FLAGSWIFT_URL/api/projects/b3a8d9c4-1e72-4f05-8c3b-6a9d0e2f4b71"
200OK
{
  "status": "success",
  "message": "Project deleted successfully",
  "data": null
}

Pin for yourself#

PUT/api/projects/{id}/marks

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

    The project id.

Body

  • kind"pin"Required

    The only kind there is.
  • valuebooleanRequired

    true to pin, false to unpin.

Errors

  • 400Malformed JSON (Invalid JSON body), or Kind is required, Kind must be pin, Value is required, or You can pin at most 3 projects. Remove one first.
  • 401No valid session. Sign in again and resend the auth_session cookie.
  • 403Your role lacks projects.read. Also returned when a write comes from another origin, or the organization is deactivated (ORG_DEACTIVATED).
  • 404Project not found: no such project in your organization, or it was deleted.
Request
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 }'
200OK
{
  "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#

POST/api/environments

The 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

  • namestringRequired

    Trimmed 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.
  • displayNamestringRequired

    Trimmed, 1 to 50 characters.
  • isProductionboolean

    Default false.

Errors

  • 400Malformed JSON (Invalid JSON body), or Name 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_session cookie.
  • 403Your role lacks environments.create. Also returned when a write comes from another origin, or the organization is deactivated (ORG_DEACTIVATED).
  • 409An environment with this name already exists.
Request
curl -s -X POST "$FLAGSWIFT_URL/api/environments" \
  -b "auth_session=$SESSION" \
  -H "Content-Type: application/json" \
  -d '{ "name": "qa", "displayName": "QA", "isProduction": false }'
201Created
{
  "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#

GET/api/environments

A 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_session cookie.
  • 403Your role lacks environments.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/environments"
200OK
{
  "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#

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

    The environment id (not its name).

Errors

  • 401No valid session. Sign in again and resend the auth_session cookie.
  • 403Your role lacks environments.read. Also returned when a write comes from another origin, or the organization is deactivated (ORG_DEACTIVATED).
  • 404Environment not found.
Request
curl -s -b "auth_session=$SESSION" \
  "$FLAGSWIFT_URL/api/environments/9e8d7c6b-5a49-4382-b1a0-f9e8d7c6b5a4"
200OK
{
  "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#

PATCH/api/environments/{id}

Authorization

environments.update

Path parameters

  • idstring (uuid)Required

    The environment id (not its name).

Body

  • displayNamestringRequired

    Trimmed, 1 to 50 characters. Required on every edit, even when only changing a flag below.
  • isProductionboolean

    Production restrictions apply to developers. Left as it is when omitted. Cannot be turned off for production.
  • requiresApprovalboolean

    Direct changes are refused with 403; changes go through a release. Left as it is when omitted.

Errors

  • 400Malformed JSON (Invalid JSON body), or Display name is required or over 50 characters.
  • 401No valid session. Sign in again and resend the auth_session cookie.
  • 403Your role lacks environments.update, or you tried to turn isProduction off for production (The production environment cannot be downgraded). Also returned when a write comes from another origin, or the organization is deactivated (ORG_DEACTIVATED).
  • 404Environment not found.
Request
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 }'
200OK
{
  "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#

PUT/api/environments/order

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

    Every environment id of the organization exactly once, in the order to show them. At least one.

Errors

  • 400Malformed JSON (Invalid JSON body), or At least one environment is required, or Environment order is required.
  • 401No valid session. Sign in again and resend the auth_session cookie.
  • 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.
Request
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"] }'
200OK
{
  "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#

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

    The environment id (not its name).

Errors

  • 401No valid session. Sign in again and resend the auth_session cookie.
  • 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).
  • 404Environment not found.
Request
curl -s -X DELETE -b "auth_session=$SESSION" \
  "$FLAGSWIFT_URL/api/environments/9e8d7c6b-5a49-4382-b1a0-f9e8d7c6b5a4"
200OK
{
  "status": "success",
  "message": "Environment removed successfully",
  "data": null
}

Names are permanent

A flag's configuration, saved versions and API keys all refer to an environment by name. Choose them as you would a database name.

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.

From active to deleted
# 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#

Create, then require 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.