Create a segment

POST/v1/segments

Secret key — sk_… or sk_test_… · Base URL https://api.volanea.com

Dynamic segments require conditions and are computed immediately; static segments start empty and are managed via the members endpoints.

Pass dryRun: true to preview instead of create — identical to POST /v1/segments/preview, and name is not required. The alias exists because the MCP create_segment tool takes dryRun and tells agents to run one first: until this was honoured, carrying that parameter into the REST call created a live segment on every "preview", and deleting it afterwards did not undo the segment.entered activity it had already written onto contacts.

Body

Required · application/json

namestring
Required unless `dryRun` is true.
descriptionstring
typeenum
dynamicstatic
conditionsobject
Nested condition tree evaluated against contacts, their custom `data`, and their activity.
- logicenumrequired
  andor
- groupsobject[]required
  - filtersobject[]required
dryRunboolean
Preview only — nothing is created. Returns the same shape as `POST /v1/segments/preview`.

Response

Preview, when `dryRun` is true.

dryRunenumrequired
true
segmentIdnull
Always null — a dry run creates nothing.
countintegerrequired
sampleobject[]
- contactIdstringrequired
- projectIdstring
- emailemailrequired
- firstNamestring | null
- lastNamestring | null
- subscribedbooleanrequired
- dataobject | null
  Arbitrary custom fields.
- localestring | null
- createdAtdate-timerequired
- updatedAtdate-timerequired

Errors

Every failure returns the standard envelope — branch on `code`, never on the wording of `error`.

401Missing or invalid API key.
422Request validation failed (code `validation_error`, 422).

Request

curl https://api.volanea.com/v1/segments \
  -X POST \
  -H "Authorization: Bearer sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Welcome",
    "description": "What this is for",
    "type": "dynamic"
  }'

Response

200 · application/json

{
  "success": true,
  "data": {
    "dryRun": true,
    "segmentId": "seg_4a71",
    "count": 1,
    "sample": [
      {
        "contactId": "con_5e90",
        "projectId": "<projectId>",
        "email": "ada@example.com",
        "firstName": "Ada",
        "lastName": "Lovelace",
        "subscribed": true,
        "data": {},
        "locale": "en",
        "createdAt": "2026-01-01T09:00:00.000Z",
        "updatedAt": "2026-01-01T09:00:00.000Z"
      }
    ]
  }
}

92 endpoints · OpenAPI document