Feature Flags API

Flag model

With no variants, a matching rule returns a simple enabled result. With variants, a matching rule returns the selected variant and its payload. With no rules, evaluation is disabled with reason no_match.

Authentication

Send an account credential on /api/*:

bash
curl https://cohorly-service.velloalabs.com/api/flags?projectId=1 \
  -H "Authorization: Bearer $API_KEY"

Send a project token on /flags/evaluate:

bash
curl -X POST https://cohorly-service.velloalabs.com/flags/evaluate \
  -H "Content-Type: application/json" \
  -H "X-Cohorly-Token: YOUR_PROJECT_TOKEN" \
  -d '{ "distinct_id": "user-123" }'

The token can also be supplied as the request body's token field. The X-Cohorly-Token header applies to the whole request.

Manage flags

List flags

Create a flag

bash
curl -X POST https://cohorly-service.velloalabs.com/api/flags \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": 1,
    "key": "checkout-redesign",
    "name": "Checkout redesign",
    "description": "Gradual rollout of the new checkout",
    "active": true,
    "variants": [
      { "key": "control", "rolloutPct": 50 },
      { "key": "new", "rolloutPct": 50, "payload": { "layout": "compact" } }
    ],
    "rules": [
      { "distinctIds": ["user-123"], "rolloutPct": 100, "variant": "new" },
      { "cohortId": 42, "rolloutPct": 25 }
    ]
  }'

The response is the complete created flag. The key is unique within the project and cannot be changed later.

Read, update, and delete a flag

The request can include name, description, active, type, variants, and rules. If variants change, existing rules are checked against the new variant keys. Send rules: [] to make an active flag explicitly disabled by configuration. Every PUT writes a flag_events row (see Activity below); when active flips, the recorded action is activated/deactivated instead of updated.

bash
curl -X PUT https://cohorly-service.velloalabs.com/api/flags/4 \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "active": true,
    "rules": [{ "rolloutPct": 50, "variant": "new" }]
  }'

Deletion removes the flag definition. Remove or retire the corresponding application code separately.

Cross-organization flag ids return 404, so the API does not disclose the existence of another organization's flags.

Archive, revive, and delete

Archive is the reversible way to turn a flag off for good, for now; delete is the one-way action and is only offered once a flag is archived, so the API never exposes two destructive paths on a live flag.

Both are idempotent: archiving an already-archived flag (or reviving an already-active one) returns the flag unchanged and writes no extra event. DELETE /api/flags/{id} returns 409 { "error": "not archived" } unless the flag is already archived.

bash
curl -X POST https://cohorly-service.velloalabs.com/api/flags/4/archive \
  -H "Authorization: Bearer $API_KEY"

Preview (Playground)

The dashboard's Playground tab calls this so a person testing a flag does not need a project token. It runs the exact same evaluator as POST /flags/evaluate, scoped to this one flag.

bash
curl -X POST https://cohorly-service.velloalabs.com/api/flags/4/preview \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "distinctId": "qa-user-1" }'

Activity

bash
curl "https://cohorly-service.velloalabs.com/api/flags/4/events?limit=20" \
  -H "Authorization: Bearer $API_KEY"

action is one of created, updated, activated, deactivated, archived, revived. activated/deactivated fire instead of updated when a PUT flips active. actor_user_id is null when the superadmin key or an MCP token made the change; actor_mcp_token_id names the MCP token in the second case. Deleting a flag deletes its event history with it (ON DELETE CASCADE).

Remote evaluation

bash
curl -X POST https://cohorly-service.velloalabs.com/flags/evaluate \
  -H "Content-Type: application/json" \
  -H "X-Cohorly-Token: YOUR_PROJECT_TOKEN" \
  -d '{
    "distinct_id": "user-123",
    "flag_keys": ["checkout-redesign"]
  }'

Remote evaluation uses the identity cluster's canonical id for cohort checks and rollout bucketing. An anonymous id linked to a user id therefore evaluates as the same identity. Exact overrides also match the raw submitted id.

Local-evaluation definitions

Authenticate with the project flag secret, not the project token:

bash
curl https://cohorly-service.velloalabs.com/flags/local-evaluation \
  -H "Authorization: Bearer $COHORLY_FLAG_SECRET"

The response contains only the fields required for local evaluation:

json
{
  "flags": [
    {
      "key": "checkout-redesign",
      "name": "Checkout redesign",
      "active": true,
      "variants": [
        { "key": "control", "rolloutPct": 50 },
        { "key": "new", "rolloutPct": 50, "payload": { "layout": "compact" } }
      ],
      "rules": [{ "rolloutPct": 100, "variant": "new" }],
      "localEvaluable": true
    }
  ]
}

localEvaluable is false when a rule references a cohort. Cohort membership depends on server-side event and profile data, so SDKs must use remote evaluation for that flag. Local evaluation hashes the raw distinct_id, while remote evaluation hashes the canonical identity id. Pass the identified user id to local server evaluation when identity linking matters.

Flag secrets

The project flag secret is generated through the account API. Only the organization owner or superadmin can mint, rotate, or revoke it.

bash
curl -X POST https://cohorly-service.velloalabs.com/api/projects/1/flag-secret \
  -H "Authorization: Bearer $API_KEY"

The response contains { "secret": "..." } once. A rotation invalidates the old value immediately. GET /api/projects reports only has_flag_secret, not the secret itself.

bash
curl -X DELETE https://cohorly-service.velloalabs.com/api/projects/1/flag-secret \
  -H "Authorization: Bearer $API_KEY"

The response is { "ok": true }. Revocation is idempotent. New local definition requests return 401; running server SDKs retain their last successful definitions by design. Restart them or remove the flag secret from their configuration to force remote evaluation immediately.

Limits and errors

Rate-limited responses are 429 and include a Retry-After header. SDKs should honor that header and retry with backoff. Invalid JSON, missing fields, invalid rollout totals, unknown variants, and foreign cohorts return 400. Creating a flag with a duplicate key returns 409 with key taken; creating one after the 100-flag project limit returns 409 with flag limit reached. Requests larger than 1 MB return 413 with { "status": 0, "error": "payload too large" }.