GraphQL API

The endpoint

Every operation is an HTTP POST to a single URL, with the same x-management-key header the REST API uses. Send Accept: application/json and the response is ordinary JSON.

POST /api/graphql
x-management-key: YOUR-MANAGEMENT-KEY
Content-Type: application/json
Accept: application/json

Curl

curl -X POST $HOST/api/graphql \
  -H "x-management-key: $FF_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"query":"{ flags { name project type isArchived } }"}'

What you can call

The field names mirror the REST endpoints one for one, so anything documented on HTTP & REST applies here too, including the request body shapes.

Mutation fields run one after another in the order you write them, so a create followed by a configure in the same document behaves the way you'd expect.

Reading flags

Ask for the fields you need and nothing else.

query ListFlags {
  flags {
    name
    project
    type
    isArchived
    variants { key value valueType }
  }
}

One round trip can answer more than one question — here, a flag and its configurations together, where REST would need two calls:

query OneFlag($name: String!) {
  flag(name: $name) {
    name
    project
    description
    tags
  }
  flagConfigs(name: $name) {
    stage
    clientId
    enabled
    defaultVariantKey
    rolloutPercentage
  }
}

Creating and configuring

Mutation

mutation CreateFlag($input: CreateFlagInput!) {
  createFlag(input: $input) {
    name
    project
    type
    createdAt
  }
}

Variables

{
  "input": {
    "name": "checkout-redesign",
    "project": "Main App",
    "type": "release",
    "description": "Q3 checkout flow rewrite",
    "tags": ["checkout", "q3"],
    "variants": [
      { "key": "on",  "value": true,  "valueType": "boolean" },
      { "key": "off", "value": false, "valueType": "boolean" }
    ]
  }
}

Targeting for one stage

mutation Configure($name: String!, $input: UpsertFlagConfigInput!) {
  upsertFlagConfig(name: $name, input: $input) {
    stage
    enabled
    rolloutPercentage
  }
}

{
  "name": "checkout-redesign",
  "input": {
    "stage": "production",
    "enabled": true,
    "defaultVariantKey": "off",
    "rolloutPercentage": 100,
    "rules": [
      {
        "id": "pro-users",
        "priority": 10,
        "conditions": [
          { "field": "plan", "operator": "==", "value": "pro" }
        ],
        "allocations": [
          { "variantKey": "on", "percentage": 100 }
        ]
      }
    ]
  }
}

Evaluating

The same evaluator that answers the REST call, reached a different way. Ask for reason and you get the explanation back — there is no separate explain switch, because requesting the field is the switch.

query Evaluate($key: String!, $userId: String!, $stage: String!, $context: Any) {
  evaluate(key: $key, userId: $userId, stage: $stage, context: $context) {
    key
    variant
    reason { code message ruleId }
  }
}

{
  "key": "checkout-redesign",
  "userId": "user-42",
  "stage": "production",
  "context": { "plan": "pro", "country": "DE" }
}

Response

{
  "data": {
    "evaluate": {
      "key": "on",
      "variant": true,
      "reason": {
        "code": "rule_matched",
        "message": "Matched rule 'pro-users' (priority 10). Variant chosen by allocation.",
        "ruleId": "pro-users"
      }
    }
  }
}

Several users in one request

Give each evaluation an alias and they come back side by side under those names — useful for rendering a whole screen's worth of flags, or for comparing what two audiences would see.

query EvaluateBoth($key: String!, $stage: String!, $pro: Any, $free: Any) {
  proUser: evaluate(key: $key, userId: "user-42", stage: $stage, context: $pro) {
    key
    variant
  }
  freeUser: evaluate(key: $key, userId: "user-77", stage: $stage, context: $free) {
    key
    variant
  }
}

How failures come back

This is the one real difference from REST. A request that reached the API answers 200 even when the operation failed, and the failure is described in errors. So check errors, not the status code.

{
  "errors": [
    {
      "message": "Flag not found.",
      "path": ["flag"],
      "extensions": { "code": "NOT_FOUND", "status": 404 }
    }
  ],
  "data": { "flag": null }
}

Each entry carries an extensions.code and the status the REST call would have returned:

Three cases still answer with an HTTP status instead, before the query is ever read: a missing or unknown key returns 401, an inactive subscription returns 402, and going over your rate limit returns 429. See rate limits and errors.