API Reference

v1.0.0

Complete REST API for the Flagify platform. 57 endpoints across 15 sections.

Production https://api.flagify.dev/v1

Back to Docs Download OpenAPI spec

Health

Health check

GET /health/check Public

Health check

Response 200 — API is healthy

status string required
env string required

Example response

{
  "status": "ok",
  "env": "production"
}

Auth

Authentication (register, login, refresh, logout)

POST /auth/register Public

Request body

email string (email) required
password string required
name string required
deviceId string required

Response 201 — User registered

user object required
- id string (uuid) required
- email string (email) required
- emailVerifiedAt string | null
- name string | null
- avatarUrl string | null
- createdAt string (date-time) required
- updatedAt string (date-time) required
tokens object required
- accessToken string required
- refreshToken string required

Example response

{
  "user": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "email": "[email protected]",
    "name": "Jane Smith",
    "createdAt": "2025-01-15T10:30:00Z",
    "updatedAt": "2025-01-15T10:30:00Z"
  },
  "tokens": {
    "accessToken": "eyJhbGciOiJIUzI1NiIs...",
    "refreshToken": "dGhpcyBpcyBhIHJlZnJlc2g..."
  }
}

Errors

409 Resource already exists

{
  "code": "conflict",
  "message": "resource already exists"
}

422 Validation failed

{
  "code": "unprocessable_entity",
  "message": "validation failed"
}

POST /auth/login Public

Request body

email string (email) required
password string required
deviceId string required

Response 200 — Login successful

user object required
- id string (uuid) required
- email string (email) required
- emailVerifiedAt string | null
- name string | null
- avatarUrl string | null
- createdAt string (date-time) required
- updatedAt string (date-time) required
tokens object required
- accessToken string required
- refreshToken string required

Example response

{
  "user": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "email": "[email protected]",
    "name": "Jane Smith",
    "createdAt": "2025-01-15T10:30:00Z",
    "updatedAt": "2025-01-15T14:22:00Z"
  },
  "tokens": {
    "accessToken": "eyJhbGciOiJIUzI1NiIs...",
    "refreshToken": "dGhpcyBpcyBhIHJlZnJlc2g..."
  }
}

Errors

401 Authentication required or invalid

{
  "code": "unauthorized",
  "message": "authentication required"
}

POST /auth/refresh Public

Refresh access token

Request body

refreshToken string required
deviceId string required

Response 200 — Tokens refreshed

accessToken string required
refreshToken string required

Example response

{
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "refreshToken": "dGhpcyBpcyBhIHJlZnJlc2g..."
}

Errors

401 Authentication required or invalid

{
  "code": "unauthorized",
  "message": "authentication required"
}

POST /auth/logout Bearer JWT

Logout (revoke session)

Request body

deviceId string required

Response 200 — Logged out

status string required

Example response

{
  "status": "ok"
}

Errors

401 Authentication required or invalid

{
  "code": "unauthorized",
  "message": "authentication required"
}

POST /auth/device/authorize Bearer JWT

Authorize a device (CLI login flow)

Request body

deviceId string required

Response 200 — Device authorized

user object required
- id string (uuid) required
- email string (email) required
- emailVerifiedAt string | null
- name string | null
- avatarUrl string | null
- createdAt string (date-time) required
- updatedAt string (date-time) required
tokens object required
- accessToken string required
- refreshToken string required

Example response

{
  "user": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "email": "[email protected]",
    "name": "Jane Smith",
    "createdAt": "2025-01-15T10:30:00Z",
    "updatedAt": "2025-01-15T14:22:00Z"
  },
  "tokens": {
    "accessToken": "eyJhbGciOiJIUzI1NiIs...",
    "refreshToken": "dGhpcyBpcyBhIHJlZnJlc2g..."
  }
}

Errors

401 Authentication required or invalid

{
  "code": "unauthorized",
  "message": "authentication required"
}

Users

Current user profile

GET /users/me Bearer JWT

Get current user profile

Response 200 — User profile

id string (uuid) required
email string (email) required
emailVerifiedAt string | null
name string | null
avatarUrl string | null
createdAt string (date-time) required
updatedAt string (date-time) required

Example response

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "email": "[email protected]",
  "name": "Jane Smith",
  "createdAt": "2025-01-15T10:30:00Z",
  "updatedAt": "2025-01-15T14:22:00Z"
}

Errors

401 Authentication required or invalid

{
  "code": "unauthorized",
  "message": "authentication required"
}

PATCH /users/me Bearer JWT

Update current user profile

Request body

name string
avatarUrl string

Response 200 — User updated

id string (uuid) required
email string (email) required
emailVerifiedAt string | null
name string | null
avatarUrl string | null
createdAt string (date-time) required
updatedAt string (date-time) required

Example response

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "email": "[email protected]",
  "name": "Jane Smith",
  "createdAt": "2025-01-15T10:30:00Z",
  "updatedAt": "2025-01-15T14:22:00Z"
}

Errors

401 Authentication required or invalid

{
  "code": "unauthorized",
  "message": "authentication required"
}

Workspaces

Workspace management

POST /workspaces Bearer JWT

Create a workspace

Request body

name string required
slug string required

Response 201 — Workspace created

id string (uuid) required
name string required
slug string required
plan string required
seatLimit integer required
createdAt string (date-time) required
updatedAt string (date-time) required

Example response

{
  "id": "w1a2b3c4-d5e6-7890-abcd-ef1234567890",
  "name": "Acme Corp",
  "slug": "acme-corp",
  "plan": "pro",
  "seatLimit": 10,
  "createdAt": "2025-01-15T10:30:00Z",
  "updatedAt": "2025-01-15T10:30:00Z"
}

Errors

409 Resource already exists

{
  "code": "conflict",
  "message": "resource already exists"
}

422 Validation failed

{
  "code": "unprocessable_entity",
  "message": "validation failed"
}

GET /workspaces Bearer JWT

List workspaces for current user

Response 200 — List of workspaces

Workspace[]

id string (uuid) required
name string required
slug string required
plan string required
seatLimit integer required
createdAt string (date-time) required
updatedAt string (date-time) required

Example response

[
  {
    "id": "w1a2b3c4-d5e6-7890-abcd-ef1234567890",
    "name": "Acme Corp",
    "slug": "acme-corp",
    "plan": "pro",
    "seatLimit": 10,
    "createdAt": "2025-01-15T10:30:00Z",
    "updatedAt": "2025-01-15T14:22:00Z"
  }
]

GET /workspaces/slug/{slug}/check Bearer JWT

Check workspace slug availability

Parameters

Name	Type	In	Description
`slug`required	`string`	path

Response 200 — Slug availability result

slug string required
available boolean required
suggestion string

Example response

{
  "slug": "acme-corp",
  "available": true
}

GET /workspaces/{wid} Bearer JWT

Get workspace details

Parameters

Name	Type	In	Description
`wid`required	`string (uuid)`	path	Workspace ID

Response 200 — Workspace details

id string (uuid) required
name string required
slug string required
plan string required
seatLimit integer required
createdAt string (date-time) required
updatedAt string (date-time) required

Example response

{
  "id": "w1a2b3c4-d5e6-7890-abcd-ef1234567890",
  "name": "Acme Corp",
  "slug": "acme-corp",
  "plan": "pro",
  "seatLimit": 10,
  "createdAt": "2025-01-15T10:30:00Z",
  "updatedAt": "2025-01-15T14:22:00Z"
}

Errors

404 Resource not found

{
  "code": "not_found",
  "message": "resource not found"
}

PATCH /workspaces/{wid} Bearer JWT workspace:update

Update workspace

Parameters

Name	Type	In	Description
`wid`required	`string (uuid)`	path	Workspace ID

Request body

name string

Response 200 — Workspace updated

id string (uuid) required
name string required
slug string required
plan string required
seatLimit integer required
createdAt string (date-time) required
updatedAt string (date-time) required

Example response

{
  "id": "w1a2b3c4-d5e6-7890-abcd-ef1234567890",
  "name": "Acme Corp",
  "slug": "acme-corp",
  "plan": "pro",
  "seatLimit": 10,
  "createdAt": "2025-01-15T10:30:00Z",
  "updatedAt": "2025-01-15T14:22:00Z"
}

Errors

403 Insufficient permissions

{
  "code": "forbidden",
  "message": "insufficient permissions"
}

GET /workspaces/{wid}/usage Bearer JWT

Get workspace usage stats

Parameters

Name	Type	In	Description
`wid`required	`string (uuid)`	path	Workspace ID

Response 200 — Usage statistics

plan string required
flagEvaluations object required
- used integer required
- limit integer required
flags object required
- used integer required
- limit integer required
members object required
- used integer required
- limit integer required

Example response

{
  "plan": "pro",
  "flagEvaluations": {
    "used": 12500,
    "limit": 100000
  },
  "flags": {
    "used": 5,
    "limit": 50
  },
  "members": {
    "used": 3,
    "limit": 10
  }
}

POST /workspaces/{wid}/leave Bearer JWT

Leave a workspace

Parameters

Name	Type	In	Description
`wid`required	`string (uuid)`	path	Workspace ID

Response 200 — Left workspace

status string required

Example response

{
  "status": "ok"
}

Members

Workspace member management

GET /workspaces/{wid}/members Bearer JWT

List workspace members

Parameters

Name	Type	In	Description
`wid`required	`string (uuid)`	path	Workspace ID

Response 200 — List of members

Member[]

id string (uuid) required
workspaceId string (uuid) required
userId string (uuid) required
role owner | admin | member | viewer required
email string
name string
createdAt string (date-time) required
updatedAt string (date-time) required

Example response

[
  {
    "id": "m1a2b3c4-d5e6-7890-abcd-ef1234567890",
    "workspaceId": "w1a2b3c4-d5e6-7890-abcd-ef1234567890",
    "userId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "role": "admin",
    "email": "[email protected]",
    "name": "Jane Smith",
    "createdAt": "2025-01-15T10:30:00Z",
    "updatedAt": "2025-01-15T14:22:00Z"
  }
]

POST /workspaces/{wid}/members Bearer JWT member:manage

Add a member to workspace

Parameters

Name	Type	In	Description
`wid`required	`string (uuid)`	path	Workspace ID

Request body

userId string (uuid) required
role owner | admin | member | viewer required

Response 201 — Member added

id string (uuid) required
workspaceId string (uuid) required
userId string (uuid) required
role owner | admin | member | viewer required
email string
name string
createdAt string (date-time) required
updatedAt string (date-time) required

Example response

{
  "id": "m1a2b3c4-d5e6-7890-abcd-ef1234567890",
  "workspaceId": "w1a2b3c4-d5e6-7890-abcd-ef1234567890",
  "userId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "role": "member",
  "email": "[email protected]",
  "name": "Jane Smith",
  "createdAt": "2025-01-15T10:30:00Z",
  "updatedAt": "2025-01-15T10:30:00Z"
}

Errors

403 Insufficient permissions

{
  "code": "forbidden",
  "message": "insufficient permissions"
}

409 Resource already exists

{
  "code": "conflict",
  "message": "resource already exists"
}

PATCH /workspaces/{wid}/members/{uid} Bearer JWT member:manage

Update member role

Parameters

Name	Type	In	Description
`wid`required	`string (uuid)`	path	Workspace ID
`uid`required	`string (uuid)`	path	User ID

Request body

role owner | admin | member | viewer required

Response 200 — Member updated

id string (uuid) required
workspaceId string (uuid) required
userId string (uuid) required
role owner | admin | member | viewer required
email string
name string
createdAt string (date-time) required
updatedAt string (date-time) required

Example response

{
  "id": "m1a2b3c4-d5e6-7890-abcd-ef1234567890",
  "workspaceId": "w1a2b3c4-d5e6-7890-abcd-ef1234567890",
  "userId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "role": "admin",
  "email": "[email protected]",
  "name": "Jane Smith",
  "createdAt": "2025-01-15T10:30:00Z",
  "updatedAt": "2025-01-15T14:22:00Z"
}

Errors

403 Insufficient permissions

{
  "code": "forbidden",
  "message": "insufficient permissions"
}

DELETE /workspaces/{wid}/members/{uid} Bearer JWT member:manage

Remove member from workspace

Parameters

Name	Type	In	Description
`wid`required	`string (uuid)`	path	Workspace ID
`uid`required	`string (uuid)`	path	User ID

Response 200 — Member removed

status string required

Example response

{
  "status": "ok"
}

Errors

403 Insufficient permissions

{
  "code": "forbidden",
  "message": "insufficient permissions"
}

Projects

Project management

POST /workspaces/{wid}/projects Bearer JWT project:create

Create a project

Auto-provisions default environments (development, staging, production).

Parameters

Name	Type	In	Description
`wid`required	`string (uuid)`	path	Workspace ID

Request body

name string required
slug string required

Response 201 — Project created

id string (uuid) required
workspaceId string (uuid) required
name string required
slug string required
environments Environment[]
- id string (uuid) required
- projectId string (uuid) required
- key string required
- name string required
- color string required
- sortOrder integer required
- createdAt string (date-time) required
- updatedAt string (date-time) required
createdAt string (date-time) required
updatedAt string (date-time) required

Example response

{
  "id": "p1a2b3c4-d5e6-7890-abcd-ef1234567890",
  "workspaceId": "w1a2b3c4-d5e6-7890-abcd-ef1234567890",
  "name": "Web App",
  "slug": "web-app",
  "createdAt": "2025-01-15T10:30:00Z",
  "updatedAt": "2025-01-15T10:30:00Z"
}

Errors

409 Resource already exists

{
  "code": "conflict",
  "message": "resource already exists"
}

GET /workspaces/{wid}/projects Bearer JWT

List projects in workspace

Parameters

Name	Type	In	Description
`wid`required	`string (uuid)`	path	Workspace ID

Response 200 — List of projects

Project[]

id string (uuid) required
workspaceId string (uuid) required
name string required
slug string required
environments Environment[]
- id string (uuid) required
- projectId string (uuid) required
- key string required
- name string required
- color string required
- sortOrder integer required
- createdAt string (date-time) required
- updatedAt string (date-time) required
createdAt string (date-time) required
updatedAt string (date-time) required

Example response

[
  {
    "id": "p1a2b3c4-d5e6-7890-abcd-ef1234567890",
    "workspaceId": "w1a2b3c4-d5e6-7890-abcd-ef1234567890",
    "name": "Web App",
    "slug": "web-app",
    "createdAt": "2025-01-15T10:30:00Z",
    "updatedAt": "2025-01-15T14:22:00Z"
  }
]

GET /projects/{pid} Bearer JWT

Get project details

Parameters

Name	Type	In	Description
`pid`required	`string (uuid)`	path	Project ID

Response 200 — Project details (includes environments)

id string (uuid) required
workspaceId string (uuid) required
name string required
slug string required
environments Environment[]
- id string (uuid) required
- projectId string (uuid) required
- key string required
- name string required
- color string required
- sortOrder integer required
- createdAt string (date-time) required
- updatedAt string (date-time) required
createdAt string (date-time) required
updatedAt string (date-time) required

Example response

{
  "id": "p1a2b3c4-d5e6-7890-abcd-ef1234567890",
  "workspaceId": "w1a2b3c4-d5e6-7890-abcd-ef1234567890",
  "name": "Web App",
  "slug": "web-app",
  "environments": [
    {
      "id": "e1-dev-0000-0000-000000000001",
      "projectId": "p1a2b3c4-d5e6-7890-abcd-ef1234567890",
      "key": "development",
      "name": "Development",
      "color": "#22c55e",
      "sortOrder": 0,
      "createdAt": "2025-01-15T10:30:00Z",
      "updatedAt": "2025-01-15T10:30:00Z"
    }
  ],
  "createdAt": "2025-01-15T10:30:00Z",
  "updatedAt": "2025-01-15T14:22:00Z"
}

Errors

404 Resource not found

{
  "code": "not_found",
  "message": "resource not found"
}

PATCH /projects/{pid} Bearer JWT project:update

Update project

Parameters

Name	Type	In	Description
`pid`required	`string (uuid)`	path	Project ID

Request body

name string

Response 200 — Project updated

id string (uuid) required
workspaceId string (uuid) required
name string required
slug string required
environments Environment[]
- id string (uuid) required
- projectId string (uuid) required
- key string required
- name string required
- color string required
- sortOrder integer required
- createdAt string (date-time) required
- updatedAt string (date-time) required
createdAt string (date-time) required
updatedAt string (date-time) required

Example response

{
  "id": "p1a2b3c4-d5e6-7890-abcd-ef1234567890",
  "workspaceId": "w1a2b3c4-d5e6-7890-abcd-ef1234567890",
  "name": "Web App",
  "slug": "web-app",
  "createdAt": "2025-01-15T10:30:00Z",
  "updatedAt": "2025-01-15T14:22:00Z"
}

Overview

Project overview statistics

GET /projects/{pid}/overview/stats Bearer JWT

Get project statistics

Parameters

Name	Type	In	Description
`pid`required	`string (uuid)`	path	Project ID

Response 200 — Project stats

totalFlags integer required
activeFlags integer required
inactiveFlags integer required
recentlyModified integer required
healthIssues integer required

Example response

{
  "totalFlags": 12,
  "activeFlags": 8,
  "inactiveFlags": 4,
  "recentlyModified": 3,
  "healthIssues": 1
}

GET /projects/{pid}/overview/activity Bearer JWT

Get recent project activity

Parameters

Name	Type	In	Description
`pid`required	`string (uuid)`	path	Project ID
`limit`	`integer`	query	Number of activity items to return

Response 200 — Recent activity

ActivityItem[]

id string (uuid) required
action string required
flagKey string required
flagName string required
actor string required
environment string required
environmentColor string
description string required
timestamp string (date-time) required

Example response

[
  {
    "id": "ae1a2b3c-d5e6-7890-abcd-ef1234567890",
    "action": "flag.toggled",
    "flagKey": "new-checkout-flow",
    "flagName": "New Checkout Flow",
    "actor": "Jane Smith",
    "environment": "production",
    "environmentColor": "#ef4444",
    "description": "Enabled flag in production",
    "timestamp": "2025-01-15T14:22:00Z"
  }
]

GET /projects/{pid}/overview/health Bearer JWT

Get project health issues

Parameters

Name	Type	In	Description
`pid`required	`string (uuid)`	path	Project ID

Response 200 — Health issues

HealthIssue[]

flagId string (uuid) required
flagKey string required
flagName string required
type string required
severity string required
message string required

Example response

[
  {
    "flagId": "f1a2b3c4-d5e6-7890-abcd-ef1234567890",
    "flagKey": "new-checkout-flow",
    "flagName": "New Checkout Flow",
    "type": "stale",
    "severity": "warning",
    "message": "Flag has not been modified in 90 days"
  }
]

Environments

Environment management

GET /projects/{pid}/environments Bearer JWT

List project environments

Parameters

Name	Type	In	Description
`pid`required	`string (uuid)`	path	Project ID

Response 200 — List of environments

Environment[]

id string (uuid) required
projectId string (uuid) required
key string required
name string required
color string required
sortOrder integer required
createdAt string (date-time) required
updatedAt string (date-time) required

Example response

[
  {
    "id": "e3-prd-0000-0000-000000000003",
    "projectId": "p1a2b3c4-d5e6-7890-abcd-ef1234567890",
    "key": "production",
    "name": "Production",
    "color": "#ef4444",
    "sortOrder": 2,
    "createdAt": "2025-01-15T10:30:00Z",
    "updatedAt": "2025-01-15T10:30:00Z"
  }
]

POST /projects/{pid}/environments Bearer JWT env:manage

Create an environment

Auto-provisions flag_environments for all existing flags.

Parameters

Name	Type	In	Description
`pid`required	`string (uuid)`	path	Project ID

Request body

key string required
name string required
color string

Response 201 — Environment created

id string (uuid) required
projectId string (uuid) required
key string required
name string required
color string required
sortOrder integer required
createdAt string (date-time) required
updatedAt string (date-time) required

Example response

{
  "id": "e3-prd-0000-0000-000000000003",
  "projectId": "p1a2b3c4-d5e6-7890-abcd-ef1234567890",
  "key": "production",
  "name": "Production",
  "color": "#ef4444",
  "sortOrder": 2,
  "createdAt": "2025-01-15T10:30:00Z",
  "updatedAt": "2025-01-15T10:30:00Z"
}

GET /environments/{eid} Bearer JWT

Get environment details

Parameters

Name	Type	In	Description
`eid`required	`string (uuid)`	path	Environment ID

Response 200 — Environment details

id string (uuid) required
projectId string (uuid) required
key string required
name string required
color string required
sortOrder integer required
createdAt string (date-time) required
updatedAt string (date-time) required

Example response

{
  "id": "e3-prd-0000-0000-000000000003",
  "projectId": "p1a2b3c4-d5e6-7890-abcd-ef1234567890",
  "key": "production",
  "name": "Production",
  "color": "#ef4444",
  "sortOrder": 2,
  "createdAt": "2025-01-15T10:30:00Z",
  "updatedAt": "2025-01-15T10:30:00Z"
}

Errors

404 Resource not found

{
  "code": "not_found",
  "message": "resource not found"
}

PATCH /environments/{eid} Bearer JWT env:manage

Update environment

Parameters

Name	Type	In	Description
`eid`required	`string (uuid)`	path	Environment ID

Request body

name string
color string

Response 200 — Environment updated

id string (uuid) required
projectId string (uuid) required
key string required
name string required
color string required
sortOrder integer required
createdAt string (date-time) required
updatedAt string (date-time) required

Example response

{
  "id": "e3-prd-0000-0000-000000000003",
  "projectId": "p1a2b3c4-d5e6-7890-abcd-ef1234567890",
  "key": "production",
  "name": "Production",
  "color": "#ef4444",
  "sortOrder": 2,
  "createdAt": "2025-01-15T10:30:00Z",
  "updatedAt": "2025-01-15T14:22:00Z"
}

DELETE /environments/{eid} Bearer JWT env:manage

Delete environment

Parameters

Name	Type	In	Description
`eid`required	`string (uuid)`	path	Environment ID

Response 200 — Environment deleted

status string required

Example response

{
  "status": "ok"
}

Flags

Feature flag management

POST /projects/{pid}/flags Bearer JWT flag:create

Create a feature flag

Key must be kebab-case. Auto-provisions flag_environments for all project environments.

Parameters

Name	Type	In	Description
`pid`required	`string (uuid)`	path	Project ID

Request body

key string required

Must be kebab-case
name string required
description string
type boolean | string | number | json required
defaultValue any

Value when flag is enabled (defaults based on type)
offValue any

Value when flag is disabled (defaults based on type)

Response 201 — Flag created (includes environments)

id string (uuid) required
projectId string (uuid) required
key string required

Kebab-case flag key
name string required
description string | null
type boolean | string | number | json required
defaultValue any required

Value when flag is enabled but no targeting rule matches
offValue any required

Value when flag is disabled
archivedAt string | null
environments FlagEnvironment[]
- id string (uuid) required
- flagId string (uuid) required
- flagKey string
- environmentId string (uuid) required
- environmentKey string
- environmentColor string
- enabled boolean required
- valueOverride any
  
  Environment-specific value override
- rolloutPercentage integer | null
- targetingRuleCount integer required
- variants FlagVariant[]
- createdAt string (date-time) required
- updatedAt string (date-time) required
createdAt string (date-time) required
updatedAt string (date-time) required

Example response

{
  "id": "f1a2b3c4-d5e6-7890-abcd-ef1234567890",
  "projectId": "p1a2b3c4-d5e6-7890-abcd-ef1234567890",
  "key": "new-checkout-flow",
  "name": "New Checkout Flow",
  "type": "boolean",
  "defaultValue": true,
  "offValue": false,
  "environments": [
    {
      "id": "fe1a2b3c-d5e6-7890-abcd-ef1234567890",
      "flagId": "f1a2b3c4-d5e6-7890-abcd-ef1234567890",
      "environmentId": "e3-prd-0000-0000-000000000003",
      "environmentKey": "production",
      "environmentColor": "#ef4444",
      "enabled": false,
      "targetingRuleCount": 0,
      "createdAt": "2025-01-15T10:30:00Z",
      "updatedAt": "2025-01-15T10:30:00Z"
    }
  ],
  "createdAt": "2025-01-15T10:30:00Z",
  "updatedAt": "2025-01-15T10:30:00Z"
}

Errors

409 Resource already exists

{
  "code": "conflict",
  "message": "resource already exists"
}

422 Validation failed

{
  "code": "unprocessable_entity",
  "message": "validation failed"
}

GET /projects/{pid}/flags Bearer JWT

List flags in project

Parameters

Name	Type	In	Description
`pid`required	`string (uuid)`	path	Project ID

Response 200 — List of flags (includes environments and variants)

Flag[]

id string (uuid) required
projectId string (uuid) required
key string required

Kebab-case flag key
name string required
description string | null
type boolean | string | number | json required
defaultValue any required

Value when flag is enabled but no targeting rule matches
offValue any required

Value when flag is disabled
archivedAt string | null
environments FlagEnvironment[]
- id string (uuid) required
- flagId string (uuid) required
- flagKey string
- environmentId string (uuid) required
- environmentKey string
- environmentColor string
- enabled boolean required
- valueOverride any
  
  Environment-specific value override
- rolloutPercentage integer | null
- targetingRuleCount integer required
- variants FlagVariant[]
- createdAt string (date-time) required
- updatedAt string (date-time) required
createdAt string (date-time) required
updatedAt string (date-time) required

Example response

[
  {
    "id": "f1a2b3c4-d5e6-7890-abcd-ef1234567890",
    "projectId": "p1a2b3c4-d5e6-7890-abcd-ef1234567890",
    "key": "new-checkout-flow",
    "name": "New Checkout Flow",
    "type": "boolean",
    "defaultValue": true,
    "offValue": false,
    "environments": [
      {
        "id": "fe1a2b3c-d5e6-7890-abcd-ef1234567890",
        "flagId": "f1a2b3c4-d5e6-7890-abcd-ef1234567890",
        "environmentId": "e3-prd-0000-0000-000000000003",
        "environmentKey": "production",
        "environmentColor": "#ef4444",
        "enabled": true,
        "targetingRuleCount": 1,
        "createdAt": "2025-01-15T10:30:00Z",
        "updatedAt": "2025-01-15T14:22:00Z"
      }
    ],
    "createdAt": "2025-01-15T10:30:00Z",
    "updatedAt": "2025-01-15T14:22:00Z"
  }
]

GET /projects/{pid}/flags/stream Bearer JWT

Stream flag changes for console (SSE)

Server-Sent Events stream for real-time flag updates in the console dashboard.

Parameters

Name	Type	In	Description
`pid`required	`string (uuid)`	path	Project ID

GET /flags/{fid} Bearer JWT

Get flag details

Parameters

Name	Type	In	Description
`fid`required	`string (uuid)`	path	Flag ID

Response 200 — Flag details (includes environments and variants)

id string (uuid) required
projectId string (uuid) required
key string required

Kebab-case flag key
name string required
description string | null
type boolean | string | number | json required
defaultValue any required

Value when flag is enabled but no targeting rule matches
offValue any required

Value when flag is disabled
archivedAt string | null
environments FlagEnvironment[]
- id string (uuid) required
- flagId string (uuid) required
- flagKey string
- environmentId string (uuid) required
- environmentKey string
- environmentColor string
- enabled boolean required
- valueOverride any
  
  Environment-specific value override
- rolloutPercentage integer | null
- targetingRuleCount integer required
- variants FlagVariant[]
- createdAt string (date-time) required
- updatedAt string (date-time) required
createdAt string (date-time) required
updatedAt string (date-time) required

Example response

{
  "id": "f1a2b3c4-d5e6-7890-abcd-ef1234567890",
  "projectId": "p1a2b3c4-d5e6-7890-abcd-ef1234567890",
  "key": "new-checkout-flow",
  "name": "New Checkout Flow",
  "type": "boolean",
  "defaultValue": true,
  "offValue": false,
  "environments": [
    {
      "id": "fe1a2b3c-d5e6-7890-abcd-ef1234567890",
      "flagId": "f1a2b3c4-d5e6-7890-abcd-ef1234567890",
      "environmentId": "e3-prd-0000-0000-000000000003",
      "environmentKey": "production",
      "environmentColor": "#ef4444",
      "enabled": true,
      "targetingRuleCount": 1,
      "createdAt": "2025-01-15T10:30:00Z",
      "updatedAt": "2025-01-15T14:22:00Z"
    }
  ],
  "createdAt": "2025-01-15T10:30:00Z",
  "updatedAt": "2025-01-15T14:22:00Z"
}

Errors

404 Resource not found

{
  "code": "not_found",
  "message": "resource not found"
}

PATCH /flags/{fid} Bearer JWT flag:update

Update flag metadata

Parameters

Name	Type	In	Description
`fid`required	`string (uuid)`	path	Flag ID

Request body

name string
description string

Response 200 — Flag updated

id string (uuid) required
projectId string (uuid) required
key string required

Kebab-case flag key
name string required
description string | null
type boolean | string | number | json required
defaultValue any required

Value when flag is enabled but no targeting rule matches
offValue any required

Value when flag is disabled
archivedAt string | null
environments FlagEnvironment[]
- id string (uuid) required
- flagId string (uuid) required
- flagKey string
- environmentId string (uuid) required
- environmentKey string
- environmentColor string
- enabled boolean required
- valueOverride any
  
  Environment-specific value override
- rolloutPercentage integer | null
- targetingRuleCount integer required
- variants FlagVariant[]
- createdAt string (date-time) required
- updatedAt string (date-time) required
createdAt string (date-time) required
updatedAt string (date-time) required

Example response

{
  "id": "f1a2b3c4-d5e6-7890-abcd-ef1234567890",
  "projectId": "p1a2b3c4-d5e6-7890-abcd-ef1234567890",
  "key": "new-checkout-flow",
  "name": "New Checkout Flow",
  "type": "boolean",
  "defaultValue": true,
  "offValue": false,
  "createdAt": "2025-01-15T10:30:00Z",
  "updatedAt": "2025-01-15T14:22:00Z"
}

POST /flags/{fid}/archive Bearer JWT flag:archive

Archive a flag

Parameters

Name	Type	In	Description
`fid`required	`string (uuid)`	path	Flag ID

Response 200 — Flag archived

id string (uuid) required
projectId string (uuid) required
key string required

Kebab-case flag key
name string required
description string | null
type boolean | string | number | json required
defaultValue any required

Value when flag is enabled but no targeting rule matches
offValue any required

Value when flag is disabled
archivedAt string | null
environments FlagEnvironment[]
- id string (uuid) required
- flagId string (uuid) required
- flagKey string
- environmentId string (uuid) required
- environmentKey string
- environmentColor string
- enabled boolean required
- valueOverride any
  
  Environment-specific value override
- rolloutPercentage integer | null
- targetingRuleCount integer required
- variants FlagVariant[]
- createdAt string (date-time) required
- updatedAt string (date-time) required
createdAt string (date-time) required
updatedAt string (date-time) required

Example response

{
  "id": "f1a2b3c4-d5e6-7890-abcd-ef1234567890",
  "projectId": "p1a2b3c4-d5e6-7890-abcd-ef1234567890",
  "key": "new-checkout-flow",
  "name": "New Checkout Flow",
  "type": "boolean",
  "defaultValue": true,
  "offValue": false,
  "archivedAt": "2025-01-15T14:22:00Z",
  "createdAt": "2025-01-15T10:30:00Z",
  "updatedAt": "2025-01-15T14:22:00Z"
}

Flag Environments

Per-environment flag configuration (toggle, variants, promote)

PUT /flag-environments/{feid} Bearer JWT flag:toggle

Update flag environment config (enable/disable, rollout)

Use this to toggle a flag on/off in a specific environment.

Parameters

Name	Type	In	Description
`feid`required	`string (uuid)`	path	Flag environment ID

Request body

enabled boolean
valueOverride any

Environment-specific value override
rolloutPercentage integer

Response 200 — Flag environment updated

id string (uuid) required
flagId string (uuid) required
flagKey string
environmentId string (uuid) required
environmentKey string
environmentColor string
enabled boolean required
valueOverride any

Environment-specific value override
rolloutPercentage integer | null
targetingRuleCount integer required
variants FlagVariant[]
- id string (uuid) required
- flagEnvironmentId string (uuid) required
- key string required
- value any required
  
  Variant value (type matches flag type)
- weight integer required
  
  Percentage weight (all variant weights should sum to 100)
- createdAt string (date-time) required
createdAt string (date-time) required
updatedAt string (date-time) required

Example response

{
  "id": "fe1a2b3c-d5e6-7890-abcd-ef1234567890",
  "flagId": "f1a2b3c4-d5e6-7890-abcd-ef1234567890",
  "environmentId": "e3-prd-0000-0000-000000000003",
  "environmentKey": "production",
  "environmentColor": "#ef4444",
  "enabled": true,
  "rolloutPercentage": 50,
  "targetingRuleCount": 1,
  "createdAt": "2025-01-15T10:30:00Z",
  "updatedAt": "2025-01-15T14:22:00Z"
}

PUT /flag-environments/{feid}/variants Bearer JWT variant:set

Set flag variants (replace all)

Replaces all existing variants.

Parameters

Name	Type	In	Description
`feid`required	`string (uuid)`	path	Flag environment ID

Request body

variants VariantInput[]
- key string required
- value any required
  
  Variant value
- weight integer

Response 200 — Variants set

FlagVariant[]

id string (uuid) required
flagEnvironmentId string (uuid) required
key string required
value any required

Variant value (type matches flag type)
weight integer required

Percentage weight (all variant weights should sum to 100)
createdAt string (date-time) required

Example response

[
  {
    "id": "v1a2b3c4-d5e6-7890-abcd-ef1234567890",
    "flagEnvironmentId": "fe1a2b3c-d5e6-7890-abcd-ef1234567890",
    "key": "variant-a",
    "value": true,
    "weight": 50,
    "createdAt": "2025-01-15T14:22:00Z"
  }
]

POST /flag-environments/{feid}/promote Bearer JWT flag:promote

Promote flag config to another environment

Copies enabled state, value override, rollout percentage, and variants.

Parameters

Name	Type	In	Description
`feid`required	`string (uuid)`	path	Flag environment ID

Request body

targetEnvironmentId string (uuid) required

Response 200 — Config promoted

id string (uuid) required
flagId string (uuid) required
flagKey string
environmentId string (uuid) required
environmentKey string
environmentColor string
enabled boolean required
valueOverride any

Environment-specific value override
rolloutPercentage integer | null
targetingRuleCount integer required
variants FlagVariant[]
- id string (uuid) required
- flagEnvironmentId string (uuid) required
- key string required
- value any required
  
  Variant value (type matches flag type)
- weight integer required
  
  Percentage weight (all variant weights should sum to 100)
- createdAt string (date-time) required
createdAt string (date-time) required
updatedAt string (date-time) required

Example response

{
  "id": "fe1a2b3c-d5e6-7890-abcd-ef1234567890",
  "flagId": "f1a2b3c4-d5e6-7890-abcd-ef1234567890",
  "environmentId": "e3-prd-0000-0000-000000000003",
  "environmentKey": "production",
  "environmentColor": "#ef4444",
  "enabled": true,
  "rolloutPercentage": 100,
  "targetingRuleCount": 1,
  "createdAt": "2025-01-15T10:30:00Z",
  "updatedAt": "2025-01-15T14:22:00Z"
}

Segments

User segment management

POST /projects/{pid}/segments Bearer JWT segment:create

Create a user segment

Parameters

Name	Type	In	Description
`pid`required	`string (uuid)`	path	Project ID

Request body

name string required
matchType ALL | ANY required
rules SegmentRuleInput[]
- attribute string required
- operator equals | not_equals | contains | not_contains | starts_with | ends_with | in | not_in | gt | lt required
- value any required
  
  Comparison value

Response 201 — Segment created

id string (uuid) required
projectId string (uuid) required
name string required
matchType ALL | ANY required

ALL = AND logic, ANY = OR logic
rules SegmentRule[]
- id string (uuid) required
- segmentId string (uuid) required
- attribute string required
- operator equals | not_equals | contains | not_contains | starts_with | ends_with | in | not_in | gt | lt required
- value any required
  
  Comparison value (type depends on operator)
- createdAt string (date-time) required
createdAt string (date-time) required
updatedAt string (date-time) required

Example response

{
  "id": "s1a2b3c4-d5e6-7890-abcd-ef1234567890",
  "projectId": "p1a2b3c4-d5e6-7890-abcd-ef1234567890",
  "name": "Beta Users",
  "matchType": "ALL",
  "rules": [
    {
      "id": "sr1a2b3c-d5e6-7890-abcd-ef1234567890",
      "segmentId": "s1a2b3c4-d5e6-7890-abcd-ef1234567890",
      "attribute": "plan",
      "operator": "equals",
      "value": "pro",
      "createdAt": "2025-01-15T10:30:00Z"
    }
  ],
  "createdAt": "2025-01-15T10:30:00Z",
  "updatedAt": "2025-01-15T10:30:00Z"
}

GET /projects/{pid}/segments Bearer JWT

List segments in project

Parameters

Name	Type	In	Description
`pid`required	`string (uuid)`	path	Project ID

Response 200 — List of segments

Segment[]

id string (uuid) required
projectId string (uuid) required
name string required
matchType ALL | ANY required

ALL = AND logic, ANY = OR logic
rules SegmentRule[]
- id string (uuid) required
- segmentId string (uuid) required
- attribute string required
- operator equals | not_equals | contains | not_contains | starts_with | ends_with | in | not_in | gt | lt required
- value any required
  
  Comparison value (type depends on operator)
- createdAt string (date-time) required
createdAt string (date-time) required
updatedAt string (date-time) required

Example response

[
  {
    "id": "s1a2b3c4-d5e6-7890-abcd-ef1234567890",
    "projectId": "p1a2b3c4-d5e6-7890-abcd-ef1234567890",
    "name": "Beta Users",
    "matchType": "ALL",
    "createdAt": "2025-01-15T10:30:00Z",
    "updatedAt": "2025-01-15T14:22:00Z"
  }
]

GET /segments/{sid} Bearer JWT

Get segment details

Parameters

Name	Type	In	Description
`sid`required	`string (uuid)`	path	Segment ID

Response 200 — Segment details (includes rules)

id string (uuid) required
projectId string (uuid) required
name string required
matchType ALL | ANY required

ALL = AND logic, ANY = OR logic
rules SegmentRule[]
- id string (uuid) required
- segmentId string (uuid) required
- attribute string required
- operator equals | not_equals | contains | not_contains | starts_with | ends_with | in | not_in | gt | lt required
- value any required
  
  Comparison value (type depends on operator)
- createdAt string (date-time) required
createdAt string (date-time) required
updatedAt string (date-time) required

Example response

{
  "id": "s1a2b3c4-d5e6-7890-abcd-ef1234567890",
  "projectId": "p1a2b3c4-d5e6-7890-abcd-ef1234567890",
  "name": "Beta Users",
  "matchType": "ALL",
  "rules": [
    {
      "id": "sr1a2b3c-d5e6-7890-abcd-ef1234567890",
      "segmentId": "s1a2b3c4-d5e6-7890-abcd-ef1234567890",
      "attribute": "plan",
      "operator": "equals",
      "value": "pro",
      "createdAt": "2025-01-15T10:30:00Z"
    }
  ],
  "createdAt": "2025-01-15T10:30:00Z",
  "updatedAt": "2025-01-15T14:22:00Z"
}

Errors

404 Resource not found

{
  "code": "not_found",
  "message": "resource not found"
}

PATCH /segments/{sid} Bearer JWT segment:update

Update segment

Replaces all rules.

Parameters

Name	Type	In	Description
`sid`required	`string (uuid)`	path	Segment ID

Request body

name string
matchType ALL | ANY
rules SegmentRuleInput[]
- attribute string required
- operator equals | not_equals | contains | not_contains | starts_with | ends_with | in | not_in | gt | lt required
- value any required
  
  Comparison value

Response 200 — Segment updated

id string (uuid) required
projectId string (uuid) required
name string required
matchType ALL | ANY required

ALL = AND logic, ANY = OR logic
rules SegmentRule[]
- id string (uuid) required
- segmentId string (uuid) required
- attribute string required
- operator equals | not_equals | contains | not_contains | starts_with | ends_with | in | not_in | gt | lt required
- value any required
  
  Comparison value (type depends on operator)
- createdAt string (date-time) required
createdAt string (date-time) required
updatedAt string (date-time) required

Example response

{
  "id": "s1a2b3c4-d5e6-7890-abcd-ef1234567890",
  "projectId": "p1a2b3c4-d5e6-7890-abcd-ef1234567890",
  "name": "Beta Users",
  "matchType": "ALL",
  "rules": [
    {
      "id": "sr1a2b3c-d5e6-7890-abcd-ef1234567890",
      "segmentId": "s1a2b3c4-d5e6-7890-abcd-ef1234567890",
      "attribute": "plan",
      "operator": "equals",
      "value": "pro",
      "createdAt": "2025-01-15T10:30:00Z"
    }
  ],
  "createdAt": "2025-01-15T10:30:00Z",
  "updatedAt": "2025-01-15T14:22:00Z"
}

DELETE /segments/{sid} Bearer JWT segment:delete

Delete segment

Parameters

Name	Type	In	Description
`sid`required	`string (uuid)`	path	Segment ID

Response 200 — Segment deleted

status string required

Example response

{
  "status": "ok"
}

Targeting

Targeting rules for flag environments

GET /flag-environments/{feid}/targeting-rules Bearer JWT

Get targeting rules for flag environment

Parameters

Name	Type	In	Description
`feid`required	`string (uuid)`	path	Flag environment ID

Response 200 — List of targeting rules

TargetingRule[]

id string (uuid) required
flagEnvironmentId string (uuid) required
priority integer required

Evaluation order (lower = evaluated first)
segmentId string | null

Reference to a reusable segment
valueOverride any

Value to serve when rule matches
rolloutPercentage integer | null

Percentage of matching users who get valueOverride (murmur3 consistent hashing)
rolloutSalt string | null

Custom salt for rollout bucketing (defaults to flag key)
enabled boolean required
matchType ALL | ANY required

How inline conditions are combined
conditions TargetingCondition[]
- id string (uuid) required
- targetingRuleId string (uuid) required
- attribute string required
- operator equals | not_equals | contains | not_contains | starts_with | ends_with | in | not_in | gt | lt required
- value any required
  
  Comparison value
- createdAt string (date-time) required
createdAt string (date-time) required
updatedAt string (date-time) required

Example response

[
  {
    "id": "tr1a2b3c-d5e6-7890-abcd-ef1234567890",
    "flagEnvironmentId": "fe1a2b3c-d5e6-7890-abcd-ef1234567890",
    "priority": 1,
    "segmentId": "s1a2b3c4-d5e6-7890-abcd-ef1234567890",
    "valueOverride": true,
    "rolloutPercentage": 100,
    "enabled": true,
    "matchType": "ALL",
    "conditions": [
      {
        "id": "tc1a2b3c-d5e6-7890-abcd-ef1234567890",
        "targetingRuleId": "tr1a2b3c-d5e6-7890-abcd-ef1234567890",
        "attribute": "plan",
        "operator": "equals",
        "value": "pro",
        "createdAt": "2025-01-15T10:30:00Z"
      }
    ],
    "createdAt": "2025-01-15T10:30:00Z",
    "updatedAt": "2025-01-15T14:22:00Z"
  }
]

PUT /flag-environments/{feid}/targeting-rules Bearer JWT targeting:set

Set targeting rules (replace all)

Replaces all existing targeting rules. Rules are evaluated in order of priority.

Parameters

Name	Type	In	Description
`feid`required	`string (uuid)`	path	Flag environment ID

Request body

rules TargetingRuleInput[]
- segmentId string | null
- valueOverride any
  
  Value to serve when rule matches
- rolloutPercentage integer
- rolloutSalt string
- enabled boolean
- matchType ALL | ANY
- conditions TargetingConditionInput[]

Response 200 — Targeting rules set

TargetingRule[]

id string (uuid) required
flagEnvironmentId string (uuid) required
priority integer required

Evaluation order (lower = evaluated first)
segmentId string | null

Reference to a reusable segment
valueOverride any

Value to serve when rule matches
rolloutPercentage integer | null

Percentage of matching users who get valueOverride (murmur3 consistent hashing)
rolloutSalt string | null

Custom salt for rollout bucketing (defaults to flag key)
enabled boolean required
matchType ALL | ANY required

How inline conditions are combined
conditions TargetingCondition[]
- id string (uuid) required
- targetingRuleId string (uuid) required
- attribute string required
- operator equals | not_equals | contains | not_contains | starts_with | ends_with | in | not_in | gt | lt required
- value any required
  
  Comparison value
- createdAt string (date-time) required
createdAt string (date-time) required
updatedAt string (date-time) required

Example response

[
  {
    "id": "tr1a2b3c-d5e6-7890-abcd-ef1234567890",
    "flagEnvironmentId": "fe1a2b3c-d5e6-7890-abcd-ef1234567890",
    "priority": 1,
    "valueOverride": true,
    "rolloutPercentage": 100,
    "enabled": true,
    "matchType": "ALL",
    "conditions": [
      {
        "id": "tc1a2b3c-d5e6-7890-abcd-ef1234567890",
        "targetingRuleId": "tr1a2b3c-d5e6-7890-abcd-ef1234567890",
        "attribute": "plan",
        "operator": "equals",
        "value": "pro",
        "createdAt": "2025-01-15T14:22:00Z"
      }
    ],
    "createdAt": "2025-01-15T14:22:00Z",
    "updatedAt": "2025-01-15T14:22:00Z"
  }
]

API Keys

API key generation and management

POST /environments/{eid}/keys Bearer JWT apikey:manage

Generate a publishable + secret key pair

Returns full key values only once.

Parameters

Name	Type	In	Description
`eid`required	`string (uuid)`	path	Environment ID

Response 201 — Key pair generated

publishableKey string required

Full publishable key value (shown only once)
secretKey string required

Full secret key value (shown only once)
publishable object required
- id string (uuid) required
- environmentId string (uuid) required
- type publishable | secret required
- prefix string required
  
  Key prefix for identification (e.g. pk_live_abc...)
- lastUsedAt string | null
- revokedAt string | null
- createdBy string (uuid) required
- createdAt string (date-time) required
secret object required
- id string (uuid) required
- environmentId string (uuid) required
- type publishable | secret required
- prefix string required
  
  Key prefix for identification (e.g. pk_live_abc...)
- lastUsedAt string | null
- revokedAt string | null
- createdBy string (uuid) required
- createdAt string (date-time) required

Example response

{
  "publishableKey": "pk_prod_AbC12xYz_Y2xpZW50",
  "secretKey": "sk_prod_XyZ98aBc_c2VjcmV0",
  "publishable": {
    "id": "k1a2b3c4-d5e6-7890-abcd-ef1234567890",
    "environmentId": "e3-prd-0000-0000-000000000003",
    "type": "publishable",
    "prefix": "pk_prod_AbC12xYz",
    "createdBy": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "createdAt": "2025-01-15T10:30:00Z"
  },
  "secret": {
    "id": "k2b3c4d5-e6f7-8901-bcde-f12345678901",
    "environmentId": "e3-prd-0000-0000-000000000003",
    "type": "secret",
    "prefix": "sk_prod_XyZ98aBc",
    "createdBy": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "createdAt": "2025-01-15T10:30:00Z"
  }
}

GET /environments/{eid}/keys Bearer JWT

List API keys for environment

Parameters

Name	Type	In	Description
`eid`required	`string (uuid)`	path	Environment ID

Response 200 — List of API keys (prefix only, not full values)

APIKey[]

id string (uuid) required
environmentId string (uuid) required
type publishable | secret required
prefix string required

Key prefix for identification (e.g. pk_live_abc...)
lastUsedAt string | null
revokedAt string | null
createdBy string (uuid) required
createdAt string (date-time) required

Example response

[
  {
    "id": "k1a2b3c4-d5e6-7890-abcd-ef1234567890",
    "environmentId": "e3-prd-0000-0000-000000000003",
    "type": "publishable",
    "prefix": "pk_prod_AbC12xYz",
    "createdBy": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "createdAt": "2025-01-15T10:30:00Z"
  }
]

POST /environments/{eid}/keys/{kid}/revoke Bearer JWT apikey:manage

Revoke a specific API key

Parameters

Name	Type	In	Description
`eid`required	`string (uuid)`	path	Environment ID
`kid`required	`string (uuid)`	path	API key ID

Response 200 — Key revoked

status string required

Example response

{
  "status": "ok"
}

POST /environments/{eid}/keys/revoke Bearer JWT apikey:manage

Revoke all API keys for environment

Parameters

Name	Type	In	Description
`eid`required	`string (uuid)`	path	Environment ID

Response 200 — All keys revoked

status string required

Example response

{
  "status": "ok"
}

Audit

Audit log

GET /workspaces/{wid}/audit Bearer JWT audit:read

List audit events

(admin role).

Parameters

Name	Type	In	Description
`wid`required	`string (uuid)`	path	Workspace ID
`cursor`	`string`	query	Cursor for pagination (from `nextCursor` in previous response)
`limit`	`integer`	query	Number of events to return

Response 200 — Paginated audit events

data AuditEvent[] required
- id string (uuid) required
- workspaceId string (uuid) required
- actorUserId string (uuid) required
- action string required
- resourceType string required
- resourceId string (uuid) required
- metadata object | null
- ip string | null
- createdAt string (date-time) required
nextCursor string
hasMore boolean required

Example response

{
  "data": [
    {
      "id": "ae1a2b3c-d5e6-7890-abcd-ef1234567890",
      "workspaceId": "w1a2b3c4-d5e6-7890-abcd-ef1234567890",
      "actorUserId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "action": "flag.toggled",
      "resourceType": "flag",
      "resourceId": "f1a2b3c4-d5e6-7890-abcd-ef1234567890",
      "metadata": {
        "enabled": true,
        "environment": "production"
      },
      "createdAt": "2025-01-15T14:22:00Z"
    }
  ],
  "hasMore": false
}

Errors

403 Insufficient permissions

{
  "code": "forbidden",
  "message": "insufficient permissions"
}

Evaluation

Flag evaluation endpoints for SDKs (API-key auth)

GET /eval/flags API Key

List all evaluated flags for environment

Returns all flags with their current values for the environment associated with the API key. Rate limited to 100 req/sec per key.

Response 200 — List of evaluated flags

EvaluatedFlag[]

key string required
name string required
value any required

Current evaluated value (type matches flag type)
type boolean | string | number | json required
defaultValue any required

Default value when enabled and no targeting rule matches
offValue any required

Value when flag is disabled
enabled boolean required
rolloutPercentage integer | null
variants EvaluatedVariant[]
- key string required
- value any required
  
  Variant value
- weight integer required
createdAt string (date-time) required
updatedAt string (date-time) required

Example response

[
  {
    "key": "new-checkout-flow",
    "name": "New Checkout Flow",
    "value": true,
    "type": "boolean",
    "defaultValue": true,
    "offValue": false,
    "enabled": true,
    "rolloutPercentage": 100,
    "createdAt": "2025-01-15T10:30:00Z",
    "updatedAt": "2025-01-15T14:22:00Z"
  }
]

Errors

401 Authentication required or invalid

{
  "code": "unauthorized",
  "message": "authentication required"
}

429 Rate limit exceeded

{
  "code": "too_many_requests",
  "message": "rate limit exceeded"
}

POST /eval/flags/evaluate API Key

Evaluate all flags with user context

Evaluates all flags in the environment using targeting rules, segments, and rollout percentages against the provided user context.

Request body

userId string required

Unique user identifier for targeting and rollout bucketing
attributes object

User attributes for segment/targeting evaluation (e.g. plan, country, role)

Response 200 — All flags evaluated

EvaluatedFlag[]

key string required
name string required
value any required

Current evaluated value (type matches flag type)
type boolean | string | number | json required
defaultValue any required

Default value when enabled and no targeting rule matches
offValue any required

Value when flag is disabled
enabled boolean required
rolloutPercentage integer | null
variants EvaluatedVariant[]
- key string required
- value any required
  
  Variant value
- weight integer required
createdAt string (date-time) required
updatedAt string (date-time) required

Example response

[
  {
    "key": "new-checkout-flow",
    "name": "New Checkout Flow",
    "value": true,
    "type": "boolean",
    "defaultValue": true,
    "offValue": false,
    "enabled": true,
    "rolloutPercentage": 100,
    "createdAt": "2025-01-15T10:30:00Z",
    "updatedAt": "2025-01-15T14:22:00Z"
  }
]

GET /eval/flags/{key} API Key

Get a single evaluated flag by key

Parameters

Name	Type	In	Description
`key`required	`string`	path	Flag key (kebab-case)

Response 200 — Evaluated flag

key string required
name string required
value any required

Current evaluated value (type matches flag type)
type boolean | string | number | json required
defaultValue any required

Default value when enabled and no targeting rule matches
offValue any required

Value when flag is disabled
enabled boolean required
rolloutPercentage integer | null
variants EvaluatedVariant[]
- key string required
- value any required
  
  Variant value
- weight integer required
createdAt string (date-time) required
updatedAt string (date-time) required

Example response

{
  "key": "new-checkout-flow",
  "name": "New Checkout Flow",
  "value": true,
  "type": "boolean",
  "defaultValue": true,
  "offValue": false,
  "enabled": true,
  "rolloutPercentage": 100,
  "createdAt": "2025-01-15T10:30:00Z",
  "updatedAt": "2025-01-15T14:22:00Z"
}

Errors

404 Resource not found

{
  "code": "not_found",
  "message": "resource not found"
}

POST /eval/flags/{key}/evaluate API Key

Evaluate a single flag with user context

Evaluates a specific flag using targeting rules, segments, and rollout percentages against the provided user context. Uses murmur3 consistent hashing for rollout bucketing.

Parameters

Name	Type	In	Description
`key`required	`string`	path	Flag key (kebab-case)

Request body

userId string required

Unique user identifier for targeting and rollout bucketing
attributes object

User attributes for segment/targeting evaluation (e.g. plan, country, role)

Response 200 — Flag evaluated

key string required
name string required
value any required

Current evaluated value (type matches flag type)
type boolean | string | number | json required
defaultValue any required

Default value when enabled and no targeting rule matches
offValue any required

Value when flag is disabled
enabled boolean required
rolloutPercentage integer | null
variants EvaluatedVariant[]
- key string required
- value any required
  
  Variant value
- weight integer required
createdAt string (date-time) required
updatedAt string (date-time) required

Example response

{
  "key": "new-checkout-flow",
  "name": "New Checkout Flow",
  "value": true,
  "type": "boolean",
  "defaultValue": true,
  "offValue": false,
  "enabled": true,
  "rolloutPercentage": 100,
  "createdAt": "2025-01-15T10:30:00Z",
  "updatedAt": "2025-01-15T14:22:00Z"
}

Errors

404 Resource not found

{
  "code": "not_found",
  "message": "resource not found"
}

GET /eval/flags/stream API Key

Stream flag changes (SSE)