Skip to main content
POST /api/v1/projects/{project_id}/flags Requires flags.write permission. The referenced environment must belong to the same project. A salt value is auto-generated for percentage-rollout hashing.

​
Path parameters

​
project_id
string
required
UUID of the project.

​
Request body

​
environment_id
string
required
UUID of the environment to associate this flag with. Must belong to the current project.
​
key
string
required
URL-safe identifier for the flag. Example: new-dashboard.
​
name
string
required
Human-readable display name. Example: New Dashboard.
​
description
string | null
Optional description. Pass null to leave it unset.
​
enabled
boolean
default:"true"
Whether the flag is active on creation.
​
default_value
boolean
default:"false"
Value returned when no rule matches (or the flag is disabled).

​
Response

​
flag
object
required
The newly created flag.

​
Errors

StatusWhen
400Request body is invalid or missing required fields
403Caller lacks flags.write permission
404Referenced environment not found
409A flag with the same key already exists in this environment

​
Example

curl -X POST http://localhost:8080/api/v1/projects/550e8400-e29b-41d4-a716-446655440000/flags \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "environment_id": "e1a2b3c4-d5e6-7890-abcd-ef1234567890",
    "key": "new-dashboard",
    "name": "New Dashboard",
    "description": "Enables the redesigned dashboard UI",
    "enabled": true,
    "default_value": false
  }'

{
  "flag": {
    "id": "f1a2b3c4-d5e6-7890-abcd-ef1234567890",
    "environment_id": "e1a2b3c4-d5e6-7890-abcd-ef1234567890",
    "key": "new-dashboard",
    "name": "New Dashboard",
    "description": "Enables the redesigned dashboard UI",
    "enabled": true,
    "default_value": false,
    "salt": "a8f3d2c1",
    "created_at": "2026-03-21T10:00:00Z",
    "updated_at": "2026-03-21T10:00:00Z"
  }
}

Build docs developers (and LLMs) love

Get started for freeTalk to us