Replace a flag
Replaces a flag with the request body. Omitted optional fields reset to their defaults. To change only some fields, use the update a flag endpoint instead.
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.
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.
application/json- body
The complete new state of the flag. Omitted optional fields reset to their defaults: no name or description, no tags, empty metadata, enabled: false, and no targeting rules.
expectedVersion?stringThe version you last read. If the flag changed since then, the request fails with 409 and nothing is saved. Omit it to skip the check.
name?stringA display name for the flag.
description?stringA description of what the flag controls.
type*stringThe flag type. It must match the current type, because the type cannot change.
"boolean""string""number""object"enabled?booleanWhether the flag is on in the credential's environment. Defaults to false.
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. Defaults to 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.
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 PUT 'https://api.toggld.io/api/v1/flags/string' \ -H 'Content-Type: application/json' \ -d '{ "expectedVersion": "b7e1c0d2-4f3a-4c8e-9a1b-2d3e4f5a6b7c.0a9b8c7d-6e5f-4a3b-8c2d-1e0f9a8b7c6d", "name": "New checkout", "type": "boolean", "enabled": true, "variants": { "on": true, "off": false }, "defaultVariant": "off", "targeting": [], "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"}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.
Delete a flag DELETE
Permanently deletes a flag from every environment. Evaluating the key afterwards returns `FLAG_NOT_FOUND`. Requires a management key. Returns `404` if no flag has this key.