API reference

Segments

Preview, create, list, pause and delete segments.

A segment is a saved rule over metrics. See Segments for how to write the predicate.

Preview a segment#

POST /v1/tenants/{tenant}/segments/preview Tenant token

Validates a rule and counts who would match, without saving anything. Good for live previews in a rule editor.

Body

workspace_id string

The workspace to count in.

predicate object

The rule. See Segments.

bash

curl -X POST "https://api.breeze.in/cdp/control-plane/v1/tenants/breeze/segments/preview" \
  -H "Authorization: Bearer $BREEZEIQ_TOKEN" -H "Content-Type: application/json" \
  -d '{
    "workspace_id": "my-store",
    "predicate": { "metric": "total_spend", "op": "gte", "value": 10000 }
  }'

json

{
  "matching_customers": 3,
  "matching_breakdown": { "customers": 2, "visitors": 1 },
  "workspace_members": 15,
  "workspace_customers": 11,
  "workspace_visitors": 4,
  "truncated": false,
  "is_temporal": false
}

Matches are counted over at most 20,000 profiles. truncated: true means the counts are a lower bound. The workspace_* totals are always exact.

Create a segment#

PUT /v1/tenants/{tenant}/segments/{segment_id} Tenant token

Creates a segment. Create-only: returns 409 if the id exists.

Body

workspace_id string Required

The workspace the segment lives in.

display_name string Required

Human-readable name.

predicate object Required

The rule. See Segments.

status string

draft, active (default), paused or archived.

automations object

Default {"on_enter": true, "on_exit": true, "on_backfill": false}.

bash

curl -X PUT "https://api.breeze.in/cdp/control-plane/v1/tenants/breeze/segments/vip-customers" \
  -H "Authorization: Bearer $BREEZEIQ_TOKEN" -H "Content-Type: application/json" \
  -d '{
    "workspace_id": "my-store",
    "display_name": "VIP customers",
    "predicate": { "metric": "total_spend", "op": "gte", "value": 10000 }
  }'

json

{
  "tenant_id": "breeze",
  "segment_id": "vip-customers",
  "is_temporal": false,
  "status": "created"
}

List segments#

GET /v1/tenants/{tenant}/segments Workspace token

Lists segments with live member counts.

Query

workspace_id string

The workspace to list.

limit number

Page size, up to 500.

cursor string

next_cursor from the previous page.

bash

curl "https://api.breeze.in/cdp/control-plane/v1/tenants/breeze/segments?workspace_id=my-store&limit=100" \
  -H "Authorization: Bearer $BREEZEIQ_TOKEN"

json

{
  "segments": [
    {
      "workspace_id": "my-store",
      "segment_id": "vip-customers",
      "display_name": "VIP customers",
      "predicate": { "metric": "total_spend", "op": "gte", "value": 10000 },
      "is_temporal": false,
      "status": "active",
      "automations": { "on_enter": true, "on_exit": true, "on_backfill": false },
      "created_at": "2026-10-08T09:00:00Z",
      "member_count": 12,
      "segment_customers": 9,
      "segment_visitors": 3
    }
  ],
  "next_cursor": null
}

Get a segment#

GET /v1/tenants/{tenant}/segments/{segment_id}/definition Workspace token

Returns one segment, in the same shape as List segments without the counts.

Query

workspace_id string

The segment's workspace.

bash

curl "https://api.breeze.in/cdp/control-plane/v1/tenants/breeze/segments/vip-customers/definition?workspace_id=my-store" \
  -H "Authorization: Bearer $BREEZEIQ_TOKEN"

Update segment status#

PUT /v1/tenants/{tenant}/segments/{segment_id}/status Tenant token

Changes the status, the only field that can change after creation.

Body

workspace_id string

The segment's workspace.

status string

draft, active, paused or archived.

bash

curl -X PUT "https://api.breeze.in/cdp/control-plane/v1/tenants/breeze/segments/vip-customers/status" \
  -H "Authorization: Bearer $BREEZEIQ_TOKEN" -H "Content-Type: application/json" \
  -d '{"workspace_id": "my-store", "status": "paused"}'

Delete a segment#

DELETE /v1/tenants/{tenant}/segments/{segment_id} Tenant token

Deletes a segment definition. Use it for mistakes. For normal retirement, prefer status: "archived".

Query

workspace_id string

The segment's workspace.

bash

curl -X DELETE "https://api.breeze.in/cdp/control-plane/v1/tenants/breeze/segments/vip-customers?workspace_id=my-store" \
  -H "Authorization: Bearer $BREEZEIQ_TOKEN"