Segment membership API
Host: https://app.toggly.io. Authenticate with a Backend application key, not a dashboard OAuth token.
Send the key in Authorization as the raw value or Bearer <key> (same as identity mint).
Never ship a Backend application key to a browser or public client. This API has CORS disabled.
Base path: /api/v2/segments
The key identifies the application. There is no applicationId in the route.
Endpoints
| Method | Path | Purpose |
|---|---|---|
GET | /api/v2/segments | Summaries the key may update (id, name, environment, itemCount) |
GET | /api/v2/segments/{segment}/items?skip=0&take=100 | Paged identifiers |
POST | /api/v2/segments/{segment}/items | Add or update identifiers |
DELETE | /api/v2/segments/{segment}/items | Remove identifiers |
PUT | /api/v2/segments/{segment}/items | Replace the whole set (max 500 members) |
{segment} is the short list id, or a unique list name among lists this key can see. Duplicate names return 409. Unknown or out-of-scope lists return 404.
Request body
{
"identifiers": ["user-123", "user-456"],
"items": [{ "identifier": "user-123", "description": "beta" }]
}
identifiers and items may be combined. Descriptions are optional. Identifiers are trimmed and stored as sent. Empty identifiers are rejected.
Limits
| Limit | Value |
|---|---|
| Identifiers per request | 500 |
| Identifiers per list | 10,000 |
| Identifier length | 256 |
Page take | max 500, default 100 |
| Body size | 512 KiB |
Writes that would exceed 10,000 members return 400.
Environment restrictions
- Unrestricted Backend key: app-level lists and every environment list on that app.
- Restricted key: only lists whose environment is in the key’s restriction set. App-level lists (
environmentnull) return 404.
Status codes
| Code | Meaning |
|---|---|
| 200 | Success |
| 400 | Validation or limit |
| 401 | Missing or unknown key |
| 403 | Key is not Backend |
| 404 | Segment not visible |
| 409 | List name is not unique for this key |
| 429 | Rate limited |
Consistency
Membership is copied into published feature definitions. SDKs see the new set on the next definitions refresh. See Syncing segment membership. Library-specific clients are on each server SDK page.