Create a flag
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.
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.
application/json- body
The flag to create. Every environment gets the same variants. Only the credential's environment gets enabled and targeting; other environments start off with no rules.
key*stringThe unique key of the flag in the workspace, such as new-checkout. It cannot change later.
1 <= lengthname?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 the credential's environment. Defaults to false, as in the dashboard. Other environments start off.
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. It must be a key of variants.
offVariant?stringThe variant served when the flag is off. Defaults to defaultVariant.
targeting?array<>Targeting rules for the credential's environment, in order. Other environments start with no rules.
metadata?Free-form key-value data for the flag. Values must be strings, numbers, or booleans. Evaluation responses return it as flag metadata.
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.
Created
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 POST 'https://api.toggld.io/api/v1/flags' \ -H 'Content-Type: application/json' \ -d '{ "key": "new-checkout", "name": "New checkout", "type": "boolean", "enabled": true, "variants": { "on": true, "off": false }, "defaultVariant": "off", "targeting": [ { "id": "beta-users", "conditions": [ { "attribute": "plan", "operator": "eq", "value": "beta" } ], "serve": { "type": "variant", "variant": "on" } } ], "tags": [ "checkout" ]}'{ "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"}List flags GET
Returns every flag in the workspace, with the configuration of the credential's environment. Pass `tag` to return only flags that have at least one of the given tags. Requires a management key.
Retrieve a flag GET
Returns a flag with the configuration of the credential's environment. Requires a management key. Returns `404` if no flag has this key.