Skip to content
WaaruDocs

Static segments

Create static segments, inspect their members and add or remove workspace contacts through the public API.

Reviewed

Only active static segments are exposed here. Contacts and segments are shared workspace data. Dynamic audience rules are managed in the dashboard.

Create and maintain membership

Create a segment with a trimmed name of 1 to 80 characters and optional trimmed description of at most 200 characters. The JSON body limit is 4 KiB. Creation returns HTTP 200, not 201. Creation has no idempotency key; if the response is lost, list and reconcile before submitting again.

PUT and DELETE membership routes take the segment and contact identifiers in the path and no body. They return HTTP 200 with changed and the resulting memberCount. changed: false is a successful desired-state result when membership already matches. Only active contacts in the same workspace may be added. Membership does not override opt-out or grant permission to send.

Page through members

Use limit from 1 to 100 (default 50) and the returned nextCursor as after. Lists sort by ID and are live, not snapshots. Membership rows return membership id, contactId and addedAt; fetch a contact separately when you need its profile.

With workspace:segments:manage, PATCH changes a name or description using the same 80/200 character bounds as creation. POST to /archive accepts {} and preserves membership records. Repeat archive is safe. Active or pinned dynamic segment dependencies return 409 resource_in_use. Archived segments leave active lists and cannot accept membership changes. Deletion, restoration and dynamic rule authoring remain unavailable through public keys.

Endpoint details

Every request uses Authorization: Bearer $WAARU_API_KEY and a connected number in Developer API mode. The scope below is required. IDs and payloads are illustrative; replace them with your own permitted resources. See authentication and common errors, size limits and retries.

PATCH /v1/developer/segments/{id}

Required scope: workspace:segments:manage

Requires workspace:segments:manage. Body limit: 4096 bytes. Requires an explicitly granted management scope. Archive preserves historical assignments and membership, reserves the name, and rejects active or pinned dynamic-segment dependencies. Repeat archive is safe; creation has no idempotency key.

Request parameters
ParameterLocationRequiredConstraints
idpathYes{"type":"string","minLength":1,"maxLength":191}

Request

curl --fail-with-body --request PATCH 'https://api.waaru.app/v1/developer/segments/id_example' \
  --header "Authorization: Bearer $WAARU_API_KEY" \
  --header 'Content-Type: application/json' \
  --data-binary @request.json

Save this illustrative JSON as request.json. The body is required.

{
  "name": "Returning customers"
}
Request body fields
FieldRequiredType and constraints
nameNo{"type":"string","minLength":1,"maxLength":80}
descriptionNo{"type":"string","maxLength":200}
Request body: complete JSON schema

Required fields appear in required. Omit optional fields unless needed. Null is accepted only where the schema includes it. Arrays describe their elements in items; variants appear in anyOf or oneOf.

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 80
    },
    "description": {
      "type": "string",
      "maxLength": 200
    }
  },
  "required": [],
  "additionalProperties": false,
  "minProperties": 1
}

Response: HTTP 200

{
  "segment": {
    "id": "segment_example",
    "name": "Returning customers",
    "description": null,
    "memberCount": 0,
    "updatedAt": "2026-10-04T00:00:00.000Z",
    "archivedAt": null
  }
}
Response body fields
FieldRequiredType and constraints
segmentYes{"type":"object","required":["id","name","description","memberCount","updatedAt","archivedAt"],"additionalProperties":false} Nested fields are in the complete schema below.
Response body: complete JSON schema

Required fields appear in required. Omit optional fields unless needed. Null is accepted only where the schema includes it. Arrays describe their elements in items; variants appear in anyOf or oneOf.

{
  "type": "object",
  "properties": {
    "segment": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "minLength": 1,
          "maxLength": 191
        },
        "name": {
          "type": "string"
        },
        "description": {
          "type": [
            "string",
            "null"
          ]
        },
        "memberCount": {
          "type": "integer"
        },
        "updatedAt": {
          "type": "string",
          "format": "date-time"
        },
        "archivedAt": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        }
      },
      "required": [
        "id",
        "name",
        "description",
        "memberCount",
        "updatedAt",
        "archivedAt"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "segment"
  ],
  "additionalProperties": false
}

Failures use a stable code and safe message. They never expose internal exception messages, traces or provider diagnostics. Check the error reference before retrying. An inaccessible resource can return 404 even if its identifier exists elsewhere.

GET /v1/developer/segments/{id}

Required scope: workspace:segments:read

Requires workspace:segments:read.

Request parameters
ParameterLocationRequiredConstraints
idpathYes{"type":"string","minLength":1,"maxLength":191}

Request

curl --fail-with-body --request GET 'https://api.waaru.app/v1/developer/segments/id_example' \
  --header "Authorization: Bearer $WAARU_API_KEY"

Send no request body.

Response: HTTP 200

{
  "segment": {
    "id": "segment_example",
    "name": "Workshop attendees",
    "description": null,
    "memberCount": 1,
    "updatedAt": "2026-10-01T09:00:00.000Z"
  }
}
Response body fields
FieldRequiredType and constraints
segmentYes{"type":"object","required":["id","name","description","memberCount","updatedAt"],"additionalProperties":false} Nested fields are in the complete schema below.
Response body: complete JSON schema

Required fields appear in required. Omit optional fields unless needed. Null is accepted only where the schema includes it. Arrays describe their elements in items; variants appear in anyOf or oneOf.

{
  "type": "object",
  "properties": {
    "segment": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "minLength": 1,
          "maxLength": 191
        },
        "name": {
          "type": "string"
        },
        "description": {
          "type": [
            "string",
            "null"
          ]
        },
        "memberCount": {
          "type": "integer",
          "minimum": 0
        },
        "updatedAt": {
          "type": "string",
          "format": "date-time"
        }
      },
      "required": [
        "id",
        "name",
        "description",
        "memberCount",
        "updatedAt"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "segment"
  ],
  "additionalProperties": false
}

Failures use a stable code and safe message. They never expose internal exception messages, traces or provider diagnostics. Check the error reference before retrying. An inaccessible resource can return 404 even if its identifier exists elsewhere.

POST /v1/developer/segments/{id}/archive

Required scope: workspace:segments:manage

Requires workspace:segments:manage. Body limit: 4096 bytes. Requires an explicitly granted management scope. Archive preserves historical assignments and membership, reserves the name, and rejects active or pinned dynamic-segment dependencies. Repeat archive is safe; creation has no idempotency key.

Request parameters
ParameterLocationRequiredConstraints
idpathYes{"type":"string","minLength":1,"maxLength":191}

Request

curl --fail-with-body --request POST 'https://api.waaru.app/v1/developer/segments/id_example/archive' \
  --header "Authorization: Bearer $WAARU_API_KEY" \
  --header 'Content-Type: application/json' \
  --data-binary @request.json

Save this illustrative JSON as request.json. The body is required.

{}
Request body fields
FieldRequiredType and constraints
Request body: complete JSON schema

Required fields appear in required. Omit optional fields unless needed. Null is accepted only where the schema includes it. Arrays describe their elements in items; variants appear in anyOf or oneOf.

{
  "type": "object",
  "properties": {},
  "required": [],
  "additionalProperties": false
}

Response: HTTP 200

{
  "segment": {
    "id": "segment_example",
    "name": "Returning customers",
    "description": null,
    "memberCount": 0,
    "updatedAt": "2026-10-04T00:00:00.000Z",
    "archivedAt": "2026-10-04T00:00:00.000Z"
  }
}
Response body fields
FieldRequiredType and constraints
segmentYes{"type":"object","required":["id","name","description","memberCount","updatedAt","archivedAt"],"additionalProperties":false} Nested fields are in the complete schema below.
Response body: complete JSON schema

Required fields appear in required. Omit optional fields unless needed. Null is accepted only where the schema includes it. Arrays describe their elements in items; variants appear in anyOf or oneOf.

{
  "type": "object",
  "properties": {
    "segment": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "minLength": 1,
          "maxLength": 191
        },
        "name": {
          "type": "string"
        },
        "description": {
          "type": [
            "string",
            "null"
          ]
        },
        "memberCount": {
          "type": "integer"
        },
        "updatedAt": {
          "type": "string",
          "format": "date-time"
        },
        "archivedAt": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        }
      },
      "required": [
        "id",
        "name",
        "description",
        "memberCount",
        "updatedAt",
        "archivedAt"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "segment"
  ],
  "additionalProperties": false
}

Failures use a stable code and safe message. They never expose internal exception messages, traces or provider diagnostics. Check the error reference before retrying. An inaccessible resource can return 404 even if its identifier exists elsewhere.

GET /v1/developer/segments

Required scope: workspace:segments:read

Requires workspace:segments:read.

Request parameters
ParameterLocationRequiredConstraints
limitqueryNo{"type":"integer","minimum":1,"maximum":100,"default":50}
afterqueryNo{"type":"string","maxLength":512} Use nextCursor from the previous response; keep filters unchanged.

Request

curl --fail-with-body --request GET 'https://api.waaru.app/v1/developer/segments' \
  --header "Authorization: Bearer $WAARU_API_KEY"

Send no request body.

Response: HTTP 200

{
  "items": [
    {
      "id": "segment_example",
      "name": "Workshop attendees",
      "description": null,
      "memberCount": 1,
      "updatedAt": "2026-10-01T09:00:00.000Z"
    }
  ],
  "nextCursor": null
}
Response body fields
FieldRequiredType and constraints
itemsYes{"type":"array","maxItems":100} Nested fields are in the complete schema below.
nextCursorYes{"type":["string","null"]}
Response body: complete JSON schema

Required fields appear in required. Omit optional fields unless needed. Null is accepted only where the schema includes it. Arrays describe their elements in items; variants appear in anyOf or oneOf.

{
  "type": "object",
  "properties": {
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 191
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "memberCount": {
            "type": "integer",
            "minimum": 0
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "name",
          "description",
          "memberCount",
          "updatedAt"
        ],
        "additionalProperties": false
      },
      "maxItems": 100
    },
    "nextCursor": {
      "type": [
        "string",
        "null"
      ]
    }
  },
  "required": [
    "items",
    "nextCursor"
  ],
  "additionalProperties": false
}

Failures use a stable code and safe message. They never expose internal exception messages, traces or provider diagnostics. Check the error reference before retrying. An inaccessible resource can return 404 even if its identifier exists elsewhere.

POST /v1/developer/segments

Required scope: workspace:segments:write

Requires workspace:segments:write.

No path or query parameters.

Request

curl --fail-with-body --request POST 'https://api.waaru.app/v1/developer/segments' \
  --header "Authorization: Bearer $WAARU_API_KEY" \
  --header 'Content-Type: application/json' \
  --data-binary @request.json

Save this illustrative JSON as request.json. The body is required.

{
  "name": "Workshop attendees"
}
Request body fields
FieldRequiredType and constraints
nameYes{"type":"string","minLength":1,"maxLength":80}
descriptionNo{"type":"string","maxLength":200}
Request body: complete JSON schema

Required fields appear in required. Omit optional fields unless needed. Null is accepted only where the schema includes it. Arrays describe their elements in items; variants appear in anyOf or oneOf.

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 80
    },
    "description": {
      "type": "string",
      "maxLength": 200
    }
  },
  "required": [
    "name"
  ],
  "additionalProperties": false
}

Response: HTTP 200

{
  "segment": {
    "id": "segment_example",
    "name": "Workshop attendees",
    "description": null,
    "memberCount": 0,
    "updatedAt": "2026-10-01T09:00:00.000Z"
  }
}
Response body fields
FieldRequiredType and constraints
segmentYes{"type":"object","required":["id","name","description","memberCount","updatedAt"],"additionalProperties":false} Nested fields are in the complete schema below.
Response body: complete JSON schema

Required fields appear in required. Omit optional fields unless needed. Null is accepted only where the schema includes it. Arrays describe their elements in items; variants appear in anyOf or oneOf.

{
  "type": "object",
  "properties": {
    "segment": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "minLength": 1,
          "maxLength": 191
        },
        "name": {
          "type": "string"
        },
        "description": {
          "type": [
            "string",
            "null"
          ]
        },
        "memberCount": {
          "type": "integer",
          "minimum": 0
        },
        "updatedAt": {
          "type": "string",
          "format": "date-time"
        }
      },
      "required": [
        "id",
        "name",
        "description",
        "memberCount",
        "updatedAt"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "segment"
  ],
  "additionalProperties": false
}

Failures use a stable code and safe message. They never expose internal exception messages, traces or provider diagnostics. Check the error reference before retrying. An inaccessible resource can return 404 even if its identifier exists elsewhere.

GET /v1/developer/segments/{id}/members

Required scope: workspace:segments:read

Requires workspace:segments:read.

Request parameters
ParameterLocationRequiredConstraints
idpathYes{"type":"string","minLength":1,"maxLength":191}
limitqueryNo{"type":"integer","minimum":1,"maximum":100,"default":50}
afterqueryNo{"type":"string","maxLength":512} Use nextCursor from the previous response; keep filters unchanged.

Request

curl --fail-with-body --request GET 'https://api.waaru.app/v1/developer/segments/id_example/members' \
  --header "Authorization: Bearer $WAARU_API_KEY"

Send no request body.

Response: HTTP 200

{
  "items": [
    {
      "id": "membership_example",
      "contactId": "contact_example",
      "addedAt": "2026-10-01T09:00:00.000Z"
    }
  ],
  "nextCursor": null
}
Response body fields
FieldRequiredType and constraints
itemsYes{"type":"array","maxItems":100} Nested fields are in the complete schema below.
nextCursorYes{"type":["string","null"]}
Response body: complete JSON schema

Required fields appear in required. Omit optional fields unless needed. Null is accepted only where the schema includes it. Arrays describe their elements in items; variants appear in anyOf or oneOf.

{
  "type": "object",
  "properties": {
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 191
          },
          "contactId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 191
          },
          "addedAt": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "contactId",
          "addedAt"
        ],
        "additionalProperties": false
      },
      "maxItems": 100
    },
    "nextCursor": {
      "type": [
        "string",
        "null"
      ]
    }
  },
  "required": [
    "items",
    "nextCursor"
  ],
  "additionalProperties": false
}

Failures use a stable code and safe message. They never expose internal exception messages, traces or provider diagnostics. Check the error reference before retrying. An inaccessible resource can return 404 even if its identifier exists elsewhere.

PUT /v1/developer/segments/{id}/members/{contactId}

Required scope: workspace:segments:write

Requires workspace:segments:write.

Request parameters
ParameterLocationRequiredConstraints
idpathYes{"type":"string","minLength":1,"maxLength":191}
contactIdpathYes{"type":"string","minLength":1,"maxLength":191}

Request

curl --fail-with-body --request PUT 'https://api.waaru.app/v1/developer/segments/id_example/members/contactId_example' \
  --header "Authorization: Bearer $WAARU_API_KEY"

Send no request body.

Response: HTTP 200

{
  "segmentId": "segment_example",
  "contactId": "contact_example",
  "changed": true,
  "memberCount": 1
}
Response body fields
FieldRequiredType and constraints
segmentIdYes{"type":"string","minLength":1,"maxLength":191}
contactIdYes{"type":"string","minLength":1,"maxLength":191}
changedYes{"type":"boolean"}
memberCountYes{"type":"integer","minimum":0}
Response body: complete JSON schema

Required fields appear in required. Omit optional fields unless needed. Null is accepted only where the schema includes it. Arrays describe their elements in items; variants appear in anyOf or oneOf.

{
  "type": "object",
  "properties": {
    "segmentId": {
      "type": "string",
      "minLength": 1,
      "maxLength": 191
    },
    "contactId": {
      "type": "string",
      "minLength": 1,
      "maxLength": 191
    },
    "changed": {
      "type": "boolean"
    },
    "memberCount": {
      "type": "integer",
      "minimum": 0
    }
  },
  "required": [
    "segmentId",
    "contactId",
    "changed",
    "memberCount"
  ],
  "additionalProperties": false
}

Failures use a stable code and safe message. They never expose internal exception messages, traces or provider diagnostics. Check the error reference before retrying. An inaccessible resource can return 404 even if its identifier exists elsewhere.

DELETE /v1/developer/segments/{id}/members/{contactId}

Required scope: workspace:segments:write

Requires workspace:segments:write.

Request parameters
ParameterLocationRequiredConstraints
idpathYes{"type":"string","minLength":1,"maxLength":191}
contactIdpathYes{"type":"string","minLength":1,"maxLength":191}

Request

curl --fail-with-body --request DELETE 'https://api.waaru.app/v1/developer/segments/id_example/members/contactId_example' \
  --header "Authorization: Bearer $WAARU_API_KEY"

Send no request body.

Response: HTTP 200

{
  "segmentId": "segment_example",
  "contactId": "contact_example",
  "changed": true,
  "memberCount": 0
}
Response body fields
FieldRequiredType and constraints
segmentIdYes{"type":"string","minLength":1,"maxLength":191}
contactIdYes{"type":"string","minLength":1,"maxLength":191}
changedYes{"type":"boolean"}
memberCountYes{"type":"integer","minimum":0}
Response body: complete JSON schema

Required fields appear in required. Omit optional fields unless needed. Null is accepted only where the schema includes it. Arrays describe their elements in items; variants appear in anyOf or oneOf.

{
  "type": "object",
  "properties": {
    "segmentId": {
      "type": "string",
      "minLength": 1,
      "maxLength": 191
    },
    "contactId": {
      "type": "string",
      "minLength": 1,
      "maxLength": 191
    },
    "changed": {
      "type": "boolean"
    },
    "memberCount": {
      "type": "integer",
      "minimum": 0
    }
  },
  "required": [
    "segmentId",
    "contactId",
    "changed",
    "memberCount"
  ],
  "additionalProperties": false
}

Failures use a stable code and safe message. They never expose internal exception messages, traces or provider diagnostics. Check the error reference before retrying. An inaccessible resource can return 404 even if its identifier exists elsewhere.

Next: All public API operations or authentication and scopes.

Contacts and labels

Read shared workspace contacts, upsert and update profiles, and apply existing labels with scoped API requests.

Template discovery

Read cached template lifecycle state and available Flow launch descriptors, then construct eligible template sends without exposing provider tokens.

On this page

Create and maintain membershipPage through membersEndpoint details