/v1/workspaces/{workspace_id}/projectsAuthCreate 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 · uuidId of the workspace.
Headers
Idempotency-KeystringIdempotency 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*stringDisplay name, 1-100 characters, unique in the workspace.
Example: "Storefront"
descriptionstringFree-text description, at most 1000 characters.
environment_presetobjectThe environments to start with when `environments` is not given: `dev_prod` (Development, Production) or `dev_staging_prod` (Development, Staging, Production). Production is protected.
environmentsarrayYour own environment list instead of a preset (1-5).
configsarrayYour own config list instead of the default "Main" config (1-10).
notestringA 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 · uuidThe project's id.
workspace_id*string · uuidThe workspace that owns the project.
name*stringDisplay name, unique in the workspace (case-insensitive).
Example: "Storefront"
description*stringFree-text description (may be empty).
Example: ""
ordinal*integerSort position in the workspace (ascending).
Example: 0
environments*arrayThe project's environments, in `ordinal` order.
configs*arrayThe project's configs, in `ordinal` order.
created_at*string · date-timeWhen the project was created.
updated_at*string · date-timeWhen 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"
}