Publiq

Segments

Rule-based subsets of an audience (`publiq.segments`).

The segments resource represents a subset of an audience, defined by a rule tree (rules) evaluated against contacts. Create, list, update and delete segments, then use them as the target of a broadcast.

Method reference

segments.create

segments.create(audienceId, params) → Promise<Segment>

Creates a segment inside an audience, defined by a rule tree (rules) that determines which contacts belong to it.

Parameters
ParameterTypeDescription
audienceIdRequiredstringID of the audience the segment will be created in (part of the URL).
nameRequiredstringThe segment name (1 to 200 characters).
rulesRequiredobjectThe rule tree that defines the segment. See the shape below.

Returns: The created segment — { object: "segment", id, name, rules, ... }.

const segment = await publiq.segments.create('aud_123', {
name: 'Active subscribers',
rules: {
  op: 'and',
  children: [{ field: 'subscribed', cmp: 'eq', value: true }],
},
});
console.log(segment.id, segment.name); // "seg_...", "Active subscribers"
rules is a tree: a leaf is { field, cmp, value } and a node is { op, children }, where op is and or or and children is a list of leaves and/or nodes — letting you combine conditions at any depth. Available comparators (cmp): eq, neq, gt, gte, lt, lte, in, contains, exists. field is validated against an allow-list — subscribed is always valid; arbitrary attribute fields may be restricted.
A segment is the audience subset you target with a Broadcasts — instead of sending to the whole Audiences, send only to whoever matches the rules.

segments.list

segments.list(audienceId, { limit?, after? }) → Promise<SegmentList>

Lists the segments of an audience, cursor-paginated.

Parameters
ParameterTypeDescription
audienceIdRequiredstringID of the audience whose segments will be listed (part of the URL).
limitOptionalnumberItems per page (default 20, max 100).
afterOptionalstringCursor: id of the last item on the previous page.

Returns: List envelope { object: "list", data: Segment[] }. Use the last item id as after on the next call.

const { data } = await publiq.segments.list('aud_123', { limit: 50 });
// next page:
const next = await publiq.segments.list('aud_123', { after: data[data.length - 1].id });
Listing is cursor-paginated: iterate by passing the last item id in after until data comes back empty. See Errors & pagination.

segments.update

segments.update(audienceId, segmentId, params) → Promise<Segment>

Updates the name and/or the rule tree of an existing segment.

Parameters
ParameterTypeDescription
audienceIdRequiredstringID of the audience the segment belongs to (part of the URL).
segmentIdRequiredstringID of the segment to update (part of the URL).
nameOptionalstringNew segment name.
rulesOptionalobjectNew rule tree — replaces the previous one entirely (no merge).

Returns: The updated segment.

const segment = await publiq.segments.update('aud_123', 'seg_123', {
rules: {
  op: 'or',
  children: [
    { field: 'plan', cmp: 'eq', value: 'pro' },
    { field: 'plan', cmp: 'eq', value: 'enterprise' },
  ],
},
});
console.log(segment.rules);

segments.delete

segments.delete(audienceId, segmentId) → Promise<void>

Permanently removes a segment. Does not affect the audience contacts, only the segment definition.

Parameters
ParameterTypeDescription
audienceIdRequiredstringID of the audience the segment belongs to (part of the URL).
segmentIdRequiredstringID of the segment to remove (part of the URL).

Returns: No content (204).

await publiq.segments.delete('aud_123', 'seg_123');

Examples show Node, Python and PHP. In Python methods are snake_case (e.g. cancel_run, from_spec) and take a dict; in PHP they are camelCase and take an associative array. Body keys are always camelCase (templateKey, firstName, scheduledAt) — API responses come back in snake_case.

Segments — Publiq Docs