Skip to main content

Segments API

POST /v1/segments/preview​

Secret key, scope subscriptions:read.

{ "segment": { "and": [ { "field": "tags.plan", "op": "in", "value": ["premium", "platinum"] }, { "field": "lastActiveAt", "op": "gt", "value": "-14d" } ] } }

Omit segment (or send {}) to count everyone.

Response

{ "count": 661, "byPlatform": { "ios": 275, "android": 264, "web": 122 } }

Counts only opted-in, non-invalidated subscriptions of the key's app — the same base filter fan-out uses, so the number is what a campaign with this segment would queue.

Errors: 422 invalid_body for a malformed request, 422 invalid_segment with the path of the offending node when the DSL does not compile (unknown operator, an object where a scalar is required, a field starting with $).

The DSL itself — fields, operators, relative dates, nesting — is documented in Features › Segments.

Saved segments​

Secret key. subscriptions:read to list, read and count; campaigns:write to create, replace and delete. See Features › Segments.

GET /v1/segments​

{ "segments": [ { "id": "66f2…", "name": "turkey-premium", "description": null, "definition": { … }, "lastCount": 512, "lastCountedAt": "…", "createdAt": "…", "updatedAt": "…" } ] }

POST /v1/segments​

{ "name": "turkey-premium", "description": "Premium plan, TR", "definition": { "and": [ … ] } }

201 with the segment; 409 duplicate_name; 422 invalid_body when the definition does not validate.

GET /v1/segments/:id · PUT /v1/segments/:id · DELETE /v1/segments/:id​

PUT replaces name, description and definition and clears the stored count. DELETE answers 204; campaigns already sent keep their copied definition, drafts that still point at the id fail at send with 404.

POST /v1/segments/:id/count​

Counts reachable devices now (same base filter as preview), stores the number as lastCount and returns { "count", "byPlatform" }. 422 invalid_segment if the stored definition no longer compiles.

Targeting one​

POST /v1/notifications takes target.segmentId; POST /v1/campaigns takes segmentId (not together with segment). The definition is copied into the campaign when it is sent.