{"openapi":"3.1.0","info":{"title":"Toggld API","version":"0.1.0","description":"The Toggld API lets you manage feature flags and evaluate them from your own code. It follows REST conventions, takes and returns JSON, and uses standard HTTP status codes.\n\n**Base URL:** `https://api.toggld.io`\n\n## Authentication\n\nSend a credential as a bearer token in the `Authorization` header: `Authorization: Bearer <token>`. Each credential belongs to one environment of one workspace. The API takes the workspace and environment from the credential, never from the URL.\n\n| Credential | Format | Use it for |\n| --- | --- | --- |\n| Management key | `ffk_…`, secret | Managing flags, segments, environments, and API keys, and reading the audit log and analytics |\n| Evaluation key | `ffk_…`, secret | Server SDKs: flag evaluation, definition sync, and telemetry |\n| Public token | `ffp_…`, not secret | Browser and mobile apps: OFREP evaluation and telemetry |\n\nCreate API keys in the Toggld dashboard or with the create an API key endpoint. Keep secret keys on your server.\n\n## Environments\n\nA flag's key, type, name, description, tags, and metadata are shared by every environment. Its variants, enabled state, and targeting rules belong to one environment. Management requests read and change the configuration of the credential's environment.\n\n## Errors\n\n- `400`: the request is malformed, or a flag could not be evaluated.\n- `401`: the credential is missing or not valid.\n- `402`: the workspace has reached a limit of its plan.\n- `403`: the credential is valid, but its role cannot perform the operation.\n- `404`: the resource does not exist.\n- `409`: the request conflicts with the current state, such as a key that is already in use or a stale `expectedVersion`.\n- `422`: the request is well formed, but the flag or segment it describes is not valid.\n- `429`: you sent too many requests. Wait for the number of seconds in the `Retry-After` header, then retry.\n\nManagement errors return a JSON body with `_tag`, which names the error, and `message`. OFREP endpoints return OFREP error bodies with an `errorCode`.\n\nRead the guides at [docs.toggld.io](https://docs.toggld.io)."},"paths":{"/api/v1/flags":{"get":{"tags":["Flags"],"operationId":"listFlags","parameters":[{"name":"tag","in":"query","schema":{"type":"array","items":{"type":"string"}},"required":false,"description":"Return only flags that have this tag. Repeat the parameter to match any of several tags, such as `?tag=checkout&tag=growth`."}],"security":[{"bearer":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Flag"}}}}},"400":{"description":"The request needs an environment, but the credential does not name one. API keys always belong to an environment, so this happens only for dashboard sessions.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvironmentRequired"}}}},"401":{"description":"The request has no credential, or the credential is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Unauthorized"}}}},"403":{"description":"The credential is valid, but it cannot perform this operation. For example, an evaluation key cannot call a management endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Forbidden"}}}}},"description":"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.\n\nRequires a management key.","summary":"List flags"},"post":{"tags":["Flags"],"operationId":"createFlag","parameters":[],"security":[{"bearer":[]}],"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Flag"}}}},"400":{"description":"The request needs an environment, but the credential does not name one. API keys always belong to an environment, so this happens only for dashboard sessions.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvironmentRequired"}}}},"401":{"description":"The request has no credential, or the credential is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Unauthorized"}}}},"402":{"description":"The workspace has reached the flag limit of its plan. Delete a flag or upgrade the plan to create more.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FlagLimitExceeded"}}}},"403":{"description":"The credential is valid, but it cannot perform this operation. For example, an evaluation key cannot call a management endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Forbidden"}}}},"409":{"description":"A flag with this key already exists in the workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FlagAlreadyExists"}}}},"422":{"description":"The flag is not valid. `issues` lists each problem, such as an undeclared variant, a value that does not match the flag type, a changed flag type, or a reference to an unknown segment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FlagValidationError"}}}}},"description":"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.\n\nRequires a management key.\n\nReturns `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.","summary":"Create a flag","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateFlagInput"}}},"required":true}}},"/api/v1/tags":{"get":{"tags":["Flags"],"operationId":"listTags","parameters":[],"security":[{"bearer":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"type":"string"}}}}},"401":{"description":"The request has no credential, or the credential is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Unauthorized"}}}},"403":{"description":"The credential is valid, but it cannot perform this operation. For example, an evaluation key cannot call a management endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Forbidden"}}}}},"description":"Returns every distinct tag used by flags in the workspace. Use it to build tag filters for the list flags endpoint.\n\nRequires a management key.","summary":"List tags"}},"/api/v1/flags/{key}":{"get":{"tags":["Flags"],"operationId":"getFlag","parameters":[{"name":"key","in":"path","schema":{"type":"string"},"required":true,"description":"The flag key, such as `new-checkout`."}],"security":[{"bearer":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Flag"}}}},"400":{"description":"The request needs an environment, but the credential does not name one. API keys always belong to an environment, so this happens only for dashboard sessions.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvironmentRequired"}}}},"401":{"description":"The request has no credential, or the credential is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Unauthorized"}}}},"403":{"description":"The credential is valid, but it cannot perform this operation. For example, an evaluation key cannot call a management endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Forbidden"}}}},"404":{"description":"No flag with this key exists in the credential's environment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FlagNotFound"}}}}},"description":"Returns a flag with the configuration of the credential's environment.\n\nRequires a management key.\n\nReturns `404` if no flag has this key.","summary":"Retrieve a flag"},"put":{"tags":["Flags"],"operationId":"replaceFlag","parameters":[{"name":"key","in":"path","schema":{"type":"string"},"required":true,"description":"The flag key, such as `new-checkout`."}],"security":[{"bearer":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Flag"}}}},"400":{"description":"The request needs an environment, but the credential does not name one. API keys always belong to an environment, so this happens only for dashboard sessions.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvironmentRequired"}}}},"401":{"description":"The request has no credential, or the credential is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Unauthorized"}}}},"403":{"description":"The credential is valid, but it cannot perform this operation. For example, an evaluation key cannot call a management endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Forbidden"}}}},"404":{"description":"No flag with this key exists in the credential's environment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FlagNotFound"}}}},"409":{"description":"The flag changed after you read it, so `expectedVersion` no longer matches. Reload the flag and try again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FlagConflict"}}}},"422":{"description":"The flag is not valid. `issues` lists each problem, such as an undeclared variant, a value that does not match the flag type, a changed flag type, or a reference to an unknown segment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FlagValidationError"}}}}},"description":"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.\n\nThe 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.\n\nRequires a management key.\n\nReturns `404` if no flag has this key, `409` if `expectedVersion` does not match the current version, and `422` if the result is not valid.","summary":"Replace a flag","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReplaceFlagInput"}}},"required":true}},"patch":{"tags":["Flags"],"operationId":"updateFlag","parameters":[{"name":"key","in":"path","schema":{"type":"string"},"required":true,"description":"The flag key, such as `new-checkout`."}],"security":[{"bearer":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Flag"}}}},"400":{"description":"The request needs an environment, but the credential does not name one. API keys always belong to an environment, so this happens only for dashboard sessions.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvironmentRequired"}}}},"401":{"description":"The request has no credential, or the credential is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Unauthorized"}}}},"403":{"description":"The credential is valid, but it cannot perform this operation. For example, an evaluation key cannot call a management endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Forbidden"}}}},"404":{"description":"No flag with this key exists in the credential's environment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FlagNotFound"}}}},"409":{"description":"The flag changed after you read it, so `expectedVersion` no longer matches. Reload the flag and try again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FlagConflict"}}}},"422":{"description":"The flag is not valid. `issues` lists each problem, such as an undeclared variant, a value that does not match the flag type, a changed flag type, or a reference to an unknown segment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FlagValidationError"}}}}},"description":"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.\n\nThe 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.\n\nRequires a management key.\n\nReturns `404` if no flag has this key, `409` if `expectedVersion` does not match the current version, and `422` if the result is not valid.","summary":"Update a flag","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchFlagInput"}}},"required":true}},"delete":{"tags":["Flags"],"operationId":"deleteFlag","parameters":[{"name":"key","in":"path","schema":{"type":"string"},"required":true,"description":"The flag key, such as `new-checkout`."}],"security":[{"bearer":[]}],"responses":{"204":{"description":"No content"},"401":{"description":"The request has no credential, or the credential is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Unauthorized"}}}},"403":{"description":"The credential is valid, but it cannot perform this operation. For example, an evaluation key cannot call a management endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Forbidden"}}}},"404":{"description":"No flag with this key exists in the credential's environment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FlagNotFound"}}}}},"description":"Permanently deletes a flag from every environment. Evaluating the key afterwards returns `FLAG_NOT_FOUND`.\n\nRequires a management key.\n\nReturns `404` if no flag has this key.","summary":"Delete a flag"}},"/api/v1/segments":{"get":{"tags":["Segments"],"operationId":"listSegments","parameters":[],"security":[{"bearer":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Segment"}}}}},"401":{"description":"The request has no credential, or the credential is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Unauthorized"}}}},"403":{"description":"The credential is valid, but it cannot perform this operation. For example, an evaluation key cannot call a management endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Forbidden"}}}}},"description":"Returns every segment in the workspace. Each segment includes its member count but not its member keys. Use the list segment members endpoint to read the members.\n\nRequires a management key.","summary":"List segments"},"post":{"tags":["Segments"],"operationId":"createSegment","parameters":[],"security":[{"bearer":[]}],"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Segment"}}}},"401":{"description":"The request has no credential, or the credential is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Unauthorized"}}}},"403":{"description":"The credential is valid, but it cannot perform this operation. For example, an evaluation key cannot call a management endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Forbidden"}}}},"409":{"description":"A segment with this key already exists in the workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SegmentAlreadyExists"}}}},"422":{"description":"The segment is not valid. `issues` lists each problem, such as an empty or duplicate rule ID, an invalid condition, or a member list over the size limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SegmentValidationError"}}}}},"description":"Creates a segment with optional membership rules. Add member keys afterwards with the update segment members endpoint.\n\nRequires a management key.\n\nReturns `409` if the key is already in use and `422` if the rules are not valid.","summary":"Create a segment","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSegmentInput"}}},"required":true}}},"/api/v1/segments/{key}":{"get":{"tags":["Segments"],"operationId":"getSegment","parameters":[{"name":"key","in":"path","schema":{"type":"string"},"required":true,"description":"The segment key, such as `beta-testers`."}],"security":[{"bearer":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Segment"}}}},"401":{"description":"The request has no credential, or the credential is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Unauthorized"}}}},"403":{"description":"The credential is valid, but it cannot perform this operation. For example, an evaluation key cannot call a management endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Forbidden"}}}},"404":{"description":"No segment with this key exists in the workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SegmentNotFound"}}}}},"description":"Returns a segment, its member count, and the keys of the flags that use it.\n\nRequires a management key.\n\nReturns `404` if no segment has this key.","summary":"Retrieve a segment"},"patch":{"tags":["Segments"],"operationId":"updateSegment","parameters":[{"name":"key","in":"path","schema":{"type":"string"},"required":true,"description":"The segment key, such as `beta-testers`."}],"security":[{"bearer":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Segment"}}}},"401":{"description":"The request has no credential, or the credential is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Unauthorized"}}}},"403":{"description":"The credential is valid, but it cannot perform this operation. For example, an evaluation key cannot call a management endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Forbidden"}}}},"404":{"description":"No segment with this key exists in the workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SegmentNotFound"}}}},"409":{"description":"The segment changed after you read it, so `expectedVersion` no longer matches. Reload the segment and try again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SegmentConflict"}}}},"422":{"description":"The segment is not valid. `issues` lists each problem, such as an empty or duplicate rule ID, an invalid condition, or a member list over the size limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SegmentValidationError"}}}}},"description":"Changes the name, description, key attribute, or rules of a segment. Omitted fields keep their current values. The change applies to every flag that uses the segment, in every environment.\n\nRequires a management key.\n\nReturns `404` if no segment has this key, `409` if `expectedVersion` does not match the current version, and `422` if the rules are not valid.","summary":"Update a segment","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchSegmentInput"}}},"required":true}},"delete":{"tags":["Segments"],"operationId":"deleteSegment","parameters":[{"name":"key","in":"path","schema":{"type":"string"},"required":true,"description":"The segment key, such as `beta-testers`."}],"security":[{"bearer":[]}],"responses":{"204":{"description":"No content"},"401":{"description":"The request has no credential, or the credential is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Unauthorized"}}}},"403":{"description":"The credential is valid, but it cannot perform this operation. For example, an evaluation key cannot call a management endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Forbidden"}}}},"404":{"description":"No segment with this key exists in the workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SegmentNotFound"}}}},"409":{"description":"Targeting rules still use this segment, so it cannot be deleted. Remove the segment from the flags in `flagKeys` first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SegmentReferenced"}}}}},"description":"Permanently deletes a segment and its member list.\n\nRequires a management key.\n\nReturns `404` if no segment has this key. Returns `409` while targeting rules still use the segment. The response lists those flags in `flagKeys`.","summary":"Delete a segment"}},"/api/v1/segments/{key}/members":{"get":{"tags":["Segments"],"operationId":"listSegmentMembers","parameters":[{"name":"key","in":"path","schema":{"type":"string"},"required":true,"description":"The segment key, such as `beta-testers`."},{"name":"query","in":"query","schema":{"type":"string"},"required":false,"description":"Return only members whose key contains this text. The match ignores case."},{"name":"limit","in":"query","schema":{"type":"string"},"required":false,"description":"The maximum number of members to return, as a whole number. Defaults to `50`. Values above `200` return 200 members."},{"name":"offset","in":"query","schema":{"type":"string"},"required":false,"description":"The number of members to skip, as a whole number. Defaults to `0`."}],"security":[{"bearer":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SegmentMemberPage"}}}},"401":{"description":"The request has no credential, or the credential is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Unauthorized"}}}},"403":{"description":"The credential is valid, but it cannot perform this operation. For example, an evaluation key cannot call a management endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Forbidden"}}}},"404":{"description":"No segment with this key exists in the workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SegmentNotFound"}}}}},"description":"Returns one page of the member list of a segment, oldest first, and the total number of matching members. Use `limit` and `offset` to page through the list.\n\nRequires a management key.\n\nReturns `404` if no segment has this key.","summary":"List segment members"},"post":{"tags":["Segments"],"operationId":"updateSegmentMembers","parameters":[{"name":"key","in":"path","schema":{"type":"string"},"required":true,"description":"The segment key, such as `beta-testers`."}],"security":[{"bearer":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Segment"}}}},"401":{"description":"The request has no credential, or the credential is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Unauthorized"}}}},"403":{"description":"The credential is valid, but it cannot perform this operation. For example, an evaluation key cannot call a management endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Forbidden"}}}},"404":{"description":"No segment with this key exists in the workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SegmentNotFound"}}}},"422":{"description":"The segment is not valid. `issues` lists each problem, such as an empty or duplicate rule ID, an invalid condition, or a member list over the size limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SegmentValidationError"}}}}},"description":"Adds and removes member keys in one request, and returns the updated segment. Adding an existing member or removing a missing one has no effect, so you can safely retry. Use this endpoint to import members in bulk.\n\nRequires a management key.\n\nReturns `404` if no segment has this key and `422` if the segment would have more than 5,000 members.","summary":"Update segment members","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateSegmentMembersInput"}}},"required":true}}},"/api/v1/environments/{environmentId}":{"patch":{"tags":["Environments"],"operationId":"updateEnvironment","parameters":[{"name":"environmentId","in":"path","schema":{"type":"string"},"required":true,"description":"The environment ID, such as `env_…`."}],"security":[{"bearer":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Environment"}}}},"401":{"description":"The request has no credential, or the credential is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Unauthorized"}}}},"403":{"description":"The credential is valid, but it cannot perform this operation. For example, an evaluation key cannot call a management endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Forbidden"}}}},"404":{"description":"No environment with this ID or key exists in the workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvironmentNotFound"}}}},"409":{"description":"An environment with this key already exists in the workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvironmentAlreadyExists"}}}}},"description":"Changes the key, name, color, or production setting of an environment. Omitted fields keep their current values. To change the order of environments, use the reorder environments endpoint.\n\nRequires a management key.\n\nReturns `404` if the environment does not exist and `409` if the new key is already in use.","summary":"Update an environment","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateEnvironmentInput"}}},"required":true}},"delete":{"tags":["Environments"],"operationId":"deleteEnvironment","parameters":[{"name":"environmentId","in":"path","schema":{"type":"string"},"required":true,"description":"The environment ID, such as `env_…`."}],"security":[{"bearer":[]}],"responses":{"204":{"description":"No content"},"401":{"description":"The request has no credential, or the credential is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Unauthorized"}}}},"403":{"description":"The credential is valid, but it cannot perform this operation. For example, an evaluation key cannot call a management endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Forbidden"}}}},"404":{"description":"No environment with this ID or key exists in the workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvironmentNotFound"}}}},"409":{"description":"The environment change conflicts with the workspace. A workspace must keep at least one environment, and a new order must list every environment exactly once.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvironmentConflict"}}}}},"description":"Permanently deletes an environment, with its flag configuration, API keys, and public token. Requests that use those credentials then fail with `401`.\n\nRequires a management key.\n\nReturns `404` if the environment does not exist. Returns `409` if it is the only environment in the workspace.","summary":"Delete an environment"}},"/api/v1/environments":{"get":{"tags":["Environments"],"operationId":"listEnvironments","parameters":[],"security":[{"bearer":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Environment"}}}}},"401":{"description":"The request has no credential, or the credential is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Unauthorized"}}}},"403":{"description":"The credential is valid, but it cannot perform this operation. For example, an evaluation key cannot call a management endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Forbidden"}}}}},"description":"Returns every environment in the workspace, in workspace order (ascending `position`).\n\nRequires a management key.","summary":"List environments"},"post":{"tags":["Environments"],"operationId":"createEnvironment","parameters":[],"security":[{"bearer":[]}],"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Environment"}}}},"401":{"description":"The request has no credential, or the credential is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Unauthorized"}}}},"403":{"description":"The credential is valid, but it cannot perform this operation. For example, an evaluation key cannot call a management endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Forbidden"}}}},"409":{"description":"An environment with this key already exists in the workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvironmentAlreadyExists"}}}}},"description":"Creates an environment and its public token. The new environment goes last in the workspace order. Every existing flag gets a copy of its values from the environment before it, but starts off, with no targeting rules. Later changes in that environment do not affect the copy.\n\nRequires a management key.\n\nReturns `409` if the key is already in use.","summary":"Create an environment","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateEnvironmentInput"}}},"required":true}}},"/api/v1/environments/order":{"put":{"tags":["Environments"],"operationId":"reorderEnvironments","parameters":[],"security":[{"bearer":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Environment"}}}}},"401":{"description":"The request has no credential, or the credential is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Unauthorized"}}}},"403":{"description":"The credential is valid, but it cannot perform this operation. For example, an evaluation key cannot call a management endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Forbidden"}}}},"409":{"description":"The environment change conflicts with the workspace. A workspace must keep at least one environment, and a new order must list every environment exactly once.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvironmentConflict"}}}}},"description":"Sets the order of every environment in the workspace. The dashboard lists environments in this order and opens the first one. A new environment copies its flag values from the last one.\n\nRequires a management key.\n\nReturns the environments in their new order. Returns `409` unless the list names every environment in the workspace exactly once.","summary":"Reorder environments","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReorderEnvironmentsInput"}}},"required":true}}},"/api/v1/keys":{"get":{"tags":["API keys"],"operationId":"listApiKeys","parameters":[],"security":[{"bearer":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ApiKey"}}}}},"401":{"description":"The request has no credential, or the credential is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Unauthorized"}}}},"403":{"description":"The credential is valid, but it cannot perform this operation. For example, an evaluation key cannot call a management endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Forbidden"}}}}},"description":"Returns every secret API key in the workspace, in all environments. The response never includes the tokens, only a short prefix of each.\n\nRequires a management key.","summary":"List API keys"},"post":{"tags":["API keys"],"operationId":"createApiKey","parameters":[],"security":[{"bearer":[]}],"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatedApiKey"}}}},"401":{"description":"The request has no credential, or the credential is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Unauthorized"}}}},"403":{"description":"The credential is valid, but it cannot perform this operation. For example, an evaluation key cannot call a management endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Forbidden"}}}},"404":{"description":"No environment with this ID or key exists in the workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvironmentNotFound"}}}}},"description":"Creates a secret API key for one environment. `environment` is required.\n\nThe response includes the token. This is the only time the API returns it, so store it securely.\n\nRequires a management key.\n\nReturns `404` if the environment does not exist.","summary":"Create an API key","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateApiKeyInput"}}},"required":true}}},"/api/v1/keys/{keyId}":{"delete":{"tags":["API keys"],"operationId":"revokeApiKey","parameters":[{"name":"keyId","in":"path","schema":{"type":"string"},"required":true,"description":"The API key ID, such as `key_…`."}],"security":[{"bearer":[]}],"responses":{"204":{"description":"No content"},"401":{"description":"The request has no credential, or the credential is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Unauthorized"}}}},"403":{"description":"The credential is valid, but it cannot perform this operation. For example, an evaluation key cannot call a management endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Forbidden"}}}},"404":{"description":"No API key with this ID exists in the workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyNotFound"}}}}},"description":"Permanently revokes a secret API key. Requests that use it then fail with `401`. It can take a short time for the key to stop working everywhere.\n\nRequires a management key.\n\nReturns `404` if no key has this ID.","summary":"Revoke an API key"}},"/api/v1/public-tokens":{"get":{"tags":["Public tokens"],"operationId":"listPublicTokens","parameters":[],"security":[{"bearer":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PublicToken"}}}}},"401":{"description":"The request has no credential, or the credential is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Unauthorized"}}}},"403":{"description":"The credential is valid, but it cannot perform this operation. For example, an evaluation key cannot call a management endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Forbidden"}}}}},"description":"Returns the public token of every environment, including the full token. If an environment has no token yet, this request creates one.\n\nRequires a management key.","summary":"List public tokens"}},"/api/v1/audit-log":{"get":{"tags":["Audit log"],"operationId":"listAuditEvents","parameters":[{"name":"resourceType","in":"query","schema":{"type":"string","enum":["flag","segment","environment","apiKey","tenant"]},"required":false,"description":"Return only events for this kind of resource."},{"name":"resourceId","in":"query","schema":{"type":"string"},"required":false,"description":"Return only events for this resource: a flag key, segment key, environment ID, or API key ID."},{"name":"environmentId","in":"query","schema":{"type":"string"},"required":false,"description":"Return only events for this environment ID."},{"name":"action","in":"query","schema":{"type":"string","enum":["flag.create","flag.update","flag.delete","segment.create","segment.update","segment.delete","environment.update","environment.create","environment.delete","apiKey.create","apiKey.revoke","tenant.create","tenant.update","tenant.delete"]},"required":false,"description":"Return only events with this action, such as `flag.update`."}],"security":[{"bearer":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/AuditEvent"}}}}},"401":{"description":"The request has no credential, or the credential is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Unauthorized"}}}},"403":{"description":"The credential is valid, but it cannot perform this operation. For example, an evaluation key cannot call a management endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Forbidden"}}}}},"description":"Returns up to 100 of the most recent configuration changes in the workspace, newest first. Use the query parameters to filter the events. When you combine filters, an event must match all of them.\n\nRequires a management key.","summary":"List audit events"}},"/api/v1/flags/{key}/analytics":{"get":{"tags":["Analytics"],"operationId":"getFlagAnalytics","parameters":[{"name":"key","in":"path","schema":{"type":"string"},"required":true,"description":"The flag key, such as `new-checkout`."},{"name":"range","in":"query","schema":{"type":"string","enum":["1h","24h","7d"]},"required":false,"description":"The time range. `1h` returns 1-minute buckets. `24h` and `7d` return 1-hour buckets. Defaults to `24h`."}],"security":[{"bearer":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FlagAnalytics"}}}},"400":{"description":"The request needs an environment, but the credential does not name one. API keys always belong to an environment, so this happens only for dashboard sessions.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvironmentRequired"}}}},"401":{"description":"The request has no credential, or the credential is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Unauthorized"}}}},"403":{"description":"The credential is valid, but it cannot perform this operation. For example, an evaluation key cannot call a management endpoint.","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/Forbidden"},{"$ref":"#/components/schemas/Forbidden"}]}}}},"404":{"description":"No flag with this key exists in the credential's environment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FlagNotFound"}}}}},"description":"Returns evaluation counts for one flag in the credential's environment, over the last hour, 24 hours, or 7 days. The counts come from telemetry, so new evaluations can take a short time to appear.\n\nRequires a management key. Evaluation keys and public tokens get `403`.\n\nReturns `404` if no flag has this key.","summary":"Retrieve flag analytics"}},"/ofrep/v1/evaluate/flags/{key}":{"post":{"tags":["Evaluation (OFREP)"],"operationId":"evaluateFlag","parameters":[{"name":"key","in":"path","schema":{"type":"string"},"required":true,"description":"The flag key, such as `new-checkout`."}],"security":[{"bearer":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OfrepEvaluationSuccess"}}}},"400":{"description":"The flag could not be evaluated. `errorCode` says why: `TARGETING_KEY_MISSING` means a percentage rollout needs a `targetingKey` that the context does not include, `PARSE_ERROR` means the request body is not valid JSON, and `INVALID_CONTEXT` means the body is JSON but not a valid evaluation request. | The request needs an environment, but the credential does not name one. API keys always belong to an environment, so this happens only for dashboard sessions.","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/OfrepEvaluationError"},{"$ref":"#/components/schemas/EnvironmentRequired"}]}}}},"401":{"description":"The request has no credential, or the credential is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Unauthorized"}}}},"404":{"description":"No flag with this key exists in the credential's environment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OfrepFlagNotFound"}}}}},"description":"Evaluates one flag for the evaluation context in the request body. Returns the value, the variant, and the reason it was served.\n\nAccepts an evaluation key, a management key, or a public token.\n\nReturns `404` with `FLAG_NOT_FOUND` if the flag does not exist in the credential's environment. Returns `400` if evaluation fails, such as `TARGETING_KEY_MISSING` when a percentage rollout needs a `targetingKey`. A request body that is not valid JSON returns `400` with `PARSE_ERROR`, and a JSON body that is not a valid evaluation request returns `400` with `INVALID_CONTEXT`.","summary":"Evaluate a flag","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OfrepEvaluationRequest"}}},"required":true}}},"/ofrep/v1/evaluate/flags":{"post":{"tags":["Evaluation (OFREP)"],"operationId":"evaluateAllFlags","parameters":[],"security":[{"bearer":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OfrepBulkEvaluationResponse"}}}},"400":{"description":"The request could not be evaluated. `PARSE_ERROR` means the request body is not valid JSON, and `INVALID_CONTEXT` means the body is JSON but not a valid evaluation request. | The request needs an environment, but the credential does not name one. API keys always belong to an environment, so this happens only for dashboard sessions.","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/OfrepBulkEvaluationError"},{"$ref":"#/components/schemas/EnvironmentRequired"}]}}}},"401":{"description":"The request has no credential, or the credential is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Unauthorized"}}}}},"description":"Evaluates every flag in the credential's environment for the evaluation context in the request body. If one flag fails to evaluate, its result has an `errorCode` instead of a value, and the request still succeeds.\n\nAccepts an evaluation key, a management key, or a public token.\n\nReturns `400` with `PARSE_ERROR` if the request body is not valid JSON, and `400` with `INVALID_CONTEXT` if it is JSON but not a valid evaluation request.","summary":"Evaluate all flags","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OfrepEvaluationRequest"}}},"required":true}}},"/sync/v1/flags":{"get":{"tags":["Definition sync"],"operationId":"getFlagSnapshot","parameters":[],"security":[{"bearer":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FlagSnapshot"}}}},"400":{"description":"The request needs an environment, but the credential does not name one. API keys always belong to an environment, so this happens only for dashboard sessions.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvironmentRequired"}}}},"401":{"description":"The request has no credential, or the credential is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Unauthorized"}}}},"403":{"description":"The credential is valid, but it cannot perform this operation. For example, an evaluation key cannot call a management endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Forbidden"}}}}},"description":"Returns every flag in the credential's environment with its targeting rules, and the segments those rules use. SDKs that evaluate locally poll this endpoint. Compare `version` with the version you have to tell whether anything changed.\n\nAccepts an evaluation key or a management key. Public tokens get `403`, because targeting rules must not reach browsers.","summary":"Retrieve a flag snapshot"}},"/v1/telemetry":{"post":{"tags":["Telemetry"],"operationId":"ingestTelemetry","parameters":[],"security":[{"bearer":[]}],"responses":{"204":{"description":"No content"},"400":{"description":"The request needs an environment, but the credential does not name one. API keys always belong to an environment, so this happens only for dashboard sessions.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvironmentRequired"}}}},"401":{"description":"The request has no credential, or the credential is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Unauthorized"}}}}},"description":"Records a batch of evaluation counts for the credential's environment. Returns `204` with no body.\n\nThe server counts each batch once. If it already received a batch with the same `sdkInstanceId` and `windowId`, it ignores the new one, so you can safely retry. It drops counts that are older than its retention period or too far in the future.\n\nAccepts an evaluation key, a management key, or a public token.","summary":"Report evaluation counts","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TelemetryBatch"}}},"required":true}}}},"components":{"schemas":{"Unauthorized":{"type":"object","properties":{"_tag":{"type":"string","enum":["Unauthorized"]},"message":{"type":"string","description":"A human-readable explanation of the error."}},"required":["_tag","message"],"additionalProperties":false,"description":"The request has no credential, or the credential is not valid."},"EnvironmentRequired":{"type":"object","properties":{"_tag":{"type":"string","enum":["EnvironmentRequired"]},"message":{"type":"string","description":"A human-readable explanation of the error."}},"required":["_tag","message"],"additionalProperties":false,"description":"The request needs an environment, but the credential does not name one. API keys always belong to an environment, so this happens only for dashboard sessions."},"TelemetryBatch":{"type":"object","properties":{"sdkInstanceId":{"type":"string","minLength":1,"maxLength":256,"description":"An ID for the SDK instance that sends the batch, such as a random UUID created at startup."},"windowId":{"type":"string","minLength":1,"maxLength":256,"description":"A unique ID for this batch, such as a random UUID. If you retry a batch, send the same `sdkInstanceId` and `windowId` so the server counts it only once."},"rollups":{"type":"array","items":{"$ref":"#/components/schemas/EvaluationRollup"},"minItems":1,"maxItems":1000,"description":"Between 1 and 1,000 evaluation counts."}},"required":["sdkInstanceId","windowId","rollups"],"additionalProperties":false,"description":"Evaluation counts that an SDK collected during one reporting window.","examples":[{"sdkInstanceId":"4b0f2e7a-9c1d-4e3b-8a6f-2d5c9e1b7a40","windowId":"c8e1a5d3-2f7b-4a9c-b6e0-3d1f8a4c7e25","rollups":[{"flagKey":"new-checkout","variant":"on","reason":"SPLIT","bucketStart":"2026-05-02T09:30:00.000Z","count":182},{"flagKey":"new-checkout","variant":"off","reason":"SPLIT","bucketStart":"2026-05-02T09:30:00.000Z","count":731}]}]},"EvaluationRollup":{"type":"object","properties":{"flagKey":{"type":"string","minLength":1,"maxLength":256,"description":"The key of the evaluated flag."},"variant":{"type":"string","maxLength":256,"description":"The served variant. Use an empty string if no variant was served."},"reason":{"type":"string","enum":["STATIC","DEFAULT","TARGETING_MATCH","SPLIT","CACHED","DISABLED","UNKNOWN","STALE","ERROR"],"description":"Why the value was served. `STATIC`: no rule matched, so the default variant was served. `TARGETING_MATCH`: a rule served a fixed variant. `SPLIT`: a percentage rollout chose the variant. `DISABLED`: the flag is off, so the off variant was served. `ERROR`: evaluation failed."},"bucketStart":{"type":"string"},"count":{"type":"integer","minimum":1,"maximum":1000000000,"description":"How many evaluations had this flag, variant, and reason in this minute."}},"required":["flagKey","variant","reason","bucketStart","count"],"additionalProperties":false,"description":"A count of flag evaluations that share a flag, variant, reason, and minute."},"Forbidden":{"type":"object","properties":{"_tag":{"type":"string","enum":["Forbidden"]},"message":{"type":"string","description":"A human-readable explanation of the error."}},"required":["_tag","message"],"additionalProperties":false,"description":"The credential is valid, but it cannot perform this operation. For example, an evaluation key cannot call a management endpoint."},"FlagSnapshot":{"type":"object","properties":{"version":{"type":"string","description":"An opaque version of the snapshot. It changes whenever a flag or segment changes. Compare it for equality only."},"flags":{"type":"array","items":{"$ref":"#/components/schemas/SnapshotFlag"},"description":"Every flag in the environment, ready for local evaluation."},"segments":{"type":"array","items":{"$ref":"#/components/schemas/SnapshotSegment"},"description":"The segments that the flags' targeting rules use."}},"required":["version","flags"],"additionalProperties":false,"description":"A versioned snapshot of every flag definition in one environment, for SDKs that evaluate flags locally.","examples":[{"version":"v_2d7f1a4c-9e3b-4c8a-b5f0-1a6d3e9c2b7f","flags":[{"key":"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"}}],"metadata":{},"createdAt":"2026-05-01T12:00:00.000Z","updatedAt":"2026-05-02T09:30:00.000Z"}],"segments":[]}]},"SnapshotSegment":{"type":"object","properties":{"key":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"keyAttribute":{"type":"string","description":"The context attribute compared with the member list. Usually `targetingKey`."},"rules":{"type":"array","items":{"$ref":"#/components/schemas/SegmentRule"}},"listMode":{"type":"string","enum":["none","inline","remote"],"description":"How the member list reaches evaluation. `none`: the segment has no listed members. `inline`: members are sent with the flag definitions. `remote` is reserved for larger lists and is not used yet."},"members":{"type":"array","items":{"type":"string"},"description":"The listed member keys. Present only when `listMode` is `inline`."},"version":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["key","keyAttribute","rules","listMode","version","createdAt","updatedAt"],"additionalProperties":false,"description":"A segment as SDKs evaluate it locally, including its inline member keys."},"SegmentRule":{"type":"object","properties":{"id":{"type":"string","description":"An ID for the rule, unique within the segment."},"description":{"type":"string"},"conditions":{"type":"array","items":{"$ref":"#/components/schemas/Condition"},"description":"Conditions that must all match for a subject to belong to the segment."}},"required":["id","conditions"],"additionalProperties":false,"description":"A membership rule. A subject is in the segment if any rule matches or the member list includes it."},"Condition":{"type":"object","properties":{"attribute":{"type":"string","description":"The evaluation context attribute to test, such as `targetingKey`, `email`, or `plan`."},"operator":{"type":"string","enum":["eq","ne","in","notIn","lt","lte","gt","gte","contains","startsWith","endsWith","exists","notExists"],"description":"How to compare the attribute with `value`. Numeric operators (`lt`, `lte`, `gt`, `gte`) need numbers. String operators (`contains`, `startsWith`, `endsWith`) need strings. `in` and `notIn` test membership in an array. `exists` and `notExists` ignore `value`."},"value":{"description":"The value to compare with. Use an array for `in` and `notIn`. Omit it for `exists` and `notExists`."}},"required":["attribute","operator"],"additionalProperties":false,"description":"A test against one attribute of the evaluation context. All conditions in a rule must match.","examples":[{"attribute":"plan","operator":"eq","value":"beta"}]},"SnapshotFlag":{"type":"object","properties":{"key":{"type":"string","description":"The unique key of the flag in the workspace, such as `new-checkout`. SDKs evaluate the flag by this key."},"name":{"type":"string","description":"A display name for the flag."},"description":{"type":"string","description":"A description of what the flag controls."},"type":{"type":"string","enum":["boolean","string","number","object"],"description":"The value type of the flag. Every variant value must match it. It cannot change after creation."},"enabled":{"type":"boolean","description":"Whether the flag is on in this environment. When `false`, evaluation serves `offVariant`."},"variants":{"type":"object","description":"The values the flag can serve, keyed by variant name. Each value must match `type`."},"defaultVariant":{"type":"string","description":"The variant served when the flag is on and no targeting rule matches."},"offVariant":{"type":"string","description":"The variant served when the flag is off. Defaults to `defaultVariant`."},"targeting":{"type":"array","items":{"$ref":"#/components/schemas/TargetingRule"},"description":"Targeting rules, in order. The first matching rule wins."},"metadata":{"$ref":"#/components/schemas/FlagMetadata"},"createdAt":{"type":"string","description":"When the flag was created, as an ISO 8601 timestamp."},"updatedAt":{"type":"string","description":"When the flag was last changed, as an ISO 8601 timestamp."}},"required":["key","type","enabled","variants","defaultVariant","targeting","metadata","createdAt","updatedAt"],"additionalProperties":false,"description":"A flag as SDKs evaluate it locally: its shared definition joined with the configuration of one environment. It has no tags or version."},"FlagMetadata":{"type":"object","additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}]},"description":"Free-form key-value data for the flag. Values must be strings, numbers, or booleans. Evaluation responses return it as flag metadata.","examples":[{"team":"growth"}]},"TargetingRule":{"type":"object","properties":{"id":{"type":"string","description":"An ID for the rule, unique within the flag. Rollouts use it to place subjects in slices."},"description":{"type":"string"},"conditions":{"type":"array","items":{"$ref":"#/components/schemas/Condition"},"description":"Conditions that must all match. An empty list matches every subject."},"segments":{"type":"array","items":{"$ref":"#/components/schemas/SegmentReference"},"description":"Segments the subject must belong to, in addition to `conditions`."},"serve":{"anyOf":[{"$ref":"#/components/schemas/ServeVariant"},{"$ref":"#/components/schemas/ServeRollout"}],"description":"What the rule serves when it matches: one fixed variant or a percentage rollout."}},"required":["id","conditions","serve"],"additionalProperties":false,"description":"An ordered targeting rule. Evaluation serves the first rule whose conditions and segments all match.","examples":[{"id":"beta-users","conditions":[{"attribute":"plan","operator":"eq","value":"beta"}],"serve":{"type":"variant","variant":"on"}}]},"ServeRollout":{"type":"object","properties":{"type":{"type":"string","enum":["rollout"]},"bucketBy":{"type":"string","description":"The context attribute that places a subject in a slice. Defaults to `targetingKey`. If the context does not include it, evaluation fails with `TARGETING_KEY_MISSING`."},"splits":{"type":"array","items":{"$ref":"#/components/schemas/RolloutSplit"}}},"required":["type","splits"],"additionalProperties":false,"description":"Serve a percentage rollout when the rule matches. The same subject always gets the same variant. The evaluation reason is `SPLIT`."},"RolloutSplit":{"type":"object","properties":{"variant":{"type":"string","description":"The variant this slice serves."},"weight":{"type":"number","minimum":0,"description":"The relative size of this slice. Weights are relative to the sum of all weights, so they do not need to add up to 100."}},"required":["variant","weight"],"additionalProperties":false,"description":"One weighted slice of a percentage rollout."},"ServeVariant":{"type":"object","properties":{"type":{"type":"string","enum":["variant"]},"variant":{"type":"string","description":"The variant to serve."}},"required":["type","variant"],"additionalProperties":false,"description":"Serve one fixed variant when the rule matches. The evaluation reason is `TARGETING_MATCH`."},"SegmentReference":{"type":"object","properties":{"segment":{"type":"string","description":"The key of the segment."},"negate":{"type":"boolean","description":"If `true`, the rule matches subjects that are **not** in the segment."}},"required":["segment"],"additionalProperties":false,"description":"A reusable segment that a targeting rule requires."},"OfrepBulkEvaluationError":{"type":"object","properties":{"errorCode":{"type":"string","enum":["PROVIDER_NOT_READY","PROVIDER_FATAL","FLAG_NOT_FOUND","PARSE_ERROR","TYPE_MISMATCH","TARGETING_KEY_MISSING","INVALID_CONTEXT","GENERAL"],"description":"The OpenFeature error code that explains why evaluation failed."},"errorDetails":{"type":"string","description":"A human-readable explanation."}},"required":["errorCode"],"additionalProperties":false,"description":"The request could not be evaluated. `PARSE_ERROR` means the request body is not valid JSON, and `INVALID_CONTEXT` means the body is JSON but not a valid evaluation request."},"OfrepBulkEvaluationResponse":{"type":"object","properties":{"flags":{"type":"array","items":{"anyOf":[{"$ref":"#/components/schemas/OfrepEvaluationSuccess"},{"$ref":"#/components/schemas/OfrepEvaluationFailure"}]},"description":"One result for each flag in the environment. A result is either a success or a failure."},"metadata":{"$ref":"#/components/schemas/FlagMetadata"}},"required":["flags"],"additionalProperties":false,"description":"The results of evaluating every flag in the environment.","examples":[{"flags":[{"key":"new-checkout","value":true,"reason":"SPLIT","variant":"on"},{"key":"pricing-page","value":"control","reason":"STATIC","variant":"control"},{"key":"gradual-rollout","errorCode":"TARGETING_KEY_MISSING","errorDetails":"Flag 'gradual-rollout' rule 'rollout' requires a bucketing key but none was provided"}]}]},"OfrepEvaluationFailure":{"type":"object","properties":{"key":{"type":"string","description":"The flag key."},"errorCode":{"type":"string","enum":["PROVIDER_NOT_READY","PROVIDER_FATAL","FLAG_NOT_FOUND","PARSE_ERROR","TYPE_MISMATCH","TARGETING_KEY_MISSING","INVALID_CONTEXT","GENERAL"],"description":"The OpenFeature error code that explains why evaluation failed."},"errorDetails":{"type":"string","description":"A human-readable explanation."},"metadata":{"$ref":"#/components/schemas/FlagMetadata"}},"required":["key","errorCode"],"additionalProperties":false,"description":"A flag that could not be evaluated, inside a bulk response."},"OfrepEvaluationSuccess":{"type":"object","properties":{"key":{"type":"string","description":"The flag key."},"value":{"description":"The evaluated value. Its type matches the flag type."},"reason":{"type":"string","enum":["STATIC","DEFAULT","TARGETING_MATCH","SPLIT","CACHED","DISABLED","UNKNOWN","STALE","ERROR"],"description":"Why the value was served. `STATIC`: no rule matched, so the default variant was served. `TARGETING_MATCH`: a rule served a fixed variant. `SPLIT`: a percentage rollout chose the variant. `DISABLED`: the flag is off, so the off variant was served. `ERROR`: evaluation failed."},"variant":{"type":"string","description":"The name of the served variant."},"metadata":{"$ref":"#/components/schemas/FlagMetadata"}},"required":["key","value","reason"],"additionalProperties":false,"description":"A successful flag evaluation.","examples":[{"key":"new-checkout","value":true,"reason":"TARGETING_MATCH","variant":"on","metadata":{"team":"growth"}}]},"OfrepEvaluationRequest":{"type":"object","properties":{"context":{"$ref":"#/components/schemas/EvaluationContext"}},"additionalProperties":false,"description":"The evaluation context to evaluate flags for. An empty body evaluates with an empty context.","examples":[{"context":{"targetingKey":"user-123","plan":"beta"}}]},"EvaluationContext":{"type":"object","description":"Attributes of the subject you evaluate flags for. `targetingKey` identifies the subject, such as a user ID, and percentage rollouts use it by default. Add any other attributes your targeting rules test, such as `email` or `plan`.","examples":[{"targetingKey":"user-123","email":"ada@example.com","plan":"pro"}]},"OfrepEvaluationError":{"type":"object","properties":{"key":{"type":"string","description":"The flag key from the request."},"errorCode":{"type":"string","enum":["PROVIDER_NOT_READY","PROVIDER_FATAL","FLAG_NOT_FOUND","PARSE_ERROR","TYPE_MISMATCH","TARGETING_KEY_MISSING","INVALID_CONTEXT","GENERAL"],"description":"The OpenFeature error code that explains why evaluation failed."},"errorDetails":{"type":"string","description":"A human-readable explanation."}},"required":["key","errorCode"],"additionalProperties":false,"description":"The flag could not be evaluated. `errorCode` says why: `TARGETING_KEY_MISSING` means a percentage rollout needs a `targetingKey` that the context does not include, `PARSE_ERROR` means the request body is not valid JSON, and `INVALID_CONTEXT` means the body is JSON but not a valid evaluation request."},"OfrepFlagNotFound":{"type":"object","properties":{"key":{"type":"string","description":"The flag key from the request."},"errorCode":{"type":"string","enum":["FLAG_NOT_FOUND"]},"errorDetails":{"type":"string","description":"A human-readable explanation."}},"required":["key","errorCode"],"additionalProperties":false,"description":"No flag with this key exists in the credential's environment."},"FlagNotFound":{"type":"object","properties":{"_tag":{"type":"string","enum":["FlagNotFound"]},"flagKey":{"type":"string","description":"The flag key from the request."},"message":{"type":"string","description":"A human-readable explanation of the error."}},"required":["_tag","flagKey","message"],"additionalProperties":false,"description":"No flag with this key exists in the credential's environment."},"FlagAnalytics":{"type":"object","properties":{"range":{"type":"string","enum":["1h","24h","7d"],"description":"The time range of the report."},"from":{"type":"string","description":"The start of the report, as an ISO 8601 timestamp."},"to":{"type":"string","description":"The end of the report (the current time), as an ISO 8601 timestamp."},"total":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},"errors":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},"lastEvaluatedAt":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The start of the latest minute with an evaluation in the range. `null` if there were none."},"timeline":{"type":"array","items":{"type":"object","properties":{"bucketStart":{"type":"string","description":"The start of the bucket, as an ISO 8601 timestamp."},"count":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]}},"required":["bucketStart","count"],"additionalProperties":false},"description":"Evaluation counts over time, oldest first. Buckets are 1 minute for `1h` and 1 hour for `24h` and `7d`. Empty buckets have a count of 0."},"variants":{"type":"array","items":{"type":"object","properties":{"variant":{"type":"string","description":"The variant name."},"count":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]}},"required":["variant","count"],"additionalProperties":false},"description":"Evaluation counts for each served variant, largest first."}},"required":["range","from","to","total","errors","lastEvaluatedAt","timeline","variants"],"additionalProperties":false,"description":"Evaluation counts for one flag in the credential's environment.","examples":[{"range":"1h","from":"2026-05-02T08:31:00.000Z","to":"2026-05-02T09:30:42.000Z","total":913,"errors":0,"lastEvaluatedAt":"2026-05-02T09:30:00.000Z","timeline":[{"bucketStart":"2026-05-02T09:29:00.000Z","count":0},{"bucketStart":"2026-05-02T09:30:00.000Z","count":913}],"variants":[{"variant":"off","count":731},{"variant":"on","count":182}]}]},"AuditEvent":{"type":"object","properties":{"id":{"type":"string","description":"The event ID, such as `aud_…`."},"tenantId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The ID of the workspace."},"environmentId":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The ID of the environment that changed. `null` for changes that apply to every environment."},"actor":{"$ref":"#/components/schemas/AuditActor"},"action":{"type":"string","enum":["flag.create","flag.update","flag.delete","segment.create","segment.update","segment.delete","environment.update","environment.create","environment.delete","apiKey.create","apiKey.revoke","tenant.create","tenant.update","tenant.delete"],"description":"What happened. `flag.update` covers both replace and partial updates."},"resourceType":{"type":"string","enum":["flag","segment","environment","apiKey","tenant"],"description":"The kind of resource that changed."},"resourceId":{"type":"string","description":"The flag key, segment key, environment ID, or API key ID of the resource."},"before":{"anyOf":[{},{"type":"null"}],"description":"The resource before the change. `null` when the resource was created. Secrets are never included."},"after":{"anyOf":[{},{"type":"null"}],"description":"The resource after the change. `null` when the resource was deleted. Secrets are never included."},"metadata":{"type":"object","description":"Extra request context. Currently always empty."},"occurredAt":{"type":"string","description":"When the change happened, as an ISO 8601 timestamp."}},"required":["id","tenantId","environmentId","actor","action","resourceType","resourceId","before","after","metadata","occurredAt"],"additionalProperties":false,"description":"One recorded change to the workspace configuration.","examples":[{"id":"aud_1e4b7d0a-3c6f-4a9e-8b2d-5f8a1c4e7b0d","tenantId":"t_5b9e2c4a-8f1d-4a7c-b3e6-9d0c2f5a8b1e","environmentId":"env_3f6b2a9c-1d4e-4f7a-8b2c-5e9d0a1f3c7b","actor":{"type":"apiKey","id":"key_8a1d4c7e-2b5f-4e9a-9c3d-6f0b1a2e4d8c"},"action":"flag.update","resourceType":"flag","resourceId":"new-checkout","before":{"key":"new-checkout","enabled":false},"after":{"key":"new-checkout","enabled":true},"metadata":{},"occurredAt":"2026-05-02T09:30:00.000Z"}]},"AuditActor":{"type":"object","properties":{"type":{"type":"string","enum":["apiKey","user","service"],"description":"The kind of actor. `apiKey`: an API key. `user`: a dashboard user. `service`: a Toggld internal service."},"id":{"type":"string","description":"The ID of the API key, user, or service."}},"required":["type","id"],"additionalProperties":false,"description":"Who made the change."},"PublicToken":{"type":"object","properties":{"id":{"type":"string","description":"The public token ID."},"tenantId":{"type":"string","description":"The ID of the workspace that owns the token."},"environmentId":{"type":"string","description":"The ID of the environment the token belongs to."},"token":{"type":"string","description":"The full token, which starts with `ffp_`. It is not secret, so you can put it in browser and mobile code."},"createdAt":{"type":"string","description":"When the token was created, as an ISO 8601 timestamp."}},"required":["id","tenantId","environmentId","token","createdAt"],"additionalProperties":false,"description":"A public client token. Each environment has exactly one. It can evaluate flags through OFREP and send telemetry, but it cannot read flag definitions or change anything. This makes it safe to use in browser and mobile apps.","examples":[{"id":"pub_c2e5f8a1-7d3b-4c6e-a9f2-0b4d7e1a3c5f","tenantId":"t_5b9e2c4a-8f1d-4a7c-b3e6-9d0c2f5a8b1e","environmentId":"env_3f6b2a9c-1d4e-4f7a-8b2c-5e9d0a1f3c7b","token":"ffp_L31673RN3zCafb2rO5fksLQ99BMjgG5I","createdAt":"2026-05-01T12:00:00.000Z"}]},"ApiKeyNotFound":{"type":"object","properties":{"_tag":{"type":"string","enum":["ApiKeyNotFound"]},"keyId":{"type":"string","description":"The API key ID from the request."},"message":{"type":"string","description":"A human-readable explanation of the error."}},"required":["_tag","keyId","message"],"additionalProperties":false,"description":"No API key with this ID exists in the workspace."},"EnvironmentNotFound":{"type":"object","properties":{"_tag":{"type":"string","enum":["EnvironmentNotFound"]},"environment":{"type":"string","description":"The environment ID or key from the request."},"message":{"type":"string","description":"A human-readable explanation of the error."}},"required":["_tag","environment","message"],"additionalProperties":false,"description":"No environment with this ID or key exists in the workspace."},"CreatedApiKey":{"type":"object","properties":{"id":{"type":"string","description":"The API key ID, such as `key_…`. Use it to revoke the key."},"tenantId":{"type":"string","description":"The ID of the workspace that owns the key."},"environmentId":{"type":"string","description":"The ID of the environment the key belongs to."},"name":{"type":"string","description":"A label for the key."},"role":{"type":"string","enum":["management","evaluation"],"description":"What the key can do. `management`: manage the workspace through the management API, and evaluate flags. `evaluation`: evaluate flags, read flag definitions for local evaluation, and send telemetry."},"prefix":{"type":"string","description":"The first characters of the token, so you can recognize the key. It is not enough to authenticate."},"createdAt":{"type":"string","description":"When the key was created, as an ISO 8601 timestamp."},"token":{"type":"string","description":"The full secret token, which starts with `ffk_`. This is the only time the API returns it. Store it securely."}},"required":["id","tenantId","environmentId","role","prefix","createdAt","token"],"additionalProperties":false,"description":"A new secret API key, including its token. The token is shown only once.","examples":[{"id":"key_8a1d4c7e-2b5f-4e9a-9c3d-6f0b1a2e4d8c","tenantId":"t_5b9e2c4a-8f1d-4a7c-b3e6-9d0c2f5a8b1e","environmentId":"env_3f6b2a9c-1d4e-4f7a-8b2c-5e9d0a1f3c7b","name":"Checkout service","role":"evaluation","prefix":"ffk_VIGOVS","createdAt":"2026-05-01T12:00:00.000Z","token":"ffk_VIGOVSCgpmV1QofLEofOmH2COc97pZW9K40xyIx0DCQ"}]},"CreateApiKeyInput":{"type":"object","properties":{"role":{"type":"string","enum":["management","evaluation"],"description":"What the key can do. `management`: manage the workspace through the management API, and evaluate flags. `evaluation`: evaluate flags, read flag definitions for local evaluation, and send telemetry."},"name":{"type":"string","description":"A label for the key, such as the service that uses it."},"environment":{"type":"string","minLength":1,"description":"The key of the environment the API key belongs to, such as `production`. Required."}},"required":["role","environment"],"additionalProperties":false,"description":"The API key to create.","examples":[{"role":"evaluation","name":"Checkout service","environment":"production"}]},"ApiKey":{"type":"object","properties":{"id":{"type":"string","description":"The API key ID, such as `key_…`. Use it to revoke the key."},"tenantId":{"type":"string","description":"The ID of the workspace that owns the key."},"environmentId":{"type":"string","description":"The ID of the environment the key belongs to."},"name":{"type":"string","description":"A label for the key."},"role":{"type":"string","enum":["management","evaluation"],"description":"What the key can do. `management`: manage the workspace through the management API, and evaluate flags. `evaluation`: evaluate flags, read flag definitions for local evaluation, and send telemetry."},"prefix":{"type":"string","description":"The first characters of the token, so you can recognize the key. It is not enough to authenticate."},"createdAt":{"type":"string","description":"When the key was created, as an ISO 8601 timestamp."}},"required":["id","tenantId","environmentId","role","prefix","createdAt"],"additionalProperties":false,"description":"A secret API key. Listing never returns the token itself, only its prefix.","examples":[{"id":"key_8a1d4c7e-2b5f-4e9a-9c3d-6f0b1a2e4d8c","tenantId":"t_5b9e2c4a-8f1d-4a7c-b3e6-9d0c2f5a8b1e","environmentId":"env_3f6b2a9c-1d4e-4f7a-8b2c-5e9d0a1f3c7b","name":"Checkout service","role":"evaluation","prefix":"ffk_VIGOVS","createdAt":"2026-05-01T12:00:00.000Z"}]},"EnvironmentConflict":{"type":"object","properties":{"_tag":{"type":"string","enum":["EnvironmentConflict"]},"message":{"type":"string","description":"A human-readable explanation of the error."}},"required":["_tag","message"],"additionalProperties":false,"description":"The environment change conflicts with the workspace. A workspace must keep at least one environment, and a new order must list every environment exactly once."},"Environment":{"type":"object","properties":{"id":{"type":"string","description":"The environment ID, such as `env_…`."},"tenantId":{"type":"string","description":"The ID of the workspace that owns the environment."},"isProduction":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Whether the environment serves production traffic."},"position":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"The environment's place in the workspace order, ascending. The dashboard lists environments in this order. A new environment goes last and copies flag values from the environment before it."},"color":{"anyOf":[{"type":"string","enum":["gray","red","orange","amber","yellow","lime","green","emerald","teal","cyan","sky","blue","indigo","violet","purple","fuchsia","pink","rose"]},{"type":"null"}],"description":"The environment's display color in the dashboard. Defaults to `gray`."},"key":{"type":"string","description":"The environment key, unique in the workspace, such as `production`."},"name":{"type":"string","description":"A display name for the environment."},"createdAt":{"type":"string","description":"When the environment was created, as an ISO 8601 timestamp."}},"required":["id","tenantId","position","key","name","createdAt"],"additionalProperties":false,"description":"A deployment stage in a workspace, such as `development` or `production`. Each environment has its own flag values, enabled states, and targeting rules. Every API key belongs to one environment.","examples":[{"id":"env_3f6b2a9c-1d4e-4f7a-8b2c-5e9d0a1f3c7b","tenantId":"t_5b9e2c4a-8f1d-4a7c-b3e6-9d0c2f5a8b1e","isProduction":true,"position":1,"color":"red","key":"production","name":"Production","createdAt":"2026-05-01T12:00:00.000Z"}]},"ReorderEnvironmentsInput":{"type":"object","properties":{"environmentIds":{"type":"array","items":{"type":"string"},"minItems":1,"description":"Every environment ID in the workspace, in the new order. Partial lists are rejected."}},"required":["environmentIds"],"additionalProperties":false,"description":"The new environment order.","examples":[{"environmentIds":["env_9a2c4e6b-1f3d-4b5a-8c7e-0d2f4a6c8e1b","env_3f6b2a9c-1d4e-4f7a-8b2c-5e9d0a1f3c7b"]}]},"EnvironmentAlreadyExists":{"type":"object","properties":{"_tag":{"type":"string","enum":["EnvironmentAlreadyExists"]},"environment":{"type":"string","description":"The environment ID or key from the request."},"message":{"type":"string","description":"A human-readable explanation of the error."}},"required":["_tag","environment","message"],"additionalProperties":false,"description":"An environment with this key already exists in the workspace."},"CreateEnvironmentInput":{"type":"object","properties":{"isProduction":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Whether the environment serves production traffic. Defaults to `false`."},"color":{"anyOf":[{"type":"string","enum":["gray","red","orange","amber","yellow","lime","green","emerald","teal","cyan","sky","blue","indigo","violet","purple","fuchsia","pink","rose"]},{"type":"null"}],"description":"The environment's display color in the dashboard. Defaults to `gray`."},"key":{"type":"string","minLength":1,"description":"The environment key, unique in the workspace, such as `staging`."},"name":{"type":"string","minLength":1,"description":"A display name for the environment."}},"required":["key","name"],"additionalProperties":false,"description":"The environment to create. It goes last in the workspace order.","examples":[{"key":"staging","name":"Staging","color":"amber"}]},"UpdateEnvironmentInput":{"type":"object","properties":{"key":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"description":"A new environment key, unique in the workspace."},"name":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"description":"A new display name."},"isProduction":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Whether the environment serves production traffic."},"color":{"anyOf":[{"type":"string","enum":["gray","red","orange","amber","yellow","lime","green","emerald","teal","cyan","sky","blue","indigo","violet","purple","fuchsia","pink","rose"]},{"type":"null"}],"description":"The environment's display color in the dashboard. Defaults to `gray`."}},"additionalProperties":false,"description":"The fields to change. Omitted fields keep their current values.","examples":[{"name":"Staging (EU)"},{"color":"violet"}]},"SegmentValidationError":{"type":"object","properties":{"_tag":{"type":"string","enum":["SegmentValidationError"]},"segmentKey":{"type":"string","description":"The segment key from the request."},"issues":{"type":"array","items":{"type":"string"},"description":"One entry for each problem found."},"message":{"type":"string","description":"A human-readable explanation of the error."}},"required":["_tag","segmentKey","issues","message"],"additionalProperties":false,"description":"The segment is not valid. `issues` lists each problem, such as an empty or duplicate rule ID, an invalid condition, or a member list over the size limit."},"SegmentNotFound":{"type":"object","properties":{"_tag":{"type":"string","enum":["SegmentNotFound"]},"segmentKey":{"type":"string","description":"The segment key from the request."},"message":{"type":"string","description":"A human-readable explanation of the error."}},"required":["_tag","segmentKey","message"],"additionalProperties":false,"description":"No segment with this key exists in the workspace."},"Segment":{"type":"object","properties":{"key":{"type":"string","description":"The unique key of the segment in the workspace, such as `beta-testers`."},"name":{"type":"string","description":"A display name for the segment."},"description":{"type":"string","description":"A description of the audience."},"keyAttribute":{"type":"string","description":"The evaluation context attribute compared with the member list. Defaults to `targetingKey`."},"rules":{"type":"array","items":{"$ref":"#/components/schemas/SegmentRule"},"description":"Membership rules. A subject is in the segment if any rule matches."},"listMode":{"type":"string","enum":["none","inline","remote"],"description":"How the member list reaches evaluation. `none`: the segment has no listed members. `inline`: members are sent with the flag definitions. `remote` is reserved for larger lists and is not used yet."},"memberCount":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},"version":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},"usedBy":{"type":"array","items":{"type":"string"},"description":"Keys of the flags whose targeting rules use this segment, in any environment."},"createdAt":{"type":"string","description":"When the segment was created, as an ISO 8601 timestamp."},"updatedAt":{"type":"string","description":"When the segment was last changed, as an ISO 8601 timestamp."}},"required":["key","keyAttribute","rules","listMode","memberCount","version","usedBy","createdAt","updatedAt"],"additionalProperties":false,"description":"A reusable audience that targeting rules can reference. A subject is in the segment if it matches any rule or its key is in the member list. Segments belong to the workspace and apply in every environment.","examples":[{"key":"beta-testers","name":"Beta testers","keyAttribute":"targetingKey","rules":[{"id":"staff","conditions":[{"attribute":"email","operator":"endsWith","value":"@example.com"}]}],"listMode":"inline","memberCount":2,"version":4,"usedBy":["new-checkout"],"createdAt":"2026-05-01T12:00:00.000Z","updatedAt":"2026-05-03T08:15:00.000Z"}]},"UpdateSegmentMembersInput":{"type":"object","properties":{"add":{"type":"array","items":{"type":"string"},"description":"Member keys to add. Keys that are already members are ignored."},"remove":{"type":"array","items":{"type":"string"},"description":"Member keys to remove. Keys that are not members are ignored."}},"additionalProperties":false,"description":"Member keys to add and remove in one request. A segment can have at most 5,000 members.","examples":[{"add":["user-123","user-456"],"remove":["user-789"]}]},"SegmentMemberPage":{"type":"object","properties":{"members":{"type":"array","items":{"$ref":"#/components/schemas/SegmentMember"},"description":"The members on this page, oldest first."},"total":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]}},"required":["members","total"],"additionalProperties":false,"description":"One page of a segment's member list.","examples":[{"members":[{"key":"user-123","addedAt":"2026-05-02T10:00:00.000Z"},{"key":"user-456","addedAt":"2026-05-02T10:00:00.000Z"}],"total":2}]},"SegmentMember":{"type":"object","properties":{"key":{"type":"string","description":"The member key, such as a user ID."},"addedAt":{"type":"string","description":"When the member was added, as an ISO 8601 timestamp."}},"required":["key","addedAt"],"additionalProperties":false,"description":"One listed member of a segment."},"SegmentReferenced":{"type":"object","properties":{"_tag":{"type":"string","enum":["SegmentReferenced"]},"segmentKey":{"type":"string","description":"The segment key from the request."},"flagKeys":{"type":"array","items":{"type":"string"},"description":"Keys of the flags whose targeting rules use the segment."},"message":{"type":"string","description":"A human-readable explanation of the error."}},"required":["_tag","segmentKey","flagKeys","message"],"additionalProperties":false,"description":"Targeting rules still use this segment, so it cannot be deleted. Remove the segment from the flags in `flagKeys` first."},"SegmentConflict":{"type":"object","properties":{"_tag":{"type":"string","enum":["SegmentConflict"]},"segmentKey":{"type":"string","description":"The segment key from the request."},"message":{"type":"string","description":"A human-readable explanation of the error."}},"required":["_tag","segmentKey","message"],"additionalProperties":false,"description":"The segment changed after you read it, so `expectedVersion` no longer matches. Reload the segment and try again."},"PatchSegmentInput":{"type":"object","properties":{"expectedVersion":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"The `version` you last read. If the segment changed since then, the request fails with `409` and nothing is saved. Omit it to skip the check."},"name":{"type":"string","description":"A display name for the segment."},"description":{"type":"string","description":"A description of the audience."},"keyAttribute":{"type":"string","description":"The evaluation context attribute compared with the member list. Defaults to `targetingKey`."},"rules":{"type":"array","items":{"$ref":"#/components/schemas/SegmentRule"},"description":"Membership rules. This replaces the whole list."}},"additionalProperties":false,"description":"The fields to change. Omitted fields keep their current values.","examples":[{"expectedVersion":4,"name":"Beta testers (EU)"}]},"SegmentAlreadyExists":{"type":"object","properties":{"_tag":{"type":"string","enum":["SegmentAlreadyExists"]},"segmentKey":{"type":"string","description":"The segment key from the request."},"message":{"type":"string","description":"A human-readable explanation of the error."}},"required":["_tag","segmentKey","message"],"additionalProperties":false,"description":"A segment with this key already exists in the workspace."},"CreateSegmentInput":{"type":"object","properties":{"key":{"type":"string","minLength":1,"description":"The unique key of the segment in the workspace, such as `beta-testers`."},"name":{"type":"string","description":"A display name for the segment."},"description":{"type":"string","description":"A description of the audience."},"keyAttribute":{"type":"string","description":"The evaluation context attribute compared with the member list. Defaults to `targetingKey`."},"rules":{"type":"array","items":{"$ref":"#/components/schemas/SegmentRule"},"description":"Membership rules. A subject is in the segment if any rule matches."}},"required":["key"],"additionalProperties":false,"description":"The segment to create. Add members later with the update members endpoint.","examples":[{"key":"beta-testers","name":"Beta testers","rules":[{"id":"staff","conditions":[{"attribute":"email","operator":"endsWith","value":"@example.com"}]}]}]},"FlagValidationError":{"type":"object","properties":{"_tag":{"type":"string","enum":["FlagValidationError"]},"flagKey":{"type":"string","description":"The flag key from the request."},"issues":{"type":"array","items":{"type":"string"},"description":"One entry for each problem found."},"message":{"type":"string","description":"A human-readable explanation of the error."}},"required":["_tag","flagKey","issues","message"],"additionalProperties":false,"description":"The flag is not valid. `issues` lists each problem, such as an undeclared variant, a value that does not match the flag type, a changed flag type, or a reference to an unknown segment."},"FlagConflict":{"type":"object","properties":{"_tag":{"type":"string","enum":["FlagConflict"]},"flagKey":{"type":"string","description":"The flag key from the request."},"message":{"type":"string","description":"A human-readable explanation of the error."}},"required":["_tag","flagKey","message"],"additionalProperties":false,"description":"The flag changed after you read it, so `expectedVersion` no longer matches. Reload the flag and try again."},"Flag":{"type":"object","properties":{"key":{"type":"string","description":"The unique key of the flag in the workspace, such as `new-checkout`. SDKs evaluate the flag by this key."},"name":{"type":"string","description":"A display name for the flag."},"description":{"type":"string","description":"A description of what the flag controls."},"type":{"type":"string","enum":["boolean","string","number","object"],"description":"The value type of the flag. Every variant value must match it. It cannot change after creation."},"enabled":{"type":"boolean","description":"Whether the flag is on in this environment. When `false`, evaluation serves `offVariant`."},"variants":{"type":"object","description":"The values the flag can serve, keyed by variant name. Each value must match `type`."},"defaultVariant":{"type":"string","description":"The variant served when the flag is on and no targeting rule matches."},"offVariant":{"type":"string","description":"The variant served when the flag is off. Defaults to `defaultVariant`."},"targeting":{"type":"array","items":{"$ref":"#/components/schemas/TargetingRule"},"description":"Targeting rules, in order. The first matching rule wins."},"metadata":{"$ref":"#/components/schemas/FlagMetadata"},"createdAt":{"type":"string","description":"When the flag was created, as an ISO 8601 timestamp."},"updatedAt":{"type":"string","description":"When the flag was last changed, as an ISO 8601 timestamp."},"tags":{"type":"array","items":{"type":"string","minLength":1},"description":"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":{"type":"string","description":"An 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."}},"required":["key","type","enabled","variants","defaultVariant","targeting","metadata","createdAt","updatedAt","tags","version"],"additionalProperties":false,"description":"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.","examples":[{"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"}]},"PatchFlagInput":{"type":"object","properties":{"expectedVersion":{"type":"string","description":"The `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":{"type":"string","description":"A display name for the flag."},"description":{"type":"string","description":"A description of what the flag controls."},"type":{"type":"string","enum":["boolean","string","number","object"],"description":"The flag type. If you send it, it must match the current type, because the type cannot change."},"enabled":{"type":"boolean","description":"Whether the flag is on in the credential's environment."},"variants":{"type":"object","description":"The values the flag can serve, keyed by variant name. Each value must match `type`."},"defaultVariant":{"type":"string","description":"The variant served when the flag is on and no targeting rule matches. It must be a key of `variants`."},"offVariant":{"type":"string","description":"The variant served when the flag is off. Defaults to `defaultVariant`."},"targeting":{"type":"array","items":{"$ref":"#/components/schemas/TargetingRule"},"description":"Targeting rules for the credential's environment, in order. This replaces the whole list."},"metadata":{"$ref":"#/components/schemas/FlagMetadata"},"tags":{"type":"array","items":{"type":"string","minLength":1},"description":"Labels that organize flags. This replaces the whole list. The server normalizes tags the same way as on create."}},"additionalProperties":false,"description":"The fields to change. Omitted fields keep their current values.","examples":[{"enabled":false},{"expectedVersion":"b7e1c0d2-4f3a-4c8e-9a1b-2d3e4f5a6b7c.0a9b8c7d-6e5f-4a3b-8c2d-1e0f9a8b7c6d","tags":["checkout","q3-launch"]}]},"ReplaceFlagInput":{"type":"object","properties":{"expectedVersion":{"type":"string","description":"The `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":{"type":"string","description":"A display name for the flag."},"description":{"type":"string","description":"A description of what the flag controls."},"type":{"type":"string","enum":["boolean","string","number","object"],"description":"The flag type. It must match the current type, because the type cannot change."},"enabled":{"type":"boolean","description":"Whether the flag is on in the credential's environment. Defaults to `false`."},"variants":{"type":"object","description":"The values the flag can serve, keyed by variant name. Each value must match `type`."},"defaultVariant":{"type":"string","description":"The variant served when the flag is on and no targeting rule matches. It must be a key of `variants`."},"offVariant":{"type":"string","description":"The variant served when the flag is off. Defaults to `defaultVariant`."},"targeting":{"type":"array","items":{"$ref":"#/components/schemas/TargetingRule"},"description":"Targeting rules for the credential's environment, in order. Defaults to no rules."},"metadata":{"$ref":"#/components/schemas/FlagMetadata"},"tags":{"type":"array","items":{"type":"string","minLength":1},"description":"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."}},"required":["type","variants","defaultVariant"],"additionalProperties":false,"description":"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.","examples":[{"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"]}]},"FlagLimitExceeded":{"type":"object","properties":{"_tag":{"type":"string","enum":["FlagLimitExceeded"]},"limit":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"The maximum number of flags the plan allows."},"current":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"The number of flags the workspace has now."},"message":{"type":"string","description":"A human-readable explanation of the error."}},"required":["_tag","limit","current","message"],"additionalProperties":false,"description":"The workspace has reached the flag limit of its plan. Delete a flag or upgrade the plan to create more."},"FlagAlreadyExists":{"type":"object","properties":{"_tag":{"type":"string","enum":["FlagAlreadyExists"]},"flagKey":{"type":"string","description":"The flag key from the request."},"message":{"type":"string","description":"A human-readable explanation of the error."}},"required":["_tag","flagKey","message"],"additionalProperties":false,"description":"A flag with this key already exists in the workspace."},"CreateFlagInput":{"type":"object","properties":{"key":{"type":"string","minLength":1,"description":"The unique key of the flag in the workspace, such as `new-checkout`. It cannot change later."},"name":{"type":"string","description":"A display name for the flag."},"description":{"type":"string","description":"A description of what the flag controls."},"type":{"type":"string","enum":["boolean","string","number","object"],"description":"The value type of the flag. Every variant value must match it. It cannot change after creation."},"enabled":{"type":"boolean","description":"Whether the flag is on in the credential's environment. Defaults to `false`, as in the dashboard. Other environments start off."},"variants":{"type":"object","description":"The values the flag can serve, keyed by variant name. Each value must match `type`."},"defaultVariant":{"type":"string","description":"The variant served when the flag is on and no targeting rule matches. It must be a key of `variants`."},"offVariant":{"type":"string","description":"The variant served when the flag is off. Defaults to `defaultVariant`."},"targeting":{"type":"array","items":{"$ref":"#/components/schemas/TargetingRule"},"description":"Targeting rules for the credential's environment, in order. Other environments start with no rules."},"metadata":{"$ref":"#/components/schemas/FlagMetadata"},"tags":{"type":"array","items":{"type":"string","minLength":1},"description":"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."}},"required":["key","type","variants","defaultVariant"],"additionalProperties":false,"description":"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.","examples":[{"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"]}]}},"securitySchemes":{"bearer":{"description":"Send a credential in the `Authorization` header: `Authorization: Bearer <token>`.\nEach credential belongs to one environment of one workspace, so the API never takes a workspace or environment in the URL.\n\n- **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.\n- **Evaluation key** (`ffk_…`, secret): for server SDKs. It evaluates flags, reads flag definitions for local evaluation, and sends telemetry.\n- **Public token** (`ffp_…`, not secret): for browser and mobile apps. It evaluates flags through OFREP and sends telemetry. It cannot read flag definitions.\n\nKeep 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.","type":"http","scheme":"Bearer"}}},"security":[],"tags":[{"name":"Flags","description":"Create and manage feature flags. The key, type, name, description, tags, and metadata of a flag are shared by every environment. The variants, enabled state, and targeting rules belong to one environment: the environment of the credential you call with."},{"name":"Segments","description":"Reusable audiences for targeting rules. A subject is in a segment if it matches one of the segment's rules or its key is in the member list. Segments belong to the workspace and apply in every environment."},{"name":"Environments","description":"Deployment stages in a workspace, such as `development` and `production`. Each environment has its own flag values, enabled states, targeting rules, API keys, and public token."},{"name":"API keys","description":"Secret keys for server-side access. Each key belongs to one environment and has a role: `management` or `evaluation`."},{"name":"Public tokens","description":"Non-secret tokens for browser and mobile apps. Each environment has exactly one public token. It can evaluate flags through OFREP and send telemetry, but it cannot read flag definitions or change anything. Public tokens cannot be rotated or revoked."},{"name":"Audit log","description":"A read-only record of every configuration change in the workspace: who changed what, and when. Flag evaluations are not recorded."},{"name":"Analytics","description":"Evaluation counts for flags, built from the telemetry that SDKs and the server report."},{"name":"Evaluation (OFREP)","description":"Evaluate flags with the OpenFeature Remote Evaluation Protocol (OFREP). OpenFeature OFREP providers call these endpoints. You send an evaluation context and get evaluated values back. Targeting rules stay on the server. These endpoints accept requests from any browser origin, so browser apps can call them with a public token.","externalDocs":{"url":"https://openfeature.dev/specification/appendix-c","description":"OFREP specification"}},{"name":"Definition sync","description":"Flag definitions for SDKs that evaluate flags locally. The SDK downloads every flag with its targeting rules, then evaluates flags without a network request. Only secret keys can read definitions."},{"name":"Telemetry","description":"Report how often SDKs evaluate flags. Toggld stores only counts for each flag, variant, reason, and minute. It never stores who was evaluated or their evaluation context."}],"servers":[{"url":"https://api.toggld.io","description":"Hosted Toggld"}],"externalDocs":{"url":"https://docs.toggld.io","description":"Toggld documentation"}}