Customer.io Workspaces API

openapi: 3.2.0
info:
  version: 1.0.0
  title: Customer.io App Workspaces API
  description: Our App API provides ways to trigger messages and retrieve information about people, campaigns, broadcasts, and more.
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).
tags:
- name: Workspaces
  description: An API to retrieve information about your workspaces in your account. You can use this to look up counts for messages sent, monthly billable emails sent, people, and objects.
paths:
  /v1/workspaces:
    servers:
    - url: https://api.customer.io
      description: This API uses bearer authorization, requiring a [token that you generate in the UI](https://fly.customer.io/settings/api_credentials?keyType=app).
    get:
      summary: List workspaces
      operationId: listWorkspaces
      security:
      - Bearer-Auth: []
      description: Returns a list of workspaces in your account.
      tags:
      - Workspaces
      responses:
        '200':
          description: Returns an array of `workspaces`.
          content:
            application/json:
              schema:
                type: object
                properties:
                  workspaces:
                    type: array
                    items:
                      x-scalar-ignore: true
                      description: Contains workspace properties including the count of messages, people, and objects. Customer.io caches these counts, so your data may be up to two hours old.
                      type: object
                      properties:
                        id:
                          type: integer
                          description: The id of the workspace.
                          example: 13XXXX
                        name:
                          type: string
                          description: The name of the workspace.
                          example: Workspace 1
                        messages_sent:
                          type: integer
                          description: The count of [messages sent](/journeys/channels/message-statuses/#sent) via any channel (email, SMS, in-app, push, slack) in the current billing period.
                          example: 100202
                        billable_messages_sent:
                          type: integer
                          description: The count of [emails sent](/journeys/channels/message-statuses/#sent) that are considered for billing in your current billing period. Ultimately, we only bill for the overages on your plan.
                          example: 75124
                        people:
                          type: integer
                          description: The current count of people profiles in the workspace. Updates roughly every hour.
                          example: 25666
                        object_types:
                          type: integer
                          description: The current count of object types in the workspace. Updates roughly every hour.
                          example: 4
                        objects:
                          type: integer
                          description: The current count of object profiles in the workspace. Updates roughly every hour.
                          example: 10
      x-codeSamples:
      - lang: Shell + Curl
        source: "curl --request GET \\\n  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \\\n  --url https://api.customer.io/v1/workspaces"
      - lang: Node + Native
        source: "const http = require(\"https\");\n\nconst options = {\n  \"method\": \"GET\",\n  \"hostname\": \"api.customer.io\",\n  \"port\": null,\n  \"path\": \"/v1/workspaces\",\n  \"headers\": {}\n};\n\nconst req = http.request(options, function (res) {\n  const chunks = [];\n\n  res.on(\"data\", function (chunk) {\n    chunks.push(chunk);\n  });\n\n  res.on(\"end\", function () {\n    const body = Buffer.concat(chunks);\n    console.log(body.toString());\n  });\n});\n\nreq.end();"
      - lang: Ruby + Native
        source: 'require ''uri''

          require ''net/http''

          require ''openssl''


          url = URI("https://api.customer.io/v1/workspaces")


          http = Net::HTTP.new(url.host, url.port)

          http.use_ssl = true

          http.verify_mode = OpenSSL::SSL::VERIFY_NONE


          request = Net::HTTP::Get.new(url)


          response = http.request(request)

          puts response.read_body'
      - lang: Python + Python3
        source: 'import http.client


          conn = http.client.HTTPSConnection("api.customer.io")


          conn.request("GET", "/v1/workspaces")


          res = conn.getresponse()

          data = res.read()


          print(data.decode("utf-8"))'
      - lang: Go + Native
        source: "package main\n\nimport (\n\t\"fmt\"\n\t\"net/http\"\n\t\"io/ioutil\"\n)\n\nfunc main() {\n\n\turl := \"https://api.customer.io/v1/workspaces\"\n\n\treq, _ := http.NewRequest(\"GET\", url, nil)\n\n\tres, _ := http.DefaultClient.Do(req)\n\n\tdefer res.Body.Close()\n\tbody, _ := ioutil.ReadAll(res.Body)\n\n\tfmt.Println(res)\n\tfmt.Println(string(body))\n\n}"
components:
  securitySchemes:
    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/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