Skip to content
FlagSwiftDocs

Evaluation API

The HTTP endpoints behind the SDKs. Use them directly from any language.

Authentication#

Send your API key as a bearer token. No cookies are used. Responses are marked Cache-Control: no-store, and every response carries an X-Request-Id you can quote when asking for help.

http
Authorization: Bearer fs_client_...

A key limited to one environment always evaluates that environment. A key that covers the whole project must say which one with ?env=production.

Client evaluation#

Evaluate flags for one person#

POST/api/v1/evaluation/client

For browsers and mobile apps. Returns only the result for one person: no reasons, targeting lists or rollout numbers. POST keeps attributes out of URLs and access logs; GET takes the same fields as query parameters.

Responses carry an ETag. Send it back as If-None-Match, on GET or POST, and an unchanged result costs a 304 with no body. Use the tag only for the same person you asked about.

Authorization

any key type · scope evaluation:read · CORS open

Query parameters

  • envstring

    Environment name. Required for a project-wide key; a key limited to one environment may omit it or name that same environment.

Body (POST)

  • identifiersstring | string[]

    The user, or the user's ids. user is accepted as an alias. Blanks are dropped and only the first 10 are used.
  • accountsstring | string[]

    The organization or tenant (alias account). Up to 10.
  • devicesstring | string[]

    The install (alias device). Up to 10.
  • attributesobject

    Free-form values that targeting rules can match, such as plan or country. A JSON object of at most 8,192 characters once serialized.

Query parameters (GET)

  • user_identifierstring

    Also user_identifier_0 to user_identifier_9. Same for account_identifier and device_identifier.
  • user_attributesJSON object

    URL-encoded attributes, at most 8,192 characters.

Errors

  • 304The If-None-Match ETag still matches (on GET and on POST). No body. On FlagSwift Commercial a 304 is not counted against the plan's request allowance.
  • 400INVALID_JSON (body is not JSON), INVALID_BODY (body is not an object, or an id list is not strings), INVALID_ATTRIBUTES (not an object, or too large) or ENV_REQUIRED (a project-wide key sent no env).
  • 401AUTH_MISSING_API_KEY or AUTH_INVALID_API_KEY (unknown, revoked or expired key, or its organization or project is switched off).
  • 403AUTH_ENVIRONMENT_MISMATCH (the key is limited to another environment) or AUTH_INSUFFICIENT_SCOPE (the key lacks evaluation:read).
  • 404ENV_NOT_FOUND: no environment with that name.
  • 429RATE_LIMITED. Wait Retry-After seconds.
Request
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"}}'
200OK
{
  "environment": "production",
  "hashVersion": 1,
  "version": "f1c2",
  "flags": {
    "new-dashboard": { "enabled": true, "version": 7 },
    "checkout-layout": { "enabled": true, "variant": "compact", "value": "compact", "version": 3 }
  }
}

Server configuration and evaluation#

Download configuration or evaluate on the server#

GET/api/v1/evaluation/server

Backend only, because it returns targeting lists and rollout numbers. There are two modes.

Evaluate for one person, with reasons
curl -s "https://flags.example.com/api/v1/evaluation/server?env=production&user_identifier=user-123&explain=true" \
  -H "Authorization: Bearer $FLAGSWIFT_SERVER_KEY"

The configuration payload includes the segments and prerequisite flags the flags depend on, so an SDK can evaluate everything locally with the same engine the server uses. Both modes send an ETag; only mode=config answers If-None-Match with a 304.

Authorization

server or admin key · scope evaluation:read · no CORS

Query parameters

  • modeconfig | evaluate

    config returns every flag's configuration for local evaluation. evaluate (the default) evaluates for the given person on the server. Anything else is INVALID_MODE.
  • envstring

    Environment name. Required for a project-wide key.
  • user_identifierstring

    Evaluate mode only. Also user_identifier_0 to user_identifier_9. Same for account_identifier and device_identifier.
  • user_attributesJSON object

    Evaluate mode only. URL-encoded attributes for targeting rules, at most 8,192 characters.
  • explainboolean

    Evaluate mode only. Only the exact value true adds each result's reason, such as ROLLOUT_IN.

Headers

  • If-None-Matchstring

    The ETag of the last configuration you hold. mode=config only.

Errors

  • 304Nothing changed since the ETag you sent (mode=config). No body.
  • 400INVALID_MODE, INVALID_ATTRIBUTES or ENV_REQUIRED.
  • 401AUTH_MISSING_API_KEY or AUTH_INVALID_API_KEY.
  • 403AUTH_INSUFFICIENT_SCOPE (a client key cannot call this endpoint), or AUTH_ENVIRONMENT_MISMATCH.
  • 404ENV_NOT_FOUND: no environment with that name.
  • 429RATE_LIMITED.
Request: download configuration
curl -s "https://flags.example.com/api/v1/evaluation/server?mode=config&env=production" \
  -H "Authorization: Bearer $FLAGSWIFT_SERVER_KEY" \
  -H 'If-None-Match: "f1c2"'
200OK · mode=config
{
  "environment": "production",
  "hashVersion": 1,
  "rulesVersion": 1,
  "version": "9d1f0c2b7a4e5f60",
  "segments": {
    "beta-testers": { "users": ["user-123"], "rules": [] }
  },
  "flags": {
    "new-dashboard": {
      "type": "boolean",
      "version": 7,
      "config": {
        "enabled": true,
        "killSwitchActive": false,
        "rolloutPercentage": 25,
        "targeting": { "enabled": true, "users": ["user-123"] },
        "segments": ["beta-testers"]
      }
    }
  }
}

Real-time change stream#

Listen for changes#

GET/api/v1/evaluation/stream

Keeps a connection open and tells the SDK the moment something changes, so it can fetch the new configuration straight away instead of waiting for its next poll. The stream carries no flag data, only the fact that something changed; the SDK then makes its usual request (a conditional GET for server SDKs, the evaluation call for client SDKs). A key can therefore listen without seeing more than the matching evaluation endpoint already shows it.

Events
EventDescription
readySent once the connection is open, with the environment name. SDKs refetch here to catch anything missed while they were disconnected.
changeA flag, segment, rollout or release in the project changed. Changes that arrive within 100 ms are sent as one event.
resetThe project's keys or availability changed. The server closes the stream and the SDK reconnects, which signs it in again.
: keep-aliveA comment line every 20 seconds so proxies do not close an idle connection. Readers ignore it.

Each connection ends after 5 minutes and the SDK reconnects. A stream needs an HTTP stack that does not buffer responses: the server sends X-Accel-Buffering: no for nginx, and other proxies must pass text/event-stream through unbuffered. Browsers cannot send an Authorization header with EventSource, which is why the SDKs read the stream with fetch.

Authorization

any key type · scope evaluation:read · CORS open · Server-Sent Events

Query parameters

  • envstring

    Environment name. Required for a project-wide key.

Errors

  • 204Streaming is switched off on this server (STREAM_ENABLED=false). No body: keep polling.
  • 400ENV_REQUIRED: a project-wide key sent no env.
  • 401AUTH_MISSING_API_KEY or AUTH_INVALID_API_KEY.
  • 403AUTH_ENVIRONMENT_MISMATCH or AUTH_INSUFFICIENT_SCOPE.
  • 429STREAM_LIMIT (too many open streams for this key or this instance) or RATE_LIMITED. Wait Retry-After seconds.
Request
curl -N "https://flags.example.com/api/v1/evaluation/stream?env=production" \
  -H "Authorization: Bearer $FLAGSWIFT_SERVER_KEY"
200OK
retry: 3000

event: ready
data: {"environment":"production"}

: keep-alive

event: change
data: {"at":1767225600000}

One instance at a time

A change reaches the streams open on the instance that handled it at once. Other instances notice it on their next database check (5 seconds by default, DELIVERY_SYNC_INTERVAL_SECONDS) and tell their open streams to refetch. SDKs also keep a slow safety-net poll (5 minutes by default while connected), so every instance catches up even if it heard nothing.

Reporting SDK errors#

Report SDK errors#

POST/api/v1/evaluation/errors

SDKs report problems they hit while evaluating (network failures, unparsable configuration, unknown flags). Only counts are stored, never who was evaluated. They appear on the Errors page as SDK-reported.

Request body
{ "errors": [{ "flagKey": "new-dashboard", "errorType": "CONFIG_PARSE_FAILED", "count": 3, "sdk": "my-service/1.4" }] }

Success is 202 with the number of entries accepted.

Authorization

any key type

Query parameters

  • envstring

    Environment name. Required for a project-wide key.

Body

  • errorsobject[]Required

    1 to 100 entries.
  • errors[].errorTypestringRequired

    Up to 40 characters. Upper snake case such as NETWORK_ERROR; lower case is upper-cased, and anything that still does not fit 2 to 40 letters, digits and underscores starting with a letter is recorded as OTHER.
  • errors[].flagKeystring

    The flag involved, up to 100 characters.
  • errors[].countinteger

    How many times it happened, 1 to 10,000. Default 1.
  • errors[].sdkstring

    SDK name and version, up to 64 characters. Defaults to the X-FlagSwift-SDK header, then the user agent.

Errors

  • 400INVALID_JSON, ENV_REQUIRED, or VALIDATION_ERROR (no errors sent, more than 100, a missing errorType, or a field too long).
  • 401AUTH_MISSING_API_KEY or AUTH_INVALID_API_KEY.
  • 403AUTH_ENVIRONMENT_MISMATCH or AUTH_INSUFFICIENT_SCOPE.
  • 429RATE_LIMITED.
Request
curl -s -X POST "https://flags.example.com/api/v1/evaluation/errors?env=production" \
  -H "Authorization: Bearer $FLAGSWIFT_SERVER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"errors":[{"flagKey":"new-dashboard","errorType":"CONFIG_PARSE_FAILED","count":3,"sdk":"my-service/1.4"}]}'
202Accepted
{ "accepted": 1 }

Reporting code references#

Report code references#

POST/api/v1/code-references

Reports where a repository uses flags. The report replaces what that repository reported before, so a flag removed from code is cleared on the next scan. The project is the key's own. The bundled scanner, tools/flagswift-scan.mjs, calls this from CI.

Request body
{
  "repository": "acme/web",
  "branch": "main",
  "commit": "9f2c1ab…",
  "flags": [
    { "flagKey": "checkout-v2", "locations": [{ "path": "src/checkout/payment.ts", "line": 42 }] }
  ]
}

Up to 2,000 flags per call, 100 locations kept per flag, and 50 repositories per project. Returns { repository, flags, locations, cleared, unknownKeys }, where unknownKeys lists reported keys that match no flag in the project.

Authorization

admin key · scope code_references:write

Body

  • repositorystringRequired

    Repository name, such as acme/web. Up to 200 characters. It identifies what to replace.
  • branchstring

    Up to 200 characters.
  • commitstring

    Up to 64 characters.
  • flagsobject[]Required

    Up to 2,000 entries, each { flagKey, locations }. An empty list clears the repository.
  • flags[].flagKeystringRequired

    Up to 100 characters.
  • flags[].locations{ path, line }[]Required

    At least one. Each needs a path (up to 500 characters) and a line of 1 or more. Only the first 100 per flag are kept.

Errors

  • 400BAD_REQUEST (“Invalid JSON body”, or a repository or project limit exceeded) or VALIDATION_ERROR (a missing or over-long field).
  • 401AUTH_MISSING_API_KEY or AUTH_INVALID_API_KEY.
  • 403AUTH_INSUFFICIENT_SCOPE: needs an admin key with code_references:write.
  • 429RATE_LIMITED.
Request
curl -s -X POST "https://flags.example.com/api/v1/code-references" \
  -H "Authorization: Bearer $FLAGSWIFT_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"repository":"acme/web","branch":"main","commit":"9f2c1ab","flags":[{"flagKey":"checkout-v2","locations":[{"path":"src/checkout/payment.ts","line":42}]}]}'
200OK
{ "repository": "acme/web", "flags": 1, "locations": 1, "cleared": 0, "unknownKeys": [] }

List flag keys#

GET/api/v1/code-references/flags

Lists the project's flag keys, archived ones included and marked, so a scanner looks for real flags instead of guessing. Returns { flags: [{ key, archived }] }. It takes no parameters; the key's own project is used and every flag is returned, with no paging.

Authorization

server or admin key · scope flags:read

Errors

  • 401AUTH_MISSING_API_KEY or AUTH_INVALID_API_KEY.
  • 403AUTH_INSUFFICIENT_SCOPE: a client key cannot call this, or the key lacks flags:read.
  • 429RATE_LIMITED.
Request
curl -s "https://flags.example.com/api/v1/code-references/flags" \
  -H "Authorization: Bearer $FLAGSWIFT_SERVER_KEY"
200OK
{ "flags": [{ "key": "checkout-v2", "archived": false }, { "key": "old-banner", "archived": true }] }

Reporting exposures and outcomes#

Tell FlagSwift who was shown which variant, and what they then did, so it can compare conversion between variants. Both take an env query parameter (not needed for a key limited to one environment) and reply 202. Nothing is kept unless the server runs with ANALYTICS_ENABLED=true; otherwise the reply is { "enabled": false, "recorded": 0, "ignored": 0 }. The SDKs do this for you; see Outcome analytics for the bodies and the privacy rules.

Report exposures#

POST/api/v1/analytics/exposures

Authorization

any key type · scope evaluation:read · CORS · 202

Query parameters

  • envstring

    Environment name. Required for a project-wide key.

Body

  • userKeystringRequired

    Who was shown the variants (alias user). Up to 255 characters. Only a keyed hash is stored.
  • exposuresobject[]Required

    1 to 50 entries. Repeats of the same flag and variant are collapsed.
  • exposures[].flagstringRequired

    The flag key.
  • exposures[].variantstring

    The variant shown. Give this or enabled.
  • exposures[].enabledboolean

    For a flag without variants: whether it was on. Give this or variant.

Errors

  • 400INVALID_JSON, INVALID_BODY (exposures must be a non-empty list, each with a flag and a variant or enabled), INVALID_USER_KEY, TOO_MANY_EXPOSURES (over 50) or ENV_REQUIRED.
  • 401AUTH_MISSING_API_KEY or AUTH_INVALID_API_KEY.
  • 403AUTH_ENVIRONMENT_MISMATCH or AUTH_INSUFFICIENT_SCOPE.
  • 429RATE_LIMITED.
Request
curl -X POST "https://flags.example.com/api/v1/analytics/exposures?env=production" \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"userKey":"user-42","exposures":[{"flag":"button-colour","variant":"green"}]}'
202Accepted
{ "enabled": true, "recorded": 1, "ignored": 0 }

Report outcomes#

POST/api/v1/analytics/outcomes

Authorization

any key type · scope evaluation:read · CORS · 202

Query parameters

  • envstring

    Environment name. Required for a project-wide key.

Body

  • userKeystringRequired

    The person who did it (alias user), up to 255 characters. Use the same key as for exposures.
  • eventstringRequired

    The event name, such as purchase. Letters, numbers and . _ / + -; other characters are removed.
  • valuenumber

    An amount to sum, such as revenue. A finite number between -1,000,000,000 and 1,000,000,000.

Errors

  • 400INVALID_JSON, INVALID_BODY, INVALID_USER_KEY, INVALID_EVENT (event is required) or INVALID_VALUE (value must be a finite number in range), or ENV_REQUIRED.
  • 401AUTH_MISSING_API_KEY or AUTH_INVALID_API_KEY.
  • 403AUTH_ENVIRONMENT_MISMATCH or AUTH_INSUFFICIENT_SCOPE.
  • 429RATE_LIMITED.
Request
curl -X POST "https://flags.example.com/api/v1/analytics/outcomes?env=production" \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"userKey":"user-42","event":"purchase","value":49.9}'
202Accepted
{ "enabled": true, "recorded": 1, "ignored": 0 }

Rollback and version history#

Roll a flag back#

POST/api/v1/flags/{flagKey}/environments/{environment}/rollback

Returns a flag's environment to its previous configuration, or to a given version, with no deploy. The rollback is recorded as a new version and in the audit log under the key's name. It never restores the emergency stop and is refused while that is active.

Authorization

admin key · scope rollouts:write

Path parameters

  • flagKeystringRequired

    The flag key. Archived flags are not found.
  • environmentstringRequired

    Environment name. A key limited to one environment must name that one.

Body

  • versioninteger

    The version to return to, 1 or more. Leave it out for the previous version.
  • reasonstring

    Why, up to 300 characters. Kept in the history and the audit log.

Errors

  • 400VALIDATION_ERROR: version must be a whole number of 1 or more, reason at most 300 characters. BAD_REQUEST for invalid JSON, when the flag is already at that version, or when it has no earlier version.
  • 401AUTH_MISSING_API_KEY or AUTH_INVALID_API_KEY.
  • 403AUTH_INSUFFICIENT_SCOPE (needs an admin key with rollouts:write), AUTH_ENVIRONMENT_MISMATCH, the key's creator lacks rollback permission in that environment, or the emergency stop is active (“Cannot roll back while the kill switch is active”).
  • 404NOT_FOUND: no flag with that key, or the version does not exist.
  • 429RATE_LIMITED.
Request
curl -s -X POST "https://flags.example.com/api/v1/flags/new-dashboard/environments/production/rollback" \
  -H "Authorization: Bearer $FLAGSWIFT_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reason":"error rate spike after release"}'
200OK
{ "flag": "new-dashboard", "environment": "production", "version": 8, "enabled": false, "rolloutPercentage": 0 }

List versions#

GET/api/v1/flags/{flagKey}/environments/{environment}/versions

Lists saved versions, newest first, so you can choose a target. Takes page and limit.

Authorization

server or admin key · scope flags:read

Path parameters

  • flagKeystringRequired

    The flag key.
  • environmentstringRequired

    Environment name.

Query parameters

  • pageinteger

    Page number, from 1. Default 1.
  • limitinteger

    Versions per page, 1 to 100. Default 20.

Errors

  • 400VALIDATION_ERROR: a page or limit out of range.
  • 401AUTH_MISSING_API_KEY or AUTH_INVALID_API_KEY.
  • 403AUTH_INSUFFICIENT_SCOPE (a client key cannot call this) or AUTH_ENVIRONMENT_MISMATCH.
  • 404NOT_FOUND: no flag with that key, or no such environment.
  • 429RATE_LIMITED.
Request
curl -s "https://flags.example.com/api/v1/flags/new-dashboard/environments/production/versions?limit=2" \
  -H "Authorization: Bearer $FLAGSWIFT_SERVER_KEY"
200OK
{
  "flag": "new-dashboard",
  "environment": "production",
  "current": 7,
  "items": [
    { "id": "...", "version": 7, "action": "...", "config": { }, "restoredFrom": null, "reason": null, "actorEmail": "...", "createdAt": "2026-10-01T09:30:00.000Z" }
  ],
  "pagination": { "page": 1, "limit": 2, "total": 7, "totalPages": 4, "hasNext": true, "hasPrev": false }
}

Reading a result#

Fields in each flag result
FieldTypeDescription
enabledbooleanWhether the flag is on for this person.
variantstringThe chosen variant of a multivariate flag.
valueanyThe variant's value: a string, number or JSON.
versionnumberThe flag's version, which rises with every change.
reasonstringOnly when requested on the server endpoint. See the reasons below.
Evaluation reasons
ReasonDescription
KILL_SWITCHAn emergency stop is active; the off result is served to everyone.
DISABLEDThe flag is off in this environment.
TARGETED_USERThe person (or their account or device) is explicitly targeted.
SEGMENT_MATCHThe person belongs to a targeted segment.
RULE_MATCHAn attribute rule matched.
DEPENDENCY_BLOCKEDA prerequisite flag is not on for this person.
FULL_ROLLOUTRolled out to 100%.
ROLLOUT_IN / ROLLOUT_OUTInside or outside the percentage rollout.
NO_IDENTIFIERThe flag buckets by something you did not send.
ENV_NOT_CONFIGUREDThe flag has no configuration for this environment.
FLAG_NOT_FOUNDNo flag with this key.

Errors and limits#

Errors use one shape, with a stable code to branch on:

json
{ "error": "Unauthorized", "code": "AUTH_INVALID_API_KEY", "details": "..." }
Status codes
StatusDescription
400Bad input, for example INVALID_ATTRIBUTES, INVALID_JSON, INVALID_MODE, ENV_REQUIRED or VALIDATION_ERROR.
401AUTH_MISSING_API_KEY or AUTH_INVALID_API_KEY (unknown, revoked or expired key).
403The key type or scope is not allowed here, or the key is limited to another environment.
404ENV_NOT_FOUND: no environment with that name.
429RATE_LIMITED. Wait for Retry-After seconds. X-RateLimit-Limit and X-RateLimit-Remaining are sent on API responses.

Rate limits

A key may make 600 requests a minute, and repeated bad keys are blocked per address. Client keys are limited per key and visitor address, so one busy visitor cannot use up everyone's allowance. The limits are fixed and counted in the database, so all instances share one count.