Boom Ai Segments API
The Segments API from Boom Ai — 7 operation(s) for segments.
OpenAPI Specification
openapi: 3.1.0
info:
title: Boom CDP Custom Objects Segments API
version: 1.0.0
description: 'Boom''s public REST API — one uniform surface over every platform capability. CDP: upsert people and custom objects, define object and relationship types, link and unlink relationships, and record behavioral events — one record per request or up to 1000 per request via the `/batch` endpoints. Segments: read (list, read, membership) and full authoring — discover the filterable catalog, validate a filter, create and update segments, preview match counts, and trigger evaluation. Initiatives: create and configure outreach initiatives, link WhatsApp templates, drive the lifecycle (launch, cancel, archive), and read collected-data summaries. Participants: enroll people into an active initiative, track their status, read conversation transcripts, and stop outreach. Journeys: read-only access to always-on message flows and their metrics. WhatsApp templates: list your WhatsApp numbers and list, read, and create message templates. The same capabilities are exposed as MCP tools with identical schemas.'
servers:
- url: https://www.useboom.ai
description: Production
- url: https://dev.useboom.ai
description: Development (sandbox — use a development organization API key)
security:
- bearerAuth: []
tags:
- name: Segments
paths:
/api/v1/segments:
get:
operationId: segments_list
summary: List segments
description: List the organization's active segments, newest first. Archived segments are excluded.
tags:
- Segments
parameters:
- name: limit
in: query
required: false
schema:
$schema: https://json-schema.org/draft/2020-12/schema
default: 100
description: Max items to return, 1-1000 (default 100).
type: integer
minimum: 1
maximum: 1000
- name: cursor
in: query
required: false
schema:
$schema: https://json-schema.org/draft/2020-12/schema
description: Opaque pagination token from a previous response's `next_cursor`. Omit for the first page.
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$schema: https://json-schema.org/draft/2020-12/schema
type: object
properties:
data:
type: array
items:
type: object
properties:
slug:
type: string
description: Unique identifier within your organization.
name:
type: string
description:
anyOf:
- type: string
- type: 'null'
evaluationCadence:
type: string
enum:
- REACTIVE_ONLY
- HOURLY
- DAILY
description: How often the segment is re-evaluated. REACTIVE_ONLY segments only change when evaluated explicitly.
memberCount:
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
description: Live count of currently active members.
lastEvaluatedAt:
anyOf:
- type: string
- type: 'null'
description: ISO 8601 timestamp; null if the segment has never evaluated.
createdAt:
type: string
description: ISO 8601 timestamp.
required:
- slug
- name
- description
- evaluationCadence
- memberCount
- lastEvaluatedAt
- createdAt
additionalProperties: false
next_cursor:
anyOf:
- type: string
- type: 'null'
description: Opaque cursor for the next page; null on the last page.
required:
- data
- next_cursor
additionalProperties: false
'400':
description: Validation failed or the request cannot proceed.
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
description: Stable machine-readable error code (snake_case).
message:
type: string
required:
- code
- message
required:
- error
'401':
description: Missing, malformed, or revoked API key.
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
description: Stable machine-readable error code (snake_case).
message:
type: string
required:
- code
- message
required:
- error
'404':
description: The resource does not exist in this organization.
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
description: Stable machine-readable error code (snake_case).
message:
type: string
required:
- code
- message
required:
- error
'409':
description: Conflicts with the current state (duplicates, wrong lifecycle state).
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
description: Stable machine-readable error code (snake_case).
message:
type: string
required:
- code
- message
required:
- error
'422':
description: The request is well-formed but semantically invalid.
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
description: Stable machine-readable error code (snake_case).
message:
type: string
required:
- code
- message
required:
- error
'429':
description: Rate limit exceeded — retry after `Retry-After`.
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
description: Stable machine-readable error code (snake_case).
message:
type: string
required:
- code
- message
required:
- error
'500':
description: Internal server error.
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
description: Stable machine-readable error code (snake_case).
message:
type: string
required:
- code
- message
required:
- error
'503':
description: Transient error — retry with a narrower request.
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
description: Stable machine-readable error code (snake_case).
message:
type: string
required:
- code
- message
required:
- error
post:
operationId: segments_create
summary: Create a segment
description: Create a segment from a filter expression. It starts empty until evaluated. Validate and preview the filter first.
tags:
- Segments
requestBody:
required: true
content:
application/json:
schema:
$schema: https://json-schema.org/draft/2020-12/schema
type: object
properties:
name:
type: string
minLength: 1
maxLength: 120
description: Display name.
slug:
type: string
minLength: 1
maxLength: 64
pattern: ^[a-z0-9]+(-[a-z0-9]+)*$
description: Permanent identifier, lowercase-kebab-case, unique in your organization. Cannot be changed after creation.
description:
anyOf:
- type: string
maxLength: 1024
- type: 'null'
filterExpression:
description: 'The audience filter: a tree of predicates over person attributes, related data, and events. Discover valid `attr` tokens and operators with segments_catalog (GET /api/v1/segments/catalog).'
type: object
properties:
kind:
type: string
const: person
op:
type: string
enum:
- AND
- OR
predicates:
type: array
items:
oneOf:
- type: object
properties:
kind:
type: string
const: has_relationship
connector:
type: string
enum:
- AND
- OR
customObjectType:
type: string
minLength: 1
attributeFilters:
type: array
items:
type: object
properties:
attr:
type: string
path:
minItems: 1
maxItems: 5
type: array
items:
type: string
pattern: ^[A-Za-z_][A-Za-z0-9_]*$
type:
type: string
enum:
- STRING
- NUMBER
- BOOLEAN
- DATE
- JSON
- ARRAY
op:
type: string
enum:
- eq
- neq
- in
- not_in
- contains
- not_contains
- starts_with
- ends_with
- gt
- gte
- lt
- lte
- 'on'
- before
- after
- between
- in_last_n
- in_next_n
- more_than_n_ago
- more_than_n_from_now
- exactly_n_from_today
- is_null
- is_not_null
value:
anyOf:
- type: string
- type: number
- type: boolean
- type: array
items:
anyOf:
- type: string
- type: number
- type: object
properties:
from:
type: string
to:
type: string
required:
- from
- to
- type: object
properties:
amount:
type: integer
minimum: 1
maximum: 9999
unit:
type: string
enum:
- days
- weeks
- months
required:
- amount
- unit
- type: object
properties:
daysOffset:
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
rollForward:
type: object
properties:
fromDow:
type: integer
minimum: 0
maximum: 6
includeDows:
minItems: 1
type: array
items:
type: integer
minimum: 0
maximum: 6
required:
- fromDow
- includeDows
required:
- daysOffset
required:
- attr
- type
- op
path:
minItems: 1
maxItems: 3
type: array
items:
type: object
properties:
customObjectType:
type: string
minLength: 1
direction:
type: string
enum:
- parent_to_child
- child_to_parent
relationshipType:
type: string
minLength: 1
attributeFilters:
type: array
items:
type: object
properties:
attr:
type: string
path:
minItems: 1
maxItems: 5
type: array
items:
type: string
pattern: ^[A-Za-z_][A-Za-z0-9_]*$
type:
type: string
enum:
- STRING
- NUMBER
- BOOLEAN
- DATE
- JSON
- ARRAY
op:
type: string
enum:
- eq
- neq
- in
- not_in
- contains
- not_contains
- starts_with
- ends_with
- gt
- gte
- lt
- lte
- 'on'
- before
- after
- between
- in_last_n
- in_next_n
- more_than_n_ago
- more_than_n_from_now
- exactly_n_from_today
- is_null
- is_not_null
value:
anyOf:
- type: string
- type: number
- type: boolean
- type: array
items:
anyOf:
- type: string
- type: number
- type: object
properties:
from:
type: string
to:
type: string
required:
- from
- to
- type: object
properties:
amount:
type: integer
minimum: 1
maximum: 9999
unit:
type: string
enum:
- days
- weeks
- months
required:
- amount
- unit
- type: object
properties:
daysOffset:
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
rollForward:
type: object
properties:
fromDow:
type: integer
minimum: 0
maximum: 6
includeDows:
minItems: 1
type: array
items:
type: integer
minimum: 0
maximum: 6
required:
- fromDow
- includeDows
required:
- daysOffset
required:
- attr
- type
- op
required:
- customObjectType
- attributeFilters
required:
- kind
- customObjectType
- attributeFilters
- type: object
properties:
kind:
type: string
const: person_attribute
connector:
type: string
enum:
- AND
- OR
attr:
type: string
path:
minItems: 1
maxItems: 5
type: array
items:
type: string
pattern: ^[A-Za-z_][A-Za-z0-9_]*$
type:
type: string
enum:
- STRING
- NUMBER
- BOOLEAN
- DATE
- JSON
- ARRAY
op:
type: string
enum:
- eq
- neq
- in
- not_in
- contains
- not_contains
- starts_with
- ends_with
- gt
- gte
- lt
- lte
- 'on'
- before
- after
- between
- in_last_n
- in_next_n
- more_than_n_ago
- more_than_n_from_now
- exactly_n_from_today
- is_null
- is_not_null
value:
anyOf:
- type: string
- type: number
- type: boolean
- type: array
items:
anyOf:
- type: string
- type: number
- type: object
properties:
from:
type: string
to:
type: string
required:
- from
- to
- type: object
properties:
amount:
type: integer
minimum: 1
maximum: 9999
unit:
type: string
enum:
- days
- weeks
- months
required:
- amount
- unit
- type: object
properties:
daysOffset:
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
rollForward:
type: object
properties:
fromDow:
type: integer
minimum: 0
maximum: 6
includeDows:
minItems: 1
type: array
items:
type: integer
minimum: 0
maximum: 6
required:
- fromDow
- includeDows
required:
- daysOffset
required:
- kind
- attr
- type
- op
- type: object
properties:
kind:
type: string
const: person_group
connector:
type: string
enum:
- AND
- OR
filters:
minItems: 1
type: array
items:
type: object
properties:
attr:
type: string
path:
minItems: 1
maxItems: 5
type: array
items:
type: string
pattern: ^[A-Za-z_][A-Za-z0-9_]*$
type:
type: string
enum:
- STRING
- NUMBER
- BOOLEAN
- DATE
- JSON
- ARRAY
op:
type: string
enum:
- eq
- neq
- in
- not_in
- contains
- not_contains
- starts_with
- ends_with
- gt
- gte
- lt
- lte
- 'on'
- before
- after
- between
- in_last_n
- in_next_n
- more_than_n_ago
- more_than_n_from_now
- exactly_n_from_today
- is_null
- is_not_null
# --- truncated at 32 KB (223 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/boom-ai/refs/heads/main/openapi/boom-ai-segments-api-openapi.yml