Flags API reference

Flags API · Projects

post/v1/workspaces/{workspace_id}/projectsAuth

Create a project

Creates the project with the environments of `environment_preset` (default `dev_prod`: Development and a protected Production) and one config, `main`, unless you pass `environments` / `configs`. Every config gets a published state in every environment. Needs `flags.project.manage`.

Path parameters

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

name*string

Display name, 1-100 characters, unique in the workspace.

Example: "Storefront"

descriptionstring

Free-text description, at most 1000 characters.

environment_presetobject

The environments to start with when `environments` is not given: `dev_prod` (Development, Production) or `dev_staging_prod` (Development, Staging, Production). Production is protected.

environmentsarray

Your own environment list instead of a preset (1-5).

configsarray

Your own config list instead of the default "Main" config (1-10).

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 project, with its environments and configs.

id*string · uuid

The project's id.

workspace_id*string · uuid

The workspace that owns the project.

name*string

Display name, unique in the workspace (case-insensitive).

Example: "Storefront"

description*string

Free-text description (may be empty).

Example: ""

ordinal*integer

Sort position in the workspace (ascending).

Example: 0

environments*array

The project's environments, in `ordinal` order.

configs*array

The project's configs, in `ordinal` order.

created_at*string · date-time

When the project was created.

updated_at*string · date-time

When the project last changed.

Example

Request

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

{
  "name": "Storefront",
  "description": "string",
  "environment_preset": {},
  "environments": [
    {
      "key": "production",
      "name": "Production",
      "color": "#c92a2a",
      "protected": false,
      "require_note": false
    }
  ],
  "configs": [
    {
      "key": "main",
      "name": "Main",
      "description": "string"
    }
  ],
  "note": "Ticket FLAG-142"
}

Response

{
  "id": "00000000-0000-0000-0000-000000000000",
  "workspace_id": "00000000-0000-0000-0000-000000000000",
  "name": "Storefront",
  "description": "",
  "ordinal": 0,
  "environments": [
    {
      "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"
    }
  ],
  "configs": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "workspace_id": "00000000-0000-0000-0000-000000000000",
      "project_id": "00000000-0000-0000-0000-000000000000",
      "key": "main",
      "name": "Main",
      "description": "",
      "ordinal": 0,
      "created_at": "2026-01-01T00:00:00.000Z",
      "updated_at": "2026-01-01T00:00:00.000Z"
    }
  ],
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}