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.
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#
/api/v1/evaluation/clientFor 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
envstringEnvironment 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.useris accepted as an alias. Blanks are dropped and only the first 10 are used.accountsstring | string[]The organization or tenant (aliasaccount). Up to 10.devicesstring | string[]The install (aliasdevice). Up to 10.attributesobjectFree-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_identifierstringAlsouser_identifier_0touser_identifier_9. Same foraccount_identifieranddevice_identifier.user_attributesJSON objectURL-encoded attributes, at most 8,192 characters.
Errors
- 304The
If-None-MatchETag still matches (onGETand onPOST). No body. On FlagSwift Commercial a304is not counted against the plan's request allowance. - 400
INVALID_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) orENV_REQUIRED(a project-wide key sent noenv). - 401
AUTH_MISSING_API_KEYorAUTH_INVALID_API_KEY(unknown, revoked or expired key, or its organization or project is switched off). - 403
AUTH_ENVIRONMENT_MISMATCH(the key is limited to another environment) orAUTH_INSUFFICIENT_SCOPE(the key lacksevaluation:read). - 404
ENV_NOT_FOUND: no environment with that name. - 429
RATE_LIMITED. WaitRetry-Afterseconds.
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"}}'{
"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#
/api/v1/evaluation/serverBackend only, because it returns targeting lists and rollout numbers. There are two modes.
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 | evaluateconfigreturns every flag's configuration for local evaluation.evaluate(the default) evaluates for the given person on the server. Anything else isINVALID_MODE.envstringEnvironment name. Required for a project-wide key.user_identifierstringEvaluate mode only. Alsouser_identifier_0touser_identifier_9. Same foraccount_identifieranddevice_identifier.user_attributesJSON objectEvaluate mode only. URL-encoded attributes for targeting rules, at most 8,192 characters.explainbooleanEvaluate mode only. Only the exact valuetrueadds each result's reason, such asROLLOUT_IN.
Headers
If-None-MatchstringTheETagof the last configuration you hold.mode=configonly.
Errors
- 304Nothing changed since the ETag you sent (mode=config). No body.
- 400
INVALID_MODE,INVALID_ATTRIBUTESorENV_REQUIRED. - 401
AUTH_MISSING_API_KEYorAUTH_INVALID_API_KEY. - 403
AUTH_INSUFFICIENT_SCOPE(a client key cannot call this endpoint), orAUTH_ENVIRONMENT_MISMATCH. - 404
ENV_NOT_FOUND: no environment with that name. - 429
RATE_LIMITED.
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"'{
"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#
/api/v1/evaluation/streamKeeps 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.
| Event | Description |
|---|---|
| ready | Sent once the connection is open, with the environment name. SDKs refetch here to catch anything missed while they were disconnected. |
| change | A flag, segment, rollout or release in the project changed. Changes that arrive within 100 ms are sent as one event. |
| reset | The project's keys or availability changed. The server closes the stream and the SDK reconnects, which signs it in again. |
| : keep-alive | A 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
envstringEnvironment name. Required for a project-wide key.
Errors
- 204Streaming is switched off on this server (
STREAM_ENABLED=false). No body: keep polling. - 400
ENV_REQUIRED: a project-wide key sent noenv. - 401
AUTH_MISSING_API_KEYorAUTH_INVALID_API_KEY. - 403
AUTH_ENVIRONMENT_MISMATCHorAUTH_INSUFFICIENT_SCOPE. - 429
STREAM_LIMIT(too many open streams for this key or this instance) orRATE_LIMITED. WaitRetry-Afterseconds.
curl -N "https://flags.example.com/api/v1/evaluation/stream?env=production" \
-H "Authorization: Bearer $FLAGSWIFT_SERVER_KEY"retry: 3000
event: ready
data: {"environment":"production"}
: keep-alive
event: change
data: {"at":1767225600000}One instance at a time
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#
/api/v1/evaluation/errorsSDKs 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.
{ "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
envstringEnvironment name. Required for a project-wide key.
Body
errorsobject[]Required1 to 100 entries.errors[].errorTypestringRequiredUp to 40 characters. Upper snake case such asNETWORK_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 asOTHER.errors[].flagKeystringThe flag involved, up to 100 characters.errors[].countintegerHow many times it happened, 1 to 10,000. Default 1.errors[].sdkstringSDK name and version, up to 64 characters. Defaults to theX-FlagSwift-SDKheader, then the user agent.
Errors
- 400
INVALID_JSON,ENV_REQUIRED, orVALIDATION_ERROR(no errors sent, more than 100, a missingerrorType, or a field too long). - 401
AUTH_MISSING_API_KEYorAUTH_INVALID_API_KEY. - 403
AUTH_ENVIRONMENT_MISMATCHorAUTH_INSUFFICIENT_SCOPE. - 429
RATE_LIMITED.
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"}]}'{ "accepted": 1 }Reporting code references#
Report code references#
/api/v1/code-referencesReports 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.
{
"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
repositorystringRequiredRepository name, such as acme/web. Up to 200 characters. It identifies what to replace.branchstringUp to 200 characters.commitstringUp to 64 characters.flagsobject[]RequiredUp to 2,000 entries, each { flagKey, locations }. An empty list clears the repository.flags[].flagKeystringRequiredUp to 100 characters.flags[].locations{ path, line }[]RequiredAt 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
- 400
BAD_REQUEST(“Invalid JSON body”, or a repository or project limit exceeded) orVALIDATION_ERROR(a missing or over-long field). - 401
AUTH_MISSING_API_KEYorAUTH_INVALID_API_KEY. - 403
AUTH_INSUFFICIENT_SCOPE: needs an admin key withcode_references:write. - 429
RATE_LIMITED.
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}]}]}'{ "repository": "acme/web", "flags": 1, "locations": 1, "cleared": 0, "unknownKeys": [] }List flag keys#
/api/v1/code-references/flagsLists 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
- 401
AUTH_MISSING_API_KEYorAUTH_INVALID_API_KEY. - 403
AUTH_INSUFFICIENT_SCOPE: a client key cannot call this, or the key lacksflags:read. - 429
RATE_LIMITED.
curl -s "https://flags.example.com/api/v1/code-references/flags" \
-H "Authorization: Bearer $FLAGSWIFT_SERVER_KEY"{ "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#
/api/v1/analytics/exposuresAuthorization
any key type · scope evaluation:read · CORS · 202
Query parameters
envstringEnvironment name. Required for a project-wide key.
Body
userKeystringRequiredWho was shown the variants (aliasuser). Up to 255 characters. Only a keyed hash is stored.exposuresobject[]Required1 to 50 entries. Repeats of the same flag and variant are collapsed.exposures[].flagstringRequiredThe flag key.exposures[].variantstringThe variant shown. Give this or enabled.exposures[].enabledbooleanFor a flag without variants: whether it was on. Give this or variant.
Errors
- 400
INVALID_JSON,INVALID_BODY(exposuresmust be a non-empty list, each with aflagand avariantorenabled),INVALID_USER_KEY,TOO_MANY_EXPOSURES(over 50) orENV_REQUIRED. - 401
AUTH_MISSING_API_KEYorAUTH_INVALID_API_KEY. - 403
AUTH_ENVIRONMENT_MISMATCHorAUTH_INSUFFICIENT_SCOPE. - 429
RATE_LIMITED.
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"}]}'{ "enabled": true, "recorded": 1, "ignored": 0 }Report outcomes#
/api/v1/analytics/outcomesAuthorization
any key type · scope evaluation:read · CORS · 202
Query parameters
envstringEnvironment name. Required for a project-wide key.
Body
userKeystringRequiredThe person who did it (aliasuser), up to 255 characters. Use the same key as for exposures.eventstringRequiredThe event name, such aspurchase. Letters, numbers and. _ / + -; other characters are removed.valuenumberAn amount to sum, such as revenue. A finite number between -1,000,000,000 and 1,000,000,000.
Errors
- 400
INVALID_JSON,INVALID_BODY,INVALID_USER_KEY,INVALID_EVENT(event is required) orINVALID_VALUE(value must be a finite number in range), orENV_REQUIRED. - 401
AUTH_MISSING_API_KEYorAUTH_INVALID_API_KEY. - 403
AUTH_ENVIRONMENT_MISMATCHorAUTH_INSUFFICIENT_SCOPE. - 429
RATE_LIMITED.
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}'{ "enabled": true, "recorded": 1, "ignored": 0 }Rollback and version history#
Roll a flag back#
/api/v1/flags/{flagKey}/environments/{environment}/rollbackReturns 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
flagKeystringRequiredThe flag key. Archived flags are not found.environmentstringRequiredEnvironment name. A key limited to one environment must name that one.
Body
versionintegerThe version to return to, 1 or more. Leave it out for the previous version.reasonstringWhy, up to 300 characters. Kept in the history and the audit log.
Errors
- 400
VALIDATION_ERROR:versionmust be a whole number of 1 or more,reasonat most 300 characters.BAD_REQUESTfor invalid JSON, when the flag is already at that version, or when it has no earlier version. - 401
AUTH_MISSING_API_KEYorAUTH_INVALID_API_KEY. - 403
AUTH_INSUFFICIENT_SCOPE(needs an admin key withrollouts: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”). - 404
NOT_FOUND: no flag with that key, or the version does not exist. - 429
RATE_LIMITED.
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"}'{ "flag": "new-dashboard", "environment": "production", "version": 8, "enabled": false, "rolloutPercentage": 0 }List versions#
/api/v1/flags/{flagKey}/environments/{environment}/versionsLists saved versions, newest first, so you can choose a target. Takes page and limit.
Authorization
server or admin key · scope flags:read
Path parameters
flagKeystringRequiredThe flag key.environmentstringRequiredEnvironment name.
Query parameters
pageintegerPage number, from 1. Default 1.limitintegerVersions per page, 1 to 100. Default 20.
Errors
- 400
VALIDATION_ERROR: apageorlimitout of range. - 401
AUTH_MISSING_API_KEYorAUTH_INVALID_API_KEY. - 403
AUTH_INSUFFICIENT_SCOPE(a client key cannot call this) orAUTH_ENVIRONMENT_MISMATCH. - 404
NOT_FOUND: no flag with that key, or no such environment. - 429
RATE_LIMITED.
curl -s "https://flags.example.com/api/v1/flags/new-dashboard/environments/production/versions?limit=2" \
-H "Authorization: Bearer $FLAGSWIFT_SERVER_KEY"{
"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#
| Field | Type | Description |
|---|---|---|
| enabled | boolean | Whether the flag is on for this person. |
| variant | string | The chosen variant of a multivariate flag. |
| value | any | The variant's value: a string, number or JSON. |
| version | number | The flag's version, which rises with every change. |
| reason | string | Only when requested on the server endpoint. See the reasons below. |
| Reason | Description |
|---|---|
| KILL_SWITCH | An emergency stop is active; the off result is served to everyone. |
| DISABLED | The flag is off in this environment. |
| TARGETED_USER | The person (or their account or device) is explicitly targeted. |
| SEGMENT_MATCH | The person belongs to a targeted segment. |
| RULE_MATCH | An attribute rule matched. |
| DEPENDENCY_BLOCKED | A prerequisite flag is not on for this person. |
| FULL_ROLLOUT | Rolled out to 100%. |
| ROLLOUT_IN / ROLLOUT_OUT | Inside or outside the percentage rollout. |
| NO_IDENTIFIER | The flag buckets by something you did not send. |
| ENV_NOT_CONFIGURED | The flag has no configuration for this environment. |
| FLAG_NOT_FOUND | No flag with this key. |
Errors and limits#
Errors use one shape, with a stable code to branch on:
{ "error": "Unauthorized", "code": "AUTH_INVALID_API_KEY", "details": "..." }| Status | Description |
|---|---|
| 400 | Bad input, for example INVALID_ATTRIBUTES, INVALID_JSON, INVALID_MODE, ENV_REQUIRED or VALIDATION_ERROR. |
| 401 | AUTH_MISSING_API_KEY or AUTH_INVALID_API_KEY (unknown, revoked or expired key). |
| 403 | The key type or scope is not allowed here, or the key is limited to another environment. |
| 404 | ENV_NOT_FOUND: no environment with that name. |
| 429 | RATE_LIMITED. Wait for Retry-After seconds. X-RateLimit-Limit and X-RateLimit-Remaining are sent on API responses. |
Rate limits