Feature Flags API Reference

Feature flags in Swisstools are organized at two levels. Global flags apply project-wide with an on/off toggle and an optional rollout percentage. Flag groups let you define a reusable set of flags (group flags) and then apply them to individual records — users, organizations, or any entity you identify — with per-record overrides. The SDK endpoint resolves all flag values for a record using an API key, so your application can fetch flag state at runtime without a session cookie. Every endpoint below is project-scoped and accepts either a dashboard session cookie or a project API key (Authorization: Bearer fk_… or the x-api-key header) — API keys are project-admin equivalent. The SDK endpoint (GET /api/flags/:recordId) is the one route that requires an API key. See Authentication for details. Project, flag, group, record, and environment IDs in these paths are public reference IDs (KSUIDs, ~27 chars) shown in the dashboard — the internal database UUID is not accepted in URLs. Flags and records resolve against an environment. Pass an optional ?env= query parameter (the environment’s key such as production, or its display name, case-insensitive) on read and check endpoints; when omitted, the project’s default environment is used.

Global Flags

List Flags

GET /api/projects/:projectId/flags Returns all global feature flags for the project, scoped to an environment. Path Parameters

projectId

string

required

The project’s public reference ID (KSUID), shown in Project settings → General.

env

string

Optional environment selector (the environment’s key or name). Defaults to the project’s default environment; an unknown value returns [].

Request

curl https://swisstools.dev/api/projects/3DS7IwHB2HHfSP61DzDHVTXt7KK/flags \
  -b cookies.txt

Response

[
  {
    "id": "2a9bX1c0d3e4f5g6h7i8j9k0",
    "projectId": "3DS7IwHB2HHfSP61DzDHVTXt7KK",
    "name": "Dark Mode",
    "key": "dark-mode",
    "enabled": true,
    "rollout": 100,
    "environment": { "id": "1Rkx7yLBcnX2tGZ4VqHfJp9wYsT", "name": "Production", "key": "production" },
    "createdAt": "2024-03-01T10:00:00.000Z",
    "updatedAt": "2024-03-01T10:00:00.000Z"
  }
]

Create Flag

POST /api/projects/:projectId/flags Creates a new global feature flag. Path Parameters

projectId

string

required

The project’s public reference ID (KSUID), shown in Project settings → General.

Request Body

name

string

required

Display name for the flag.

string

Optional user-supplied public reference ID (^[A-Za-z0-9_-]{1,128}$). Stored as-is and must be unique across the project’s flags. When omitted, a KSUID is generated.

key

string

A unique, URL-friendly identifier for the flag within this project (e.g., dark-mode). Defaults to a slug of name when omitted. Must be unique per project and environment.

enabled

boolean

Whether the flag is active. Defaults to false.

rollout

integer

Rollout percentage from 0 to 100. Defaults to 100.

environmentKey

string

Environment the flag is created in (accepts an environment key or name). Defaults to the project’s default environment.

Request

curl -X POST https://swisstools.dev/api/projects/3DS7IwHB2HHfSP61DzDHVTXt7KK/flags \
  -b cookies.txt \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Dark Mode",
    "key": "dark-mode",
    "enabled": true,
    "rollout": 100
  }'

Response — 201 Created

{
  "id": "2a9bX1c0d3e4f5g6h7i8j9k0",
  "projectId": "3DS7IwHB2HHfSP61DzDHVTXt7KK",
  "name": "Dark Mode",
  "key": "dark-mode",
  "enabled": true,
  "rollout": 100,
  "environment": { "id": "1Rkx7yLBcnX2tGZ4VqHfJp9wYsT", "name": "Production", "key": "production" },
  "createdAt": "2024-03-01T10:00:00.000Z",
  "updatedAt": "2024-03-01T10:00:00.000Z"
}

Get Flag

GET /api/projects/:projectId/flags/:flagId Returns a single global flag by its ID. Path Parameters

projectId

string

required

The project’s public reference ID (KSUID), shown in Project settings → General.

flagId

string

required

The flag’s public reference ID — a KSUID, or the value you supplied as id when creating the flag.

Request

curl https://swisstools.dev/api/projects/3DS7IwHB2HHfSP61DzDHVTXt7KK/flags/2a9bX1c0d3e4f5g6h7i8j9k0 \
  -b cookies.txt

Response

{
  "id": "2a9bX1c0d3e4f5g6h7i8j9k0",
  "projectId": "3DS7IwHB2HHfSP61DzDHVTXt7KK",
  "name": "Dark Mode",
  "key": "dark-mode",
  "enabled": true,
  "rollout": 100,
  "environment": { "id": "1Rkx7yLBcnX2tGZ4VqHfJp9wYsT", "name": "Production", "key": "production" },
  "createdAt": "2024-03-01T10:00:00.000Z",
  "updatedAt": "2024-03-01T10:00:00.000Z"
}

Update Flag

PUT /api/projects/:projectId/flags/:flagId Updates a global flag’s name, enabled state, or rollout percentage. Path Parameters

projectId

string

required

The project’s public reference ID (KSUID), shown in Project settings → General.

flagId

string

required

The flag’s public reference ID — a KSUID, or the value you supplied as id when creating the flag.

Request Body

name

string

Updated display name.

enabled

boolean

Updated enabled state.

rollout

integer

Updated rollout percentage.

Request

curl -X PUT https://swisstools.dev/api/projects/3DS7IwHB2HHfSP61DzDHVTXt7KK/flags/2a9bX1c0d3e4f5g6h7i8j9k0 \
  -b cookies.txt \
  -H "Content-Type: application/json" \
  -d '{"enabled": false, "rollout": 0}'

Response

{
  "id": "2a9bX1c0d3e4f5g6h7i8j9k0",
  "projectId": "3DS7IwHB2HHfSP61DzDHVTXt7KK",
  "name": "Dark Mode",
  "key": "dark-mode",
  "enabled": false,
  "rollout": 0,
  "environment": { "id": "1Rkx7yLBcnX2tGZ4VqHfJp9wYsT", "name": "Production", "key": "production" },
  "createdAt": "2024-03-01T10:00:00.000Z",
  "updatedAt": "2024-04-01T08:00:00.000Z"
}

Delete Flag

DELETE /api/projects/:projectId/flags/:flagId Permanently deletes a global flag. Request

curl -X DELETE https://swisstools.dev/api/projects/3DS7IwHB2HHfSP61DzDHVTXt7KK/flags/2a9bX1c0d3e4f5g6h7i8j9k0 \
  -b cookies.txt

Response

{"success": true}

Check Flag

GET /api/projects/:projectId/flags/check/:flagKey Checks whether a global flag is currently enabled by its key. Useful for server-side flag resolution without going through the SDK. Path Parameters

projectId

string

required

The project’s public reference ID (KSUID), shown in Project settings → General.

flagKey

string

required

The key value of the flag (e.g., dark-mode).

env

string

Optional environment selector (the environment’s key or name, case-insensitive). Defaults to the project’s default environment; an unknown value returns 404. Results are cached for 60 seconds in Redis per (project, flagKey, env).

Request

curl https://swisstools.dev/api/projects/3DS7IwHB2HHfSP61DzDHVTXt7KK/flags/check/dark-mode \
  -b cookies.txt

Response

{
  "enabled": true,
  "rollout": 75,
  "source": "global",
  "environment": { "id": "1Rkx7yLBcnX2tGZ4VqHfJp9wYsT", "name": "Production", "key": "production" }
}

enabled already reflects the rollout roll. source is "cache" when served from the Redis cache or "global" when freshly computed.

Flag Groups

Groups are reusable collections of flags that you attach to records (users, orgs, etc.). Each group has its own set of group flags with default values; records in the group can override any flag’s value.

List Groups

GET /api/projects/:projectId/groups Request

curl https://swisstools.dev/api/projects/3DS7IwHB2HHfSP61DzDHVTXt7KK/groups \
  -b cookies.txt

Response

[
  {
    "id": "1Rz7Y9LpH8mC3nQ4VkRwBpTfYsT",
    "projectId": "3DS7IwHB2HHfSP61DzDHVTXt7KK",
    "name": "Beta Users",
    "key": "beta-users",
    "prefix": "beta",
    "description": null,
    "color": "#8C7AB0",
    "createdAt": "2024-03-05T09:00:00.000Z",
    "updatedAt": "2024-03-05T09:00:00.000Z"
  }
]

Create Group

POST /api/projects/:projectId/groups Request Body

name

string

required

Display name for the group.

key

string

Unique identifier for the group within this project. Defaults to a slug of name when omitted.

prefix

string

A 2–5 character lowercase alphanumeric prefix used to namespace auto-generated record IDs in this group (e.g., beta). Must be unique per project. Auto-derived from name when omitted.

description

string

Optional description for the group.

color

string

Optional hex color used as the group’s label in the dashboard (e.g., #8C7AB0).

Request

curl -X POST https://swisstools.dev/api/projects/3DS7IwHB2HHfSP61DzDHVTXt7KK/groups \
  -b cookies.txt \
  -H "Content-Type: application/json" \
  -d '{"name": "Beta Users", "key": "beta-users", "prefix": "beta"}'

Response — 201 Created

{
  "id": "1Rz7Y9LpH8mC3nQ4VkRwBpTfYsT",
  "projectId": "3DS7IwHB2HHfSP61DzDHVTXt7KK",
  "name": "Beta Users",
  "key": "beta-users",
  "prefix": "beta",
  "description": null,
  "color": "#8C7AB0",
  "createdAt": "2024-03-05T09:00:00.000Z",
  "updatedAt": "2024-03-05T09:00:00.000Z"
}

Get Group

GET /api/projects/:projectId/groups/:groupId Request

curl https://swisstools.dev/api/projects/3DS7IwHB2HHfSP61DzDHVTXt7KK/groups/1Rz7Y9LpH8mC3nQ4VkRwBpTfYsT \
  -b cookies.txt

Response

{
  "id": "1Rz7Y9LpH8mC3nQ4VkRwBpTfYsT",
  "projectId": "3DS7IwHB2HHfSP61DzDHVTXt7KK",
  "name": "Beta Users",
  "key": "beta-users",
  "prefix": "beta",
  "description": null,
  "color": "#8C7AB0",
  "createdAt": "2024-03-05T09:00:00.000Z",
  "updatedAt": "2024-03-05T09:00:00.000Z"
}

Update Group

PUT /api/projects/:projectId/groups/:groupId Request Body

name

string

Updated display name.

key

string

Updated key.

prefix

string

Updated prefix.

Request

curl -X PUT https://swisstools.dev/api/projects/3DS7IwHB2HHfSP61DzDHVTXt7KK/groups/1Rz7Y9LpH8mC3nQ4VkRwBpTfYsT \
  -b cookies.txt \
  -H "Content-Type: application/json" \
  -d '{"name": "Early Access Users"}'

Response

{
  "id": "1Rz7Y9LpH8mC3nQ4VkRwBpTfYsT",
  "projectId": "3DS7IwHB2HHfSP61DzDHVTXt7KK",
  "name": "Early Access Users",
  "key": "beta-users",
  "prefix": "beta",
  "description": null,
  "color": "#8C7AB0",
  "createdAt": "2024-03-05T09:00:00.000Z",
  "updatedAt": "2024-04-10T14:00:00.000Z"
}

Delete Group

DELETE /api/projects/:projectId/groups/:groupId Request

curl -X DELETE https://swisstools.dev/api/projects/3DS7IwHB2HHfSP61DzDHVTXt7KK/groups/1Rz7Y9LpH8mC3nQ4VkRwBpTfYsT \
  -b cookies.txt

Response

{"success": true}

Group Flags

Group flags are the individual flags within a group. Each has a defaultEnabled and defaultPercentage that applies to all records unless overridden.

List Group Flags

GET /api/projects/:projectId/groups/:groupId/flags Request

curl https://swisstools.dev/api/projects/3DS7IwHB2HHfSP61DzDHVTXt7KK/groups/1Rz7Y9LpH8mC3nQ4VkRwBpTfYsT/flags \
  -b cookies.txt

Response

[
  {
    "id": "4kPq2Lm8nR3sT5vW7xY9zA1bC3d",
    "groupId": "1Rz7Y9LpH8mC3nQ4VkRwBpTfYsT",
    "name": "New Dashboard",
    "key": "new-dashboard",
    "defaultEnabled": true,
    "defaultPercentage": 100,
    "createdAt": "2024-03-05T09:30:00.000Z",
    "updatedAt": "2024-03-05T09:30:00.000Z"
  }
]

Create Group Flag

POST /api/projects/:projectId/groups/:groupId/flags Request Body

name

string

required

Display name for the flag.

key

string

required

Unique identifier within the group.

defaultEnabled

boolean

Default enabled state for records that have no override. Defaults to false.

defaultPercentage

integer

Default rollout percentage. Defaults to 100.

Request

curl -X POST https://swisstools.dev/api/projects/3DS7IwHB2HHfSP61DzDHVTXt7KK/groups/1Rz7Y9LpH8mC3nQ4VkRwBpTfYsT/flags \
  -b cookies.txt \
  -H "Content-Type: application/json" \
  -d '{
    "name": "New Dashboard",
    "key": "new-dashboard",
    "defaultEnabled": true,
    "defaultPercentage": 100
  }'

Response — 201 Created

{
  "id": "4kPq2Lm8nR3sT5vW7xY9zA1bC3d",
  "groupId": "1Rz7Y9LpH8mC3nQ4VkRwBpTfYsT",
  "name": "New Dashboard",
  "key": "new-dashboard",
  "defaultEnabled": true,
  "defaultPercentage": 100,
  "createdAt": "2024-03-05T09:30:00.000Z",
  "updatedAt": "2024-03-05T09:30:00.000Z"
}

Group Records

Records represent the entities (users, organizations, devices, etc.) that belong to a group. Each record’s id is either a stable identifier you supply from your own system, or — when you omit it — an auto-generated {groupPrefix}-{ksuid} value (e.g., beta-2a9bX1c0d3e4f5g6h7i8j9k0).

List Records

GET /api/projects/:projectId/groups/:groupId/records Request

curl https://swisstools.dev/api/projects/3DS7IwHB2HHfSP61DzDHVTXt7KK/groups/1Rz7Y9LpH8mC3nQ4VkRwBpTfYsT/records \
  -b cookies.txt

Response

[
  {
    "id": "user_alice_123",
    "group": { "id": "1Rz7Y9LpH8mC3nQ4VkRwBpTfYsT", "name": "Beta Users" },
    "name": "Alice",
    "metadata": {"plan": "pro", "region": "us-east"},
    "createdAt": "2024-03-10T08:00:00.000Z",
    "updatedAt": "2024-03-10T08:00:00.000Z"
  }
]

Create Record

POST /api/projects/:projectId/groups/:groupId/records Adds a record (entity) to the group. Request Body

string

Optional stable identifier from your own system (^[A-Za-z0-9_-]{1,128}$), stored verbatim and unique across all records. When omitted, the server generates {groupPrefix}-{ksuid}. Supplying your own entity ID lets SDK callers resolve flags via GET /api/flags/{yourId} directly.

name

string

Optional human-readable label for this record, shown in the dashboard.

metadata

object

Optional JSON object with arbitrary key-value pairs (e.g., plan, region, cohort).

Request — user-supplied ID

curl -X POST https://swisstools.dev/api/projects/3DS7IwHB2HHfSP61DzDHVTXt7KK/groups/1Rz7Y9LpH8mC3nQ4VkRwBpTfYsT/records \
  -b cookies.txt \
  -H "Content-Type: application/json" \
  -d '{
    "id": "user_alice_123",
    "name": "Alice",
    "metadata": {"plan": "pro", "region": "us-east"}
  }'

To let the server generate the ID instead, omit id (e.g. -d '{"name": "Alice"}'); the response id will be {groupPrefix}-{ksuid}. Response — 201 Created

{
  "id": "user_alice_123",
  "group": { "id": "1Rz7Y9LpH8mC3nQ4VkRwBpTfYsT", "name": "Beta Users" },
  "name": "Alice",
  "metadata": {"plan": "pro", "region": "us-east"},
  "createdAt": "2024-03-10T08:00:00.000Z",
  "updatedAt": "2024-03-10T08:00:00.000Z"
}

Environments

Flags and overrides are scoped to environments (e.g. production, staging). Reference an environment by its key or name via the ?env= query parameter on read/check endpoints; omitting it uses the project’s default environment.

List Environments

GET /api/projects/:projectId/environments

curl https://swisstools.dev/api/projects/3DS7IwHB2HHfSP61DzDHVTXt7KK/environments \
  -b cookies.txt

Response

[
  { "id": "1Rkx7yLBcnX2tGZ4VqHfJp9wYsT", "name": "Production", "key": "production", "isDefault": true }
]

Create Environment

POST /api/projects/:projectId/environments Request Body

name

string

required

Display name for the environment (e.g., Staging).

key

string

URL-friendly identifier (e.g., staging). Defaults to a slug of name.

isDefault

boolean

Whether this becomes the project’s default environment. Defaults to false.

curl -X POST https://swisstools.dev/api/projects/3DS7IwHB2HHfSP61DzDHVTXt7KK/environments \
  -b cookies.txt \
  -H "Content-Type: application/json" \
  -d '{"name": "Staging", "key": "staging"}'

Per-Record Overrides

Set or clear an individual record’s value for a group flag in a given environment: PUT /api/projects/:projectId/groups/:groupId/records/:recordId/values/:groupFlagId

curl -X PUT https://swisstools.dev/api/projects/3DS7IwHB2HHfSP61DzDHVTXt7KK/groups/1Rz7Y9LpH8mC3nQ4VkRwBpTfYsT/records/user_alice_123/values/4kPq2Lm8nR3sT5vW7xY9zA1bC3d \
  -b cookies.txt \
  -H "Content-Type: application/json" \
  -d '{"enabled": true, "rollout": 100, "environmentKey": "production"}'

To read the raw overrides currently set for a record (override-vs-default state, before the rollout roll), use GET /api/projects/:projectId/records/:recordId/values.

SDK Endpoint

GET /api/flags/:recordId Resolves all feature flag values for a given record. This endpoint uses API key bearer auth rather than a session cookie, so you can call it from your backend or edge functions at runtime. The response maps each group flag key to its resolved value for the specified record and environment, taking per-record overrides into account. enabled is the final decision — the server applies the rollout dice-roll, so a flag that is on but outside the rollout returns enabled: false. Path Parameters

recordId

string

required

The ID of the record whose flags you want to resolve — the auto-generated {groupPrefix}-{ksuid} form or the value you supplied as id. Must belong to the same project as the API key.

env

string

Optional environment selector (the environment’s key or name). Defaults to the project’s default environment. If it doesn’t match any environment, environment is null and flags is {}.

Request

curl https://swisstools.dev/api/flags/user_alice_123 \
  -H "Authorization: Bearer fk_2a9bX1c0d3e4f5g6h7i8j9k0"

Response

{
  "recordId": "user_alice_123",
  "projectId": "3DS7IwHB2HHfSP61DzDHVTXt7KK",
  "environment": { "id": "1Rkx7yLBcnX2tGZ4VqHfJp9wYsT", "name": "Production", "key": "production" },
  "flags": {
    "new-dashboard": {"enabled": true, "rollout": 100, "source": "record"},
    "beta-export":   {"enabled": false, "rollout": 0, "source": "group-default"}
  }
}

Each flag’s source is "record" when the value comes from a per-record override, or "group-default" when it falls back to the group flag’s defaultEnabled / defaultPercentage.

Documentation Index

​Global Flags

​List Flags

​Create Flag

​Get Flag

​Update Flag

​Delete Flag

​Check Flag

​Flag Groups

​List Groups

​Create Group

​Get Group

​Update Group

​Delete Group

​Group Flags

​List Group Flags

​Create Group Flag

​Group Records

​List Records

​Create Record

​Environments

​List Environments

​Create Environment

​Per-Record Overrides

​SDK Endpoint

Global Flags

List Flags

Create Flag

Get Flag

Update Flag

Delete Flag

Check Flag

Flag Groups

List Groups

Create Group

Get Group

Update Group

Delete Group

Group Flags

List Group Flags

Create Group Flag

Group Records

List Records

Create Record

Environments

List Environments

Create Environment

Per-Record Overrides

SDK Endpoint