Feature flags

Feature flags tell your app which Wingspan features are on for a given subject. Read them to show or hide a screen in an app you build on Wingspan. The API only evaluates flags. It does not let you create or change them.

Endpoints

Person flags

These routes use the Person you are signed in as. personId must be that Person, or the API returns 404. They are Person-scoped, so X-Wingspan-Account is rejected with 400 AccountScopeNotApplicable.

curl https://api.wingspan.app/v3/platform/persons/Pq3mT8vLw2NzKc5xRb7HdA/feature-flags \
  -H "Authorization: Bearer $WINGSPAN_TOKEN"

{ "subjectType": "Person", "personId": "Pq3mT8vLw2NzKc5xRb7HdA", "enabledFlags": ["new-invoice-editor"] }

The flag name in the example is illustrative. The response lists the names of the flags that are on. A flag that is off is not listed.

Account flags

The accountId in the path must equal the effective Account (the Account in X-Wingspan-Account, or the credential's own Account). If it does not, the API returns 403 AccountMismatch. The scope is users.account:read.

curl https://api.wingspan.app/v3/platform/accounts/Nw7kQ2pLx9RtVb3mHc5dZa/feature-flags/new-invoice-editor \
  -H "Authorization: Bearer $WINGSPAN_TOKEN" \
  -H "X-Wingspan-Account: Nw7kQ2pLx9RtVb3mHc5dZa"

{ "accountId": "Nw7kQ2pLx9RtVb3mHc5dZa", "flagName": "new-invoice-editor", "isEnabled": true }

A flag name Wingspan does not recognize returns isEnabled: false, never 404. Flag definitions are private, so you cannot tell an unknown flag from one that is off.

Visitors who have not signed in

Evaluate needs no authentication. Send a stable anonymousId you generate for the visitor.

curl -X POST https://api.wingspan.app/v3/platform/feature-flags/anonymous-evaluations \
  -H "Content-Type: application/json" \
  -d '{ "anonymousId": "visitor-7f3a9c" }'

The response has subjectType: "Anonymous", the anonymousId, and enabledFlags, which lists only flags marked for anonymous evaluation. It returns 200, since nothing is created. X-Wingspan-Account is rejected with 400 AccountScopeNotApplicable.

Caching and errors

Person and Account responses carry Cache-Control: private, no-store. Re-read them when you need a current value.