Emotive Segments API
Create, retrieve, update and archive audience segments used to target SMS broadcasts and flows.
OpenAPI Specification
components:
parameters:
Limit:
description: The limit of objects to return
in: query
name: limit
schema:
default: 10
type: integer
Offset:
description: The offset to return
in: query
name: offset
schema:
default: 0
type: integer
SegmentId:
description: Segment's id to update
in: path
name: segment_id
required: true
schema:
type: integer
SegmentIsFavorite:
description: The is_favorite filter to apply to segments
in: query
name: is_favorite
schema:
type: boolean
SegmentOrder:
description: Whether order is ascending or descending
in: query
name: order
schema:
default: asc
enum:
- asc
- desc
type: string
SegmentSortBy:
description: The sorting for segments which are returned
in: query
name: sort_by
schema:
enum:
- title
- user_count
- created
- is_favorite
type: string
SegmentTitle:
description: The title filter to apply to segments
in: query
name: title
schema:
type: string
SegmentType:
description: The category / segment type filter to apply to segments
in: query
name: segment_type
schema:
enum:
- conversational
- behavioral
- third_party
- custom
type: string
schemas:
PaginatedSegments:
description: Basic segment list response object
properties:
limit:
description: The currently returned limit number
type: integer
offset:
description: The currently returned offset number
type: integer
results:
items:
$ref: '#/components/schemas/SegmentObjectWithBroadcastCount'
type: array
total_count:
description: total number of matching segments
type: integer
title: PaginatedSegments
type: object
SegmentBase:
description: Basic segment response object
properties:
is_template:
type: boolean
rules:
items:
items:
$ref: '#/components/schemas/SegmentRule'
type: array
type: array
title:
description: Label / searchable title for Segment
type: string
title: SegmentBase
type: object
SegmentObject:
allOf:
- $ref: '#/components/schemas/SegmentBase'
description: Basic segment response object
properties:
created:
description: Creation date of segment
type: string
id:
description: Unique identifier for the given Segment
type: integer
is_favorite:
description: Whether it is a favorited Segment
type: boolean
user_count:
description: Number of customers in Segment
nullable: true
type: integer
title: SegmentObject
type: object
SegmentObjectWithBroadcastCount:
allOf:
- $ref: '#/components/schemas/SegmentObject'
properties:
broadcast_count:
description: Count of broadcasts
type: integer
SegmentRule:
description: Segment rule array
properties:
conditional_variable:
nullable: true
type: string
entity:
type: string
value:
anyOf:
- nullable: true
type: string
- nullable: true
type: number
required:
- entity
- conditional_variable
title: SegmentRules
type: object
SegmentSearchBody:
description: Request body for segment search
properties:
limit:
default: 10
description: The currently returned limit number
type: integer
offset:
default: 0
description: The currently returned offset number
type: integer
order:
allOf:
- $ref: '#/components/parameters/SegmentOrder'
query:
description: The query to perform a case insenstive contains search on segment title
type: string
sort_by:
allOf:
- $ref: '#/components/parameters/SegmentSortBy'
title: SegmentSearchBody
type: object
info:
license:
name: Private
title: Segments API
version: 0.1.0
x-origin:
- url: https://api-gw.emotiveapp.co/segments/openapi.json
format: openapi
version: 3.0.2
method: searched
retrieved: '2026-08-13'
note: 'Fetched verbatim from the Emotive API gateway. Original servers[] was relative ([{"url": "/segments"}]);
resolved to the absolute gateway base for portability. Verbatim copy retained at openapi/_original/emotive-segments-openapi.json.'
openapi: 3.0.2
paths:
/api/v2/segments:
get:
description: Return array of matching segments
operationId: controllers.segments.get_segments
parameters:
- $ref: '#/components/parameters/SegmentType'
- $ref: '#/components/parameters/SegmentTitle'
- $ref: '#/components/parameters/SegmentIsFavorite'
- $ref: '#/components/parameters/SegmentOrder'
- $ref: '#/components/parameters/SegmentSortBy'
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/Offset'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedSegments'
description: Successful operation
summary: Retrieve a list of matching segments
tags:
- Segment Filter
post:
description: Add a new Segment
operationId: controllers.segments.post_segments
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SegmentBase'
description: Create a new segment
required: true
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/SegmentObject'
description: Successful operation
summary: Add a new Segment
tags:
- Single Segment
/api/v2/segments/{segment_id}:
delete:
description: Archive (delete) a segment
operationId: controllers.segments.delete_segment
parameters:
- $ref: '#/components/parameters/SegmentId'
responses:
'204':
description: Successful operation
summary: Archive (delete) a segment
tags:
- Single Segment
get:
description: Return details about a segment by its id
operationId: controllers.segments.get_segment
parameters:
- $ref: '#/components/parameters/SegmentId'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/SegmentObject'
description: Successful operation
summary: Retrieve a single Segment
tags:
- Single Segment
patch:
description: Update is_favorite field
operationId: controllers.segments.patch_segment
parameters:
- $ref: '#/components/parameters/SegmentId'
requestBody:
content:
application/json:
schema:
properties:
is_favorite:
type: boolean
type: object
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/SegmentObject'
description: Successful operation
summary: Update fields of a segment
tags:
- Single Segment
servers:
- url: https://api-gw.emotiveapp.co/segments
description: Emotive API gateway — segments service