segment Tracking Plans API

openapi: 3.1.0
info:
  title: Segment Config Alias Tracking Plans 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: Tracking Plans
  description: Operations for managing tracking plans that enforce data schemas.
paths:
  /workspaces/{workspaceName}/tracking-plans:
    get:
      operationId: listTrackingPlans
      summary: List tracking plans
      description: Returns a list of all tracking plans in the workspace.
      tags:
      - Tracking Plans
      parameters:
      - $ref: '#/components/parameters/WorkspaceName'
      responses:
        '200':
          description: Tracking plans retrieved successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  tracking_plans:
                    type: array
                    items:
                      $ref: '#/components/schemas/TrackingPlan'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createTrackingPlan
      summary: Create tracking plan
      description: Creates a new tracking plan in the workspace.
      tags:
      - Tracking Plans
      parameters:
      - $ref: '#/components/parameters/WorkspaceName'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - tracking_plan
              properties:
                tracking_plan:
                  type: object
                  required:
                  - display_name
                  properties:
                    display_name:
                      type: string
                      description: The display name of the tracking plan.
                    rules:
                      type: object
                      description: The rules for the tracking plan.
                      properties:
                        events:
                          type: array
                          description: Event rules for the tracking plan.
                          items:
                            $ref: '#/components/schemas/TrackingPlanRule'
      responses:
        '200':
          description: Tracking plan created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrackingPlan'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /tracking-plans:
    get:
      operationId: listTrackingPlans
      summary: List tracking plans
      description: Returns a list of all tracking plans in the workspace.
      tags:
      - Tracking Plans
      parameters:
      - $ref: '#/components/parameters/PaginationCursor'
      - $ref: '#/components/parameters/PaginationCount'
      responses:
        '200':
          description: Tracking plans retrieved successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      trackingPlans:
                        type: array
                        items:
                          $ref: '#/components/schemas/TrackingPlan_2'
                      pagination:
                        $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createTrackingPlan
      summary: Create tracking plan
      description: Creates a new tracking plan in the workspace with the specified rules and configuration.
      tags:
      - Tracking Plans
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              properties:
                name:
                  type: string
                  description: The name of the tracking plan.
                description:
                  type: string
                  description: A description of the tracking plan.
                type:
                  type: string
                  description: The type of tracking plan.
                  enum:
                  - ENGAGE
                  - LIVE
                  - PROPERTY_LIBRARY
                  - RULE_LIBRARY
                  - TEMPLATE
                rules:
                  type: array
                  description: The rules that define the tracking plan.
                  items:
                    $ref: '#/components/schemas/TrackingPlanRule_2'
      responses:
        '200':
          description: Tracking plan created successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      trackingPlan:
                        $ref: '#/components/schemas/TrackingPlan_2'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /tracking-plans/{trackingPlanId}:
    get:
      operationId: getTrackingPlan
      summary: Get tracking plan
      description: Returns a single tracking plan by its ID.
      tags:
      - Tracking Plans
      parameters:
      - $ref: '#/components/parameters/TrackingPlanId'
      responses:
        '200':
          description: Tracking plan retrieved successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      trackingPlan:
                        $ref: '#/components/schemas/TrackingPlan_2'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: updateTrackingPlan
      summary: Update tracking plan
      description: Updates an existing tracking plan with the provided changes.
      tags:
      - Tracking Plans
      parameters:
      - $ref: '#/components/parameters/TrackingPlanId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: Updated name for the tracking plan.
                description:
                  type: string
                  description: Updated description.
      responses:
        '200':
          description: Tracking plan updated successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      trackingPlan:
                        $ref: '#/components/schemas/TrackingPlan_2'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteTrackingPlan
      summary: Delete tracking plan
      description: Deletes a tracking plan from the workspace.
      tags:
      - Tracking Plans
      parameters:
      - $ref: '#/components/parameters/TrackingPlanId'
      responses:
        '200':
          description: Tracking plan deleted successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      status:
                        type: string
                        description: Status of the delete operation.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  parameters:
    WorkspaceName:
      name: workspaceName
      in: path
      required: true
      description: The name of the workspace.
      schema:
        type: string
    PaginationCursor:
      name: pagination[cursor]
      in: query
      description: Cursor for pagination. Use the cursor returned in a previous response to fetch the next page.
      schema:
        type: string
    PaginationCount:
      name: pagination[count]
      in: query
      description: Number of items to return per page.
      schema:
        type: integer
        minimum: 1
        maximum: 200
        default: 10
    TrackingPlanId:
      name: trackingPlanId
      in: path
      required: true
      description: The unique identifier of the tracking plan.
      schema:
        type: string
  schemas:
    TrackingPlanRule_2:
      type: object
      properties:
        type:
          type: string
          description: The type of event this rule applies to.
          enum:
          - COMMON
          - GROUP
          - IDENTIFY
          - PAGE
          - SCREEN
          - TRACK
        key:
          type: string
          description: The event name this rule matches, for track events.
        jsonSchema:
          type: object
          description: The JSON Schema that defines the expected properties.
          additionalProperties: true
        version:
          type: number
          description: The version of the rule.
    Error:
      type: object
      properties:
        error:
          type: string
          description: The error type.
        message:
          type: string
          description: A human-readable error message.
    TrackingPlan_2:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier of the tracking plan.
        name:
          type: string
          description: The name of the tracking plan.
        slug:
          type: string
          description: The URL-friendly slug of the tracking plan.
        description:
          type: string
          description: A description of the tracking plan.
        type:
          type: string
          description: The type of tracking plan.
          enum:
          - ENGAGE
          - LIVE
          - PROPERTY_LIBRARY
          - RULE_LIBRARY
          - TEMPLATE
        createdAt:
          type: string
          format: date-time
          description: When the tracking plan was created.
        updatedAt:
          type: string
          format: date-time
          description: When the tracking plan was last updated.
    TrackingPlanRule:
      type: object
      properties:
        name:
          type: string
          description: The event name this rule applies to.
        description:
          type: string
          description: A description of the event.
        rules:
          type: object
          description: The JSON Schema rules for the event properties.
          additionalProperties: true
        version:
          type: number
          description: The version of the rule.
    Pagination:
      type: object
      properties:
        current:
          type: string
          description: Cursor pointing to the current page.
        next:
          type: string
          description: Cursor pointing to the next page. Null if no more pages.
        totalEntries:
          type: integer
          description: Total number of entries across all pages.
    Error_2:
      type: object
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
                description: The error type.
              message:
                type: string
                description: A human-readable error message.
              field:
                type: string
                description: The field that caused the error, if applicable.
              data:
                type: object
                description: Additional error data.
                additionalProperties: true
    TrackingPlan:
      type: object
      properties:
        name:
          type: string
          description: The fully qualified name of the tracking plan.
        display_name:
          type: string
          description: The display name of the tracking plan.
        rules:
          type: object
          description: The rules of the tracking plan.
          properties:
            events:
              type: array
              description: Event rules.
              items:
                $ref: '#/components/schemas/TrackingPlanRule'
        create_time:
          type: string
          format: date-time
          description: When the tracking plan was created.
        update_time:
          type: string
          format: date-time
          description: When the tracking plan was last updated.
  responses:
    Unauthorized:
      description: Authentication credentials were missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: The request was invalid or malformed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error_2'
  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/