Skip to content
FlagSwiftDocs

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.

  1. 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 a server key instead when the call comes from your backend and you want reasons or the full configuration; see API keys.

  2. Call the Evaluation API

    Send the key as a bearer token and say who you are asking about. identifiers is the user; attributes are 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"}}'
  3. Read the result

    A 200 returns every flag in the environment, already decided for this person. A flag with variants also carries variant and value. 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 code to branch on: AUTH_INVALID_API_KEY for a mistyped or revoked key, ENV_REQUIRED when a project-wide key sent no env, and ENV_NOT_FOUND for 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.

The APIs at a glance
APIPathDescription
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, /analyticsUsed 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/streamUsed by SDKs that want changes pushed. Server-Sent Events with any API key; it carries no flag data.
Prometheus metrics/api/prometheusUsed 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.

Key endpoints of the Evaluation API
EndpointMethodDescription
/api/v1/evaluation/clientPOST, GETEvaluate every flag for one person. Any key type.
/api/v1/evaluation/serverGETDownload configuration (mode=config) or evaluate on the server. Server or admin key.
/api/v1/evaluation/errorsPOSTSDKs 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.

Key endpoints of the Automation API
EndpointMethodDescription
/api/v1/flags/{flagKey}/environments/{environment}/rollbackPOSTReturn a flag to a previous version with no deploy. Admin key, rollouts:write.
/api/v1/flags/{flagKey}/environments/{environment}/versionsGETList saved versions. flags:read.
/api/v1/code-referencesPOSTReport where a repository uses flags. Admin key, code_references:write.
/api/v1/code-references/flagsGETList the project's flag keys for a scanner.
/api/v1/analytics/exposuresPOSTRecord which variant a person was shown.
/api/v1/analytics/outcomesPOSTRecord what a person then did.

Change stream#

Called by: SDKs. Authentication: any API key (client, server or admin) as a bearer token.

Key endpoints of the change stream
EndpointMethodDescription
/api/v1/evaluation/streamGETServer-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.

Key endpoints of the Dashboard API
EndpointMethodDescription
/api/auth/loginPOSTSign in and receive the session cookie. See Authentication.
/api/flagsGET, POSTList and create flags. See Flags.
/api/flags/{id}GET, PATCH, DELETERead, change or delete one flag.
/api/flags/{id}/togglePOSTTurn a flag on or off in an environment. See Rollouts and history.
/api/segmentsGET, POSTReusable groups of people. See Segments.
/api/releasesGET, POSTReviewed, scheduled changes. See Releases.
/api/api-keysGET, POSTCreate and list API keys. See Key management.
/api/audit-logsGETThe 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.

Key endpoints of the metrics API
EndpointMethodDescription
/api/prometheusGETPrometheus 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

There is no generated OpenAPI file. This reference, written against the source, is the specification: every path, field and status code here was checked against the route handlers.

Two surfaces#

The server exposes two kinds of endpoint, and they authenticate differently. Pick by who is calling.

The two API surfaces
SurfaceDescription
Evaluation APILives 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 APILives 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?

For deploy pipelines and scripts, use the Evaluation API: an admin key can read versions and roll a flag back, and a key can be revoked without touching anyone's account. The Dashboard API is not versioned and acts as a person, so it can change between releases. Use it for one-off tooling and when you need something no key can do yet, such as managing segments or releases.

Credentials at a glance#

What each credential can reach
CredentialLooks likeDescription
Session cookieauth_sessionA 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 keyfs_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 keyfs_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 keyfs_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 tokenMETRICS_TOKENOne shared secret the operator sets in the server's environment. Reaches only /api/prometheus.

Keys cannot call the Dashboard API

API keys are for the Evaluation API only. They are scoped, revocable and never carry a person's permissions. See API keys for rotation and scopes.

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.

bash
# 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.

Success
{ "status": "success", "message": "Flag created successfully", "data": { "id": "...", "name": "new-dashboard" } }
Failure
{ "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 codes
StatusDescription
400Invalid JSON or a field that failed validation.
401No session, or it has expired. Sign in again.
403Your 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).
402FlagSwift Commercial only: the action is not in the organization's plan, or is at its cap (FEATURE_NOT_IN_PLAN, PLAN_LIMIT_REACHED).
404The resource does not exist in your organization.
409A conflict, such as a key that is already taken.
429Too 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.

Evaluation API error · 401
{
  "error": "Unauthorized",
  "code": "AUTH_INVALID_API_KEY",
  "details": "The provided API key is invalid or revoked."
}
Status codes and error codes on /api/v1
Status · codeDescription
400 INVALID_JSONThe body is not valid JSON.
400 INVALID_MODEmode is neither config nor evaluate.
400 ENV_REQUIREDA project-wide key did not say which environment with ?env=.
400 VALIDATION_ERRORA field failed validation; details lists every problem.
401 AUTH_MISSING_API_KEYNo bearer token was sent.
401 AUTH_INVALID_API_KEYThe key is unknown, revoked or expired, or its project or organization is no longer active.
403 AUTH_INSUFFICIENT_SCOPEThe key lacks the scope, or its type cannot call this endpoint.
403 AUTH_ENVIRONMENT_MISMATCHThe key is limited to another environment.
404 ENV_NOT_FOUNDNo environment with that name.
402 FEATURE_NOT_IN_PLAN · PLAN_LIMIT_REACHEDFlagSwift 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_LIMITEDOver the per-key budget, or too many bad keys from this address. Wait Retry-After seconds.
429 STREAM_LIMITToo many streams are open for this key.
500 INTERNAL_ERRORUnexpected. 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.

Rate limits and the settings that change them
LimitLimitDescription
Per API key600 per minuteEvery 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 keys30 per minutePer address. Past it, even a good key from that address gets 429.
Sign-in, per address and email10 per 15 minutesFailed attempts only; a successful sign-in clears it.
Sign-in, per address50 per 15 minutesFailed attempts across all emails: five times the limit above.
Sign-up and invitation accept5 per hourPer address.
Verification emails5 per hour, 20 per hourPer 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 minutesPer address.
Change password5 per 15 minutesWrong current passwords, per member.
Open streams100 per keyThe 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.

429 Too Many Requests
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

The caller's address comes from 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#

Which endpoints allow cross-origin browser calls
EndpointsCORSDescription
Client evaluationOpen (*)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.
StreamOpen (*)Allows GET and OPTIONS.
Exposures and outcomesOpen (*)Allows POST and OPTIONS.
Server evaluation, errors, code references, rollback, versionsNoneNo CORS headers: call them from a backend, never a browser.
Dashboard APINoneNo 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. Within v1 the 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 of message or details.

Retries and idempotency#

  • GET calls are safe to repeat. Send If-None-Match with the last ETag to turn an unchanged poll into a 304.
  • On 429, wait Retry-After seconds. On 5xx, retry with exponential backoff and a little jitter. Do not retry other 4xx responses; they will fail the same way.
  • A rollback is not idempotent: each one is recorded as a new version. Pass version so 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

Server and admin keys read targeting data and can change flags. Keep them in a secret store or environment variable on your backend, never in a browser, mobile app, repository or log. Only client keys are meant to be public. If a key leaks, revoke or rotate it on the API keys page.

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.

json
{ "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 403 never 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#