Custom Cohort Segmentation (CCS) — evaluate a batch of up to ten events for a user against the workspace's cohort definitions and return the cohorts they belong to plus per-destination activation values. Two modes: stateful, where Permutive persists segmentation state, and stateless, where the caller round-trips the state blob. For server-side, CTV and SDK-less deployments.
openapi: 3.1.0
info:
title: Custom Cohort Segmentation API
version: v1
servers:
- url: https://api.permutive.app
paths:
/ccs/v1/segmentation:
post:
tags:
- API version 1
summary: Segment user based on provided events and pre-existing state
description: 'This endpoint accepts a list of events for a given user and combines them with any
pre-existing state for the user to determine the full list of cohorts of which they are a member.
State is also persisted, to be applied to subsequent requests for the same user.
Events provided to this endpoint are published to the Permutive Events API, meaning that they
will be reflected in other areas of Permutive, for example Insights.
'
operationId: postCcsV1Segmentation
parameters:
- name: activations
in: query
description: Return a list of activated cohorts in the response
required: false
schema:
default: false
type: boolean
- name: synchronous-validation
in: query
description: 'Validate provided event(s) against their schema before proceeding with segmentation.
By default validation is performed asynchronously after segmentation has been performed and
the response has been returned. This can make it difficult to debug issues with invalid events.
It is recommended to use this option only during development and debugging, as validation can
be expensive and slow.'
required: false
schema:
default: false
type: boolean
requestBody:
description: 'A user identifier together with a list of events to be used for segmentation.
The user identifier must be either a `user_id`, an `alias`, or a list of prioritised aliases.
The largest number of events that can currently be included in a single request is 10.
'
content:
application/json:
schema:
$ref: '#/components/schemas/SegmentationRequest'
example:
user_id: 2008c38f-dece-4570-976d-87593ed001c3
alias: null
aliases: null
events:
- name: Pageview
time: '2022-06-22T19:40:43.179Z'
view_id: a55a9c8b-4a0b-4fe7-99a9-170624850501
session_id: 1d145310-1338-4ff7-96dd-e6128f54cbe5
properties:
my_property: interesting
- name: Pageview
time: '2022-06-22T19:40:45.152Z'
view_id: a55a9c8b-4a0b-4fe7-99a9-170624850501
session_id: 1d145310-1338-4ff7-96dd-e6128f54cbe5
properties:
my_object:
inner_property: 42
required: true
responses:
'200':
description: List of cohorts of which the user is currently a member, along with the Permutive
User ID and activations if requested
content:
application/json:
schema:
$ref: '#/components/schemas/SegmentationResponse'
example:
user_id: 2008c38f-dece-4570-976d-87593ed001c3
cohorts:
- '12345'
- '23456'
- '34567'
activations:
gam:
- '12345'
'400':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/HttpErrorResponse'
'401':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/HttpErrorResponse'
'403':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/HttpErrorResponse'
'500':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/HttpErrorResponse'
security:
- apiKeyAuth: []
- apiKeyAuth1: []
/ccs/v1/segmentation/stateless:
post:
tags:
- API version 1
summary: Segment user based on provided events and state only
description: 'This endpoint accepts a list of events for a given user and optionally some pre-existing
state for the user. It uses these to determine the full list of cohorts of which they are a member,
and returns these along with the updated state for the user. State is not persisted, so will not
be used in the next request unless it is passed back in as part of that request.
It is likely that this endpoint is more performant than the stateful segmentation endpoint, since
it does not need to read state for the user from a database. It is also useful for testing purposes.
Events provided to this endpoint are published to the Permutive Events API, meaning that they
will be reflected in other areas of Permutive, for example Insights.
'
operationId: postCcsV1SegmentationStateless
parameters:
- name: synchronous-validation
in: query
description: 'Validate provided event(s) against their schema before proceeding with segmentation.
By default validation is performed asynchronously after segmentation has been performed and
the response has been returned. This can make it difficult to debug issues with invalid events.
It is recommended to use this option only during development and debugging, as validation can
be expensive and slow.'
required: false
schema:
default: false
type: boolean
requestBody:
description: 'A user identifier and a list of events to be used for segmentation, plus optional
pre-existing state for the user.
The user identifier must be either a `user_id`, an `alias`, or a list of prioritised aliases.
The largest number of events that can currently be included in a single request is 10.
State is in the JSON format returned by this endpoint. It is not intended to be parsed or understood
outside the context of this API or a Permutive SDK.
'
content:
application/json:
schema:
$ref: '#/components/schemas/SegmentationRequestWithState'
example:
user_id: 2008c38f-dece-4570-976d-87593ed001c3
alias: null
aliases: null
events:
- name: Pageview
time: '2022-06-22T19:40:43.179Z'
view_id: a55a9c8b-4a0b-4fe7-99a9-170624850501
session_id: 1d145310-1338-4ff7-96dd-e6128f54cbe5
properties:
my_property: interesting
- name: Pageview
time: '2022-06-22T19:40:45.152Z'
view_id: a55a9c8b-4a0b-4fe7-99a9-170624850501
session_id: 1d145310-1338-4ff7-96dd-e6128f54cbe5
properties:
my_object:
inner_property: 42
state:
internal_state:
'12345':
0c8b70cdb7:
- p
- 1
external_state:
'67890':
0c8b70cdb7:
- p
- 1
cohorts:
- '12345'
- '67890'
required: true
responses:
'200':
description: The Permutive User ID and the user's state (including the list of cohorts of which
they are a member).
content:
application/json:
schema:
$ref: '#/components/schemas/SegmentationResponseWithState'
example:
user_id: 2008c38f-dece-4570-976d-87593ed001c3
state:
internal_state:
'12345':
0c8b70cdb7:
- p
- 1
external_state:
'67890':
0c8b70cdb7:
- p
- 1
cohorts:
- '12345'
- '67890'
'400':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/HttpErrorResponse'
'401':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/HttpErrorResponse'
'403':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/HttpErrorResponse'
'500':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/HttpErrorResponse'
security:
- apiKeyAuth: []
- apiKeyAuth1: []
components:
schemas:
Alias:
title: Alias
type: object
required:
- tag
- id
properties:
tag:
type: string
id:
type: string
ChecksummedState:
title: ChecksummedState
examples:
- 0c8b70cdb7:
- p
- 1
type: object
additionalProperties:
$ref: '#/components/schemas/CohortState'
CohortId:
title: CohortId
examples:
- 12345
type: string
CohortState:
title: CohortState
DeviceState:
title: DeviceState
examples:
- '12345':
0c8b70cdb7:
- p
- 1
type: object
additionalProperties:
$ref: '#/components/schemas/ChecksummedState'
Event:
title: Event
type: object
required:
- name
- time
- properties
properties:
name:
type: string
time:
type: string
format: date-time
view_id:
type: string
format: uuid
session_id:
type: string
format: uuid
properties:
$ref: '#/components/schemas/JsonObject'
HttpErrorResponse:
title: HttpErrorResponse
type: object
required:
- request_id
- error
properties:
request_id:
$ref: '#/components/schemas/RequestId'
error:
type: object
required:
- type
- status_code
- status
- code
- message
- docs
properties:
type:
type: string
status_code:
type: integer
format: int32
status:
type: string
code:
type: integer
format: int32
message:
type: string
docs:
type: string
cause:
type: string
JsonObject:
title: JsonObject
type: object
Map_Seq_String:
title: Map_Seq_String
type: object
additionalProperties:
type: array
items:
type: string
PrioritisedAlias:
title: PrioritisedAlias
type: object
required:
- priority
- tag
- id
properties:
priority:
type: integer
format: int32
tag:
type: string
id:
type: string
RequestId:
title: RequestId
oneOf:
- type: string
- type: string
- type: string
format: uuid
SegmentationRequest:
title: SegmentationRequest
type: object
properties:
user_id:
type: string
format: uuid
alias:
$ref: '#/components/schemas/Alias'
aliases:
type: array
items:
$ref: '#/components/schemas/PrioritisedAlias'
events:
type: array
items:
$ref: '#/components/schemas/Event'
SegmentationRequestWithState:
title: SegmentationRequestWithState
type: object
properties:
user_id:
type: string
format: uuid
alias:
$ref: '#/components/schemas/Alias'
aliases:
type: array
items:
$ref: '#/components/schemas/PrioritisedAlias'
events:
type: array
items:
$ref: '#/components/schemas/Event'
state:
$ref: '#/components/schemas/UserState'
SegmentationResponse:
title: SegmentationResponse
type: object
required:
- user_id
properties:
user_id:
type: string
format: uuid
cohorts:
type: array
items:
type: string
activations:
$ref: '#/components/schemas/Map_Seq_String'
SegmentationResponseWithState:
title: SegmentationResponseWithState
type: object
required:
- user_id
- state
properties:
user_id:
type: string
format: uuid
state:
$ref: '#/components/schemas/UserState'
UserState:
title: UserState
type: object
required:
- internal_state
- external_state
properties:
internal_state:
$ref: '#/components/schemas/DeviceState'
external_state:
$ref: '#/components/schemas/DeviceState'
cohorts:
type: array
uniqueItems: true
items:
$ref: '#/components/schemas/CohortId'
securitySchemes:
apiKeyAuth:
type: apiKey
name: k
in: query
apiKeyAuth1:
type: apiKey
name: X-Api-Key
in: header