Actuator

Appearance

Projects ​

A project is a logical group of flags, configs, and segments inside an organization, with one or more environments under it.

The Project object:

json
{
  "id": "9f7a32b5-…",
  "key": "web",
  "name": "Web app",
  "targetIdField": null,
  "effectiveTargetIdField": "userId",
  "createdAt": "2026-04-12T10:00:00Z",
  "updatedAt": "2026-04-29T14:33:00Z"
}

targetIdField is the per-project override for percentage-rollout stickiness; effectiveTargetIdField is what the evaluator actually uses (override if set, otherwise the org's defaultTargetIdField). key is unique within the org and used in URLs for project-scope CRUD; id is the UUID used everywhere else.

List projects ​

http
GET /api/v1/orgs/{slug}/projects

Response: 200 → Project[] | 404 not_found

Create a project ​

http
POST /api/v1/orgs/{slug}/projects
Content-Type: application/json

{
  "key": "web",
  "name": "Web app",
  "targetIdField": "userId"
}

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

targetIdField is optional — omit to inherit from the org default.

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

Get a project ​

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

Response: 200 → Project | 404 not_found

Update a project ​

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

{
  "name": "Web app v2",
  "targetIdField": "userId"
}

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

Touching targetIdField (setting a new value, or explicit null to clear the override) cascades a re-materialize across every environment in the project — stickiness is recomputed against the new attribute.

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

Project-scope flag, config, and segment CRUD ​

The "project scope" of a primitive carries identity: key, type, description, JSON schema. Per-environment state (rules, default value, allow / deny lists) is edited under /envs/{envId}/.... See:

  • Flags API — POST/PATCH/DELETE /api/v1/projects/{id}/flags, PUT /api/v1/envs/{envId}/flags/{key}/state.
  • Configs API — same shape with type-aware validation.
  • Segments API — same shape; segments add a reference-checking endpoint.