Adobe Suite Source connections API

openapi: 3.2.0
info:
  title: Adobe Suite Source connections API
  version: '1.0'
  description: 'Operations tagged Source connections across 2 of this provider''s published API definitions: adobe-suite-aep-destinations-openapi.yaml, adobe-suite-aep-flow-service-openapi.yaml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://{environment}.adobe.io/data/foundation/flowservice
  description: Adobe IO gateway endpoint
  variables:
    environment:
      default: platform
      enum:
      - platform
      - platform-stage
- url: //{environment}.adobe.io/data/foundation/flowservice
  variables:
    environment:
      default: platform
      enum:
      - platform
      - platform-stage
tags:
- name: Source connections
  description: Source connections create and manage a connection to the internal source from where data is exported. For destination connections, the source connection can be either the Experience Platform Profile Store or the Experience Platform Data Lake. Source connections contain information like data source, data format, and the source connection ID needed to create a dataflow. A source connection instance is specific to a tenant and organization.
paths:
  /sourceConnections:
    get:
      tags:
      - Source connections
      summary: Retrieve a list of source connections for destinations
      description: 'You can retrieve a list of all source connections for destinations in your organization by making a GET request to the `/sourceConnections` endpoint. <br> You can use query parameters to return only the base connections for a specific destination type. To do this, pass in the `connectionSpec.id` of the desired destination by using the `property` query parameter, as shown further below.

        '
      operationId: getSourceConnections
      parameters:
      - $ref: '#/components/parameters/Authorization'
      - $ref: '#/components/parameters/XApiKey'
      - $ref: '#/components/parameters/XImsOrgId'
      - $ref: '#/components/parameters/XSandboxId'
      - $ref: '#/components/parameters/Accept'
      - in: query
        name: property
        description: 'A comma-separated list of top-level object properties to be returned in the response. Used to cut down the amount of data returned in the response body. For example, `property=id==f2d1a98b-6b8c-420b-80a1-696c3f192eb2,b6730e09-7da6-40e2-b5cf-289545056dc3,49d17eff-9fa7-4e92-b84e-ab65fcb4730a`.

          '
        required: false
        schema:
          type: string
        examples:
          filterProfileSourceConnection:
            summary: Filter source connection to the Experience Platform Profile Store
            value: connectionSpec.id==8a9c3494-9708-43d7-ae3f-cda01e5030e1
          filterProfileSourceConnectionByDate:
            summary: Filter all source connections to the Experience Platform Profile Store created after August 7th, 2022
            value: createdAt>=1659907304000&property=connectionSpec.id==8a9c3494-9708-43d7-ae3f-cda01e5030e1
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/orderby'
      - $ref: '#/components/parameters/count'
      - $ref: '#/components/parameters/continuationToken'
      responses:
        '200':
          description: Successful operation. A successful response returns a list of source connections that match the request parameters.
          x-summary: List of Source Connections Retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SourceConnectionItem'
              examples:
                Connections:
                  $ref: '#/components/examples/SourceConnectionsResponse'
        '401':
          description: The token provided in the Authorization header is invalid.
          x-summary: Invalid Authorization Token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error_code: 401013
                message: Oauth token is not valid
        '403':
          description: You are not authorized to perform this operation
          x-summary: Authorization Error - Access Denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An Internal error occurred.
          x-summary: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      tags:
      - Source connections
      summary: Create a source connection
      description: 'A source connection for destinations establishes the connection to the Experience Platform Profile Store or Experience Platform Data Lake. The `sourceConnection ID` returned in a successful response must be used when creating a dataflow to your desired destination.

        '
      operationId: postSourceConnection
      parameters:
      - $ref: '#/components/parameters/Authorization'
      - $ref: '#/components/parameters/Content-type'
      - $ref: '#/components/parameters/XApiKey'
      - $ref: '#/components/parameters/XImsOrgId'
      - $ref: '#/components/parameters/XSandboxId'
      - $ref: '#/components/parameters/Accept'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
              - $ref: '#/components/schemas/Create_Source_Connection_Request'
              - $ref: '#/components/schemas/Create_Data_Lake_Source_Connection_Request'
            examples:
              Create_Source_Connection_Profile_Store:
                $ref: '#/components/examples/Create_Source_Connection_Profile_Store'
              Create_Source_Connection_Data_Lake:
                $ref: '#/components/examples/Create_Source_Connection_Data_Lake'
      responses:
        '201':
          description: A new source connection was successfully created. The response contains the unique identifier (ID) and the etag value of the source connection.
          x-summary: Source connection created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Create_Source_Connection_Response'
              examples:
                Create_Source_Connection_Response:
                  $ref: '#/components/examples/Create_Source_Connection_Response'
        '401':
          description: The token provided in the Authorization header is invalid.
          x-summary: Invalid authentication token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error_code: 401013
                message: Oauth token is not valid
        '403':
          description: You are not authorized to perform this operation
          x-summary: Unauthorized access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: connectionSpec.version 'version' is required for spec info
          x-summary: Missing required field
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An Internal error occurred.
          x-summary: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    servers:
    - url: https://{environment}.adobe.io/data/foundation/flowservice
      description: Adobe IO gateway endpoint
      variables:
        environment:
          default: platform
          enum:
          - platform
          - platform-stage
  /sourceConnections/{id}:
    get:
      tags:
      - Source connections
      summary: Retrieve the details of a source connection
      description: 'You can retrieve detailed information about a specific source connection by making a GET request to the `/sourceConnections` endpoint and providing the ID of the connection you want to inspect.

        '
      operationId: getSourceConnectionById
      parameters:
      - name: id
        in: path
        description: The ID of the source connection you are looking to retrieve.
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/Authorization'
      - $ref: '#/components/parameters/XApiKey'
      - $ref: '#/components/parameters/XImsOrgId'
      - $ref: '#/components/parameters/XSandboxId'
      - $ref: '#/components/parameters/Accept'
      responses:
        '200':
          description: The specified source connection was successfully retrieved.
          x-summary: Source Connection Details Retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SourceConnectionItem'
              examples:
                SourceConnectionsResponseUPS:
                  $ref: '#/components/examples/SourceConnectionsResponseUPS'
                SourceConnectionsResponseDataLake:
                  $ref: '#/components/examples/SourceConnectionsResponseDataLake_V2'
        '401':
          description: The token provided in the Authorization header is invalid.
          x-summary: Invalid Authorization Token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error_code: 401013
                message: Oauth token is not valid
        '403':
          description: You are not authorized to perform this operation
          x-summary: Authorization Error - Access Denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: The specified source connection ID was not found. The resource may have been deleted, or the requested path was entered incorrectly.
          x-summary: Not Found - Source Connection ID Missing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                errorMessage: sourceConnections not found with id = [4890fc95-5a1f-4983-94bb-e060c08e3f]
                errorDetails: sourceConnections not found with id = [4890fc95-5a1f-4983-94bb-e060c08e3f]
        '500':
          description: An Internal error occurred.
          x-summary: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      tags:
      - Source connections
      summary: Delete a source connection
      description: 'You can delete the specified source connection by making a DELETE request to the `/sourceConnections` endpoint and providing the ID of the source connection that you wish to delete in the request path.

        '
      operationId: deleteSourceConnectionById
      parameters:
      - name: id
        in: path
        description: The ID of the source connection you are looking to delete.
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/Authorization'
      - $ref: '#/components/parameters/XApiKey'
      - $ref: '#/components/parameters/XImsOrgId'
      - $ref: '#/components/parameters/XSandboxId'
      - $ref: '#/components/parameters/Accept'
      responses:
        '202':
          description: A successful response returns HTTP status 202 (No Content) and a blank body. You can confirm the deletion by attempting a lookup (GET) request to the source connection. The API will return an HTTP 404 (Not Found) error, indicating that the source connection has been deleted.
          x-summary: Deletion Accepted - Source Connection Marked for Deletion
        '401':
          description: The token provided in the Authorization header is invalid.
          x-summary: Invalid Authorization Token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error_code: 401013
                message: Oauth token is not valid
        '403':
          description: You are not authorized to perform this operation
          x-summary: Authorization Error - Access Denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: The specified source connection ID was not found. The resource may have been deleted, or the requested path was entered incorrectly.
          x-summary: Not Found - Source Connection ID Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                errorMessage: sourceConnections not found with id = [ca5c6e9a-8559-4a08-97a5-f15b756da600-]
                errorDetails: sourceConnections not found with id = [ca5c6e9a-8559-4a08-97a5-f15b756da600-]
        '500':
          description: An Internal error occurred.
          x-summary: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    servers:
    - url: https://{environment}.adobe.io/data/foundation/flowservice
      description: Adobe IO gateway endpoint
      variables:
        environment:
          default: platform
          enum:
          - platform
          - platform-stage
  /sourceConnections/{SOURCE_CONNECTION_ID}:
    get:
      tags:
      - Source connections
      summary: Retrieve a source connection by ID
      description: Retrieve a single source connection by making a GET request to the `/sourceConnections/{SOURCE_CONNECTION_ID}` endpoint while providing the ID of the source connection you want to retrieve.
      operationId: retrieveSourceConnection
      parameters:
      - name: Authorization
        in: header
        description: The access token which can be copied from your Experience Platform integration, prefixed with 'Bearer '. For more information on how to obtain this value, visit the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en).
        required: true
        schema:
          type: string
      - name: x-api-key
        in: header
        description: The API key which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en).
        required: true
        schema:
          type: string
      - name: x-gw-ims-org-id
        in: header
        description: The organization ID which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en).
        required: true
        schema:
          type: string
      - name: x-sandbox-name
        in: header
        description: All resources in Experience Platform are isolated to specific virtual sandboxes. Requests to Platform APIs require a header that specifies the name of the sandbox in which the operation will take place.
        schema:
          type: string
      - name: SOURCE_CONNECTION_ID
        in: path
        description: The ID of the source connection you want to retrieve.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful operation. A successful response returns details of specified source connection in JSON format.
          x-summary: Source Connection Details Retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SourceConnectionsListResponse'
        '403':
          description: The OAuth token is missing.
          x-summary: Authorization Error - Missing OAuth Token
          content: {}
        '503':
          description: The service is unavailable.
          x-summary: Server Error - Service Unavailable
          content: {}
    delete:
      tags:
      - Source connections
      summary: Delete a source connection
      description: Use this endpoint to delete an instance of a source connection.
      operationId: deleteSourceConnection
      parameters:
      - name: Authorization
        in: header
        description: The access token which can be copied from your Experience Platform integration, prefixed with 'Bearer '. For more information on how to obtain this value, visit the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en).
        required: true
        schema:
          type: string
      - name: x-api-key
        in: header
        description: The API key which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en).
        required: true
        schema:
          type: string
      - name: x-gw-ims-org-id
        in: header
        description: The organization ID which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en).
        required: true
        schema:
          type: string
      - name: x-sandbox-name
        in: header
        description: All resources in Experience Platform are isolated to specific virtual sandboxes. Requests to Platform APIs require a header that specifies the name of the sandbox in which the operation will take place.
        schema:
          type: string
      - name: SOURCE_CONNECTION_ID
        in: path
        description: The ID of the source connection you want to delete.
        required: true
        schema:
          type: string
      responses:
        '204':
          description: The source connection was successfully deleted.
          x-summary: Source Connection Deleted
          content: {}
        '403':
          description: The OAuth token is missing.
          x-summary: Authorization Error - Missing OAuth Token
          content: {}
        '503':
          description: The service is unavailable.
          x-summary: Server Error - Service Unavailable
          content: {}
    patch:
      tags:
      - Source connections
      summary: Update a source connection
      description: Update the information of a source connection by making a PATCH request to the `/sourceConnections/{SOURCE_CONNECTION_ID}` endpoint while providing the ID of the source connection you want to update. To update a source connection, you must also provide the current `etag` of your source connection as the `if-match` header.
      operationId: patchSourceConnection
      parameters:
      - name: Authorization
        in: header
        description: The access token which can be copied from your Experience Platform integration, prefixed with 'Bearer '. For more information on how to obtain this value, visit the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en).
        required: true
        schema:
          type: string
      - name: x-api-key
        in: header
        description: The API key which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en).
        required: true
        schema:
          type: string
      - name: x-gw-ims-org-id
        in: header
        description: The organization ID which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en).
        required: true
        schema:
          type: string
      - name: x-sandbox-name
        in: header
        description: All resources in Experience Platform are isolated to specific virtual sandboxes. Requests to Platform APIs require a header that specifies the name of the sandbox in which the operation will take place.
        schema:
          type: string
      - name: if-match
        in: header
        description: A parameter required when updating a connection or a dataflow. When making a PUT or PATCH request, you must add an `if-match` header parameter and include the current version/etag of the resource that you want to update to complete the update.
        required: true
        schema:
          type: string
      - name: SOURCE_CONNECTION_ID
        in: path
        description: The ID of the source connection you want to update.
        required: true
        schema:
          type: string
      requestBody:
        description: '- **op** - **(Required)** The operation call used to define the action needed to update the connection. Operations include `add`, `replace`, and `remove`.

          - **path** - (Optional) The path of the parameter to be updated.

          - **value** - **(Required)** The new value you want to update your parameter with.'
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/PatchInstruction'
        required: true
      responses:
        '200':
          description: Successful operation. A successful response returns updated source connection in JSON format.
          x-summary: Source Connection Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SourceConnectionsListResponse'
        '403':
          description: The OAuth token is missing.
          x-summary: Authorization Error - Missing OAuth Token
          content: {}
        '503':
          description: The service is unavailable.
          x-summary: Server Error - Service Unavailable
          content: {}
      x-codegen-request-body-name: body
    servers:
    - url: //{environment}.adobe.io/data/foundation/flowservice
      variables:
        environment:
          default: platform
          enum:
          - platform
          - platform-stage
  /sourceConnections/{SOURCE_CONNECTION_ID}/action:
    post:
      tags:
      - Source connections
      summary: Performs a state transition action on an existing source connection.
      description: Use this endpoint to perform a state transition action on an existing source connection.
      operationId: performAction_1
      parameters:
      - name: Authorization
        in: header
        description: The access token which can be copied from your Experience Platform integration, prefixed with 'Bearer '. For more information on how to obtain this value, visit the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en).
        required: true
        schema:
          type: string
      - name: x-api-key
        in: header
        description: The API key which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en).
        required: true
        schema:
          type: string
      - name: x-gw-ims-org-id
        in: header
        description: The organization ID which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en).
        required: true
        schema:
          type: string
      - name: x-sandbox-name
        in: header
        description: All resources in Experience Platform are isolated to specific virtual sandboxes. Requests to Platform APIs require a header that specifies the name of the sandbox in which the operation will take place.
        schema:
          type: string
      - name: SOURCE_CONNECTION_ID
        in: path
        description: The ID of the queried source connection.
        required: true
        schema:
          type: string
      - name: op
        in: query
        description: The operative action to perform against the queried source connection.
        required: true
        schema:
          type: string
          enum:
          - PUBLISH
      responses:
        '200':
          x-summary: Success
          description: Successful operation. A successful response returns the source connection with the updated state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateSourceConnectionResponse'
        '401':
          description: The user is unauthorized. Contact your administrator to resolve permissions and access the resource.
        '500':
          description: An internal error has occurred. Please try again. If the problem persisits, contact customer support.
    servers:
    - url: //{environment}.adobe.io/data/foundation/flowservice
      variables:
        environment:
          default: platform
          enum:
          - platform
          - platform-stage
components:
  parameters:
    XApiKey:
      in: header
      name: x-api-key
      description: The API key which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en).
      schema:
        type: string
      required: true
    orderby:
      in: query
      name: orderby
      description: Sort response by specified fields separated by `,` and/or prefix field with `-` for descending order.
      required: false
      schema:
        type: string
    Accept:
      in: header
      name: Accept
      description: An optional content negotiation header which allows you to use a specific version of the API. If you don't use it, the HTTP responses fall back to the latest version of the API.
      schema:
        type: string
        default: application/json; version=1
      required: false
    continuationToken:
      in: query
      name: continuationToken
      description: A token for fetching records for next page. This is a system-generated token.
      required: false
      schema:
        type: string
    count:
      in: query
      name: count
      description: A boolean value specifying if the count of resources should be returned. By default the count is not returned (`count=false`).
      required: false
      schema:
        type: boolean
    Content-type:
      in: header
      name: Content-type
      description: The type of content being sent in the body of the request. Should be 'application/json'.
      schema:
        type: string
        default: application/json
      required: true
    XSandboxId:
      in: header
      name: x-sandbox-name
      description: All resources in Experience Platform are isolated to specific virtual sandboxes. Requests to Platform APIs require a header that specifies the name of the sandbox in which the operation will take place.
      schema:
        type: string
      required: true
    Authorization:
      in: header
      name: Authorization
      description: The access token which can be copied from your Experience Platform integration, prefixed with 'Bearer '. For more information on how to obtain this value, visit the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en).
      schema:
        type: string
      required: true
    limit:
      in: query
      name: limit
      description: Limit response to a specific number of objects. Must be a positive number. For example, `limit=10`.
      required: false
      schema:
        type: integer
        maximum: 100
    XImsOrgId:
      in: header
      name: x-gw-ims-org-id
      description: The organization ID which can be copied from your Experience Platform integration. For more information on how to obtain this value, visit the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en).
      schema:
        type: string
      required: true
  schemas:
    Create_Source_Connection_Request:
      type: object
      title: Create Profile Store Source Connection Request
      description: 'API request to create a source connection to the Experience Platform Profile Store.  In the request payload, always use the hardcoded value `connectionSpec.id=8a9c3494-9708-43d7-ae3f-cda01e5030e1`.

        '
      required:
      - name
      - connectionSpec
      properties:
        name:
          type: string
          title: Name
          description: The name of the source connection.
        description:
          type: string
          title: Description
          description: An optional description for the source connection.
        connectionSpec:
          type: object
          title: Connection Spec.
          description: Request model for connection spec information.
          required:
          - id
          - version
          properties:
            id:
              type: string
              title: Id
              description: 'Connection spec ID. Each destination connector has a unique connection spec ID, which must be used when establishing base, source, or target connections for that specific destination. For connections to the Experience Platform Profile Store, the connection spec ID is always `8a9c3494-9708-43d7-ae3f-cda01e5030e1`.

                '
            version:
              type: string
              title: Version
              description: Connection spec version. This value is `1.0` unless clearly specified otherwise.
    ErrorResponse:
      type: object
    SourceConnectionItem:
      type: object
      title: Source Connection Items
      description: Parameters specific to source connections.
      required:
      - id
      - createdAt
      - updatedAt
      - createdBy
      - updatedBy
      - createdClient
      - updatedClient
      - sandboxId
      - imsOrgId
      - name
      - connectionSpec
      - state
      - typeInfo
      - version
      - etag
      - inheritedAttributes
      properties:
        id:
          type: string
          title: Connection ID
          description: The ID of the source connection.
        createdAt:
          type: integer
          title: Connection creation time
          description: The epoch time in milliseconds when the source connection was created.
        updatedAt:
          type: integer
          title: Connection update time
          description: The epoch time in milliseconds when the source connection was last updated.
        createdBy:
          type: string
          title: Created User
          description: The Adobe ID of the Identity Management System (IMS) user who created the source connection. In the case of service tokens, the value for `createdBy` is the same as `createdClient`.
        updatedBy:
          type: string
          title: Updated User
          description: The Adobe ID of the Identity Management System (IMS) user who last updated the source connection. In the case of service tokens, the value for `createdBy` is the same as `createdClient`.
        createdClient:
          type: string
          title: Created client
          description: The Adobe Identity Management System (IMS) client who created the source connection. This can be an application or a user. For example, the value `exc_app` represents source connections created in the Experience Platform UI.
        updatedClient:
          type: string
          title: Updated client
          description: The Adobe Identity Management System (IMS) client who last updated the source connection. This can be an application or a user. For example, the value `exc_app` represents source connections created in the Experience Platform UI.
        imsOrgId:
          type: string
          title: IMS org ID
          description: The organization ID to which the source connection belongs.
        sandboxId:
          type: string
          title: Sandbox ID
          description: The ID of the sandbox in which the source connection was created.
        sandboxName:
          type: string
          title: Created client
          descript

# --- truncated at 32 KB (53 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/adobe-suite/refs/heads/main/openapi/adobe-suite-source-connections-api-openapi.yml