Flags API reference

Flags API · Environments

post/v1/workspaces/{workspace_id}/projects/{project_id}/environmentsAuth

Create an environment

Adds an environment to every config of the project. The key `production` starts protected unless you say otherwise. Needs `flags.project.manage`.

Path parameters

project_id*string · uuid

Id of the project.

workspace_id*string · uuid

Id of the workspace.

Headers

Idempotency-Keystring

Idempotency key (1-256 characters, `[A-Za-z0-9._:-]`). A retry with the same key and body returns the first response for 24 h.

Request body

key*string

Stable key, unique in the project; must be a lowercase slug: a-z, 0-9 and "-", 1-63 characters, not starting with "-". Cannot change later.

Example: "staging"

name*string

Display name, 1-100 characters.

Example: "Staging"

colorstring

Display color, `#rrggbb`. Defaults to gray.

Example: "#e67700"

ordinalinteger

Sort position. Defaults to after the last one.

Example: 1

protectedboolean

Require `flags.protected.update` for value changes. Defaults to true for the key `production`, else false.

require_noteboolean

Require a `note` on value changes. Defaults to false.

notestring

A change note (at most 500 characters), saved on the history entry. Environments with `require_note` refuse value writes without one.

Example: "Ticket FLAG-142"

Response · 201 The new environment.

id*string · uuid

The environment's id.

workspace_id*string · uuid

The workspace that owns the environment.

project_id*string · uuid

The project the environment belongs to.

key*string

Stable key, unique in the project. Cannot change.

Example: "production"

name*string

Display name.

Example: "Production"

color*string

Display color, `#rrggbb`.

Example: "#c92a2a"

ordinal*integer

Sort position in the project (ascending).

Example: 1

protected*boolean

Protected environments need `flags.protected.update` (owners and admins by default) for any value change, on top of `flags.value.update`.

Example: true

require_note*boolean

Value changes in this environment must carry a `note`.

Example: false

created_at*string · date-time

When the environment was created.

updated_at*string · date-time

When the environment last changed.

Example

Request

POST https://api.flags.productcraft.co/v1/workspaces/{workspace_id}/projects/{project_id}/environments
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "key": "staging",
  "name": "Staging",
  "color": "#e67700",
  "ordinal": 1,
  "protected": false,
  "require_note": false,
  "note": "Ticket FLAG-142"
}

Response

{
  "id": "00000000-0000-0000-0000-000000000000",
  "workspace_id": "00000000-0000-0000-0000-000000000000",
  "project_id": "00000000-0000-0000-0000-000000000000",
  "key": "production",
  "name": "Production",
  "color": "#c92a2a",
  "ordinal": 1,
  "protected": true,
  "require_note": false,
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}