openapi: 3.0.3
info:
  title: Tealium Authentication Auth Collect API
  description: Provides JWT bearer token generation for Tealium v3 APIs. Exchange a username (email address) and API key for a time-limited JWT bearer token used to authenticate all other Tealium v3 API calls. Tokens are valid for 30 minutes. The response also includes a region-specific host for subsequent API calls. API keys are obtained from Tealium iQ Tag Management and are not used directly in API calls — only for token generation.
  version: '3.0'
  contact:
    name: Tealium Support
    url: https://docs.tealium.com/api/v3/getting-started/authentication/
servers:
- url: https://platform.tealiumapis.com/v3
  description: Tealium platform API base URL
tags:
- name: Collect
paths:
  /collect/event:
    get:
      operationId: collectEventGet
      summary: Send single event (GET)
      description: Sends a single event via HTTP GET. Returns a 1x1 transparent GIF image. Useful for pixel-based tracking scenarios.
      parameters:
      - name: tealium_account
        in: query
        required: true
        schema:
          type: string
        description: Tealium account name
      - name: tealium_profile
        in: query
        required: true
        schema:
          type: string
        description: Tealium profile name
      - name: tealium_event
        in: query
        required: true
        schema:
          type: string
        description: Event type identifier
      - name: tealium_visitor_id
        in: query
        required: false
        schema:
          type: string
        description: Visitor identifier (GUID or formatted known-visitor ID)
      - name: tealium_datasource
        in: query
        required: false
        schema:
          type: string
        description: Data source key
      responses:
        '200':
          description: Event accepted; returns 1x1 transparent GIF
          content:
            image/gif:
              schema:
                type: string
                format: binary
        '400':
          description: Bad request — missing required parameters
        '401':
          description: Unauthorized — invalid or expired bearer token
        '429':
          description: Too many requests — rate limit exceeded (100 events/second)
      tags:
      - Collect
    post:
      operationId: collectEventPost
      summary: Send single event (POST)
      description: Sends a single event via HTTP POST with a JSON body. Returns an empty JSON response with content-length 0.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EventPayload'
            example:
              tealium_account: my-account
              tealium_profile: main
              tealium_event: page_view
              tealium_datasource: abc123
              page_type: '123'
              page_name: testName
      responses:
        '200':
          description: Event accepted
        '400':
          description: Bad request — missing required fields, invalid JSON keys, or empty body
        '401':
          description: Unauthorized — invalid or expired bearer token
        '429':
          description: Too many requests — rate limit exceeded
      tags:
      - Collect
  /collect/bulk-event:
    post:
      operationId: collectBulkEvent
      summary: Send bulk events (up to 10)
      description: Sends up to 10 events in a single POST request. The shared object provides common fields applied to all events; individual event objects can override or extend them.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkEventPayload'
            example:
              shared:
                tealium_account: my-account
                tealium_profile: main
                tealium_environment: prod
                tealium_datasource: abc123
                tealium_visitor_id: abc123_071222_1
              events:
              - page_name: home
                tealium_event: page_view
              - page_name: checkout
                tealium_event: page_view
      responses:
        '200':
          description: Bulk events accepted
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '429':
          description: Too many requests — rate limit exceeded
      tags:
      - Collect
  /collect/regional/event:
    post:
      operationId: collectRegionalEvent
      summary: Send single event to regional endpoint
      description: Sends a single event to a region-specific endpoint. Use the regional host returned from the authentication API.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EventPayload'
      responses:
        '200':
          description: Event accepted
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '429':
          description: Too many requests
      tags:
      - Collect
  /collect/regional/bulk-event:
    post:
      operationId: collectRegionalBulkEvent
      summary: Send bulk events to regional endpoint
      description: Sends up to 10 events to a region-specific endpoint.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkEventPayload'
      responses:
        '200':
          description: Bulk events accepted
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '429':
          description: Too many requests
      tags:
      - Collect
  /collect/integration/event/accounts/{account}/profiles/{profile}/datasources/{datasourceId}:
    post:
      operationId: collectIntegrationEvent
      summary: Send event via webhook/integration datasource
      description: Sends a single event via a dedicated datasource integration endpoint. Returns 204 No Content on success. Suitable for webhook and connector-based integrations.
      parameters:
      - name: account
        in: path
        required: true
        schema:
          type: string
        description: Tealium account name
      - name: profile
        in: path
        required: true
        schema:
          type: string
        description: Tealium profile name
      - name: datasourceId
        in: path
        required: true
        schema:
          type: string
        description: Data source key for the integration
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IntegrationEventPayload'
            example:
              tealium_event: page_view
              tealium_datasource: abc123
              page_type: '123'
              page_name: homepage
      responses:
        '204':
          description: Event accepted — no content returned
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '429':
          description: Too many requests
      tags:
      - Collect
components:
  schemas:
    IntegrationEventPayload:
      type: object
      required:
      - tealium_event
      properties:
        tealium_event:
          type: string
          description: Event type identifier
        tealium_datasource:
          type: string
          description: Data source key
      additionalProperties:
        type: string
        description: Custom event attributes
    EventPayload:
      type: object
      required:
      - tealium_account
      - tealium_profile
      - tealium_event
      properties:
        tealium_account:
          type: string
          description: Tealium account name
        tealium_profile:
          type: string
          description: Tealium profile name
        tealium_event:
          type: string
          description: Event type identifier
        tealium_visitor_id:
          type: string
          description: Visitor identifier (GUID or formatted known-visitor ID)
        tealium_datasource:
          type: string
          description: Data source key
        tealium_environment:
          type: string
          enum:
          - dev
          - qa
          - prod
          description: Deployment environment
      additionalProperties:
        type: string
        description: Custom event attributes as additional key-value pairs
    BulkEventPayload:
      type: object
      required:
      - shared
      - events
      properties:
        shared:
          type: object
          description: Common fields applied to all events in this batch
          properties:
            tealium_account:
              type: string
            tealium_profile:
              type: string
            tealium_environment:
              type: string
              enum:
              - dev
              - qa
              - prod
            tealium_datasource:
              type: string
            tealium_visitor_id:
              type: string
          additionalProperties:
            type: string
        events:
          type: array
          description: Array of event objects (max 10 per request)
          maxItems: 10
          items:
            type: object
            required:
            - tealium_event
            properties:
              tealium_event:
                type: string
            additionalProperties:
              type: string