Skip to content
FlagSwiftDocs

Automate with the HTTP API

Evaluate flags and roll one back from a script with an API key, and know when you need the signed-in dashboard API instead.

Time
About 14 min
Who can do it
Anyone who can create an API key (admins)
Where
Your terminal or CI, with curl
You finish with
A script that evaluates flags and rolls one back

What and why#

Anything you can do in the console you can eventually script, but FlagSwift has two separate HTTP surfaces and choosing the right one is the whole job. The Evaluation API is for software: it takes an API key and does a small, fixed set of things such as evaluating flags and rolling one back. The Dashboard API is what the console itself uses: it takes a signed-in session and acts as a person.

Pick the surface
SurfaceAuthenticates withDescription
Evaluation API, under /api/v1API key as a bearer tokenPipelines and services. Versioned and stable. Evaluate, read configuration, stream changes, report errors, code references and analytics, list versions and roll back.
Dashboard API, under /apiauth_session cookie from signing inEverything else: flags, segments, releases, members, keys. Acts as the person who signed in, with their role. Not versioned.

Why keys cannot call the dashboard API#

Keys are scoped, revocable and never carry a person's permissions. Keeping them out of the Dashboard API means a leaked key can evaluate flags or roll one back, and nothing more.

Before you start#

  • Create the keys you need on the API Keys page. Use a client key to evaluate for one person, a server key to read configuration, and an admin key for rollback. See Create, rotate and revoke API keys.
  • Keep keys in environment variables, for example FLAGSWIFT_ADMIN_KEY, and out of source control.
  • Know your base URL. The examples use https://flags.example.com.
  • A key limited to one environment always evaluates that environment. A project-wide key must say which with ?env=.
Which key for which call
EndpointKeyDescription
POST /api/v1/evaluation/clientAny keyResults for one person. CORS is open, so browsers can call it.
GET /api/v1/evaluation/serverServer or adminFull configuration or server-side evaluation. No CORS.
GET .../environments/{environment}/versionsServer or admin, scope flags:readSaved versions, newest first.
POST .../environments/{environment}/rollbackAdmin, scope rollouts:writeReturns an environment to an earlier version.

Walk through it#

  1. Evaluate flags for one person

    Send the key as a bearer token. The body names the person with identifiers (up to 10) and can carry attributes for targeting rules, up to 8 KB.

    bash
    curl -s -X POST "https://flags.example.com/api/v1/evaluation/client?env=production" \
      -H "Authorization: Bearer $KEY" \
      -H "Content-Type: application/json" \
      -d '{"identifiers":["user-123"],"attributes":{"plan":"pro"}}'
    200 OK
    {
      "environment": "production",
      "hashVersion": 1,
      "version": "f1c2",
      "flags": {
        "new-dashboard": { "enabled": true, "version": 7 },
        "checkout-layout": { "enabled": true, "variant": "compact", "value": "compact", "version": 3 }
      }
    }
    You should see. A 200 with a flags object holding one result per flag. A wrong key returns 401.
  2. Read configuration or explain a result

    A server or admin key can download every flag's configuration with mode=config. Send the ETag back as If-None-Match and an unchanged configuration costs a 304. With mode=evaluate and explain=true, each result includes its reason, such as ROLLOUT_IN or SEGMENT_MATCH, which is the quickest way to see why a person got a value.

    bash
    curl -s "https://flags.example.com/api/v1/evaluation/server?mode=config&env=production" \
      -H "Authorization: Bearer $KEY"
    
    curl -s "https://flags.example.com/api/v1/evaluation/server?mode=evaluate&explain=true&user_identifier=user-123&env=production" \
      -H "Authorization: Bearer $KEY"
  3. List versions and roll back

    The versions call needs the flags:read scope. Rollback needs an admin key with rollouts:write. Without a version it returns the environment to its previous configuration. The rollback is saved as a new version, appears in the audit log under the key's name, and is refused while the emergency stop is active.

    Versions, then rollback

    version is a whole number of 1 or more and optional. reason is optional, up to 300 characters, and is kept with the version. The versions call takes page and limit (default 20, maximum 100) and returns flag, environment, current, items and pagination. These responses are plain JSON without the dashboard envelope. The values shown are illustrative.

    Request
    curl -s "https://flags.example.com/api/v1/flags/new-dashboard/environments/production/versions" \
      -H "Authorization: Bearer $KEY"
    
    curl -s -X POST "https://flags.example.com/api/v1/flags/new-dashboard/environments/production/rollback" \
      -H "Authorization: Bearer $KEY" \
      -H "Content-Type: application/json" \
      -d '{"version":6,"reason":"error rate spike after release"}'
    Rollback response
    {
      "flag": "new-dashboard",
      "environment": "production",
      "version": 8,
      "enabled": false,
      "rolloutPercentage": 0
    }
    After the script runs, the Roll back list shows the new version as current. The reason you sent is kept with it.
    You should see. The rollback response shows the new version number and the restored state. The flag's History & rollback tab shows a version with the action rollback.
  4. Use the dashboard API when no key can do it

    Segments, releases, members, keys and most flag management are only in the Dashboard API. Sign in once, keep the auth_session cookie and send it on each call. The response envelope is { status, message, data }, and failures carry status: "error" and a message.

    bash
    curl -s -c jar.txt -X POST https://flags.example.com/api/auth/login \
      -H "Content-Type: application/json" \
      -d '{"email":"you@example.com","password":"..."}'
    
    curl -s -b jar.txt "https://flags.example.com/api/flags?projectId=PROJECT_ID&limit=20"

    Read the result

    The permission is checked per route, for example alerts.read here, so a script signed in as a person with a narrow role can only do what that role allows. A refusal comes back with status: "error" and a message you can show in the job log.

    Request
    # Every dashboard response has the same envelope
    curl -s -b jar.txt "https://flags.example.com/api/alerts"
    200 OK
    {
      "status": "success",
      "message": "OK",
      "data": { "items": [], "counts": { "firing": 0, "total": 0 } }
    }

    The dashboard API is not versioned

    It is what the console screens use and it can change between releases. Requests that change data are refused with 403 if a browser sends them from another site. Scripts that send no Origin header are fine; if your tool runs from another address, the operator lists it in ALLOWED_ORIGINS.

A rollback you can drop into CI#

This script rolls a flag back and fails the job with the server's message if it is refused.

rollback.sh
#!/usr/bin/env bash
set -euo pipefail

FLAG="${1:?flag key}"
ENVIRONMENT="${2:-production}"
BASE="${FLAGSWIFT_URL:-https://flags.example.com}"

code=$(curl -s -o rollback.json -w "%{http_code}" -X POST \
  "$BASE/api/v1/flags/$FLAG/environments/$ENVIRONMENT/rollback" \
  -H "Authorization: Bearer $FLAGSWIFT_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reason":"rolled back from CI"}')

if [ "$code" != "200" ]; then
  echo "Rollback refused ($code):" >&2
  cat rollback.json >&2
  exit 1
fi
cat rollback.json

Limits to plan for#

  • By default a key may make 600 requests a minute. Past that you get 429 with Retry-After, and X-RateLimit-Limit and X-RateLimit-Remaining are sent on API responses. Operators can change the limit, and it is counted per server instance.
  • Errors from the Evaluation API carry a stable code, such as AUTH_INVALID_API_KEY, to branch on. Quote the X-Request-Id header when you ask for help.
  • Dashboard API list endpoints take page and limit, with a maximum of 100, and sign-in is rate limited after repeated failures.
  • Poll sparingly. Use ETag and If-None-Match for configuration, or the change stream, rather than a tight loop.

Good to know#

Use SDKs for application code

Scripts and pipelines are the right place for raw HTTP. For a service evaluating flags on every request, an SDK caches configuration, handles outages and reports errors for you. See Choose and set up an SDK.
Can I create flags or segments with an API key?
No. Keys call the Evaluation API only. Creating and editing flags, segments and releases is in the Dashboard API, which needs a signed-in session.
How do I script the Dashboard API without a person?
Create a member for the automation, such as a Developer or a custom role, sign in with it to get a session cookie, and give it only the permissions the script needs. Sessions expire, so sign in at the start of each run.
Why does my client key get 403 on the server endpoint?
The server endpoint needs a server or admin key. A client key is evaluation only.
What does a key limited to another environment return?
A 403. A key limited to one environment always uses that environment, so asking for another is refused.

If something goes wrong#

401 with AUTH_MISSING_API_KEY or AUTH_INVALID_API_KEY

Why: No Authorization header, or the key is unknown, revoked or expired.

Fix: Send Authorization: Bearer $KEY. Check the key's status on the API Keys page and rotate it if needed.

403 on an endpoint

Why: The key type or scope is not allowed there, or the key is limited to another environment.

Fix: Use a server key for configuration and an admin key with the needed scope for rollback and versions.

Cannot roll back while the kill switch is active

Why: A rollback never restores the emergency stop and is refused while it is active.

Fix: Lift the kill switch in the console, then retry the rollback.

The flag is already at this version, or There is no earlier version to roll back to

Why: The target version is the current one, or the environment has no earlier version.

Fix: List versions and pick a different one, or send no version to use the previous one.

Dashboard API call returns 403 from a script

Why: The request carried an Origin header that does not match the app, or the organization is deactivated, or your role lacks the permission.

Fix: Remove the Origin header, or ask the operator to add your address to ALLOWED_ORIGINS. Check the message in the response.

400 Reason must be 300 characters or less

Why: The reason on a rollback or kill switch is longer than the server allows. The console box accepts more text than the server will take.

Fix: Shorten the reason to 300 characters.

429 RATE_LIMITED

Why: The key made more requests in a minute than the limit allows.

Fix: Wait for Retry-After seconds, cache configuration with ETag, and spread calls out.

What to check#

  • The evaluation call returns 200 with a flags object, and a wrong key returns 401.
  • A client key sent to the server endpoint is refused with 403.
  • A rollback from your script shows in the audit log with the key's name.