Manage Flags

/api/v1/org/flags and /api/v1/org/flag-environments are the management surface behind the dashboard and the grantiva CLI. The SDK-facing GET /api/v1/flags only reads resolved values; everything here writes configuration.

Authentication

Operation	Key scope	Session role
Read	`flags:read`	viewer+
Write	`flags:write`	member+

Send an API key as Authorization: Bearer gpat_…/aat_…, or use a dashboard session. Wire format is snake_case. :flagRef accepts either the flag’s UUID or its flag_key.

The flag object

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "flag_key": "dark_mode",
  "name": "Dark Mode",
  "description": "Enables the dark colour scheme",
  "app_id": null,
  "value_type": "boolean",
  "is_active": true,
  "environment_values": {
    "production": { "on_value": "true", "off_value": "false", "is_active": true },
    "staging": { "on_value": "true", "off_value": "false", "is_active": false }
  },
  "rule_count": 2,
  "created_at": "2026-01-15T12:00:00Z",
  "updated_at": "2026-07-01T08:30:00Z"
}

Field	Description
`app_id`	The app this flag is scoped to, or `null` for an organization-wide flag
`value_type`	`boolean`, `integer`, `double`, `string`, or `json`
`is_active`	The global kill switch. Turning it off also deactivates the flag in every environment
`environment_values`	Keyed by environment slug. `is_active` per environment decides whether the SDK receives `on_value` or `off_value`
`rule_count`	Number of active targeting rules

List flags

GET /api/v1/org/flags

Returns an array of flag objects sorted by flag_key.

Parameter	Type	Description
`app_id`	UUID	Only flags scoped to this app. A non-UUID returns `400`
`environment`	string	Restrict `environment_values` to this slug. An unknown slug returns `404`

Create a flag

POST /api/v1/org/flags

{
  "flag_key": "dark_mode",
  "name": "Dark Mode",
  "description": "Enables the dark colour scheme",
  "app_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "value_type": "boolean",
  "is_active": true,
  "environment_values": {
    "production": { "on_value": "true", "off_value": "false", "is_active": false }
  }
}

Field	Type	Required	Description
`flag_key`	string	Yes	Lowercase letters, digits, and underscores, starting with a letter. Unique per organization
`name`	string	Yes	Display name
`value_type`	string	Yes	`boolean`, `integer`, `double`, `string`, or `json`
`description`	string	No	Free-form description
`app_id`	UUID string	No	Scope the flag to one app. Must belong to your organization
`is_active`	boolean	No	Global kill switch
`environment_values`	object	No	Per-slug values. Slugs must exist. Environments you omit get type-appropriate defaults

The flag row, its per-environment values, and this payload commit together — a rejected request leaves nothing behind. Response — the created flag object.

Get a flag

GET /api/v1/org/flags/:flagRef

Returns the flag with its rules and overrides inlined:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "flag_key": "dark_mode",
  "name": "Dark Mode",
  "description": null,
  "app_id": null,
  "value_type": "boolean",
  "is_active": true,
  "environment_values": {
    "production": { "on_value": "true", "off_value": "false", "is_active": true }
  },
  "rules": [
    {
      "id": "6f9619ff-8b86-d011-b42d-00cf4fc964ff",
      "name": "Beta testers on iOS 18+",
      "priority": 0,
      "value": "true",
      "rollout_percentage": 50,
      "is_active": true
    }
  ],
  "overrides": [
    {
      "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "flag_id": "550e8400-e29b-41d4-a716-446655440000",
      "device_key_id": "abc123",
      "forced_value": "true",
      "expires_at": "2026-04-01T00:00:00Z",
      "created_at": "2026-03-01T12:00:00Z",
      "created_by": "qa@example.com"
    }
  ],
  "created_at": "2026-01-15T12:00:00Z",
  "updated_at": "2026-07-01T08:30:00Z"
}

Rules are sorted by priority; overrides newest first.

Update a flag

PUT /api/v1/org/flags/:flagRef

Partial update — only the fields you send change. flag_key and value_type are immutable.

{
  "name": "Dark Mode (v2)",
  "is_active": false,
  "environment_values": {
    "staging": { "is_active": true }
  }
}

is_active is applied first and propagates to every environment; the environment_values you name are then applied on top, so a per-environment is_active wins for exactly those environments. Response — the updated flag object.

Toggle a flag

POST /api/v1/org/flags/:flagRef/toggle

{ "is_active": true, "environment": "staging" }

Field	Type	Description
`is_active`	boolean	The state to set. Omit it (or send an empty body) to flip the current state
`environment`	string	Toggle only this environment. Omit to toggle globally, across every environment

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "flag_key": "dark_mode",
  "is_active": true,
  "environment": "staging"
}

A body that is present but doesn’t decode returns 400 rather than being treated as a flip.

Delete a flag

DELETE /api/v1/org/flags/:flagRef

{ "deleted": true, "id": "550e8400-e29b-41d4-a716-446655440000" }

Change history

GET /api/v1/org/flags/:flagRef/history

Parameter	Type	Default	Description
`limit`	int	20	1–100
`offset`	int	0	Entries to skip

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "flag_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "actor_email": "dev@example.com",
    "change_type": "flag.updated",
    "summary": "Updated flag settings",
    "created_at": "2026-07-01T08:30:00Z"
  }
]

change_type is the audit action — flag.created, flag.updated, flag.toggled, flag.deleted, flag.rule_created, flag.rule_updated, flag.rule_deleted, flag.override_created, or flag.override_deleted — and summary is its human-readable form.

Recent evaluations

GET /api/v1/org/flags/:flagRef/evaluations

Parameter	Type	Default	Description
`limit`	int	50	1–200

{
  "evaluations": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "device_key_id": "abc123",
      "value": "true",
      "evaluated_at": "2026-07-26T11:59:31Z"
    }
  ]
}

Newest first. device_key_id is null when the device sent no X-Device-ID.

Overrides

GET    /api/v1/org/flags/:flagRef/overrides
POST   /api/v1/org/flags/:flagRef/overrides
DELETE /api/v1/org/flags/:flagRef/overrides/:overrideId

{
  "device_key_id": "abc123",
  "forced_value": "true",
  "expires_at": "2026-04-01T00:00:00Z"
}

Same rules as the dashboard surface — see Flag Overrides for semantics and validation. Delete returns 204 No Content.

Environments

GET    /api/v1/org/flag-environments
POST   /api/v1/org/flag-environments
PUT    /api/v1/org/flag-environments/:envId
DELETE /api/v1/org/flag-environments/:envId

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Production",
  "slug": "production",
  "color": "#6b7280",
  "is_default": true,
  "sort_order": 0,
  "created_at": "2026-01-15T12:00:00Z"
}

Create takes { "name": "QA", "slug": "qa", "color": "#22c55e" }. slug defaults to a slugified name; color defaults to #6b7280. Update is partial and accepts name, color, sort_order, and reorder ("up" or "down" to move the environment in the list). Delete returns { "deleted": true, "id": "…" } and refuses (403) on the default environment.

Errors

Status	Meaning
400	Invalid `flag_key` format, unknown `value_type`, `app_id` that is not a UUID or not one of your apps, or an invalid `reorder` direction
401	No session and no API key
403	Key lacks the required scope, session role too low, feature-flag or environment tier limit reached, or deleting the default environment
404	No such flag, override, or environment — including an `environment_values` slug that doesn’t exist
409	A flag with that `flag_key`, or an environment with that slug, already exists

Overview

Attestation

Platform

Feedback

Feature Flags

Custom Claims

Analytics

Webhooks

Organization

Push

Entitlements

Visual Regression Testing

Auth

Authentication

The flag object

List flags

Create a flag

Get a flag

Update a flag

Toggle a flag

Delete a flag

Change history

Recent evaluations

Overrides

Environments

Errors

See also

​Authentication

​The flag object

​List flags

​Create a flag

​Get a flag

​Update a flag

​Toggle a flag

​Delete a flag

​Change history

​Recent evaluations

​Overrides

​Environments

​Errors

​See also

Authentication

The flag object

List flags

Create a flag

Get a flag

Update a flag

Toggle a flag

Delete a flag

Change history

Recent evaluations

Overrides

Environments

Errors

See also