Manage collections of data used in message personalization.
Each operation below carries the questions people ask an LLM about it and the instructions they give an agent to run it. Generated by API Evangelist overlay
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/customer-io:customer-io-collections-api"curl "https://apis.io/api/v1/apis?limit=25"Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
version: 1.0.0
title: Customer.io Journeys API Reference Collections API
description: Customer.io provides REST APIs to send real-time customer data, retrieve data from your account, and trigger messages.
servers:
- url: https://track.customer.io
description: The base URL for the Track API. Track endpoints use basic authentication with your Site ID as the user name and your secret key as the password.
- url: https://track-eu.customer.io
description: The base URL for the Track API (EU region). Track endpoints use basic authentication with your Site ID as the user name and your secret key as the password.
- url: https://api.customer.io
description: The base URL for broadcasts, transactional messages, and data-retrieval APIs. These endpoints use bearer authorization, and require a [token that you generate in the UI](https://fly.customer.io/settings/api_credentials?keyType=app).
- url: https://api-eu.customer.io
description: The base URL for broadcasts, transactional messages, and data-retrieval APIs (EU region). These endpoints use bearer authorization, and require a [token that you generate in the UI](https://fly.customer.io/settings/api_credentials?keyType=app).
tags:
- name: Collections
description: Collections are arbitrary sets of data that you want to use in automation messages or workflows independent of attributes or events. They might represent things like upcoming events, coupons/promotions, etc.
paths:
/v1/collections:
servers:
- url: https://api.customer.io
description: The base URL for broadcasts, transactional messages, and data-retrieval APIs. These endpoints use bearer authorization, and require a [token that you generate in the UI](https://fly.customer.io/settings/api_credentials?keyType=app).
- url: https://api-eu.customer.io
description: The base URL for broadcasts, transactional messages, and data-retrieval APIs (EU region). These endpoints use bearer authorization, and require a [token that you generate in the UI](https://fly.customer.io/settings/api_credentials?keyType=app).
post:
summary: Create a collection
description: 'Create a new collection and provide the `data` that you''ll access from the collection or the `url` that you''ll download CSV or JSON data from.
**Note**: A collection cannot be more than 10 MB in size. No individual row in the collection can be more than 10 KB.'
tags:
- Collections
operationId: addCollection
security:
- Bearer-Auth: []
requestBody:
content:
application/json:
schema:
oneOf:
- title: Local data
type: object
required:
- name
- data
properties:
name:
type: string
description: The name of the collection. This is how you'll reference your collection in messages—`{{collection_name.data-property}}`.
data:
type: array
description: An array of data objects that you want to reference in this collection.
items:
type: object
additionalProperties:
x-additionalPropertiesName: collection data
- title: Data by URL
type: object
required:
- name
- url
properties:
name:
type: string
description: The name of the collection. This is how you'll reference your collection in messages—`{{collection_name.data-property}}`.
url:
type: string
format: url
description: 'The URL for your CSV or JSON data. If your URL does not return a `Content-Type`, we use the file extension; otherwise, Customer.io assumes your data is JSON.
'
example:
name: events
data:
- eventName: christmas
eventDate: '2021-12-25T12:00:00.000Z'
presents:
something_you_want: toys
something_you_need: socks
total: 2
- eventName: birthday
eventDate: '2021-03-15T12:00:00.000Z'
presents:
something_you_want: video games
something_you_need: books
total: 2
responses:
'200':
description: The collection was created successfully.
content:
application/json:
schema:
type: object
properties:
collection:
$ref: '#/components/schemas/collectionResponse'
'400':
description: Your request was malformed.
'429':
$ref: '#/components/responses/429'
get:
operationId: getCollections
summary: List your collections
description: Returns a list of all of your collections, including the `name` and `schema` for each collection.
tags:
- Collections
security:
- Bearer-Auth: []
responses:
'200':
description: Returns metadata about your collection.
content:
application/json:
schema:
type: object
properties:
collections:
type: array
items:
$ref: '#/components/schemas/collectionResponse'
'429':
$ref: '#/components/responses/429'
/v1/collections/{collection_id}:
parameters:
- $ref: '#/components/parameters/collection_id'
servers:
- url: https://api.customer.io
description: The base URL for broadcasts, transactional messages, and data-retrieval APIs. These endpoints use bearer authorization, and require a [token that you generate in the UI](https://fly.customer.io/settings/api_credentials?keyType=app).
- url: https://api-eu.customer.io
description: The base URL for broadcasts, transactional messages, and data-retrieval APIs (EU region). These endpoints use bearer authorization, and require a [token that you generate in the UI](https://fly.customer.io/settings/api_credentials?keyType=app).
get:
summary: Lookup a collection
description: Retrieves details about a collection, including the `schema` and `name`. This request does not include the `content` of the collection (the values associated with keys in the schema).
tags:
- Collections
operationId: getCollection
security:
- Bearer-Auth: []
responses:
'200':
description: Returns metadata about your collection.
content:
application/json:
schema:
type: object
properties:
collection:
$ref: '#/components/schemas/collectionResponse'
'404':
description: The collection `id` does not exist.
'429':
$ref: '#/components/responses/429'
delete:
summary: Delete a collection
description: Remove a collection and associated contents. Before you delete a collection, make sure that you aren't referencing it in active automation messages or broadcasts; references to a deleted collection will appear empty and may prevent your messages from making sense to your audience.
tags:
- Collections
operationId: deleteCollection
security:
- Bearer-Auth: []
responses:
'204':
description: The collection is deleted.
'404':
description: The collection `id` does not exist.
'429':
$ref: '#/components/responses/429'
put:
summary: Update a collection
description: 'Update the `name` or replace the contents of a collection. Updating the `data` or `url` for your collection fully replaces the contents of the collection.
**Note**:
* If you reference your collection by name in active automation messages, changing the name of the collection will cause references to the previous name to return an empty data set.
* A collection cannot be more than 10 MB in size. No individual row in the collection can be more than 10 KB.'
tags:
- Collections
operationId: updateCollection
security:
- Bearer-Auth: []
requestBody:
content:
application/json:
schema:
oneOf:
- title: Local data
type: object
properties:
name:
type: string
description: The name of the collection. This is how you'll reference your collection in messages—`{{collection_name.data-property}}`.
data:
type: array
description: An array of data objects that you want to reference in this collection.
items:
type: object
additionalProperties:
x-additionalPropertiesName: collection data
- title: Data by URL
type: object
properties:
name:
type: string
description: The name of the collection. This is how you'll reference your collection in messages—`{{collection_name.data-property}}`.
url:
type: string
format: url
description: 'The URL for your CSV or JSON data. If your URL does not return a `Content-Type`, we use the file extension; otherwise, Customer.io assumes your data is JSON.
'
example:
name: events
data:
- eventName: christmas
eventDate: '2021-12-25T12:00:00.000Z'
presents:
something_you_want: toys
something_you_need: socks
total: 2
- eventName: birthday
eventDate: '2021-03-15T12:00:00.000Z'
presents:
something_you_want: video games
something_you_need: books
total: 2
responses:
'200':
description: The collection was created successfully.
content:
application/json:
schema:
type: object
properties:
collection:
$ref: '#/components/schemas/collectionResponse'
'400':
description: Your request was malformed.
'429':
$ref: '#/components/responses/429'
/v1/collections/{collection_id}/content:
parameters:
- $ref: '#/components/parameters/collection_id'
servers:
- url: https://api.customer.io
description: The base URL for broadcasts, transactional messages, and data-retrieval APIs. These endpoints use bearer authorization, and require a [token that you generate in the UI](https://fly.customer.io/settings/api_credentials?keyType=app).
- url: https://api-eu.customer.io
description: The base URL for broadcasts, transactional messages, and data-retrieval APIs (EU region). These endpoints use bearer authorization, and require a [token that you generate in the UI](https://fly.customer.io/settings/api_credentials?keyType=app).
get:
summary: Lookup collection contents
description: Retrieve the contents of a collection (the `data` from when you created or updated a collection). Each `row` in the collection is represented as a JSON blob in the response.
tags:
- Collections
operationId: getCollectionContents
security:
- Bearer-Auth: []
responses:
'200':
description: Returns your collection's contents—the `data` (or `url` contents) from your POST or PUT call.
content:
application/json:
schema:
type: object
additionalProperties:
x-additionalPropertiesName: collection data
example:
eventName: christmas
eventDate: '2021-12-25T12:00:00.000Z'
presents:
something_you_want: toys
something_you_need: socks
total: 2
'404':
description: The collection `id` does not exist.
'429':
$ref: '#/components/responses/429'
put:
summary: Update the contents of a collection
description: 'Replace the contents of a collection (the `data` from when you created or updated a collection). The request is a free-form object containing the keys you want to reference from the collection and the corresponding values. This request replaces the current contents of the collection entirely.
If you don''t want to update the contents directly—you want to change the `name` or data `url` for your collection, use the update a collection endpoint.
**Note**: A collection cannot be more than 10 MB in size. No individual row in the collection can be more than 10 KB.'
tags:
- Collections
operationId: updateCollectionContents
security:
- Bearer-Auth: []
requestBody:
description: Your request is a free form object representing the contents of your collection. This request replaces the contents of the collection entirely, so include all contents that you want to remain in the collection—whether they change or not.
content:
application/json:
schema:
type: object
additionalProperties:
x-additionalPropertiesName: collection contents
example:
eventName: christmas
eventDate: '2021-12-25T12:00:00.000Z'
presents:
something_you_want: toys
something_you_need: socks
total: 2
responses:
'200':
description: Returns your collection metadata and the updated schema.
content:
application/json:
schema:
type: object
properties:
collection:
$ref: '#/components/schemas/collectionResponse'
'404':
description: The collection `id` does not exist.
'429':
$ref: '#/components/responses/429'
components:
parameters:
collection_id:
name: collection_id
description: The identifier for a collection.
in: path
required: true
schema:
type: integer
schemas:
appApiError:
x-scalar-ignore: true
type: object
description: An array/list of failures where each entry is a separate failure reason.
required:
- errors
properties:
errors:
type: array
description: One entry for each reason the request failed.
items:
type: object
required:
- detail
- status
properties:
detail:
type: string
description: What went wrong, in plain text. Most messages end with a support reference you can use if you need to contact support.
example: bad request (reference a1b2c3)
status:
type: string
description: The HTTP status code as a string.
example: '400'
code:
type: string
description: A stable identifier for the failure, on the errors that carry one. Use this rather than the text in `detail` if you need to identify the error programmatically.
example: invalid_credentials
source:
type: object
description: The part of the request that the error refers to.
properties:
pointer:
type: string
description: A JSON pointer to the part of the request body that the error refers to.
example: /data/attributes/email
meta:
type: object
additionalProperties: true
description: Extra context (if available).
updated:
x-scalar-ignore: true
type: integer
format: unix timestamp
description: The date time when the referenced ID was last updated.
example: 1552341937
readOnly: true
collectionResponse:
x-scalar-ignore: true
type: object
properties:
bytes:
type: integer
description: The size of the collection in bytes.
example: 296
created_at:
$ref: '#/components/schemas/created'
updated_at:
$ref: '#/components/schemas/updated'
id:
type: integer
description: The identifier for the collection. This is how you'll reference the collection from the API.
example: 1
name:
type: string
description: The name of the collection. This is how you'll reference the collection in liquid, e.g. `{{collection_name.data_property}}`.
example: upcoming events
rows:
type: integer
description: Represents the number of objects in the `data` array or CSV rows in your collection schema.
example: 2
schema:
type: array
description: Lists the top-level keys that you can reference within this collection. Customer.io does not enforce any of these keys as required from your `data`.
items:
type: string
example:
- eventDate
- eventName
- presents
created:
x-scalar-ignore: true
type: integer
format: unix timestamp
description: The date time when the referenced ID was created.
example: 1552341937
readOnly: true
responses:
'429':
description: Your request is over the 10-per-second limit. `Retry-After` tells you how many seconds you must wait before you send the next request.
headers:
Retry-After:
$ref: '#/components/headers/Retry-After'
content:
application/json:
schema:
$ref: '#/components/schemas/appApiError'
example:
errors:
- detail: rate limited to 10 requests per 1s (reference a1b2c3)
status: '429'
headers:
Retry-After:
description: How many seconds you must wait before you send another request. This header is present when you are rate limited by a per-second limit. If you hit a daily quota, this header is not set.
schema:
type: integer
minimum: 1
example: 1
securitySchemes:
Tracking-API-Key:
type: http
scheme: basic
description: 'The Track API uses a basic authentication scheme. Your credentials are your **Site ID** and your **API key**, **Base-64 encoded** in the format `site_id:api_key`.
You can find your Site ID and API key on the [Track API Keys page](https://fly.customer.io/settings/api_credentials).
'
Bearer-Auth:
type: http
scheme: bearer
description: 'The App API uses a bearer authentication scheme.
You can generate a bearer token, known as an **App API Key**, with a defined scope in [your account settings](https://fly.customer.io/settings/api_credentials?keyType=app). [Learn more about bearer authorization in Customer.io](/accounts/settings/managing-credentials).
'
ServiceAccount-Auth:
x-scalar-ignore: true
type: http
scheme: bearer
bearerFormat: sa_live_
description: 'Transactional send endpoints (`/v1/send/email`, `/v1/send/push`, `/v1/send/sms`, `/v1/send/whatsapp`, `/v1/send/in_app`, `/v1/send/inbox_message`) also accept a service-account bearer token, prefixed with `sa_live_`. Service-account tokens work across workspaces, so you must pass the target workspace as the `X-Workspace-Id` header on each request.
Service-account tokens are intended for testing and one-off sends—for example, using the Customer.io CLI with an AI agent like Claude to verify that a transactional message renders correctly before wiring it into your production backend. **For the production integration that triggers the message from your application, use an App API Key instead**: it''s workspace-scoped, easier to rotate, and has a smaller blast radius.
Service-account tokens are server-side credentials. Treat them like any API key—keep them in environment variables or a secret manager, and never embed them in client-side code, mobile apps, or other untrusted contexts.
'
bearerAuth:
type: http
scheme: bearer
description: API key passed as a Bearer token.
x-tagGroups:
- name: Track API v2
tags:
- track_v2
- Object Schemas
- Person Schemas
- Deliveries
- name: Track API
tags:
- trackOverview
- trackJsOrBackend
- trackLimit
- trackRegion
- Track Customers
- Track Events
- Forms
- Track Segments
- Track v1 Overview
- name: App API
tags:
- appOverview
- appLimit
- appAuth
- Activities
- Automations
- Broadcasts
- Collections
- Customers
- Data Index
- ESP Suppression
- Exports
- Imports
- Info
- Live Notifications
- Messages
- Newsletters
- Opt-outs
- Reporting Webhooks
- Segments
- Sender Identities
- Snippets
- Subscription Center
- Transactional
- Workspaces
- Send Messages
- Objects
- Newsletter Variants
- Newsletter Metrics
- Assets
- name: Design Studio API
tags:
- Folders
- Components
- Emails
- Email link and publish
- Email testing
- SMS
- SMS link and publish
x-provenance:
method: harvested
publisher: Customer.io
source: https://docs.customer.io/openapi.yaml
note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
stamped by stamp-openapi-provenance.py (roadmap#793)