Segments

Segments are JSON rule trees applied against app_users + engagement_events. They're re-evaluated by a Temporal cron workflow every 15 minutes; the /evaluate endpoint triggers an immediate out-of-band re-evaluation.

Source: apps/api/src/routes/admin/segments.ts. Shared rule types: packages/shared/src/segment-rules.ts.

Endpoints

Method	Path	Description
POST	`/admin/projects/:projectId/segments`	Create a segment.
GET	`/admin/projects/:projectId/segments`	List segments (system segments first).
GET	`/admin/projects/:projectId/segments/:segmentId`	Fetch a segment.
PATCH	`/admin/projects/:projectId/segments/:segmentId`	Update a non-system segment.
DELETE	`/admin/projects/:projectId/segments/:segmentId`	Delete a non-system segment.
POST	`/admin/projects/:projectId/segments/:segmentId/evaluate`	Kick off an out-of-band re-evaluation.

Rule shape

{
  "operator": "AND",
  "conditions": [
    { "field": "last_seen_at", "op": "gte", "value": "2025-01-01T00:00:00Z" },
    { "field": "properties.plan", "op": "eq", "value": "pro" }
  ]
}

Operators: eq, neq, gt, gte, lt, lte, contains, not_contains, exists, not_exists, within, not_within.

POST /admin/projects/:projectId/segments

Request

Field	Type	Required
`name`	string	yes
`description`	string	no
`rules`	`SegmentRules` object	yes

Response 201

{
  "data": {
    "id": "…",
    "name": "…",
    "rules": {},
    "is_system": false,
    "user_count": 0,
    "last_evaluated_at": null,
    "created_at": "…"
  }
}

Errors

500 CREATE_FAILED.

Try it:

POST/admin/projects/%7B%7BprojectId%7D%7D/segments

developer auth

curl -X POST 'https://api.amba.dev/admin/projects/%7B%7BprojectId%7D%7D/segments'

Loading auth… Configure auth in the settings drawer (top-right) to run this request.

Curl:

curl -X POST '${BASE_URL}/admin/projects/{projectId}/segments' \
  -H 'Authorization: Bearer ${DEV_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{}'

GET /admin/projects/:projectId/segments

List segments. System segments (created by provisioning) are returned first.

Response 200

{ "data": [ { "id": "…", "name": "active_7d", "is_system": true, "user_count": 1234 }, … ] }

Try it:

GET/admin/projects/%7B%7BprojectId%7D%7D/segments

developer auth

curl -X GET 'https://api.amba.dev/admin/projects/%7B%7BprojectId%7D%7D/segments'

Loading auth… Configure auth in the settings drawer (top-right) to run this request.

Curl:

curl -X GET '${BASE_URL}/admin/projects/{projectId}/segments' \
  -H 'Authorization: Bearer ${DEV_TOKEN}'

GET /admin/projects/:projectId/segments/:segmentId

Response 200

{ "data": { "id": "…", "name": "…", "rules": {}, "user_count": 0, "last_evaluated_at": "…" } }

Errors

404 NOT_FOUND.

Try it:

GET/admin/projects/%7B%7BprojectId%7D%7D/segments/%7B%7BsegmentId%7D%7D

developer auth

curl -X GET 'https://api.amba.dev/admin/projects/%7B%7BprojectId%7D%7D/segments/%7B%7BsegmentId%7D%7D'

Loading auth… Configure auth in the settings drawer (top-right) to run this request.

Curl:

curl -X GET '${BASE_URL}/admin/projects/{projectId}/segments/{segmentId}' \
  -H 'Authorization: Bearer ${DEV_TOKEN}'

PATCH /admin/projects/:projectId/segments/:segmentId

Update name, description, and/or rules. Only keys present in the body are changed — a PATCH never nulls out omitted keys.

Errors

403 SYSTEM_SEGMENT — system segments are read-only.
404 NOT_FOUND.
500 UPDATE_FAILED.

Try it:

PATCH/admin/projects/%7B%7BprojectId%7D%7D/segments/%7B%7BsegmentId%7D%7D

developer auth

curl -X PATCH 'https://api.amba.dev/admin/projects/%7B%7BprojectId%7D%7D/segments/%7B%7BsegmentId%7D%7D'

Loading auth… Configure auth in the settings drawer (top-right) to run this request.

Curl:

curl -X PATCH '${BASE_URL}/admin/projects/{projectId}/segments/{segmentId}' \
  -H 'Authorization: Bearer ${DEV_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{}'

DELETE /admin/projects/:projectId/segments/:segmentId

Response 200

{ "data": { "deleted": true } }

Errors

403 SYSTEM_SEGMENT.
500 DELETE_FAILED.

Try it:

DELETE/admin/projects/%7B%7BprojectId%7D%7D/segments/%7B%7BsegmentId%7D%7D

developer auth

curl -X DELETE 'https://api.amba.dev/admin/projects/%7B%7BprojectId%7D%7D/segments/%7B%7BsegmentId%7D%7D'

Loading auth… Configure auth in the settings drawer (top-right) to run this request.

Curl:

curl -X DELETE '${BASE_URL}/admin/projects/{projectId}/segments/{segmentId}' \
  -H 'Authorization: Bearer ${DEV_TOKEN}'

POST /admin/projects/:projectId/segments/:segmentId/evaluate

Start a SEGMENT_EVALUATION Temporal workflow for a single segment. Returns immediately — poll the segment row to see last_evaluated_at advance.

Response 200

{ "data": { "status": "evaluating", "segment_id": "…" } }

Errors

404 NOT_FOUND.
500 EVALUATE_FAILED.

Try it:

POST/admin/projects/%7B%7BprojectId%7D%7D/segments/%7B%7BsegmentId%7D%7D/evaluate

developer auth

curl -X POST 'https://api.amba.dev/admin/projects/%7B%7BprojectId%7D%7D/segments/%7B%7BsegmentId%7D%7D/evaluate'

Loading auth… Configure auth in the settings drawer (top-right) to run this request.

Curl:

curl -X POST '${BASE_URL}/admin/projects/{projectId}/segments/{segmentId}/evaluate' \
  -H 'Authorization: Bearer ${DEV_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{}'

On this page