openapi: 3.1.0
info:
  title: Segment Config Alias Batch API
  description: The Segment Config API allows programmatic management of Segment workspaces, sources, destinations, and other configuration resources. It provides endpoints to list workspace sources and destinations, create or delete destinations, and manage tracking plans. As of early 2024, Segment has stopped issuing new Config API tokens and recommends migrating to the Public API for access to the latest features. The Config API remains functional for existing users but is no longer actively developed.
  version: 1.0.0
  contact:
    name: Segment Support
    url: https://segment.com/help/
  termsOfService: https://segment.com/legal/terms/
  x-status: deprecated
servers:
- url: https://platform.segmentapis.com/v1beta
  description: Production Server (v1beta)
security:
- bearerAuth: []
tags:
- name: Batch
  description: Operations for sending multiple calls in a single request.
paths:
  /batch:
    post:
      operationId: batch
      summary: Send a batch of events
      description: Sends multiple identify, track, page, screen, group, and alias calls in a single request. The batch endpoint accepts up to 500 KB per request and a maximum of 2500 events per batch. Each individual event must be less than 32 KB.
      tags:
      - Batch
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchCall'
      responses:
        '200':
          description: Batch accepted successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '400':
          description: Invalid request payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Invalid or missing write key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    Context:
      type: object
      description: Dictionary of extra context for the call. Context is a dictionary of extra information that provides useful context about a data point, such as the user's IP address, locale, or device information.
      properties:
        active:
          type: boolean
          description: Whether the user is active.
        ip:
          type: string
          description: The IP address of the user.
        locale:
          type: string
          description: The locale string for the user.
        userAgent:
          type: string
          description: The user agent string of the client.
        library:
          type: object
          description: Information about the library making the call.
          properties:
            name:
              type: string
              description: The name of the library.
            version:
              type: string
              description: The version of the library.
        page:
          type: object
          description: Information about the current page.
          properties:
            path:
              type: string
              description: The path of the page.
            referrer:
              type: string
              format: uri
              description: The referrer URL.
            search:
              type: string
              description: The search query string.
            title:
              type: string
              description: The page title.
            url:
              type: string
              format: uri
              description: The full URL of the page.
        device:
          type: object
          description: Information about the user's device.
          properties:
            id:
              type: string
              description: The device ID.
            manufacturer:
              type: string
              description: The device manufacturer.
            model:
              type: string
              description: The device model.
            name:
              type: string
              description: The device name.
            type:
              type: string
              description: The device type.
    BatchCall:
      type: object
      required:
      - batch
      description: A batch call sends multiple events in a single request.
      properties:
        batch:
          type: array
          description: An array of identify, track, page, screen, group, or alias call objects. Maximum 2500 events per batch. Each event must be less than 32 KB.
          maxItems: 2500
          items:
            type: object
            required:
            - type
            properties:
              type:
                type: string
                description: The type of call.
                enum:
                - identify
                - track
                - page
                - screen
                - group
                - alias
              userId:
                type: string
                description: Unique identifier for the user.
              anonymousId:
                type: string
                description: A pseudo-unique substitute for a user ID.
              event:
                type: string
                description: Event name, required for track calls.
              properties:
                type: object
                description: Event or page/screen properties.
                additionalProperties: true
              traits:
                type: object
                description: User or group traits.
                additionalProperties: true
              groupId:
                type: string
                description: Group ID, required for group calls.
              previousId:
                type: string
                description: Previous ID, required for alias calls.
              name:
                type: string
                description: Page or screen name.
              context:
                $ref: '#/components/schemas/Context'
              integrations:
                $ref: '#/components/schemas/Integrations'
              timestamp:
                type: string
                format: date-time
                description: ISO 8601 date string.
              messageId:
                type: string
                description: Unique identifier for the message.
        context:
          $ref: '#/components/schemas/Context'
        integrations:
          $ref: '#/components/schemas/Integrations'
    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          description: Always false for error responses.
        message:
          type: string
          description: A human-readable error message.
    SuccessResponse:
      type: object
      properties:
        success:
          type: boolean
          description: Whether the request was accepted.
    Integrations:
      type: object
      description: Dictionary of destinations to enable or disable. Pass a destination name as key and true/false as the value to control which destinations receive the data.
      additionalProperties:
        oneOf:
        - type: boolean
        - type: object
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Segment Config API access token. Note that as of early 2024, Segment has stopped issuing new Config API tokens.
externalDocs:
  description: Segment Config API Documentation
  url: https://segment.com/docs/api/config-api/