APIs
Every HTTP endpoint FlagSwift Enterprise serves, how each one authenticates, and the conventions they share: errors, rate limits, CORS and versioning.
Make your first call#
Three steps take you from nothing to a real flag result. You need a project with at least one flag, and a running FlagSwift server. The examples use https://flags.example.com; replace it with your own address.
Get a key
Open API keys in the console, create a new key and pick the Client type, your project and, ideally, one environment such as production. Copy the secret when it is shown: it starts with
fs_client_and appears once. You can also create keys over HTTP; see Key management.Keep it out of your code export FLAGSWIFT_CLIENT_KEY="fs_client_..."A key limited to one environment always evaluates that environment. A key for the whole project must name one with
?env=production, as the examples do. Use aserverkey instead when the call comes from your backend and you want reasons or the full configuration; see API keys.Call the Evaluation API
Send the key as a bearer token and say who you are asking about.
identifiersis the user;attributesare optional values your targeting rules can match.segments(up to 100 keys of at most 128 characters) adds segment membership; it is trusted input, so it suits personalisation, not security gating, unless the caller is your own backend.bash curl -s -X POST "https://flags.example.com/api/v1/evaluation/client?env=production" \ -H "Authorization: Bearer $FLAGSWIFT_CLIENT_KEY" \ -H "Content-Type: application/json" \ -d '{"identifiers":["user-123"],"attributes":{"plan":"pro"}}'Read the result
A
200returns every flag in the environment, already decided for this person. A flag with variants also carriesvariantandvalue. Targeting lists, rollout numbers and reasons never reach a client key.Response · 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 } } }bash # Print one flag with jq curl -s -X POST "https://flags.example.com/api/v1/evaluation/client?env=production" \ -H "Authorization: Bearer $FLAGSWIFT_CLIENT_KEY" \ -H "Content-Type: application/json" \ -d '{"identifiers":["user-123"]}' | jq '.flags["new-dashboard"].enabled'If something is wrong, the reply is an error with a
codeto branch on:AUTH_INVALID_API_KEYfor a mistyped or revoked key,ENV_REQUIREDwhen a project-wide key sent noenv, andENV_NOT_FOUNDfor a misspelled environment. See Errors. For everything else this endpoint takes, see the Evaluation API; or let an SDK do the calling for you.
The APIs at a glance#
Pick the API by who is calling. Each one has its own credential, and a credential for one never works on another.
| API | Path | Description |
|---|---|---|
| Evaluation API | /api/v1/evaluation/* | Used by SDKs and your services, with an API key. Evaluate flags, download configuration, listen for changes and report SDK errors. See Evaluation API. |
| Automation API | /api/v1/flags, /code-references, /analytics | Used by pipelines and CI, with a server or admin key. Roll a flag back, list its versions, report code references and send exposure and outcome events. Documented on the same page as evaluation. |
| Dashboard API | /api/* (not /api/v1) | Used by the console and one-off tooling, with a signed-in session cookie. Everything the console can do: flags, projects, segments, releases, members, keys, audit. |
| Change stream | /api/v1/evaluation/stream | Used by SDKs that want changes pushed. Server-Sent Events with any API key; it carries no flag data. |
| Prometheus metrics | /api/prometheus | Used by your monitoring. A plain-text scrape endpoint behind a shared token, off unless the operator sets METRICS_TOKEN. |
Each API in brief#
Evaluation API#
Called by: browsers and mobile apps (client key), your backend (server key). Authentication: Authorization: Bearer fs_client_… or fs_srv_…. No cookies.
| Endpoint | Method | Description |
|---|---|---|
| /api/v1/evaluation/client | POST, GET | Evaluate every flag for one person. Any key type. |
| /api/v1/evaluation/server | GET | Download configuration (mode=config) or evaluate on the server. Server or admin key. |
| /api/v1/evaluation/errors | POST | SDKs report errors they met while evaluating. |
Automation API#
Called by: deploy pipelines, CI and scanners. Authentication: a server or admin key that holds the endpoint's scope.
| Endpoint | Method | Description |
|---|---|---|
| /api/v1/flags/{flagKey}/environments/{environment}/rollback | POST | Return a flag to a previous version with no deploy. Admin key, rollouts:write. |
| /api/v1/flags/{flagKey}/environments/{environment}/versions | GET | List saved versions. flags:read. |
| /api/v1/code-references | POST | Report where a repository uses flags. Admin key, code_references:write. |
| /api/v1/code-references/flags | GET | List the project's flag keys for a scanner. |
| /api/v1/analytics/exposures | POST | Record which variant a person was shown. |
| /api/v1/analytics/outcomes | POST | Record what a person then did. |
Change stream#
Called by: SDKs. Authentication: any API key (client, server or admin) as a bearer token.
| Endpoint | Method | Description |
|---|---|---|
| /api/v1/evaluation/stream | GET | Server-Sent Events: ready, change and reset. See the stream details. |
Dashboard API#
Called by: the console, and scripts acting as a person. Authentication: the auth_session cookie from signing in; each endpoint names the permission it needs.
| Endpoint | Method | Description |
|---|---|---|
| /api/auth/login | POST | Sign in and receive the session cookie. See Authentication. |
| /api/flags | GET, POST | List and create flags. See Flags. |
| /api/flags/{id} | GET, PATCH, DELETE | Read, change or delete one flag. |
| /api/flags/{id}/toggle | POST | Turn a flag on or off in an environment. See Rollouts and history. |
| /api/segments | GET, POST | Reusable groups of people. See Segments. |
| /api/releases | GET, POST | Reviewed, scheduled changes. See Releases. |
| /api/api-keys | GET, POST | Create and list API keys. See Key management. |
| /api/audit-logs | GET | The audit trail. See Audit, events and metrics. |
Prometheus metrics#
Called by: a Prometheus server. Authentication: Authorization: Bearer followed by the operator's METRICS_TOKEN, a shared secret, not an API key.
| Endpoint | Method | Description |
|---|---|---|
| /api/prometheus | GET | Prometheus text format. Returns 404 when METRICS_TOKEN is not set and 401 for a wrong token. It is not at /metrics, which is the console's Metrics page. |
API specification
Two surfaces#
The server exposes two kinds of endpoint, and they authenticate differently. Pick by who is calling.
| Surface | Description |
|---|---|
| Evaluation API | Lives under /api/v1. Called by SDKs and your services with an API key as a bearer token. No cookies. Stable and versioned. See the Evaluation API. |
| Dashboard API | Lives under /api (everything except /api/v1). Called by the console with a signed-in session cookie. It is what the screens use, so it covers everything the console can do. |
Which one should my automation use?
Credentials at a glance#
| Credential | Looks like | Description |
|---|---|---|
| Session cookie | auth_session | A signed-in member, with that member's role. Reaches the Dashboard API: everything the console can do. For one-off tooling and the console itself. |
| Client key | fs_client_… | Evaluation only, for one person at a time. Safe to ship in a browser or mobile app. Holds only the evaluation:read scope, and reaches the client evaluation endpoint, the stream, exposures and outcomes. |
| Server key | fs_srv_… | Reads full flag configuration and can use the emergency stop. Scopes: evaluation:read, flags:read, environment:read, kill_switch:execute. For your backend and the server SDKs. Keep it secret. |
| Admin key | fs_admin_… | For automation that manages flags, for example instant rollback from a pipeline. May also hold flags:write, rollouts:write, audit:read and code_references:write. Never put it in an app. |
| Metrics token | METRICS_TOKEN | One shared secret the operator sets in the server's environment. Reaches only /api/prometheus. |
Keys cannot call the Dashboard API
Calling the Dashboard API#
Sign in once, keep the cookie, send it on every call. The session cookie is called auth_session, is HttpOnly and SameSite=Lax, and every request acts as the member who signed in, with that member's role.
# Sign in and keep the cookie
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":"..."}'
# Then call anything, as that member
curl -s -b jar.txt "https://flags.example.com/api/flags?projectId=PROJECT_ID&limit=20"Requests that change data are checked against the app's own address: a browser request from another site is refused with 403. Scripts and curl that send no Origin header are fine. If your tool runs on another address, list it in ALLOWED_ORIGINS.
Responses#
Every Dashboard API response is JSON with the same envelope, and every response carries an X-Request-Id header that matches the audit log and the server logs.
{ "status": "success", "message": "Flag created successfully", "data": { "id": "...", "name": "new-dashboard" } }{ "status": "error", "message": "Key may only contain lowercase letters, numbers, hyphens and underscores" }A validation failure lists every problem in one message, joined with commas. Creating returns 201; everything else that succeeds returns 200.
| Status | Description |
|---|---|
| 400 | Invalid JSON or a field that failed validation. |
| 401 | No session, or it has expired. Sign in again. |
| 403 | Your role does not hold the permission, the action is withdrawn in production for your role, a cross-site request was blocked, or the organization is deactivated (only GET /api/organization and the owner's reactivate still work). |
| 402 | FlagSwift Commercial only: the action is not in the organization's plan, or is at its cap (FEATURE_NOT_IN_PLAN, PLAN_LIMIT_REACHED). |
| 404 | The resource does not exist in your organization. |
| 409 | A conflict, such as a key that is already taken. |
| 429 | Too many attempts. Wait Retry-After seconds. Applies to sign-in and sign-up. |
Errors#
The two surfaces report errors in different shapes. The Dashboard API shape is under Responses. The Evaluation and Automation APIs return a stable machine-readable code to branch on, and never cache an error response.
{
"error": "Unauthorized",
"code": "AUTH_INVALID_API_KEY",
"details": "The provided API key is invalid or revoked."
}| Status · code | Description |
|---|---|
| 400 INVALID_JSON | The body is not valid JSON. |
| 400 INVALID_MODE | mode is neither config nor evaluate. |
| 400 ENV_REQUIRED | A project-wide key did not say which environment with ?env=. |
| 400 VALIDATION_ERROR | A field failed validation; details lists every problem. |
| 401 AUTH_MISSING_API_KEY | No bearer token was sent. |
| 401 AUTH_INVALID_API_KEY | The key is unknown, revoked or expired, or its project or organization is no longer active. |
| 403 AUTH_INSUFFICIENT_SCOPE | The key lacks the scope, or its type cannot call this endpoint. |
| 403 AUTH_ENVIRONMENT_MISMATCH | The key is limited to another environment. |
| 404 ENV_NOT_FOUND | No environment with that name. |
| 402 FEATURE_NOT_IN_PLAN · PLAN_LIMIT_REACHED | FlagSwift Commercial only. A dashboard or automation action is not in the organization's plan, or is at its cap. The Evaluation API never answers 402: flag delivery is not cut off by a plan. See Plans and limits. |
| 429 RATE_LIMITED | Over the per-key budget, or too many bad keys from this address. Wait Retry-After seconds. |
| 429 STREAM_LIMIT | Too many streams are open for this key. |
| 500 INTERNAL_ERROR | Unexpected. Quote the X-Request-Id header when asking for help. |
Send your own X-Request-Id (8 to 128 letters, digits, dots, dashes or underscores) and it is echoed back and written to the logs; otherwise the server makes one.
Rate limiting#
Limits are fixed windows: a counter starts at the first request and resets when the window ends. They are counted in the database by default, so every instance shares one count and a restart does not clear it. If the database cannot be reached, a request is counted in that instance's memory instead of being refused.
| Limit | Limit | Description |
|---|---|---|
| Per API key | 600 per minute | Every Evaluation and Automation request. Client-key endpoints (client evaluation, stream, exposures, outcomes) count per key and visitor address, so one busy visitor cannot use up the key. |
| Bad API keys | 30 per minute | Per address. Past it, even a good key from that address gets 429. |
| Sign-in, per address and email | 10 per 15 minutes | Failed attempts only; a successful sign-in clears it. |
| Sign-in, per address | 50 per 15 minutes | Failed attempts across all emails: five times the limit above. |
| Sign-up and invitation accept | 5 per hour | Per address. |
| Verification emails | 5 per hour, 20 per hour | Per address and email, and per address. Sign-up, resend and refused sign-ins on an unverified account count. |
| Verify email (submit a link) | 10 per 15 minutes | Per address. |
| Change password | 5 per 15 minutes | Wrong current passwords, per member. |
| Open streams | 100 per key | The instance as a whole accepts 5,000, and each stream lasts 300 seconds. |
There is no global limit across all callers, and no limit on the signed-in Dashboard API beyond the sign-in, sign-up and password limits above. Successful key responses carry X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (seconds until the window ends, not a timestamp). A 429 carries Retry-After in seconds.
Retry-After: 23
Content-Type: application/json
{ "error": "Too Many Requests", "code": "RATE_LIMITED", "details": "Rate limit exceeded for this API key." }Behind a proxy
X-Forwarded-For, or X-Real-IP. Run the server behind a proxy that sets it, or every visitor shares one address. The limits are fixed and counted in the database, so every instance shares them. Operators can set RATE_LIMIT_ENABLED=false to turn them all off.CORS#
| Endpoints | CORS | Description |
|---|---|---|
| Client evaluation | Open (*) | Allows GET, POST and OPTIONS, the headers Authorization, Content-Type, If-None-Match, X-FlagSwift-SDK and X-Request-Id. Preflights are cached for a day. |
| Stream | Open (*) | Allows GET and OPTIONS. |
| Exposures and outcomes | Open (*) | Allows POST and OPTIONS. |
| Server evaluation, errors, code references, rollback, versions | None | No CORS headers: call them from a backend, never a browser. |
| Dashboard API | None | No CORS headers. State-changing requests must come from the app's own origin, or one listed in ALLOWED_ORIGINS; otherwise 403. |
Open CORS is safe here because these endpoints use a bearer key, never a cookie, and a client key can do nothing but evaluate.
Versioning and stability#
- Evaluation and Automation APIs are versioned in the path:
/api/v1. Withinv1the documented fields and codes are meant to stay, so build on them. - Dashboard API is not versioned. It serves the console and can change between releases; prefer the Evaluation and Automation APIs for anything you cannot update quickly.
- Treat unknown fields in a response as additions and ignore them. Branch on
code, not on the wording ofmessageordetails.
Retries and idempotency#
GETcalls are safe to repeat. SendIf-None-Matchwith the lastETagto turn an unchanged poll into a304.- On
429, waitRetry-Afterseconds. On5xx, retry with exponential backoff and a little jitter. Do not retry other4xxresponses; they will fail the same way. - A rollback is not idempotent: each one is recorded as a new version. Pass
versionso a retry lands on the same target, and check the result before repeating it. - A code-reference report replaces the repository's previous report, so sending it twice leaves the same result.
Keep your keys private
Lists and pagination#
List endpoints that can grow return { items, pagination } and take page (from 1) and limit. The default limit is shown on each page; the maximum is 100.
{ "items": [ ... ], "pagination": { "page": 1, "limit": 10, "total": 42, "totalPages": 5, "hasNext": true, "hasPrev": false } }Roles and permissions#
Each endpoint names the permission it needs, shown beside its path, such as flags.update. A role either holds it or does not. Organization admins hold every permission except the system.* ones; viewers hold read permissions only.
- In an environment marked production, developers lose the permissions that change what people see: toggling, rollouts, targeting and the kill switch. Release managers and admins keep them.
- Some actions ask a second question of the data. Moving a flag between projects needs
flags.move(admins only), and deactivating the organization is owner-only. - A
403never says which permission was missing beyond its message; the console hides controls you cannot use, but hiding is a convenience, not security.
Where to go next#
- Evaluation API: client and server evaluation, SDK error reports, rollback and version history by key.
- Authentication, Flags, Rollouts and history: the day-to-day calls.
- Projects and environments, Segments, Releases: how work is organised and reviewed.
- Members, Key management, Alerts, Audit, events and metrics, Organization: administration and operations.