openapi: 3.1.0
info:
  title: Segment Config Alias Catalog 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: Catalog
  description: Operations for browsing the Segment catalog of available sources and destination integrations.
paths:
  /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'
components:
  schemas:
    CatalogDestination:
      type: object
      properties:
        id:
          type: string
          description: The metadata ID of the catalog destination.
        name:
          type: string
          description: The name of the destination integration.
        slug:
          type: string
          description: The URL-friendly slug.
        description:
          type: string
          description: A description of the destination integration.
        logos:
          type: object
          description: Logo URLs for the integration.
          properties:
            default:
              type: string
              format: uri
              description: Default logo URL.
            alt:
              type: string
              format: uri
              description: Alternative logo URL.
            mark:
              type: string
              format: uri
              description: Mark logo URL.
        categories:
          type: array
          items:
            type: string
          description: Categories this destination belongs to.
        supportedMethods:
          type: object
          description: Which Segment methods this destination supports.
          properties:
            track:
              type: boolean
              description: Whether track calls are supported.
            identify:
              type: boolean
              description: Whether identify calls are supported.
            page:
              type: boolean
              description: Whether page calls are supported.
            screen:
              type: boolean
              description: Whether screen calls are supported.
            group:
              type: boolean
              description: Whether group calls are supported.
            alias:
              type: boolean
              description: Whether alias calls are supported.
    CatalogSource:
      type: object
      properties:
        id:
          type: string
          description: The metadata ID of the catalog source.
        name:
          type: string
          description: The name of the source integration.
        slug:
          type: string
          description: The URL-friendly slug.
        description:
          type: string
          description: A description of the source integration.
        logos:
          type: object
          description: Logo URLs for the integration.
          properties:
            default:
              type: string
              format: uri
              description: Default logo URL.
            alt:
              type: string
              format: uri
              description: Alternative logo URL.
            mark:
              type: string
              format: uri
              description: Mark logo URL.
        categories:
          type: array
          items:
            type: string
          description: Categories this source belongs to.
    Error:
      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
    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.
  parameters:
    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
  responses:
    Unauthorized:
      description: Authentication credentials were missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  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/