segment Destinations API

openapi: 3.2.0
info:
  title: Segment Destinations API
  version: 1.0.0
  contact:
    name: Segment Support
    url: https://segment.com/help/
  termsOfService: https://segment.com/legal/terms/
  x-refined-note:
  - x-status differs across the merged source definitions and was not carried
  description: 'Operations tagged Destinations across 2 of this provider''s published API definitions: segment-config-api-openapi.yml, segment-public-api-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://platform.segmentapis.com/v1beta
  description: Production Server (v1beta)
- url: https://api.segmentapis.com
  description: Production Server
security:
- bearerAuth: []
tags:
- name: Destinations
  description: Operations for managing destinations where collected data is sent.
paths:
  /workspaces/{workspaceName}/sources/{sourceName}/destinations:
    get:
      operationId: listDestinations
      summary: List destinations
      description: Returns a list of all destinations for a specific source in the workspace.
      tags:
      - Destinations
      parameters:
      - $ref: '#/components/parameters/WorkspaceName'
      - $ref: '#/components/parameters/SourceName'
      responses:
        '200':
          description: Destinations retrieved successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  destinations:
                    type: array
                    items:
                      $ref: '#/components/schemas/Destination'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createDestination
      summary: Create destination
      description: Creates a new destination for a specific source in the workspace.
      tags:
      - Destinations
      parameters:
      - $ref: '#/components/parameters/WorkspaceName'
      - $ref: '#/components/parameters/SourceName'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - destination
              properties:
                destination:
                  type: object
                  required:
                  - name
                  - connection_mode
                  properties:
                    name:
                      type: string
                      description: The fully qualified name of the destination.
                    connection_mode:
                      type: string
                      description: The connection mode for the destination.
                      enum:
                      - CLOUD
                      - DEVICE
                      - UNSPECIFIED
                    enabled:
                      type: boolean
                      description: Whether the destination is enabled.
                    config:
                      type: array
                      description: Configuration settings for the destination.
                      items:
                        $ref: '#/components/schemas/DestinationConfig'
      responses:
        '200':
          description: Destination created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Destination'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
    servers:
    - url: https://platform.segmentapis.com/v1beta
      description: Production Server (v1beta)
  /workspaces/{workspaceName}/sources/{sourceName}/destinations/{destinationName}:
    get:
      operationId: getDestination
      summary: Get destination
      description: Returns a single destination by name for a specific source.
      tags:
      - Destinations
      parameters:
      - $ref: '#/components/parameters/WorkspaceName'
      - $ref: '#/components/parameters/SourceName'
      - $ref: '#/components/parameters/DestinationName'
      responses:
        '200':
          description: Destination retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Destination'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: updateDestination
      summary: Update destination
      description: Updates a destination's configuration, including enabling or disabling it.
      tags:
      - Destinations
      parameters:
      - $ref: '#/components/parameters/WorkspaceName'
      - $ref: '#/components/parameters/SourceName'
      - $ref: '#/components/parameters/DestinationName'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                destination:
                  type: object
                  properties:
                    enabled:
                      type: boolean
                      description: Whether the destination is enabled.
                    config:
                      type: array
                      description: Updated configuration settings.
                      items:
                        $ref: '#/components/schemas/DestinationConfig'
      responses:
        '200':
          description: Destination updated successfully.
          content:
            application/json:
              schema:
                $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 a source in the workspace.
      tags:
      - Destinations
      parameters:
      - $ref: '#/components/parameters/WorkspaceName'
      - $ref: '#/components/parameters/SourceName'
      - $ref: '#/components/parameters/DestinationName'
      responses:
        '200':
          description: Destination deleted successfully.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    servers:
    - url: https://platform.segmentapis.com/v1beta
      description: Production Server (v1beta)
  /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_2'
                      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_2'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
    servers:
    - url: https://api.segmentapis.com
      description: Production Server
  /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_2'
        '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_2'
        '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'
    servers:
    - url: https://api.segmentapis.com
      description: Production Server
components:
  responses:
    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'
    Unauthorized:
      description: Authentication credentials were missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
          description: The error type.
        message:
          type: string
          description: A human-readable error message.
    Destination:
      type: object
      properties:
        name:
          type: string
          description: The fully qualified name of the destination.
        parent:
          type: string
          description: The parent source name.
        display_name:
          type: string
          description: The display name of the destination.
        enabled:
          type: boolean
          description: Whether the destination is enabled.
        connection_mode:
          type: string
          description: The connection mode.
          enum:
          - CLOUD
          - DEVICE
          - UNSPECIFIED
        config:
          type: array
          description: Configuration settings for the destination.
          items:
            $ref: '#/components/schemas/DestinationConfig'
        create_time:
          type: string
          format: date-time
          description: When the destination was created.
        update_time:
          type: string
          format: date-time
          description: When the destination was last updated.
    DestinationConfig:
      type: object
      properties:
        name:
          type: string
          description: The fully qualified name of the config setting.
        display_name:
          type: string
          description: The display name of the setting.
        value:
          description: The value of the setting. Can be any JSON type.
        type:
          type: string
          description: The data type of the setting.
          enum:
          - boolean
          - string
          - number
          - list
          - map
          - mixed
    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
    Destination_2:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier of the destination.
        name:
          type: string
          description: The display name of the destination.
        enabled:
          type: boolean
          description: Whether the destination is enabled.
        sourceId:
          type: string
          description: The ID of the connected source.
        metadata:
          $ref: '#/components/schemas/CatalogDestination'
        settings:
          type: object
          description: Configuration settings for the destination.
          additionalProperties: true
        labels:
          type: array
          items:
            $ref: '#/components/schemas/Label'
          description: Labels applied to the destination.
    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.
    Label:
      type: object
      properties:
        key:
          type: string
          description: The label key.
        value:
          type: string
          description: The label value.
        description:
          type: string
          description: A description of the label.
    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:
    DestinationName:
      name: destinationName
      in: path
      required: true
      description: The name of the destination.
      schema:
        type: string
    SourceName:
      name: sourceName
      in: path
      required: true
      description: The name of the source.
      schema:
        type: string
    WorkspaceName:
      name: workspaceName
      in: path
      required: true
      description: The name of the workspace.
      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
    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
    DestinationId:
      name: destinationId
      in: path
      required: true
      description: The unique identifier of the destination.
      schema:
        type: string
  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.
x-refined-from:
- segment-config-api-openapi.yml
- segment-public-api-openapi.yml