Amba

Segments

CRUD for rule-based user segments and on-demand re-evaluation.

Segments are JSON rule trees evaluated against user profile properties and the engagement-event stream. They're re-evaluated within 15 minutes of a change to user data, and on the clock for within / not_within rules (cadence); the /evaluate endpoint triggers an immediate out-of-band re-evaluation.

Endpoints

MethodPathDescription
POST/admin/projects/:projectId/segmentsCreate a segment.
GET/admin/projects/:projectId/segmentsList segments (system segments first).
GET/admin/projects/:projectId/segments/:segmentIdFetch a segment.
PATCH/admin/projects/:projectId/segments/:segmentIdUpdate a non-system segment.
DELETE/admin/projects/:projectId/segments/:segmentIdDelete a non-system segment.
POST/admin/projects/:projectId/segments/:segmentId/evaluateKick off an out-of-band re-evaluation.
GET/admin/projects/:projectId/segments/historyDefinition changes, whole project.
GET/admin/projects/:projectId/segments/:segmentId/historyDefinition changes for one segment.

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, in (an array of up to 100 values). An unknown operator answers 400 INVALID_SEGMENT_RULES.

Built-in device fields, reported by the SDKs for signed-in users: platform, os, app_version and country. See Built-in device fields for their operators and values.

POST /admin/projects/:projectId/segments

Request

FieldTypeRequired
namestringyes
descriptionstringno
rulesSegmentRules objectyes

Response 201

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

Errors

  • 400 INVALID_SEGMENT_RULES — rules is missing or malformed.
  • 400 SEGMENT_RULES_TOO_DEEP — rules nests deeper than the supported cap (5 levels).
  • 500 CREATE_FAILED.

rules is a recursive shape: each group has operator (AND / OR) and a conditions array, where each entry is either a leaf ({ field, op, value }) or a nested group. See Segment operators → Composing rules for the full reference.

Try it:

POST/admin/projects/%7B%7BprojectId%7D%7D/segments
developer auth
curl -X POST 'https://api.amba.dev/v1/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/${PROJECT_ID}/segments" \
  -H "Authorization: Bearer ${DEV_TOKEN}" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "ios_paid",
    "rules": {
      "operator": "AND",
      "conditions": [
        { "field": "properties.platform", "op": "eq", "value": "ios" },
        {
          "operator": "OR",
          "conditions": [
            { "field": "properties.plan", "op": "eq", "value": "pro" },
            { "field": "properties.plan", "op": "eq", "value": "enterprise" }
          ]
        }
      ]
    }
  }'

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/v1/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/${PROJECT_ID}/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/v1/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/${PROJECT_ID}/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/v1/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/${PROJECT_ID}/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.
  • 409 SEGMENT_IN_USE — a store targets this segment; details.stores lists them. Deleting the segment would open those stores to every user, so detach it first (PATCH the store with segment_id: null or another segment) or delete the stores.
  • 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/v1/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/${PROJECT_ID}/segments/{segmentId}" \
  -H "Authorization: Bearer ${DEV_TOKEN}"

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

Start a SEGMENT_EVALUATION 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/v1/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/${PROJECT_ID}/segments/{segmentId}/evaluate" \
  -H "Authorization: Bearer ${DEV_TOKEN}" \
  -H 'Content-Type: application/json' \
  -d '{}'

GET /admin/projects/:projectId/segments/history

Every segment definition change in the project, newest first. Create, update and delete each record one entry in the same transaction as the write; an update that changes nothing records none. Evaluation (membership changes) records nothing.

Query

ParamTypeDescription
limitinteger1-200, default 50.
beforestringThe id of the last entry from the previous page, for older ones.

Response 200

{
  "data": [
    {
      "id": "…",
      "segment_id": "…",
      "action": "update",
      "actor_kind": "pat",
      "actor_id": "…",
      "before": {
        "name": "Beta",
        "description": null,
        "rules": { "operator": "AND", "conditions": [] },
        "is_system": false
      },
      "after": {
        "name": "Beta",
        "description": "Opted in",
        "rules": { "operator": "AND", "conditions": [] },
        "is_system": false
      },
      "created_at": "…"
    }
  ]
}

actor_kind is pat (a developer), server_key or operator, with the matching id in actor_id.

Errors

  • 400 INVALID_INPUT — limit outside 1-200, or before is not a change id.
  • 500 HISTORY_FAILED.

Try it:

GET/admin/projects/%7B%7BprojectId%7D%7D/segments/history
developer auth
curl -X GET 'https://api.amba.dev/v1/admin/projects/%7B%7BprojectId%7D%7D/segments/history'
Loading auth… Configure auth in the settings drawer (top-right) to run this request.

Curl:

curl -X GET "${BASE_URL}/admin/projects/${PROJECT_ID}/segments/history" \
  -H "Authorization: Bearer ${DEV_TOKEN}"

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

The changes to one segment, newest first, with the same shape and paging. A deleted segment keeps its history.

Errors

  • 400 INVALID_SEGMENT_ID — segmentId is not a UUID.
  • 400 INVALID_INPUT.
  • 500 HISTORY_FAILED.

Try it:

GET/admin/projects/%7B%7BprojectId%7D%7D/segments/%7B%7BsegmentId%7D%7D/history
developer auth
curl -X GET 'https://api.amba.dev/v1/admin/projects/%7B%7BprojectId%7D%7D/segments/%7B%7BsegmentId%7D%7D/history'
Loading auth… Configure auth in the settings drawer (top-right) to run this request.

Curl:

curl -X GET "${BASE_URL}/admin/projects/${PROJECT_ID}/segments/{segmentId}/history" \
  -H "Authorization: Bearer ${DEV_TOKEN}"