Create a segment
Creates a segment with optional membership rules. Add member keys afterwards with the update segment members endpoint.
Requires a management key.
Returns 409 if the key is already in use 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.
application/json- body
The segment to create. Add members later with the update members endpoint.
key*stringThe unique key of the segment in the workspace, such as beta-testers.
1 <= lengthname?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.
Created
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 POST 'https://api.toggld.io/api/v1/segments' \ -H 'Content-Type: application/json' \ -d '{ "key": "beta-testers", "name": "Beta testers", "rules": [ { "id": "staff", "conditions": [ { "attribute": "email", "operator": "endsWith", "value": "@example.com" } ] } ]}'{ "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"}List segments GET
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. Requires a management key.
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.