# Feature flags

Create and change a project's feature flags, their environments and targeting rules.

Source: https://docs.orbits.africa/api/flags

A flag has a value per environment and, in each, rules that pick a value for some visitors. Your app reads flags with `@useorbits/flags`, using the environment's key that deployments get as `ORBITS_FLAGS`. See [Feature flags](https://docs.orbits.africa/features/flags).

Endpoints:

- `GET /v1/teams/{team}/projects/{project}/flags`: A project's feature flags
- `POST /v1/teams/{team}/projects/{project}/flags`: Create a flag
- `GET /v1/teams/{team}/projects/{project}/flag-keys`: Each environment's ORBITS_FLAGS key
- `GET /v1/teams/{team}/projects/{project}/flags/{flag}`: A flag, its history and who it was checked for
- `PATCH /v1/teams/{team}/projects/{project}/flags/{flag}`: Change a flag's description
- `DELETE /v1/teams/{team}/projects/{project}/flags/{flag}`: Delete a flag
- `PUT /v1/teams/{team}/projects/{project}/flags/{flag}/environments/{environment}`: Switch a flag, set its rollout or its value in one environment
- `POST /v1/teams/{team}/projects/{project}/flags/{flag}/environments/{environment}/rules`: Add a targeting rule
- `PATCH /v1/teams/{team}/projects/{project}/flags/{flag}/environments/{environment}/rules/{rule}`: Change what a rule serves
- `DELETE /v1/teams/{team}/projects/{project}/flags/{flag}/environments/{environment}/rules/{rule}`: Remove a rule

## The flag object



- `key` (string, required)
- `description` (string, required)
- `type` (string, required): One of `boolean`, `string`, `number`.
- `environments` (object, required)
  - `production` (FlagEnvironment, required)
    - `on` (boolean, required): A boolean flag's switch; always true for the others.
    - `rollout` (integer, required): From 1 to 100.
    - `value` (string | number or null, required): A string or number flag's value; null for a boolean.
    - `rules` (array of FlagRule, required)
      - `id` (string, required)
      - `attribute` (string, required)
      - `operator` (string, required): One of `equals`, `not_equals`, `one_of`, `ends_with`, `starts_with`, `contains`.
      - `values` (array of string, required)
      - `serve` (boolean | string | number, required)
      - `label` (string, required)
  - `preview` (FlagEnvironment, required)
    - `on` (boolean, required): A boolean flag's switch; always true for the others.
    - `rollout` (integer, required): From 1 to 100.
    - `value` (string | number or null, required): A string or number flag's value; null for a boolean.
    - `rules` (array of FlagRule, required)
      - `id` (string, required)
      - `attribute` (string, required)
      - `operator` (string, required): One of `equals`, `not_equals`, `one_of`, `ends_with`, `starts_with`, `contains`.
      - `values` (array of string, required)
      - `serve` (boolean | string | number, required)
      - `label` (string, required)
  - `development` (FlagEnvironment, required)
    - `on` (boolean, required): A boolean flag's switch; always true for the others.
    - `rollout` (integer, required): From 1 to 100.
    - `value` (string | number or null, required): A string or number flag's value; null for a boolean.
    - `rules` (array of FlagRule, required)
      - `id` (string, required)
      - `attribute` (string, required)
      - `operator` (string, required): One of `equals`, `not_equals`, `one_of`, `ends_with`, `starts_with`, `contains`.
      - `values` (array of string, required)
      - `serve` (boolean | string | number, required)
      - `label` (string, required)
- `created_by` (FlagPerson, required)
  - `id` (string, required)
  - `name` (string, required)
  - `email` (string, required)
  - `avatar_url` (string or null, required)
- `updated_by` (FlagPerson, required)
  - `id` (string, required)
  - `name` (string, required)
  - `email` (string, required)
  - `avatar_url` (string or null, required)
- `created_at` (string, required)
- `updated_at` (string, required)
## A project's feature flags

```http
GET /v1/teams/{team}/projects/{project}/flags
```

The Flags page: every flag, newest first, with each environment's setting. `q` matches the key or description, `type` narrows to one type; `total` counts them all, for "3 of 5 flags".

**Permissions:** Any team member. A non-member gets 404.

Token: any API token (`read` or `full`).

Path parameters:

- `team`: Team slug or `team_` id.
- `project`: Project slug or `prj_` id.

Query parameters:

- `q` (string): At most 100 characters.
- `type` (string): One of `boolean`, `string`, `number`.

Example:

```sh
curl "https://api.theorbits.app/v1/teams/my-team/projects/my-app/flags" \
  -H "Authorization: Bearer $ORBITS_TOKEN"
```

Response `200`:

```json
{
  "items": [
    {
      "key": "new-checkout",
      "description": "description",
      "type": "boolean",
      "environments": {
        "production": {
          "on": false,
          "rollout": 1,
          "value": null,
          "rules": [
            {
              "id": null,
              "attribute": null,
              "operator": null,
              "values": null,
              "serve": null,
              "label": null
            }
          ]
        },
        "preview": {
          "on": false,
          "rollout": 1,
          "value": null,
          "rules": [
            {
              "id": null,
              "attribute": null,
              "operator": null,
              "values": null,
              "serve": null,
              "label": null
            }
          ]
        },
        "development": {
          "on": false,
          "rollout": 1,
          "value": null,
          "rules": [
            {
              "id": null,
              "attribute": null,
              "operator": null,
              "values": null,
              "serve": null,
              "label": null
            }
          ]
        }
      },
      "created_by": {
        "id": "id",
        "name": "my-app",
        "email": "ada@example.com",
        "avatar_url": "https://my-app.theorbits.app"
      },
      "updated_by": {
        "id": "id",
        "name": "my-app",
        "email": "ada@example.com",
        "avatar_url": "https://my-app.theorbits.app"
      },
      "created_at": "2026-11-10T09:30:00Z",
      "updated_at": "2026-11-10T09:30:00Z"
    }
  ],
  "total": 1
}
```

Errors:

- `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose).
- `422`: Validation failed, or the Idempotency-Key was reused with a different body.
## Create a flag

```http
POST /v1/teams/{team}/projects/{project}/flags
```

A boolean flag starts off in each environment unless `environments.<name>.on` says otherwise, at 100% rollout and with no rules. A string or number flag needs `environments.<name>.value` for all three. Keys are lowercase letters, digits and single dashes, unique in the project.

**Permissions:** Owners, admins and members. Viewers get 403.

Token: a `full` API token. Send an `Idempotency-Key` header.

Path parameters:

- `team`: Team slug or `team_` id.
- `project`: Project slug or `prj_` id.

Body:

- `key` (string, required): At most 48 characters.
- `description` (string): At most 120 characters.
- `type` (string, required): One of `boolean`, `string`, `number`.
- `environments` (object)
  - `production` (object)
    - `on` (boolean): A boolean flag's switch.
    - `value` (string | number): A string or number flag's value.
  - `preview` (object)
    - `on` (boolean): A boolean flag's switch.
    - `value` (string | number): A string or number flag's value.
  - `development` (object)
    - `on` (boolean): A boolean flag's switch.
    - `value` (string | number): A string or number flag's value.

Example:

```sh
curl -X POST "https://api.theorbits.app/v1/teams/my-team/projects/my-app/flags" \
  -H "Authorization: Bearer $ORBITS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "new-checkout",
    "type": "boolean"
  }'
```

Response `201`:

```json
{
  "key": "new-checkout",
  "description": "description",
  "type": "boolean",
  "environments": {
    "production": {
      "on": false,
      "rollout": 1,
      "value": null,
      "rules": [
        {
          "id": "id",
          "attribute": "email",
          "operator": "equals",
          "values": [
            "values"
          ],
          "serve": false,
          "label": "Email ends with @kudi.ng"
        }
      ]
    },
    "preview": {
      "on": false,
      "rollout": 1,
      "value": null,
      "rules": [
        {
          "id": "id",
          "attribute": "email",
          "operator": "equals",
          "values": [
            "values"
          ],
          "serve": false,
          "label": "Email ends with @kudi.ng"
        }
      ]
    },
    "development": {
      "on": false,
      "rollout": 1,
      "value": null,
      "rules": [
        {
          "id": "id",
          "attribute": "email",
          "operator": "equals",
          "values": [
            "values"
          ],
          "serve": false,
          "label": "Email ends with @kudi.ng"
        }
      ]
    }
  },
  "created_by": {
    "id": "id",
    "name": "my-app",
    "email": "ada@example.com",
    "avatar_url": "https://my-app.theorbits.app"
  },
  "updated_by": {
    "id": "id",
    "name": "my-app",
    "email": "ada@example.com",
    "avatar_url": "https://my-app.theorbits.app"
  },
  "created_at": "2026-11-10T09:30:00Z",
  "updated_at": "2026-11-10T09:30:00Z"
}
```

Errors:

- `403`: Authenticated but not allowed in this team.
- `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose).
- `422`: Validation failed, or the Idempotency-Key was reused with a different body.
## Each environment's ORBITS_FLAGS key

```http
GET /v1/teams/{team}/projects/{project}/flag-keys
```

Deployments get their environment's key as `ORBITS_FLAGS` (and the API's address as `ORBITS_API_URL`) without asking. These are for code that runs elsewhere: put `development`'s in `.env.local` to read Development's flags locally. A key reads its environment's flags and reports checks, nothing else.

**Permissions:** Owners, admins and members. Viewers get 403.

Token: any API token (`read` or `full`).

Path parameters:

- `team`: Team slug or `team_` id.
- `project`: Project slug or `prj_` id.

Example:

```sh
curl "https://api.theorbits.app/v1/teams/my-team/projects/my-app/flag-keys" \
  -H "Authorization: Bearer $ORBITS_TOKEN"
```

Response `200`:

```json
{
  "production": "ofl_cHJqXzE6cHJvZHVjdGlvbg.k3W…",
  "preview": "preview",
  "development": "development"
}
```

Errors:

- `403`: Authenticated but not allowed in this team.
- `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose).
## A flag, its history and who it was checked for

```http
GET /v1/teams/{team}/projects/{project}/flags/{flag}
```

The flag's page. `history` is newest first, 50 at most, each line written as the page says it. `seen` is each environment's last 24 hours as the SDK reported them: `people` the ids it was checked for, `checks` every check, with or without one.

**Permissions:** Any team member.

Token: any API token (`read` or `full`).

Path parameters:

- `team`: Team slug or `team_` id.
- `project`: Project slug or `prj_` id.
- `flag`

Example:

```sh
curl "https://api.theorbits.app/v1/teams/my-team/projects/my-app/flags/new-checkout" \
  -H "Authorization: Bearer $ORBITS_TOKEN"
```

Response `200`:

```json
{
  "key": "new-checkout",
  "description": "description",
  "type": "boolean",
  "environments": {
    "production": {
      "on": false,
      "rollout": 1,
      "value": null,
      "rules": [
        {
          "id": "id",
          "attribute": "email",
          "operator": null,
          "values": [
            null
          ],
          "serve": false,
          "label": "Email ends with @kudi.ng"
        }
      ]
    },
    "preview": {
      "on": false,
      "rollout": 1,
      "value": null,
      "rules": [
        {
          "id": "id",
          "attribute": "email",
          "operator": null,
          "values": [
            null
          ],
          "serve": false,
          "label": "Email ends with @kudi.ng"
        }
      ]
    },
    "development": {
      "on": false,
      "rollout": 1,
      "value": null,
      "rules": [
        {
          "id": "id",
          "attribute": "email",
          "operator": null,
          "values": [
            null
          ],
          "serve": false,
          "label": "Email ends with @kudi.ng"
        }
      ]
    }
  },
  "created_by": {
    "id": "id",
    "name": "my-app",
    "email": "ada@example.com",
    "avatar_url": "https://my-app.theorbits.app"
  },
  "updated_by": {
    "id": "id",
    "name": "my-app",
    "email": "ada@example.com",
    "avatar_url": "https://my-app.theorbits.app"
  },
  "created_at": "2026-11-10T09:30:00Z",
  "updated_at": "2026-11-10T09:30:00Z",
  "history": [
    {
      "id": "id",
      "by": {
        "id": "id",
        "name": "my-app",
        "email": "ada@example.com",
        "avatar_url": "https://my-app.theorbits.app"
      },
      "text": "Set Preview rollout to 10%",
      "at": "2026-11-10T09:30:00Z"
    }
  ],
  "seen": {
    "production": {
      "people": 1,
      "checks": 1
    },
    "preview": {
      "people": 1,
      "checks": 1
    },
    "development": {
      "people": 1,
      "checks": 1
    }
  }
}
```

Errors:

- `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose).
## Change a flag's description

```http
PATCH /v1/teams/{team}/projects/{project}/flags/{flag}
```

The key and type never change; make another flag for that.

**Permissions:** Owners, admins and members.

Token: a `full` API token.

Path parameters:

- `team`: Team slug or `team_` id.
- `project`: Project slug or `prj_` id.
- `flag`

Body:

- `description` (string): At most 120 characters.

Example:

```sh
curl -X PATCH "https://api.theorbits.app/v1/teams/my-team/projects/my-app/flags/new-checkout" \
  -H "Authorization: Bearer $ORBITS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "description"
  }'
```

Response `200`:

```json
{
  "key": "new-checkout",
  "description": "description",
  "type": "boolean",
  "environments": {
    "production": {
      "on": false,
      "rollout": 1,
      "value": null,
      "rules": [
        {
          "id": "id",
          "attribute": "email",
          "operator": "equals",
          "values": [
            "values"
          ],
          "serve": false,
          "label": "Email ends with @kudi.ng"
        }
      ]
    },
    "preview": {
      "on": false,
      "rollout": 1,
      "value": null,
      "rules": [
        {
          "id": "id",
          "attribute": "email",
          "operator": "equals",
          "values": [
            "values"
          ],
          "serve": false,
          "label": "Email ends with @kudi.ng"
        }
      ]
    },
    "development": {
      "on": false,
      "rollout": 1,
      "value": null,
      "rules": [
        {
          "id": "id",
          "attribute": "email",
          "operator": "equals",
          "values": [
            "values"
          ],
          "serve": false,
          "label": "Email ends with @kudi.ng"
        }
      ]
    }
  },
  "created_by": {
    "id": "id",
    "name": "my-app",
    "email": "ada@example.com",
    "avatar_url": "https://my-app.theorbits.app"
  },
  "updated_by": {
    "id": "id",
    "name": "my-app",
    "email": "ada@example.com",
    "avatar_url": "https://my-app.theorbits.app"
  },
  "created_at": "2026-11-10T09:30:00Z",
  "updated_at": "2026-11-10T09:30:00Z"
}
```

Errors:

- `403`: Authenticated but not allowed in this team.
- `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose).
- `422`: Validation failed, or the Idempotency-Key was reused with a different body.
## Delete a flag

```http
DELETE /v1/teams/{team}/projects/{project}/flags/{flag}
```

The SDK stops getting it on its next refresh, and code checking it gets the default it passed.

**Permissions:** Owners, admins and members.

Token: a `full` API token.

Path parameters:

- `team`: Team slug or `team_` id.
- `project`: Project slug or `prj_` id.
- `flag`

Example:

```sh
curl -X DELETE "https://api.theorbits.app/v1/teams/my-team/projects/my-app/flags/new-checkout" \
  -H "Authorization: Bearer $ORBITS_TOKEN"
```

Response `204`: Deleted.

Errors:

- `403`: Authenticated but not allowed in this team.
- `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose).
## Switch a flag, set its rollout or its value in one environment

```http
PUT /v1/teams/{team}/projects/{project}/flags/{flag}/environments/{environment}
```

A boolean flag takes `on` and `rollout` (1–100, the share of ids it's on for); a string or number flag takes `value`. Fields left out stay as they are. Deployments see the change within seconds, without a redeploy.

**Permissions:** Owners, admins and members.

Token: a `full` API token.

Path parameters:

- `team`: Team slug or `team_` id.
- `project`: Project slug or `prj_` id.
- `flag`
- `environment`

Body:

- `on` (boolean)
- `rollout` (integer): From 1 to 100.
- `value` (string | number)

Example:

```sh
curl -X PUT "https://api.theorbits.app/v1/teams/my-team/projects/my-app/flags/new-checkout/environments/production" \
  -H "Authorization: Bearer $ORBITS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "on": false,
    "rollout": 1,
    "value": "value"
  }'
```

Response `200`:

```json
{
  "key": "new-checkout",
  "description": "description",
  "type": "boolean",
  "environments": {
    "production": {
      "on": false,
      "rollout": 1,
      "value": null,
      "rules": [
        {
          "id": "id",
          "attribute": "email",
          "operator": "equals",
          "values": [
            "values"
          ],
          "serve": false,
          "label": "Email ends with @kudi.ng"
        }
      ]
    },
    "preview": {
      "on": false,
      "rollout": 1,
      "value": null,
      "rules": [
        {
          "id": "id",
          "attribute": "email",
          "operator": "equals",
          "values": [
            "values"
          ],
          "serve": false,
          "label": "Email ends with @kudi.ng"
        }
      ]
    },
    "development": {
      "on": false,
      "rollout": 1,
      "value": null,
      "rules": [
        {
          "id": "id",
          "attribute": "email",
          "operator": "equals",
          "values": [
            "values"
          ],
          "serve": false,
          "label": "Email ends with @kudi.ng"
        }
      ]
    }
  },
  "created_by": {
    "id": "id",
    "name": "my-app",
    "email": "ada@example.com",
    "avatar_url": "https://my-app.theorbits.app"
  },
  "updated_by": {
    "id": "id",
    "name": "my-app",
    "email": "ada@example.com",
    "avatar_url": "https://my-app.theorbits.app"
  },
  "created_at": "2026-11-10T09:30:00Z",
  "updated_at": "2026-11-10T09:30:00Z"
}
```

Errors:

- `403`: Authenticated but not allowed in this team.
- `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose).
- `422`: Validation failed, or the Idempotency-Key was reused with a different body.
## Add a targeting rule

```http
POST /v1/teams/{team}/projects/{project}/flags/{flag}/environments/{environment}/rules
```

Rules are checked in order before the environment's switch: the first that matches decides, `serve` being on or off for a boolean flag and the value for the others. `attribute` names what the app passes to `flag()` (`email`, `id`, `plan`, `user.country`); `one_of` takes several values, every other operator one; comparisons ignore case, and an attribute the app didn't pass matches nothing. 20 rules at most.

**Permissions:** Owners, admins and members.

Token: a `full` API token. Send an `Idempotency-Key` header.

Path parameters:

- `team`: Team slug or `team_` id.
- `project`: Project slug or `prj_` id.
- `flag`
- `environment`

Body:

- `attribute` (string, required): At most 64 characters.
- `operator` (string, required): One of `equals`, `not_equals`, `one_of`, `ends_with`, `starts_with`, `contains`.
- `values` (array of string, required): At most 50 items.
- `serve` (boolean | string | number, required)

Example:

```sh
curl -X POST "https://api.theorbits.app/v1/teams/my-team/projects/my-app/flags/new-checkout/environments/production/rules" \
  -H "Authorization: Bearer $ORBITS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "attribute": "email",
    "operator": "equals",
    "values": [
      "@kudi.ng"
    ],
    "serve": false
  }'
```

Response `201`:

```json
{
  "key": "new-checkout",
  "description": "description",
  "type": "boolean",
  "environments": {
    "production": {
      "on": false,
      "rollout": 1,
      "value": null,
      "rules": [
        {
          "id": "id",
          "attribute": "email",
          "operator": "equals",
          "values": [
            "values"
          ],
          "serve": false,
          "label": "Email ends with @kudi.ng"
        }
      ]
    },
    "preview": {
      "on": false,
      "rollout": 1,
      "value": null,
      "rules": [
        {
          "id": "id",
          "attribute": "email",
          "operator": "equals",
          "values": [
            "values"
          ],
          "serve": false,
          "label": "Email ends with @kudi.ng"
        }
      ]
    },
    "development": {
      "on": false,
      "rollout": 1,
      "value": null,
      "rules": [
        {
          "id": "id",
          "attribute": "email",
          "operator": "equals",
          "values": [
            "values"
          ],
          "serve": false,
          "label": "Email ends with @kudi.ng"
        }
      ]
    }
  },
  "created_by": {
    "id": "id",
    "name": "my-app",
    "email": "ada@example.com",
    "avatar_url": "https://my-app.theorbits.app"
  },
  "updated_by": {
    "id": "id",
    "name": "my-app",
    "email": "ada@example.com",
    "avatar_url": "https://my-app.theorbits.app"
  },
  "created_at": "2026-11-10T09:30:00Z",
  "updated_at": "2026-11-10T09:30:00Z"
}
```

Errors:

- `403`: Authenticated but not allowed in this team.
- `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose).
- `422`: Validation failed, or the Idempotency-Key was reused with a different body.
## Change what a rule serves

```http
PATCH /v1/teams/{team}/projects/{project}/flags/{flag}/environments/{environment}/rules/{rule}
```

**Permissions:** Owners, admins and members.

Token: a `full` API token.

Path parameters:

- `team`: Team slug or `team_` id.
- `project`: Project slug or `prj_` id.
- `flag`
- `environment`
- `rule`

Body:

- `serve` (boolean | string | number, required)

Example:

```sh
curl -X PATCH "https://api.theorbits.app/v1/teams/my-team/projects/my-app/flags/new-checkout/environments/production/rules/rule_1" \
  -H "Authorization: Bearer $ORBITS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "serve": false
  }'
```

Response `200`:

```json
{
  "key": "new-checkout",
  "description": "description",
  "type": "boolean",
  "environments": {
    "production": {
      "on": false,
      "rollout": 1,
      "value": null,
      "rules": [
        {
          "id": "id",
          "attribute": "email",
          "operator": "equals",
          "values": [
            "values"
          ],
          "serve": false,
          "label": "Email ends with @kudi.ng"
        }
      ]
    },
    "preview": {
      "on": false,
      "rollout": 1,
      "value": null,
      "rules": [
        {
          "id": "id",
          "attribute": "email",
          "operator": "equals",
          "values": [
            "values"
          ],
          "serve": false,
          "label": "Email ends with @kudi.ng"
        }
      ]
    },
    "development": {
      "on": false,
      "rollout": 1,
      "value": null,
      "rules": [
        {
          "id": "id",
          "attribute": "email",
          "operator": "equals",
          "values": [
            "values"
          ],
          "serve": false,
          "label": "Email ends with @kudi.ng"
        }
      ]
    }
  },
  "created_by": {
    "id": "id",
    "name": "my-app",
    "email": "ada@example.com",
    "avatar_url": "https://my-app.theorbits.app"
  },
  "updated_by": {
    "id": "id",
    "name": "my-app",
    "email": "ada@example.com",
    "avatar_url": "https://my-app.theorbits.app"
  },
  "created_at": "2026-11-10T09:30:00Z",
  "updated_at": "2026-11-10T09:30:00Z"
}
```

Errors:

- `403`: Authenticated but not allowed in this team.
- `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose).
- `422`: Validation failed, or the Idempotency-Key was reused with a different body.
## Remove a rule

```http
DELETE /v1/teams/{team}/projects/{project}/flags/{flag}/environments/{environment}/rules/{rule}
```

**Permissions:** Owners, admins and members.

Token: a `full` API token.

Path parameters:

- `team`: Team slug or `team_` id.
- `project`: Project slug or `prj_` id.
- `flag`
- `environment`
- `rule`

Example:

```sh
curl -X DELETE "https://api.theorbits.app/v1/teams/my-team/projects/my-app/flags/new-checkout/environments/production/rules/rule_1" \
  -H "Authorization: Bearer $ORBITS_TOKEN"
```

Response `204`: Removed.

Errors:

- `403`: Authenticated but not allowed in this team.
- `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose).
