Update a segment
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.
Requires a management key.
Returns 404 if no segment has this key, 409 if expectedVersion does not match the current version, and 422 if the rules are not valid.
bearerAuthorizationBearer <token>Send a credential in the Authorization header: Authorization: Bearer <token>.
Each credential belongs to one environment of one workspace, so the API never takes a workspace or environment in the URL.
- Management key (
ffk_…, secret): manages flags, segments, environments, and API keys, and reads the audit log and analytics. It can also do everything an evaluation key can. - Evaluation key (
ffk_…, secret): for server SDKs. It evaluates flags, reads flag definitions for local evaluation, and sends telemetry. - Public token (
ffp_…, not secret): for browser and mobile apps. It evaluates flags through OFREP and sends telemetry. It cannot read flag definitions.
Keep secret keys on your server. A 401 response means the credential is missing or not valid. A 403 response means the credential is valid but its role cannot perform the operation.
key*stringThe segment key, such as beta-testers.
application/json- body
The fields to change. Omitted fields keep their current values.
expectedVersion?integerThe 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.
0 <= value <= 9007199254740991name?stringA display name for the segment.
description?stringA description of the audience.
keyAttribute?stringThe evaluation context attribute compared with the member list. Defaults to targetingKey.
rules?array<>Membership rules. This replaces the whole list.
OK
application/json- response
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.
key*stringThe unique key of the segment in the workspace, such as beta-testers.
name?stringA display name for the segment.
description?stringA description of the audience.
keyAttribute*stringThe evaluation context attribute compared with the member list. Defaults to targetingKey.
rules*array<>Membership rules. A subject is in the segment if any rule matches.
listMode*stringHow 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.
"none""inline""remote"memberCount*number|version*number|usedBy*array<string>Keys of the flags whose targeting rules use this segment, in any environment.
createdAt*stringWhen the segment was created, as an ISO 8601 timestamp.
updatedAt*stringWhen the segment was last changed, as an ISO 8601 timestamp.
curl -X PATCH 'https://api.toggld.io/api/v1/segments/string' \ -H 'Content-Type: application/json' \ -d '{ "expectedVersion": 4, "name": "Beta testers (EU)"}'{ "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"}Retrieve a segment GET
Returns a segment, its member count, and the keys of the flags that use it. Requires a management key. Returns `404` if no segment has this key.
Delete a segment DELETE
Permanently deletes a segment and its member list. Requires a management key. Returns `404` if no segment has this key. Returns `409` while targeting rules still use the segment. The response lists those flags in `flagKeys`.