Segment Public API

openapi: 3.1.0
info:
  title: Segment Public API
  description: >-
    The Segment Public API allows developers to programmatically manage
    Segment workspaces and their resources. It supports full CRUD operations
    for sources, destinations, warehouses, tracking plans, functions,
    transformations, and catalog entries. The API follows REST conventions
    with standard HTTP methods and predictable resource-oriented URLs. It
    is available for Team and Business tier customers and is the recommended
    API going forward, replacing the older Config API.
  version: '1.0.0'
  contact:
    name: Segment Support
    url: https://segment.com/help/
  termsOfService: https://segment.com/legal/terms/
externalDocs:
  description: Segment Public API Documentation
  url: https://docs.segmentapis.com/
servers:
  - url: https://api.segmentapis.com
    description: Production Server
tags:
  - name: Catalog
    description: >-
      Operations for browsing the Segment catalog of available sources
      and destination integrations.
  - name: Destinations
    description: >-
      Operations for managing destinations where collected data is
      sent, including configuration and connection settings.
  - name: Functions
    description: >-
      Operations for managing custom functions that transform or
      enrich data flowing through Segment.
  - name: Labels
    description: >-
      Operations for managing labels used to organize and control
      access to workspace resources.
  - name: Regulations
    description: >-
      Operations for managing data privacy regulations and
      suppression requests.
  - name: Sources
    description: >-
      Operations for creating, reading, updating, and deleting data
      collection sources within a workspace.
  - name: Tracking Plans
    description: >-
      Operations for managing tracking plans that define and enforce
      data schemas for event tracking.
  - name: Transformations
    description: >-
      Operations for managing transformations that modify event data
      before it reaches destinations.
  - name: Warehouses
    description: >-
      Operations for managing data warehouse connections, including
      creating and configuring warehouse destinations.
  - name: Workspaces
    description: >-
      Operations for managing Segment workspaces, including retrieving
      workspace details and configuration.
security:
  - bearerAuth: []
paths:
  /workspace:
    get:
      operationId: getWorkspace
      summary: Get workspace
      description: >-
        Returns the workspace associated with the access token used
        to make the request, including the workspace name, ID, and slug.
      tags:
        - Workspaces
      responses:
        '200':
          description: Workspace retrieved successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      workspace:
                        $ref: '#/components/schemas/Workspace'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /sources:
    get:
      operationId: listSources
      summary: List sources
      description: >-
        Returns a list of all sources in the workspace, including their
        configuration, write keys, and metadata.
      tags:
        - Sources
      parameters:
        - $ref: '#/components/parameters/PaginationCursor'
        - $ref: '#/components/parameters/PaginationCount'
      responses:
        '200':
          description: Sources retrieved successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      sources:
                        type: array
                        items:
                          $ref: '#/components/schemas/Source'
                      pagination:
                        $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createSource
      summary: Create source
      description: >-
        Creates a new source in the workspace with the specified
        configuration and metadata.
      tags:
        - Sources
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - slug
                - metadataId
              properties:
                slug:
                  type: string
                  description: >-
                    URL-friendly name for the source.
                metadataId:
                  type: string
                  description: >-
                    The ID of the source metadata from the catalog.
                enabled:
                  type: boolean
                  description: >-
                    Whether the source is enabled.
                settings:
                  type: object
                  description: >-
                    Configuration settings for the source.
                  additionalProperties: true
      responses:
        '200':
          description: Source created successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      source:
                        $ref: '#/components/schemas/Source'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /sources/{sourceId}:
    get:
      operationId: getSource
      summary: Get source
      description: >-
        Returns a single source by its ID, including its configuration,
        write key, and metadata.
      tags:
        - Sources
      parameters:
        - $ref: '#/components/parameters/SourceId'
      responses:
        '200':
          description: Source retrieved successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      source:
                        $ref: '#/components/schemas/Source'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: updateSource
      summary: Update source
      description: >-
        Updates an existing source with the provided configuration changes.
      tags:
        - Sources
      parameters:
        - $ref: '#/components/parameters/SourceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: >-
                    Updated name for the source.
                enabled:
                  type: boolean
                  description: >-
                    Whether the source is enabled.
                slug:
                  type: string
                  description: >-
                    Updated URL-friendly name.
                settings:
                  type: object
                  description: >-
                    Updated configuration settings.
                  additionalProperties: true
      responses:
        '200':
          description: Source updated successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      source:
                        $ref: '#/components/schemas/Source'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteSource
      summary: Delete source
      description: >-
        Deletes a source from the workspace by its ID. This action
        is irreversible.
      tags:
        - Sources
      parameters:
        - $ref: '#/components/parameters/SourceId'
      responses:
        '200':
          description: Source 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'
  /destinations:
    get:
      operationId: listDestinations
      summary: List destinations
      description: >-
        Returns a list of all destinations in the workspace, including
        their configuration and connection status.
      tags:
        - Destinations
      parameters:
        - $ref: '#/components/parameters/PaginationCursor'
        - $ref: '#/components/parameters/PaginationCount'
      responses:
        '200':
          description: Destinations retrieved successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      destinations:
                        type: array
                        items:
                          $ref: '#/components/schemas/Destination'
                      pagination:
                        $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createDestination
      summary: Create destination
      description: >-
        Creates a new destination connected to a source in the workspace.
      tags:
        - Destinations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - sourceId
                - metadataId
              properties:
                sourceId:
                  type: string
                  description: >-
                    The ID of the source to connect.
                metadataId:
                  type: string
                  description: >-
                    The ID of the destination metadata from the catalog.
                enabled:
                  type: boolean
                  description: >-
                    Whether the destination is enabled.
                name:
                  type: string
                  description: >-
                    Optional display name for the destination.
                settings:
                  type: object
                  description: >-
                    Configuration settings for the destination.
                  additionalProperties: true
      responses:
        '200':
          description: Destination created successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      destination:
                        $ref: '#/components/schemas/Destination'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /destinations/{destinationId}:
    get:
      operationId: getDestination
      summary: Get destination
      description: >-
        Returns a single destination by its ID, including its configuration
        and connection status.
      tags:
        - Destinations
      parameters:
        - $ref: '#/components/parameters/DestinationId'
      responses:
        '200':
          description: Destination retrieved successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      destination:
                        $ref: '#/components/schemas/Destination'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: updateDestination
      summary: Update destination
      description: >-
        Updates an existing destination with the provided changes.
      tags:
        - Destinations
      parameters:
        - $ref: '#/components/parameters/DestinationId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: >-
                    Updated display name.
                enabled:
                  type: boolean
                  description: >-
                    Whether the destination is enabled.
                settings:
                  type: object
                  description: >-
                    Updated configuration settings.
                  additionalProperties: true
      responses:
        '200':
          description: Destination updated successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      destination:
                        $ref: '#/components/schemas/Destination'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteDestination
      summary: Delete destination
      description: >-
        Deletes a destination from the workspace by its ID.
      tags:
        - Destinations
      parameters:
        - $ref: '#/components/parameters/DestinationId'
      responses:
        '200':
          description: Destination 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'
  /warehouses:
    get:
      operationId: listWarehouses
      summary: List warehouses
      description: >-
        Returns a list of all warehouses in the workspace.
      tags:
        - Warehouses
      parameters:
        - $ref: '#/components/parameters/PaginationCursor'
        - $ref: '#/components/parameters/PaginationCount'
      responses:
        '200':
          description: Warehouses retrieved successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      warehouses:
                        type: array
                        items:
                          $ref: '#/components/schemas/Warehouse'
                      pagination:
                        $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createWarehouse
      summary: Create warehouse
      description: >-
        Creates a new warehouse connection in the workspace.
      tags:
        - Warehouses
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - metadataId
              properties:
                metadataId:
                  type: string
                  description: >-
                    The ID of the warehouse metadata from the catalog.
                enabled:
                  type: boolean
                  description: >-
                    Whether the warehouse is enabled.
                settings:
                  type: object
                  description: >-
                    Configuration settings for the warehouse connection.
                  additionalProperties: true
      responses:
        '200':
          description: Warehouse created successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      warehouse:
                        $ref: '#/components/schemas/Warehouse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /warehouses/{warehouseId}:
    get:
      operationId: getWarehouse
      summary: Get warehouse
      description: >-
        Returns a single warehouse by its ID.
      tags:
        - Warehouses
      parameters:
        - $ref: '#/components/parameters/WarehouseId'
      responses:
        '200':
          description: Warehouse retrieved successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      warehouse:
                        $ref: '#/components/schemas/Warehouse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: updateWarehouse
      summary: Update warehouse
      description: >-
        Updates an existing warehouse with the provided changes.
      tags:
        - Warehouses
      parameters:
        - $ref: '#/components/parameters/WarehouseId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                enabled:
                  type: boolean
                  description: >-
                    Whether the warehouse is enabled.
                settings:
                  type: object
                  description: >-
                    Updated configuration settings.
                  additionalProperties: true
      responses:
        '200':
          description: Warehouse updated successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      warehouse:
                        $ref: '#/components/schemas/Warehouse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteWarehouse
      summary: Delete warehouse
      description: >-
        Deletes a warehouse connection from the workspace.
      tags:
        - Warehouses
      parameters:
        - $ref: '#/components/parameters/WarehouseId'
      responses:
        '200':
          description: Warehouse 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'
  /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'
                      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'
      responses:
        '200':
          description: Tracking plan created successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      trackingPlan:
                        $ref: '#/components/schemas/TrackingPlan'
        '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'
        '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'
        '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'
  /catalog/sources:
    get:
      operationId: listCatalogSources
      summary: List catalog sources
      description: >-
        Returns a list of all available source integrations in the
        Segment catalog.
      tags:
        - Catalog
      parameters:
        - $ref: '#/components/parameters/PaginationCursor'
        - $ref: '#/components/parameters/PaginationCount'
      responses:
        '200':
          description: Catalog sources retrieved successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      sourcesCatalog:
                        type: array
                        items:
                          $ref: '#/components/schemas/CatalogSource'
                      pagination:
                        $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /catalog/sources/{sourceMetadataId}:
    get:
      operationId: getCatalogSource
      summary: Get catalog source
      description: >-
        Returns a single source integration from the catalog by its
        metadata ID.
      tags:
        - Catalog
      parameters:
        - name: sourceMetadataId
          in: path
          required: true
          description: >-
            The ID of the source metadata.
          schema:
            type: string
      responses:
        '200':
          description: Catalog source retrieved successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      sourceCatalog:
                        $ref: '#/components/schemas/CatalogSource'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /catalog/destinations:
    get:
      operationId: listCatalogDestinations
      summary: List catalog destinations
      description: >-
        Returns a list of all available destination integrations in the
        Segment catalog.
      tags:
        - Catalog
      parameters:
        - $ref: '#/components/parameters/PaginationCursor'
        - $ref: '#/components/parameters/PaginationCount'
      responses:
        '200':
          description: Catalog destinations retrieved successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      destinationsCatalog:
                        type: array
                        items:
                          $ref: '#/components/schemas/CatalogDestination'
                      pagination:
                        $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /catalog/destinations/{destinationMetadataId}:
    get:
      operationId: getCatalogDestination
      summary: Get catalog destination
      description: >-
        Returns a single destination integration from the catalog by its
        metadata ID.
      tags:
        - Catalog
      parameters:
        - name: destinationMetadataId
          in: path
          required: true
          description: >-
            The ID of the destination metadata.
          schema:
            type: string
      responses:
        '200':
          description: Catalog destination retrieved successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      destinationCatalog:
                        $ref: '#/components/schemas/CatalogDestination'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /functions:
    get:
      operationId: listFunctions
      summary: List functions
      description: >-
        Returns a list of all custom functions in the workspace.
      tags:
        - Functions
      parameters:
        - $ref: '#/components/parameters/PaginationCursor'
        - $ref: '#/components/parameters/PaginationCount'
        - name: resourceType
          in: query
          description: >-
            Filter functions by resource type.
          schema:
            type: string
            enum:
              - DESTINATION
              - INSERT_DESTINATION
              - INSERT_SOURCE
              - SOURCE
      responses:
        '200':
          description: Functions retrieved successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      functions:
                        type: array
                        items:
                          $ref: '#/components/schemas/Function'
                      pagination:
                        $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createFunction
      summary: Create function
      description: >-
        Creates a new custom function in the workspace.
      tags:
        - Functions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - code
                - resourceType
              properties:
                code:
                  type: string
                  description: >-
                    The 

# --- truncated at 32 KB (67 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/segment/refs/heads/main/openapi/segment-public-api-openapi.yml