Segments API
This page is written for AI agents. People ask their agent to do the work; see How it fits together.
Full parity with the UI. Segments are addressed by key, not by database id, so a definitions file can name one without knowing anything about your database.
Every endpoint needs a bearer token from Settings → Agents & API.
Endpoints
| Method | Path | What it does |
|---|---|---|
| GET | /api/v1/segments |
Every segment with its live count |
| POST | /api/v1/segments |
Create one |
| GET | /api/v1/segments/:key |
One segment, with rules and where it's used |
| PATCH | /api/v1/segments/:key |
Update it |
| DELETE | /api/v1/segments/:key |
Delete it |
| GET | /api/v1/segments/:key/count |
Just the number |
| GET | /api/v1/segments/:key/members |
The people, paginated |
| POST | /api/v1/segments/preview |
Check and count rules without saving them |
Count and members are separate on purpose. Asking "how many?" shouldn't make you pay for the list, and asking for the list shouldn't hand you forty thousand rows in one response. members is paginated, capped at 500 per page.
Creating a segment
curl -X POST https://your-mimeo.com/api/v1/segments \
-H "Authorization: Bearer $MIMEO_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Engaged customers",
"description": "Bought something and opened recent mail.",
"rules": {
"type": "all",
"conditions": [
{ "type": "total_spend", "op": "greater", "value": 0 },
{ "type": "opened_email", "email_id": 12, "within_days": 60 },
{ "type": "not", "condition": { "type": "suppressed" } }
]
}
}'
The key is derived from the name (engaged_customers) unless you supply one.
Checking rules before you commit to them
preview validates and counts a rule set without creating anything — the API's answer to the editor's live count, and what a definitions-repo diff should call before applying a change.
curl -X POST https://your-mimeo.com/api/v1/segments/preview \
-H "Authorization: Bearer $MIMEO_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "rules": { "type": "has_tag", "tag": "customer" } }'
{
"count": 412,
"total": 5310,
"exact": true,
"expensive": false,
"validation": { "valid": true, "errors": [], "warnings": [] }
}
exact— the whole rule set resolved in SQL.expensive— it needs a query per candidate person (a code predicate, or an event matched on its details).
Errors name the fix
Invalid rules come back as 422 with messages written to be acted on rather than just reported:
{
"errors": [
"This rule tests field \"plan_tier\", which is not a defined field. Create it under People → Fields first."
],
"validation": { "valid": false, "errors": [ … ] }
}
Deleting a segment something still references is refused, with used_by listing what would break.
The rule vocabulary
The same condition types flows and guards use — see the schema reference for the full list. Segments add total_spend. within_days works on event_occurred, received_email, opened_email, clicked_email, started_sequence and finished_sequence: leave it out to mean ever, or set a whole number of days, 1 or more, to mean in the last N days. Anything else is refused with condition_within_days_invalid — see the schema reference.
email compares the person's email address, ignoring case, with equals, starts_with, ends_with or contains — so "everyone at acme.com" is { "type": "email", "op": "ends_with", "value": "@acme.com" }.
in_segment takes a segment key. A reference loop is rejected on save.
subscribed_on compares the date a person joined the list against a value like "2026-06-01", using less (before), greater (after) or equals (on). Both comparisons are strict. Everyone has the date, so this is a single condition with no null case to wrap:
{ "type": "all", "conditions": [
{ "type": "subscribed_on", "op": "less", "value": "2026-06-01" },
{ "type": "not", "condition": { "type": "suppressed" } }
] }