Retrieve a flag
Returns a flag with the configuration of the credential's environment.
Requires a management key.
Returns 404 if no flag has this key.
bearerAuthorizationBearer <token>Send a credential in the Authorization header: Authorization: Bearer <token>.
Each credential belongs to one environment of one workspace, so the API never takes a workspace or environment in the URL.
- Management key (
ffk_…, secret): manages flags, segments, environments, and API keys, and reads the audit log and analytics. It can also do everything an evaluation key can. - Evaluation key (
ffk_…, secret): for server SDKs. It evaluates flags, reads flag definitions for local evaluation, and sends telemetry. - Public token (
ffp_…, not secret): for browser and mobile apps. It evaluates flags through OFREP and sends telemetry. It cannot read flag definitions.
Keep secret keys on your server. A 401 response means the credential is missing or not valid. A 403 response means the credential is valid but its role cannot perform the operation.
key*stringThe flag key, such as new-checkout.
OK
application/json- response
A feature flag. The key, type, name, description, tags, and metadata are shared by all environments. The variants, enabled state, and targeting rules belong to the environment of the credential.
key*stringThe unique key of the flag in the workspace, such as new-checkout. SDKs evaluate the flag by this key.
name?stringA display name for the flag.
description?stringA description of what the flag controls.
type*stringThe value type of the flag. Every variant value must match it. It cannot change after creation.
"boolean""string""number""object"enabled*booleanWhether the flag is on in this environment. When false, evaluation serves offVariant.
variants*The values the flag can serve, keyed by variant name. Each value must match type.
defaultVariant*stringThe variant served when the flag is on and no targeting rule matches.
offVariant?stringThe variant served when the flag is off. Defaults to defaultVariant.
targeting*array<>Targeting rules, in order. The first matching rule wins.
metadata*Free-form key-value data for the flag. Values must be strings, numbers, or booleans. Evaluation responses return it as flag metadata.
createdAt*stringWhen the flag was created, as an ISO 8601 timestamp.
updatedAt*stringWhen the flag was last changed, as an ISO 8601 timestamp.
tags*array<>Labels that organize flags. They do not affect evaluation. The server trims, lowercases, and removes duplicate tags, and keeps at most 50 tags of up to 64 characters.
version*stringAn opaque version of the flag in this environment. Send it as expectedVersion on an update to reject the update if someone else changed the flag first.
curl -X GET 'https://api.toggld.io/api/v1/flags/string'{ "key": "new-checkout", "name": "New checkout", "description": "Serve the redesigned checkout flow.", "type": "boolean", "enabled": true, "variants": { "on": true, "off": false }, "defaultVariant": "off", "offVariant": "off", "targeting": [ { "id": "beta-users", "conditions": [ { "attribute": "plan", "operator": "eq", "value": "beta" } ], "serve": { "type": "variant", "variant": "on" } }, { "id": "rollout", "conditions": [], "serve": { "type": "rollout", "bucketBy": "targetingKey", "splits": [ { "variant": "on", "weight": 20 }, { "variant": "off", "weight": 80 } ] } } ], "metadata": { "team": "growth" }, "tags": [ "checkout", "growth" ], "version": "b7e1c0d2-4f3a-4c8e-9a1b-2d3e4f5a6b7c.0a9b8c7d-6e5f-4a3b-8c2d-1e0f9a8b7c6d", "createdAt": "2026-05-01T12:00:00.000Z", "updatedAt": "2026-05-02T09:30:00.000Z"}Create a flag POST
Creates a flag in every environment of the workspace. Every environment gets the same variants, default variant, and off variant. Only the credential's environment gets `enabled` and `targeting`. Other environments start off, with no targeting rules. Requires a management key. Returns `409` if the key is already in use, `422` if the flag is not valid, and `402` if the workspace has reached the flag limit of its plan.
Update a flag PATCH
Changes only the fields in the request body. Omitted fields keep their current values. A list field, such as `targeting` or `tags`, replaces the whole list. The name, description, tags, and metadata change in every environment. The variants, enabled state, and targeting rules change only in the credential's environment. The flag type cannot change. Requires a management key. Returns `404` if no flag has this key, `409` if `expectedVersion` does not match the current version, and `422` if the result is not valid.