openapi: 3.2.0
info:
  version: v1.0.0
  title: External APIs for Customer Integration Destinations API
  description: APIs to create and fetch Clean Room and related details from LiveRamp (previously Habu) for Customer Integration.
  contact:
    name: LiveRamp (previously Habu)
    url: https://liveramp.com/
    email: platform_admin@habu.com
servers:
- description: External APIs for Customer Integration
  url: https://api.habu.com/v1/
security:
- application: []
tags:
- name: Destinations
paths:
  /destinations/partners:
    get:
      summary: List destination partners
      operationId: listDestinationPartners
      description: This operation fetches the list of destination partners available.
      responses:
        '200':
          description: Destination partners fetched successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListDestinationPartnersResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      tags:
      - Destinations
  /destinations:
    get:
      summary: List destination connections
      operationId: listDestinations
      description: This operation fetches a list destination connections (partner accounts) for the organisation.
      parameters:
      - name: limit
        in: query
        description: The number of destination connections returned per page - default is 30, minimum is 1, maximum is 100
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 30
      - name: offset
        in: query
        description: The offset - default is 0, minimum is 0
        schema:
          type: integer
          minimum: 0
          default: 0
      responses:
        '200':
          description: Destination connections fetched successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListDestinationsResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      tags:
      - Destinations
    post:
      summary: Create destination connection
      operationId: createDestination
      description: Creates a destination connection (partner account) for the organisation. requires name and partner id; credential and publicKey are optional depending on partner type.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDestinationRequest'
      responses:
        '200':
          description: Destination connection created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartnerAccount'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      tags:
      - Destinations
  /destinations/{partnerAccountId}:
    patch:
      summary: Update destination connection
      operationId: updateDestinationConnection
      description: Updates an existing destination connection (partner account) for the organization. Partner cannot be changed; only name, credential, and publicKey may be updated.
      parameters:
      - name: partnerAccountId
        in: path
        description: Partner Account ID for the destination connection to be updated
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateDestinationRequest'
      responses:
        '200':
          description: Destination connection updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateDestinationResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      tags:
      - Destinations
    delete:
      summary: Delete destination connection
      operationId: deleteDestinationConnection
      description: Deletes a destination connection (partner account) for the organization.
      parameters:
      - name: partnerAccountId
        in: path
        description: Partner Account ID for the destination connection to be deleted
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Destination connection deleted successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      tags:
      - Destinations
components:
  schemas:
    ListDestinationPartnersResponse:
      type: object
      properties:
        partners:
          type: array
          items:
            $ref: '#/components/schemas/Partner'
    PartnerConfig:
      type: object
      properties:
        ID:
          type: string
        name:
          type: string
        index:
          type: integer
          format: int32
        type:
          type: string
        encrypted:
          type: boolean
    PicanmixType:
      type: string
      enum:
      - UNKNOWN_PICANMIX_TYPE
      - USER_LIST
      - OFFLINE_CONVERSIONS
      - EXPORTS
      - QUESTION_USER_LIST
    PrimageCredential:
      type: object
      properties:
        ID:
          type: string
        name:
          type: string
        value:
          type: string
    DeleteResponse:
      type: object
      properties:
        success:
          type: boolean
    ListDestinationsResponse:
      type: object
      properties:
        partnerAccounts:
          type: array
          items:
            $ref: '#/components/schemas/PartnerAccount'
        total:
          type: integer
          description: Total count of destination connections
        limit:
          type: integer
          description: The number of destination connections returned per page
        offset:
          type: integer
          description: The offset used for pagination
    PrimageOrganizationCredential:
      type: object
      properties:
        ID:
          type: string
        name:
          type: string
        credentials:
          type: array
          items:
            $ref: '#/components/schemas/PrimageCredential'
    TimeAudit:
      type: object
      properties:
        createdAt:
          type: string
          format: date-time
          description: Timestamp for when the object was created
        updatedAt:
          type: string
          format: date-time
          description: Timestamp for when the object was last updated
        deletedAt:
          type: string
          format: date-time
          description: Timestamp for when the object was deleted (if applicable)
    UpdateDestinationResponse:
      type: object
      description: Response after updating a destination connection (partner account).
      properties:
        partnerAccount:
          $ref: '#/components/schemas/PartnerAccount'
    JobCount:
      type: object
      properties:
        jobType:
          type: string
        count:
          type: integer
          format: int32
          minimum: 0
    PartnerAccount:
      type: object
      properties:
        ID:
          type: string
        name:
          type: string
        organizationID:
          type: string
        partner:
          $ref: '#/components/schemas/Partner'
        credential:
          $ref: '#/components/schemas/PrimageOrganizationCredential'
        timeAudit:
          $ref: '#/components/schemas/TimeAudit'
        userAudit:
          $ref: '#/components/schemas/UserAudit'
        jobCount:
          type: array
          items:
            $ref: '#/components/schemas/JobCount'
        latestJobRunStatusCount:
          $ref: '#/components/schemas/LatestJobRunStatusCount'
        configStatus:
          $ref: '#/components/schemas/ConfigStatus'
        errorMessage:
          type: string
        publicKey:
          type: string
    LatestJobRunStatusCount:
      type: object
      properties:
        numSuccess:
          type: integer
          format: int32
          minimum: 0
        numProcessing:
          type: integer
          format: int32
          minimum: 0
        numThresholdWarning:
          type: integer
          format: int32
          minimum: 0
        numPartiallyFailed:
          type: integer
          format: int32
          minimum: 0
        numFailed:
          type: integer
          format: int32
          minimum: 0
        numQueued:
          type: integer
          format: int32
          minimum: 0
    ReturnObject:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
      required:
      - code
      - message
    UserAudit:
      type: object
      properties:
        createdBy:
          type: string
          description: Identifier of the user who created the object
        updatedBy:
          type: string
          description: Identifier of the user who last updated the object
    CreateDestinationRequest:
      type: object
      required:
      - name
      - partner
      description: Request to create a destination connection (partner account).
      properties:
        name:
          type: string
          description: Display name for the destination connection
        partner:
          type: object
          required:
          - ID
          properties:
            ID:
              type: string
              description: Partner id (from list destination partners)
          description: Partner to connect; only ID is required for create
        credential:
          $ref: '#/components/schemas/PrimageOrganizationCredential'
          description: Optional; required for partners with a credential source. Use existing ID or name + credentials for new.
        publicKey:
          type: string
          description: Optional; only allowed for certain partners (e.g. S3 IAM Role Export, GCS Export)
    Partner:
      type: object
      properties:
        ID:
          type: string
        name:
          type: string
        displayName:
          type: string
        logoUrl:
          type: string
        credentialSourceName:
          type: string
        partnerConfigArray:
          $ref: '#/components/schemas/PartnerConfigs'
        timeAudit:
          $ref: '#/components/schemas/TimeAudit'
        userAudit:
          $ref: '#/components/schemas/UserAudit'
        type:
          $ref: '#/components/schemas/PicanmixType'
        credentialSources:
          type: array
          items:
            type: string
        partnerConfigMap:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/PartnerConfigs'
    PartnerConfigs:
      type: array
      items:
        $ref: '#/components/schemas/PartnerConfig'
    ConfigStatus:
      type: string
      enum:
      - UNKNOWN_CONFIG_STATUS
      - CONFIG_PENDING
      - CONFIG_CONFIGURED
      - CONFIG_FAILED
      - CONFIG_AVAILABLE
    UpdateDestinationRequest:
      type: object
      description: Request to update a destination connection (partner account).
      properties:
        name:
          type: string
          description: Optional; if provided, updates name for the destination connection.
        credential:
          $ref: '#/components/schemas/PrimageOrganizationCredential'
          description: Optional; if provided, updates credential associated with this destination connection.
        publicKey:
          type: string
          description: Optional; if provided, updates public key associated with this destination connection.
  responses:
    BadRequest:
      description: Bad Request - Incorrect syntax or request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ReturnObject'
        application/xml:
          schema:
            $ref: '#/components/schemas/ReturnObject'
    Forbidden:
      description: This action is not allowed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ReturnObject'
        application/xml:
          schema:
            $ref: '#/components/schemas/ReturnObject'
    Unauthorized:
      description: Authorization information was missing or invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ReturnObject'
        application/xml:
          schema:
            $ref: '#/components/schemas/ReturnObject'
    NotFound:
      description: The specified resource was not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ReturnObject'
        application/xml:
          schema:
            $ref: '#/components/schemas/ReturnObject'
    InternalServerError:
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ReturnObject'
        application/xml:
          schema:
            $ref: '#/components/schemas/ReturnObject'
  securitySchemes:
    application:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api.habu.com/v1/oauth/token
          scopes: {}