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.
| Surface | Authenticates with | Description |
|---|---|---|
| Evaluation API, under /api/v1 | API key as a bearer token | Pipelines and services. Versioned and stable. Evaluate, read configuration, stream changes, report errors, code references and analytics, list versions and roll back. |
| Dashboard API, under /api | auth_session cookie from signing in | Everything 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=.
| Endpoint | Key | Description |
|---|---|---|
| POST /api/v1/evaluation/client | Any key | Results for one person. CORS is open, so browsers can call it. |
| GET /api/v1/evaluation/server | Server or admin | Full configuration or server-side evaluation. No CORS. |
| GET .../environments/{environment}/versions | Server or admin, scope flags:read | Saved versions, newest first. |
| POST .../environments/{environment}/rollback | Admin, scope rollouts:write | Returns an environment to an earlier version. |
Walk through it#
Evaluate flags for one person
Send the key as a bearer token. The body names the person with
identifiers(up to 10) and can carryattributesfor 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. A200with aflagsobject holding one result per flag. A wrong key returns401.Read configuration or explain a result
A server or admin key can download every flag's configuration with
mode=config. Send theETagback asIf-None-Matchand an unchanged configuration costs a304. Withmode=evaluateandexplain=true, each result includes its reason, such asROLLOUT_INorSEGMENT_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"List versions and roll back
The versions call needs the
flags:readscope. Rollback needs an admin key withrollouts:write. Without aversionit 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
versionis a whole number of 1 or more and optional.reasonis optional, up to 300 characters, and is kept with the version. The versions call takespageandlimit(default 20, maximum 100) and returnsflag,environment,current,itemsandpagination. 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 actionrollback.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_sessioncookie and send it on each call. The response envelope is{ status, message, data }, and failures carrystatus: "error"and amessage.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.readhere, so a script signed in as a person with a narrow role can only do what that role allows. A refusal comes back withstatus: "error"and amessageyou 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 with403if a browser sends them from another site. Scripts that send noOriginheader are fine; if your tool runs from another address, the operator lists it inALLOWED_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.
#!/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.jsonLimits to plan for#
- By default a key may make 600 requests a minute. Past that you get
429withRetry-After, andX-RateLimit-LimitandX-RateLimit-Remainingare 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 asAUTH_INVALID_API_KEY, to branch on. Quote theX-Request-Idheader when you ask for help. - Dashboard API list endpoints take
pageandlimit, with a maximum of 100, and sign-in is rate limited after repeated failures. - Poll sparingly. Use
ETagandIf-None-Matchfor configuration, or the change stream, rather than a tight loop.
Good to know#
Use SDKs for application code
Can I create flags or segments with an API key?
How do I script the Dashboard API without a person?
Why does my client key get 403 on the server endpoint?
What does a key limited to another environment return?
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
200with aflagsobject, and a wrong key returns401. - 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.