openapi: 3.0.1
info:
title: cdp-api
description: >-
All of the CDP APIs are organized around REST - if you've interacted with a
RESTful API already, many of the concepts will be familiar to you. All API
calls to CDP API should be made to the following endpoints depending on the
[region](https://docs.treasuredata.com/display/public/PD/Sites+and+Endpoints#SitesandEndpoints-Endpoints).
For historical reasons there are REST API endpoints and JSON:API endpoints.
JSON:API endpoints are located under "/entities".
termsOfService: https://www.treasuredata.com/terms/
version: 1.0.0
externalDocs:
description: Treasure Data Support Site
url: https://support.treasuredata.com/hc/en-us
servers:
- url: https://api-cdp.treasuredata.com
- url: https://api-cdp.treasuredata.co.jp
- url: https://api-cdp.eu01.treasuredata.com
- url: https://api-cdp.ap02.treasuredata.com
- url: https://api-cdp.ap03.treasuredata.com
tags:
- name: Parent Segment Configurations
description: >-
Defining a data model for customer data is done by defining parent
segments. Parent segments give you an ability to build a single view of a
customer, including capturing all interactions, such as attributes and
behaviors associated with your brand. In parent segments, you unify your
customer data. When the customer data is unified, you can create customer
segments without writing any SQL queries. You can personalize customer
communications and conversations of any size and in any channel.<br> <br>
<br>_Treasure Data is making an effort to use more inclusive language in
its product, content, and customer solutions. As we gradually make the
move to replace insensitive language beginning in our UI, you may continue
to see parent segments in the UI, for example, referenced as master
segment in portions of Treasure Data APIs._
- name: Parent Segments
description: >-
After you have created the parent segment, you can view data about the
parent segment, such as details about a single segment, audience data, the
list of segment folders it contains, or a list of parent segments
available.
- name: Segments
description: >-
In marketing, a segment is a container that groups profiles (usually
people) who share one or more common characteristics. In Treasure Data,
the parent segment is your total population of people, accounts, or other
type of collection and can be both existing and potential customers. <br>
<br>You create segments to divide the population into subgroups of
consumers based on some type of shared characteristics. Segments and
subsegments enable more specific targeting for your marketing campaigns.
<br> <br> <br>_Treasure Data is making an effort to use more inclusive
language in its product, content, and customer solutions. As we gradually
make the move to replace insensitive language beginning in our UI, you may
continue to see parent segments in the UI, for example, referenced as
master segment in portions of Treasure Data APIs._
- name: Folders
description: >-
Folders are containers in which you can organize information. Nested
folders offer flexible organization controls. Large volumes of data and
application assets can be organized into multi-nested folders by
categories such as geographical markets, brands, and business functions.
Granular permissions can be set for each folder to ensure security.
- name: Activations
description: >-
Activation is the process that allows marketers to personalize
communication to users interested in your brand. <br> <ul> <li> **Funnel
activation** — Create a funnel activation for each funnel stage. The
activation exports to external marketing tools for campaigns or BI tools
for analysis and reporting.</li> <li> **Segment activation** —
Activate the segment data (export) to external tools for activities such
as marketing campaigns, business analysis, and social media. Targets
include Email Marketing Systems, Marketing Automation Systems, Advertising
Platforms, CRM, ERP, Cloud Services, and SFTP.</li> </ul><br>_Known
formerly as syndication in Audience Studio Legacy. You may continue to see
syndication referenced in Treasure Data APIs._
- name: Tokens
description: >-
The Profiles API Token enables your ability to increase personalized
content based on detailed customer information. This REST API returns
customer data in real-time and updates your segment information. The
ability to create a Profiles API token is based on your <a
href="https://docs.treasuredata.com/display/public/PD/Folder-based+Permissions">folder
permissions.</a> <br> <br> You can also use Profiles API Token to
personalize your customers' experience on your website. You can combine
Treasure Data’s personalization feature with A/B Testing tools such as
Adobe Target, Optimizely, or Google Optimize, to determine the version of
your website that yields results. <br> <br> When the underlying
personalization workflow completes, the personalization data set is
refreshed. You can see a current list of the segments to which a specific
profile belongs. You can also see a list of attributes associated with the
specific profile.<br> <br> The parent segment must already exist. The
parent segment is the basis for all data accessed by Profiles API Tokens.
<br> <br> The use of the Profiles API Token with your tools requires the
use of the Treasure Data JavaScript SDK and support or services
consultation.
- name: Funnels
description: >-
One of the challenges of targeting customers with relevant campaigns is
understanding where they are in their customer journey. Many organizations
use the traditional marketing funnel to understand where their customers
are in the buying process. Knowing where customers are in the marketing
funnel allows organizations to create campaigns and analyze customer
behaviors that are specific to individual customers or customer groups.
Being able to use all available customer data to accurately identify
exactly in which stage customers are in gives marketers a clear advantage.
<br> <br> Treasure Data offers Funnels, a premium subscription feature in
Audience Studio, which provides this advantage to its users. Funnels make
it easier for marketers to see exactly where their customers are in the
buying process, allowing them to create more customer-tailored marketing
campaigns using multi-channel activations.<br> <br> Funnels enables
marketers to create and customize a marketing funnel with up to eight
stages in the Audience Studio to reflect the exact buying experience of
their customers. After the Funnel stages have been created, marketers can
further analyze and refine the stages and activate specific stages for
campaigns.
- name: Predictive Segments
description: >-
Using Treasure Data’s predictive scoring model, based on predictive
segments, marketers can predict profile behavior such as who is likely to
churn, purchase, click, or convert in the near future. <br> <br> A
predictive model is a set of rules that makes it possible to predict an
unmeasured value from other, known values. The form of the rules is
suggested by reviewing the data collected. Training is then used to make
some predictions. Predictive modeling uses statistics to predict outcomes.
<br><br>Predictive modeling is a typically used statistical technique to
predict future behavior. Predictive modeling solutions analyze historical
and current data and the generated model helps predict future outcomes. In
predictive modeling, data is collected, a statistical model is formulated,
predictions are made, and the model is validated (or revised) as
additional data becomes available. For example, risk models can be created
to combine member information in complex ways with demographic and
lifestyle information from external sources to improve underwriting
accuracy. Predictive models analyze past performance to assess how likely
a customer is to exhibit a specific behavior in the future. This category
also encompasses models that seek out subtle data patterns to answer
questions about customer performance, such as fraud detection models.
Predictive models often perform calculations during live transactions—for
example, to evaluate the risk or opportunity of a given customer or
transaction to guide a decision. <br> <br> Treasure Data’s predictive
scoring model uses predictive segments to customize predictive scoring
models for a particular segment.
- name: Journeys
description: >-
In Audience Studio, a journey represents a timeline of events that can
help you motivate a customer’s behavior about your product. After
marketers create journey stages, they can further analyze and refine the
stages and activate specific stages for campaigns. <br><br> _Journeys is a
premium feature. Contact your Customer Success Representative for more
information._
- name: Activation Templates
description: >-
Marketers find creating an activation challenging because they have to
enter technical information they might not understand, which can lead to
activations failing due to misconfigurations. Treasure Data solves this
problem with the Activation Template. The Activation Template allows data
engineers to create templates with pre-populated fields so that the
marketer can confidently create an activation.
- name: Composable Audiences
description: >-
Composable Audiences enable zero-copy audience management by connecting
directly to external data warehouses (Snowflake, BigQuery, Databricks)
without moving data. This approach supports federated queries that execute
in-place on customer data, providing faster insights and reducing data
duplication. Composable Audiences include features for attribute and
behavior tracking, segment preview queries, and sample value retrieval for
data exploration.
- name: Composable Segments
description: >-
Composable Segments are segments defined for composable audiences, using
federated query execution on external data warehouses. They enable
zero-copy segmentation with rule-based filtering executed directly on
customer data in Snowflake, BigQuery, or Databricks.
paths:
/audiences:
x-external: true
get:
tags:
- Parent Segment Configurations
summary: Retrieve list of parent segment configurations
description: >-
Retrieve a list of parent segment configurations by name. You can get
the parent segment's schedules, created_by, the parent database name and
tables, its attributes and behaviors, as well as the population for the
retrieved Parent Segment.
operationId: audiences#index
responses:
'200':
description: successful operation
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Audience'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
4XX:
$ref: '#/components/responses/ClientError'
5XX:
$ref: '#/components/responses/ServerError'
security:
- TdApikeyAuth: []
post:
tags:
- Parent Segment Configurations
summary: Create new parent segment configuration
description: Create a new parent segment configuration.
operationId: audiences#create
requestBody:
description: Create a new Master Segment Config
content:
application/json:
schema:
$ref: '#/components/schemas/Audience'
required: true
responses:
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
4XX:
$ref: '#/components/responses/ClientError'
5XX:
$ref: '#/components/responses/ServerError'
security:
- TdApikeyAuth: []
/audiences/{audienceId}:
x-external: true
get:
tags:
- Parent Segment Configurations
summary: Retrieve parent segment configuration by ID
description: >-
Search and find a specified parent segment configuration by its
identifier.
operationId: audiences#show
parameters:
- name: audienceId
in: path
description: ID of Master Segment Config to return
required: true
schema:
type: integer
format: int64
responses:
'200':
description: successful operation
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/Audience'
- $ref: '#/components/schemas/ComposableAudience'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
4XX:
$ref: '#/components/responses/ClientError'
5XX:
$ref: '#/components/responses/ServerError'
security:
- TdApikeyAuth: []
put:
tags:
- Parent Segment Configurations
summary: Update parent segment configuration
description: >
Update the specified parent segment configuration by its identifier.
**Important: Update Behavior and the `master` Field**
This endpoint supports two different update modes depending on whether
the `master` field is included in the request body:
1. **Partial Update (without `master` field)**: When the `master` field
is omitted, only the scalar fields (e.g., `name`, `description`,
`scheduleType`) in the request body are updated. The `attributes`,
`behaviors`, and `audienceFilters` collections are left untouched, even
if they are omitted or set to `null` or `[]` in the request.
2. **Full Replacement (with `master` field)**: When the `master` field
is included in the request body, the endpoint performs a full
replacement of `attributes`, `behaviors`, and `audienceFilters`. All
existing entries in these collections are deleted and replaced with
exactly what is provided in the request:
- If `attributes`, `behaviors`, or `audienceFilters` are omitted, set to `null`, or set to `[]`, those collections will be **cleared** (all existing entries deleted).
- Only the items explicitly included in the request body will exist after the update.
- This is a destructive operation that cannot be undone.
**Recommendations**:
- For partial updates of scalar fields only: omit the `master` field
from the request body.
- For full replacement: include the `master` field and provide complete
definitions for `attributes`, `behaviors`, and `audienceFilters` to
avoid unintended data loss.
operationId: audiences#update
parameters:
- name: audienceId
in: path
description: ID of Master Segment Config that needs to be updated
required: true
schema:
type: integer
format: int64
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Audience'
responses:
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
4XX:
$ref: '#/components/responses/ClientError'
5XX:
$ref: '#/components/responses/ServerError'
security:
- TdApikeyAuth: []
delete:
tags:
- Parent Segment Configurations
summary: Delete parent segment configuration
description: Delete a previously created parent segment configuration.
operationId: audiences#delete
parameters:
- name: audienceId
in: path
description: Master Segment Config id to delete
required: true
schema:
type: integer
format: int64
responses:
'404':
description: Master Segment Config not found
content: {}
security:
- TdApikeyAuth: []
/audiences/{audienceId}/attributes:
x-external: true
get:
tags:
- Parent Segment Configurations
summary: Retrieve list of audience attributes
description: >-
Retrieve a list of parent segment attributes. You can also specify the
visibility level for sensitive attributes.
operationId: audience_attributes#index
parameters:
- name: audienceId
in: path
description: ID of Master Segment Config to return
required: true
schema:
type: integer
format: int64
responses:
'200':
description: successful operation
content:
application/json:
schema:
type: array
items:
oneOf:
- $ref: '#/components/schemas/AudienceAttributeWithVisibility'
- $ref: '#/components/schemas/AudienceMasterAttribute'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
4XX:
$ref: '#/components/responses/ClientError'
5XX:
$ref: '#/components/responses/ServerError'
security:
- TdApikeyAuth: []
/audiences/{audienceId}/behaviors:
x-external: true
get:
tags:
- Parent Segment Configurations
summary: Retrieve list of audience behaviors
description: Retrieve a list of parent segment behaviors.
operationId: audience_behaviors#index
parameters:
- name: audienceId
in: path
description: ID of Master Segment Config to return
required: true
schema:
type: integer
format: int64
- name: realtime
in: query
schema:
type: boolean
responses:
'200':
description: successful operation
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/AudienceBehaviorWithVisibility'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
4XX:
$ref: '#/components/responses/ClientError'
5XX:
$ref: '#/components/responses/ServerError'
security:
- TdApikeyAuth: []
/audiences/{audienceId}/run:
x-external: true
post:
tags:
- Parent Segment Configurations
summary: Run workflow to (re)generate parent segment
description: Run the workflow to generate or regenerate a parent segment.
operationId: audiences#run
parameters:
- name: audienceId
in: path
description: Master Segment Config id to delete
required: true
schema:
type: integer
format: int64
responses:
'200':
description: Succeeded to run the workflow
content:
application/json:
schema:
$ref: '#/components/schemas/AudienceExecution'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
4XX:
$ref: '#/components/responses/ClientError'
5XX:
$ref: '#/components/responses/ServerError'
security:
- TdApikeyAuth: []
/audiences/{audienceId}/folders:
x-external: true
get:
tags:
- Parent Segments
summary: Retrieve list of segment folders
description: >-
Retrieve a list of segment folders based on a parent segment's
identifier.
parameters:
- name: audienceId
in: path
description: Master segment ID
required: true
schema:
type: integer
format: int64
responses:
'200':
description: |
Retrieves a list of segment folders.
N.B. that `createdAt` can be `null`, meaning that it is not known
which user created the folder.
N.B. that `updatedAt` can be `null`, meaning that is is not known
which user last updated the folder.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/SegmentFolderReadRepresentation'
security:
- TdApikeyAuth: []
post:
tags:
- Folders
summary: Create new segment folder
description: Create a new parent segment folder.
parameters:
- name: audienceId
in: path
description: Master segment ID
required: true
schema:
type: integer
format: int64
requestBody:
description: Segment Folder to create
content:
application/json:
schema:
$ref: '#/components/schemas/SegmentFolderCreateRepresentation'
responses:
'200':
description: Returns the segment folder which was created
content:
application/json:
schema:
$ref: '#/components/schemas/SegmentFolderReadRepresentation'
security:
- TdApikeyAuth: []
/audiences/{audienceId}/folders/{folderId}:
x-external: true
get:
tags:
- Folders
summary: Retrieve single segment folder
description: Retrieve a single segment folder based on a parent segment identifier.
parameters:
- name: audienceId
in: path
description: Master segment ID
required: true
schema:
type: integer
format: int64
- name: folderId
in: path
description: Segment Folder ID
required: true
schema:
type: integer
format: int64
responses:
'200':
description: |
Retrieves a single segment folder.
N.B. that `createdAt` can be `null`, meaning that it is not known
which user created the folder.
N.B. that `updatedAt` can be `null`, meaning that is is not known
which user last updated the folder.
content:
application/json:
schema:
$ref: '#/components/schemas/SegmentFolderReadRepresentation'
security:
- TdApikeyAuth: []
patch:
tags:
- Folders
summary: Update segment folder (legacy)
description: >-
Update a segment folder. <br> <br> <br> _This endpoint is for Audience
Studio legacy. For the latest Audience Studio, contact your Customer
Success Representative._
parameters:
- name: audienceId
in: path
description: Master segment ID
required: true
schema:
type: integer
format: int64
- name: folderId
in: path
description: Segment folder to update
required: true
schema:
type: integer
format: int64
requestBody:
description: Segment Folder to update
content:
application/json:
schema:
$ref: '#/components/schemas/SegmentFolderUpdateRepresentation'
responses:
'200':
description: |
Retrieves the segment folder which was updated
N.B. that `createdAt` can be `null`, meaning that it is not known
which user created the folder.
content:
application/json:
schema:
$ref: '#/components/schemas/SegmentFolderReadRepresentation'
security:
- TdApikeyAuth: []
delete:
tags:
- Folders
summary: Delete segment folder (legacy)
description: >-
Delete a segment folder.<br> <br> <br> _This endpoint is for Audience
Studio legacy. For the latest Audience Studio, contact your Customer
Success Representative._
parameters:
- name: audienceId
in: path
description: Master segment ID
required: true
schema:
type: integer
format: int64
- name: folderId
in: path
description: Segment folder to update
required: true
schema:
type: integer
format: int64
responses:
'200':
description: The segment folder was deleted successfully
security:
- TdApikeyAuth: []
/audiences/{audienceId}/folders/{folderId}/put_in:
x-external: true
post:
tags:
- Folders
summary: Move segment into folder (legacy)
description: >-
Move a segment or segments into an existing folder. <br> <br> <br> _This
endpoint is for Audience Studio legacy. For the latest Audience Studio,
contact your Customer Success Representative._
parameters:
- name: audienceId
in: path
description: Master segment ID
required: true
schema:
type: integer
format: int64
- name: folderId
in: path
description: Segment folder to put segments in
required: true
schema:
type: integer
format: int64
requestBody:
description: Segment ids to move
content:
application/json:
schema:
type: array
items:
type: string
responses:
'200':
description: successful operation
content:
application/json:
schema:
type: object
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
4XX:
$ref: '#/components/responses/ClientError'
5XX:
$ref: '#/components/responses/ServerError'
security:
- TdApikeyAuth: []
/audiences/{audienceId}/executions:
x-external: true
get:
tags:
- Parent Segment Configurations
summary: Retrieve list of executions using audienceId
description: >-
Retrieve a list of workflow executions, whether they were succesful or
not, and their status.
operationId: audiences#executions
parameters:
- name: audienceId
in: path
description: Master Segment Config id to delete
required: true
schema:
type: integer
format: int64
responses:
'200':
description: Succeeded to run the workflow
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/AudienceExecution'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
4XX:
$ref: '#/components/responses/ClientError'
5XX:
$ref: '#/components/responses/ServerError'
security:
- TdApikeyAuth: []
/audiences/{audienceId}/statistics:
x-external: true
get:
tags:
- Parent Segment Configurations
summary: Retrieve population statistics audience
description: >-
Retrieve the population history of the audience. The history is returned
per day and those days are calculated in the timezone of the audience.
operationId: audiences#statistics
parameters:
- name: audienceId
in: path
description: Master Segment Config id to delete
required: true
schema:
type: integer
format: int64
example: 1234
- name: from
in: query
description: from date
schema:
type: string
format: date
example: '2019-01-01'
- name: to
in: query
description: to date (inclusive)
schema:
type: string
format: date
example: '2019-04-30'
responses:
'200':
description: array of tuple of statistics
content:
application/json:
schema:
$ref: '#/components/schemas/Statistic'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
4XX:
$ref: '#/components/responses/ClientError'
5XX:
$ref: '#/components/responses/ServerError'
security:
- TdApikeyAuth: []
/audiences/{audienceId}/segments:
x-external: true
get:
tags:
- Segments
summary: Retrieve list of segments
description: Retrieve a list of segments.
operationId: segments#index
parameters:
- name: audienceId
in: path
description: Master Segment id of the segment
required: true
schema:
type: integer
format: int64
responses:
'200':
description: successful operation
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Segment'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
4XX:
$ref: '#/components/responses/ClientError'
5XX:
$ref: '#/components/responses/ServerError'
security:
- TdApikeyAuth: []
post:
tags:
- Segments
summary: Create new segment
description: Create a new segment.
operationId: segments#create
parameters:
- name: audienceId
in: path
description: Master Segment id of the segment
required: true
schema:
type: integer
format: int64
requestBody:
description: Segment parameters to create
content:
applicati
# --- truncated at 32 KB (565 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/treasure-data/refs/heads/main/openapi/treasure-data-cdp-api-openapi.yml