Customer.io Snippets API

openapi: 3.2.0
info:
  version: 1.0.0
  title: Customer.io Journeys API Reference Snippets 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: Snippets
  description: Snippets are reusable pieces of messages, like a common email footer or link that you use in your messages. Use these endpoints to create, get, or delete snippets.
paths:
  /v1/snippets:
    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: List snippets
      operationId: listSnippets
      security:
      - Bearer-Auth: []
      description: Returns a list of snippets in your workspace. Snippets are pieces of reusable content, like a common footer for your emails.
      tags:
      - Snippets
      responses:
        '200':
          description: Returns an array of `snippets`.
          content:
            application/json:
              schema:
                type: object
                properties:
                  snippets:
                    type: array
                    items:
                      $ref: '#/components/schemas/snippet'
    post:
      summary: Create a snippet
      operationId: createSnippet
      security:
      - Bearer-Auth: []
      description: Create a new snippet. If a snippet with that name already exists, we'll return a `422` error. If the value contains Liquid, we validate it.
      tags:
      - Snippets
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/snippetRequest'
      responses:
        '200':
          description: Returns the created snippet.
          content:
            application/json:
              schema:
                type: object
                properties:
                  snippet:
                    $ref: '#/components/schemas/snippet'
        '401':
          $ref: '#/components/responses/401'
        '422':
          description: Validation error or a snippet with that name already exists.
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    description: Contains an array of error objects.
                    items:
                      type: object
                      properties:
                        detail:
                          type: string
                          description: The reason for the response.
                        status:
                          type: string
                          description: The HTTP status code.
                          example: '422'
                        source:
                          type: object
                          description: The field or path that caused the error.
                          properties:
                            pointer:
                              type: string
              examples:
                name_blank:
                  summary: Name empty or blank
                  value:
                    errors:
                    - detail: name cannot be blank
                      source:
                        pointer: /name
                      status: '422'
                value_blank:
                  summary: Value empty or blank
                  value:
                    errors:
                    - detail: value cannot be blank
                      source:
                        pointer: /value
                      status: '422'
                name_too_long:
                  summary: Name longer than 150 characters
                  value:
                    errors:
                    - detail: name cannot exceed 150 characters
                      source:
                        pointer: /name
                      status: '422'
                value_too_long:
                  summary: Value exceeds max length
                  value:
                    errors:
                    - detail: value cannot exceed 16000 characters
                      source:
                        pointer: /value
                      status: '422'
                snippet_reference:
                  summary: Value contains snippet reference
                  value:
                    errors:
                    - detail: Snippets cannot contain Liquid code referencing other snippets.
                      source:
                        pointer: /value
                      status: '422'
                name_exists:
                  summary: Name already exists
                  value:
                    errors:
                    - detail: A snippet with that name already exists
                      source:
                        pointer: /name
                      status: '422'
        '429':
          $ref: '#/components/responses/429'
        '500':
          description: Internal server error (for example, render service failure when validating Liquid).
    put:
      summary: Update snippets
      operationId: updateSnippets
      security:
      - Bearer-Auth: []
      description: In your payload, you'll pass a `name` and `value`. Snippet names are unique. If the snippet `name` does not exist, we'll create a new snippet. If the `name` exists, we'll update the existing snippet.
      tags:
      - Snippets
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/snippetRequest'
      responses:
        '200':
          description: Returns an array of `snippets`.
          content:
            application/json:
              schema:
                type: object
                properties:
                  snippet:
                    $ref: '#/components/schemas/snippet'
        '400':
          description: The request is malformed.
        '429':
          $ref: '#/components/responses/429'
  /v1/snippets/{snippet_name}:
    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).
    parameters:
    - name: snippet_name
      in: path
      required: true
      description: The name of a snippet.
      schema:
        type: string
    delete:
      summary: Delete a snippet
      operationId: deleteSnippet
      security:
      - Bearer-Auth: []
      description: Remove a snippet. You can only remove a snippet that is not in use. If your snippet is in use, you'll receive a `400` error.
      tags:
      - Snippets
      responses:
        '204':
          description: A successful delete operation returns no content.
        '400':
          description: The snippet is in use. You can't delete a snippet until you remove it from messages, templates, etc.
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    description: Contains an array of error objects.
                    type: array
                    items:
                      type: object
                      properties:
                        detail:
                          type: string
                          description: Describes the error.
                          example: unable to delete snippet in use
                        status:
                          type: string
                          description: The HTTP status code.
                          example: '400'
        '404':
          description: The snippet does not exist.
        '429':
          $ref: '#/components/responses/429'
components:
  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).
    snippet:
      x-scalar-ignore: true
      type: object
      description: describes a piece of reusable content. You must provide a name for the snippet and the `value`—the content that appears in messages that use the snippet.
      required:
      - name
      - value
      properties:
        name:
          type: string
          description: The name of the snippet, must be unique.
        value:
          type: string
          description: The contents of the snippet.
        updated_at:
          type: integer
          format: unix timestamp
          description: The last date-time the snippet was updated.
          readOnly: true
      example:
        name: address
        value: <strong>My Company</strong></br>1234 Fake St<br/>Fake,NY<br/>10111
        updated_at: 1582500000
    snippetRequest:
      x-scalar-ignore: true
      type: object
      description: Request body for creating or updating a snippet. Only `name` and `value` are accepted; `updated_at` is returned in responses only.
      required:
      - name
      - value
      properties:
        name:
          type: string
          maxLength: 150
          description: The name of the snippet, must be unique. Trimmed of leading and trailing whitespace before storage.
        value:
          type: string
          description: The contents of the snippet (plain text or Liquid). Trimmed of leading and trailing whitespace before storage. Max length is environment-specific (default 16000).
      example:
        name: address
        value: <strong>My Company</strong></br>1234 Fake St<br/>Fake,NY<br/>10111
  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'
    '401':
      description: Unauthorized request. Make sure that you provided the right credentials.
  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