Customer.io Components API

openapi: 3.2.0
info:
  version: 1.0.0
  title: Customer.io Journeys API Reference Components 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: Components
  description: 'Custom components are reusable blocks of content that you build once and reference from any email. Use these endpoints to list, create, update, and delete custom components.


    Updating a component through the API changes the component itself. It doesn''t publish the change to the messages that reference the component; you do that from your workspace.'
paths:
  /v1/design_studio/components:
    servers:
    - url: https://api.customer.io
      description: The base URL for the Design Studio API. These endpoints use bearer authorization, and require an [App API Key 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 the Design Studio API (EU region). These endpoints use bearer authorization, and require an [App API Key that you generate in the UI](https://fly.customer.io/settings/api_credentials?keyType=app).
    get:
      tags:
      - Components
      summary: List components
      description: Returns a paginated list of components and any folders in the result set.
      operationId: listComponents
      security:
      - Bearer-Auth: []
      parameters:
      - name: tag
        in: query
        schema:
          type: string
        description: Filter by component tag name. This is the name of the tag inserted into your emails.
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/ParentFolderID'
      - $ref: '#/components/parameters/DirectDescendantsOnly'
      - $ref: '#/components/parameters/SortBy'
      - $ref: '#/components/parameters/SortOrder'
      - $ref: '#/components/parameters/CreatedBefore'
      - $ref: '#/components/parameters/CreatedAfter'
      - $ref: '#/components/parameters/UpdatedBefore'
      - $ref: '#/components/parameters/UpdatedAfter'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  components:
                    type: array
                    items:
                      $ref: '#/components/schemas/ComponentSummary'
                  folders:
                    type: array
                    items:
                      $ref: '#/components/schemas/Folder'
                  meta:
                    $ref: '#/components/schemas/ListMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      tags:
      - Components
      summary: Create a component
      description: Creates a custom component.
      operationId: createComponent
      security:
      - Bearer-Auth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              - tag
              - content
              properties:
                name:
                  type: string
                  description: Display name of the component. You see this on your Design Studio dashboard. This may be different from the component tag name.
                  minLength: 1
                  maxLength: 255
                  example: Custom footer
                tag:
                  type: string
                  description: The component tag name, used to reference your component in an email. [Learn what characters you can use](/journeys/design-studio/reusable/components/code-custom-component/#component-tag-name-validation).
                  example: custom-footer
                parent_folder_id:
                  type:
                  - string
                  - 'null'
                  format: uuid
                  description: UUID of the parent folder. Omit or pass `null` to create in the root directory.
                content:
                  type: string
                  description: HTML content
      responses:
        '200':
          description: Component created
          content:
            application/json:
              schema:
                type: object
                properties:
                  component:
                    $ref: '#/components/schemas/Component'
        '400':
          description: "Bad request. Possible reasons:\n  - Missing or invalid name\n  - Missing or invalid tag\n  - parent_folder_id is an empty string\n  - Unknown JSON field in request body\n"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
  /v1/design_studio/components/{id}:
    servers:
    - url: https://api.customer.io
      description: The base URL for the Design Studio API. These endpoints use bearer authorization, and require an [App API Key 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 the Design Studio API (EU region). These endpoints use bearer authorization, and require an [App API Key that you generate in the UI](https://fly.customer.io/settings/api_credentials?keyType=app).
    get:
      tags:
      - Components
      summary: Get a component
      description: Returns a single component with its full content.
      operationId: getComponent
      security:
      - Bearer-Auth: []
      parameters:
      - $ref: '#/components/parameters/component_id'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  component:
                    $ref: '#/components/schemas/Component'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      tags:
      - Components
      summary: Update a component
      description: 'Update part of a component: its name, tag, folder, or content.'
      operationId: updateComponent
      security:
      - Bearer-Auth: []
      parameters:
      - $ref: '#/components/parameters/component_id'
      requestBody:
        required: true
        description: You must provide a body with at least one of the following properties. Omitting a field leaves it unchanged.
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  minLength: 1
                  maxLength: 255
                  description: Display name of the component. You see this on your Design Studio dashboard. This may be different from the component tag name.
                  example: custom-footer
                tag:
                  type: string
                  description: The component tag name, used to reference your component in an email. Learn what [characters](/journeys/design-studio/reusable/components/code-custom-component/#component-tag-name-validation) you can use.
                parent_folder_id:
                  $ref: '#/components/schemas/parent_folder_id'
                content:
                  type: string
                  description: HTML content
      responses:
        '204':
          description: Component updated
        '400':
          description: "Bad request. Possible reasons:\n  - No fields provided\n  - Invalid name\n  - Invalid tag\n  - parent_folder_id is an empty string\n  - Unknown JSON field in request body\n"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
    delete:
      tags:
      - Components
      summary: Delete a component
      description: Delete a component. Note, this deletes any component. If you delete a component in use, the emails that reference it could fail to send.
      operationId: deleteComponent
      security:
      - Bearer-Auth: []
      parameters:
      - $ref: '#/components/parameters/component_id'
      responses:
        '204':
          description: Component deleted
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  parameters:
    CreatedAfter:
      name: created_after
      in: query
      schema:
        type: integer
        format: Unix timestamp
      description: Return records created after this time. Must be a unix timestamp.
      example: 1773856017
    UpdatedBefore:
      name: updated_before
      in: query
      schema:
        type: integer
        format: Unix timestamp
      description: Return records updated before this time. Must be a unix timestamp.
      example: 1773856017
    Page:
      name: page
      in: query
      description: The page number of results you want to display. Use with `limit`.
      schema:
        type: integer
        minimum: 1
        default: 1
    component_id:
      name: id
      in: path
      required: true
      description: The UUID of the component.
      schema:
        type: string
        format: uuid
    DirectDescendantsOnly:
      name: direct_descendants_only
      in: query
      description: When `true`, the response includes only the immediate children of the parent folder. When `false`, it includes the parent folder's entire subtree.
      schema:
        type: boolean
        default: false
    SortBy:
      name: sort_by
      in: query
      schema:
        type: string
        enum:
        - created
        - updated
        - name
        default: created
    Limit:
      name: limit
      in: query
      description: The maximum number of results per page.
      schema:
        type: integer
        minimum: 1
        maximum: 10000
        default: 1000
    ParentFolderID:
      name: parent_folder_id
      in: query
      schema:
        type: string
        format: uuid
      description: 'Filter by parent folder. Must reference an existing folder. If not set, the response filters by the root level directory.


        To list only items in the root folder, leave `parent_folder_id` unset and only set `direct_descendants_only` to `true`.

        '
    CreatedBefore:
      name: created_before
      in: query
      schema:
        type: integer
        format: Unix timestamp
      description: Return records created before this time. Must be a unix timestamp.
      example: 1773856017
    UpdatedAfter:
      name: updated_after
      in: query
      schema:
        type: integer
        format: Unix timestamp
      description: Return records updated after this time. Must be a unix timestamp.
      example: 1773856017
    SortOrder:
      name: sort_order
      in: query
      schema:
        type: string
        enum:
        - asc
        - desc
        default: asc
  responses:
    BadRequest:
      description: The request is invalid due to malformed parameters, missing required fields, or constraint violations.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Conflict:
      description: Conflict - linked resource or other constraint violation
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            errors:
            - detail: a constraint violation prevents this operation
              status: '409'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            errors:
            - detail: resource not found
              status: '404'
    Unauthorized:
      description: Authentication failed due to a missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            errors:
            - detail: unauthorized
              status: '401'
  schemas:
    Component:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: ID of the component
          example: e89b-12d3
        name:
          type: string
          description: Display name of the component. You see this on your Design Studio dashboard. This may be different from the component tag name.
          example: Custom footer
        tag:
          type: string
          description: The component tag name, used to reference your component in an email.
          example: custom-footer
        parent_folder_id:
          type:
          - string
          - 'null'
          format: uuid
          description: ID of the parent folder, or `null` if the component is in your root directory.
          example: 123e4567-e89b-12d3-a456-426614174000
        created:
          type: integer
          format: int64
          description: Unix timestamp of when the component was created.
          example: 1773856017
        updated:
          type: integer
          format: int64
          description: Unix timestamp of the last update to the component.
        content:
          type: string
          description: HTML content
    ComponentSummary:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: ID of the component
          example: e89b-12d3
        name:
          type: string
          description: Display name of the component. You see this on your Design Studio dashboard. This may be different from the component tag name.
          example: Custom footer
        tag:
          type: string
          description: The component tag name, used to reference your component in an email.
          example: custom-footer
        parent_folder_id:
          type:
          - string
          - 'null'
          format: uuid
          description: ID of the parent folder, or `null` if the component is in your root directory.
          example: 123e4567-e89b-12d3-a456-426614174000
        created:
          type: integer
          format: int64
          description: Unix timestamp of when the component was created.
          example: 1773856017
        updated:
          type: integer
          format: int64
          description: Unix timestamp of the last update to the component.
          example: 1773856019
    Folder:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: ID of folder
        name:
          type: string
          description: The name of the folder.
        parent_folder_id:
          type:
          - string
          - 'null'
          format: uuid
          description: The ID of the parent folder. Returns `null` if there is no parent, which means the folder is in the root directory.
        created:
          type: integer
          format: Unix timestamp
          description: Timestamp of when the folder was created.
        updated:
          type: integer
          format: Unix timestamp
          description: Timestamp of last update to the folder.
      example:
        id: 123e4567-e89b-12d3-a456-426614174000
        name: Product Announcements
        parent_folder_id: null
        created: 1714732800
        updated: 1714732800
    Error:
      type: object
      description: An error response containing one or more error details.
      properties:
        errors:
          type: array
          description: A list of errors that occurred while processing the request.
          items:
            type: object
            properties:
              detail:
                type: string
                description: A human-readable description of the error.
              status:
                type: string
                description: The HTTP status code for this error, as a string.
              source:
                type: object
                description: The request field that caused the error. Validation errors (`422`) include it.
                properties:
                  pointer:
                    type: string
                    description: The path to the field that failed, like `/data/attributes/content`.
              meta:
                type: object
                description: Additional detail about the error, when there is any. A failed publish uses this to list Liquid errors per language.
    parent_folder_id:
      type:
      - string
      - 'null'
      format: uuid
      description: 'The UUID of the parent folder.


        Omit if you want no change to where the folder or file is located. Include `null` to move it to your root directory. Or add the UUID of another folder to move it there.

        '
    ListMeta:
      type: object
      properties:
        pagination:
          type: object
          properties:
            page:
              type: integer
              description: The page number of results you're on.
            limit:
              type: integer
              description: The number of results per page.
            total:
              type: integer
              description: The total number of folders.
        filters:
          type: object
          description: The filters applied in your request.
          example:
            parent_folder_id: 123e4567-e89b-12d3-a456-426614174000
            direct_descendants_only: true
            sort_by: created
            sort_order: desc
            created_before: 1714732800
            created_after: null
            updated_before: null
            updated_after: null
  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