Create and use flags

1. Create an application with POST /admin/applications; you become its owner.
2. Create a development environment with POST /admin/applications/:applicationId/environments.
3. Add hostnames with POST /admin/applications/:applicationId/environments/:environmentId/hosts so runtime calls resolve the right environment.
4. Create groups or conversion events when the flag needs targeted rules or experiment metrics.
5. Create the flag with POST /admin/applications/:applicationId/flags.
6. Create or replace environment config with PUT /admin/applications/:applicationId/environments/:environmentId/flags/:flagId.
7. Add group, attribute, or percentage rules when the default value is not enough.
8. Optionally create an experiment, add variants, attach conversion events, then start it.
9. Create a runtime API key with POST /admin/applications/:applicationId/api-keys and store the plaintext value; it is only shown once.
10. Call POST /flags/:flagKey/evaluate with X-API-Key from the application and use the returned value.
11. Call POST /events/:eventKey with X-API-Key after a tracked conversion.

Creates the application-scoped flag identity. The key is what runtime applications use for evaluation.

POST /admin/applications/3/flags
X-Tenant-ID: tenant-uuid
Authorization: Bearer <admin-jwt>

{
  "key": "checkout-redesign",
  "name": "Checkout redesign",
  "description": "Controls the new checkout flow"
}

{
  "flag": {
    "id": 12,
    "key": "checkout-redesign",
    "name": "Checkout redesign",
    "description": "Controls the new checkout flow",
    "isArchived": false,
    "createdAt": "2026-09-01T10:00:00.000Z"
  }
}

Sets the enabled state, default value, optional rollout percentage, and experiment toggle for one environment.

PUT /admin/applications/3/environments/1/flags/12
X-Tenant-ID: tenant-uuid
Authorization: Bearer <admin-jwt>

{
  "enabled": true,
  "defaultValue": true,
  "rolloutPercentage": 25,
  "experimentEnabled": false
}

{
  "config": {
    "id": 77,
    "flagId": 12,
    "environmentId": 1,
    "enabled": true,
    "defaultValue": true,
    "rolloutPercentage": 25,
    "experimentEnabled": false,
    "rules": [],
    "experiment": null
  }
}

Runtime applications call this endpoint before deciding which behavior or UI to show.

POST /flags/checkout-redesign/evaluate
X-API-Key: <application-api-key>
X-Hostname: app.example.com
X-Visitor-ID: vis_4f8a1b2c

{
  "groups": ["beta-testers"],
  "attributes": {
    "plan": "premium",
    "country": "ZA"
  }
}

{
  "key": "checkout-redesign",
  "enabled": true,
  "value": true,
  "variant": "treatment"
}

• When no environment or config matches, the endpoint returns enabled: false.
• Authenticated requests may include a bearer token for stable user-based experiment assignment.