SegOps AIDocs

Segments API

Create and manage segments, preview definitions, trigger membership computation, and query membership at runtime.

List Segments#

GET /api/segments/

bash
curl https://api.segops.ai/api/segments/ \
  -H "Authorization: Bearer $JWT"

Get a Segment#

GET /api/segments/<id>/

bash
curl https://api.segops.ai/api/segments/7/ \
  -H "Authorization: Bearer $JWT"

Create a Segment#

POST /api/segments/

bash
curl -X POST https://api.segops.ai/api/segments/ \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "High-Value Churners",
    "tenant": 1,
    "segment_type": "rule",
    "description": "Users who spent ≥$500 but haven'''t returned in 30 days"
  }'

segment_type accepts rule, ai, or lookalike. The segment definition is set separately via PATCH.

Update a Segment Definition#

PATCH /api/segments/<id>/

bash
curl -X PATCH https://api.segops.ai/api/segments/7/ \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "definition": {
      "logic": "AND",
      "conditions": [
        {
          "type": "monetary",
          "event_type": "order_placed",
          "property": "total",
          "metric": "sum",
          "operator": "gte",
          "value": 500
        },
        {
          "type": "recency",
          "event_type": "page_viewed",
          "operator": "gt",
          "window_days": 30
        }
      ]
    }
  }'

Preview a Segment#

POST /api/segments/preview/

Test a definition before saving. Returns matched user count and a sample of matching user IDs.

bash
curl -X POST https://api.segops.ai/api/segments/preview/ \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "definition": {
      "logic": "AND",
      "conditions": [...]
    },
    "limit": 10
  }'
json
{
  "matched_users": 3482,
  "sample_user_ids": ["u-001", "u-002"],
  "sql": "SELECT user_id FROM events WHERE ..."
}

Compute Membership#

POST /api/segments/<id>/compute/

bash
curl -X POST https://api.segops.ai/api/segments/7/compute/ \
  -H "Authorization: Bearer $JWT"

# Response: { "status": "queued" }

Delivery API#

Per-user membership check

GET /api/segments/membership/?user_id=user-123

bash
curl "https://api.segops.ai/api/segments/membership/?user_id=user-123" \
  -H "Authorization: ApiKey $API_KEY"
json
{
  "user_id": "user-123",
  "segment_ids": [4, 7, 12],
  "cached": true
}

Paginated member list

GET /api/segments/<id>/members/

bash
curl "https://api.segops.ai/api/segments/7/members/?limit=1000" \
  -H "Authorization: Bearer $JWT"
json
{
  "results": [
    { "user_id": "user-001", "computed_at": "2026-04-25T12:00:00Z" }
  ],
  "next_cursor": "dXNlci0wMDM=",
  "count": 3482
}

Bulk export

bash
# Start export
curl -X POST https://api.segops.ai/api/segments/7/export/ \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{ "format": "parquet" }'

# Poll
curl "https://api.segops.ai/api/segments/7/export/?export_id=14" \
  -H "Authorization: Bearer $JWT"

# Download
curl -L https://api.segops.ai/api/segments/exports/14/download/ \
  -H "Authorization: Bearer $JWT" \
  -o members.parquet

Version History#

GET /api/segments/<id>/versions/

bash
curl https://api.segops.ai/api/segments/7/versions/ \
  -H "Authorization: Bearer $JWT"