Actuator

Appearance

Environments ​

An environment is a per-project context for evaluating rulesets — typically dev, staging, production, or whatever shape your team uses.

The Environment object:

json
{
  "id": "9f7a32b5-…",
  "projectId": "1234abcd-…",
  "key": "production",
  "name": "Production",
  "version": 142,
  "createdAt": "2026-04-12T10:00:00Z",
  "updatedAt": "2026-04-29T14:33:00Z"
}

key is immutable post-create. name is editable. version is the monotonically increasing ruleset version — see Evaluation → Versioning.

List environments ​

http
GET /api/v1/projects/{id}/environments

Response: 200 → Environment[] | 404 not_found

Create an environment ​

http
POST /api/v1/projects/{id}/environments
Content-Type: application/json

{
  "key": "production",
  "name": "Production"
}

Session role: editor+. Bearer scope: write action.

The new environment is created with an empty v1 ruleset blob in the same transaction, so /evaluate returns 200 immediately — no 503 ruleset_not_cached on a fresh environment.

If the project already has flags, configs, or segments, every existing primitive gets a default-state row inserted for the new environment in the same transaction (rules [], default value: type's zero — false for boolean flags, "" for string flags / configs, 0 for number configs, null for json configs; segments get empty rules / allow / deny lists). The new environment evaluates as a default-everywhere mirror of the project, ready to diverge.

Response: 201 → EnvironmentErrors: 400 invalid_request, 403 insufficient_role, 404 not_found.

Get an environment ​

http
GET /api/v1/envs/{id}

Response: 200 → Environment | 404 not_found

Update an environment ​

http
PATCH /api/v1/envs/{id}
Content-Type: application/json

{ "name": "Prod (US)" }

Session role: editor+. Bearer scope: write action.

Only name is mutable. key is immutable post-create.

Response: 200 → EnvironmentErrors: 400 invalid_request, 403 insufficient_role, 404 not_found.

Per-environment state ​

The CRUD endpoints for editing rules and default values live under /envs/{envId}/.../state. See:

  • Flags API — PUT /api/v1/envs/{envId}/flags/{key}/state.
  • Configs API — same shape with type-aware validation.
  • Segments API — same shape, plus allow / deny lists.

Ruleset version probe ​

For a fast SSE-fallback poll, fetch only the version:

http
GET /api/v1/envs/{envId}/ruleset/version
If-None-Match: W/"142"

Returns 200 → { "version": 143 } if the env has moved, or 304 Not Modified with a fresh ETag: W/"142" if not. See Evaluation API for details.