Adobe Suite Connection specs API

openapi: 3.2.0
info:
  title: Flow Service API - Sources Connection specs API
  description: "Adobe Experience Platform allows data to be ingested from external sources while providing you with the ability to structure, label, and enhance incoming data using Platform services. You can ingest data from a variety of sources such as Adobe applications, cloud-based storages, databases, and many others. The service provides a RESTful API from which all supported sources are connectable.\n>**NOTE**: Refer to [Flow Service API - Destinations](https://developer.adobe.com/experience-platform-apis/references/destinations/) if you are looking for API documentation to perform operations on *destinations* in Experience Platform.\n- **Related documentation**:\n  - [Sources documentation](https://www.adobe.com/go/sources-overview-en)\n\n- **Visualize API calls with Postman** (a free, third-party software):\n  - [Flow Service API Postman collection on GitHub](https://github.com/adobe/experience-platform-postman-samples/blob/master/apis/experience-platform/Flow%20Service%20API.postman_collection.json)\n  - [Video guide for creating the Postman environment](https://video.tv.adobe.com/v/28832)\n  - [Steps for importing environments and collections in Postman](https://learning.postman.com/docs/getting-started/importing-and-exporting-data/)\n\n- **API paths**:\n  - PLATFORM Gateway URL: https://<span>platform.adobe.io/\n  - Base path for this API: /data/foundation/flowservice\n  - Example of a complete path: https://<span>platform.adobe.io/data/foundation/flowservice/connections\n\n- **Required headers**:\n  - All calls require the headers `Authorization`, `x-gw-ims-org-id`, and `x-api-key`. For more information on how to obtain these values, see the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en).\n  - All resources in Experience Platform are isolated to specific virtual sandboxes. All requests to Platform APIs require the header `x-sandbox-name` whose value is the all-lowercase name of the sandbox the operation will take place in (for example, \"prod\"). See the [sandboxes overview](https://adobe.com/go/sandbox-overview-en) for more information.\n  - All requests with a payload in the request body (such as POST, PUT, and PATCH calls) must include the header `Content-Type` with a value of `application/json`.\n\n- **API error handling**:\n    - Refer to the Experience Platform API troubleshooting guide for [FAQs](https://experienceleague.adobe.com/docs/experience-platform/landing/troubleshooting.html?lang=en#faq), [API status codes](https://experienceleague.adobe.com/docs/experience-platform/landing/troubleshooting.html?lang=en#api-status-codes), and [request header errors](https://experienceleague.adobe.com/docs/experience-platform/landing/troubleshooting.html?lang=en#request-header-errors). You can also view a list of [common Flow Service error messages](https://experienceleague.adobe.com/docs/experience-platform/sources/errors/flow-service-errors.html) and resolution suggestions.\n\n- **Sorting and filtering responses**:\n    - When performing listing (GET) requests in the Flow Service API, you can use query parameters to [sort and filter responses](https://experienceleague.adobe.com/docs/experience-platform/dataflows/api/sort-and-filter.html?lang=en)."
  version: '1.0'
servers:
- url: //{environment}.adobe.io/data/foundation/flowservice
  variables:
    environment:
      default: platform
      enum:
      - platform
      - platform-stage
tags:
- name: Connection specs
  description: Connection specifications retain the connector properties of a given source. A connection spec can be divided into three distinct sections, authentication specifications (authSpec), source specifications (sourceSpec), and explore specifications (exploreSpec). The authSpec defines the authentication type(s) that you can use to connect your source to Experience Platform. The sourceSpec consists of source connection parameters that a given source requires from a user. For example, the sourceSpec of a cloud storage source can require a user to provide values for path or recursive parameter. The sourceSpec also includes properties that are used when the source is displayed in the Platform UI catalog. The exploreSpec defines the structure of returned data when a source is queried against. Connection specs include a connection spec ID. This ID is fixed and each source on Experience Platform has its own fixed connection spec ID. This ID is required to create a base connection and a source connection. Connection specs are organization agnostic.
paths:
  /connectionSpecs:
    get:
      tags:
      - Connection specs
      summary: List connection specs
      description: Use this endpoint to list all connection specs in your organization.
      operationId: listConnectionSpecs
      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: property
        in: query
        description: A comma-separated list of top-level object properties to be returned in the response. This parameter is used to filter the response data based on the properties provided. For example, `property=lastRunDetails.startedAtUTC>=1670880253121` returns only the flows whos last run iterations were started during or after the specified epoch time in milliseconds. This parameter is also used to cut down the amount of data returned in the response body. For example, `property=state==enabled&orderby=createdAt` returns only base connections that have a status of `enabled` in the order of their creation, in ascending order.
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
      responses:
        '200':
          description: Successful operation. A successful response returns a list of connection specs that match the request parameters in JSON format.
          x-summary: Connection Specifications Listed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectionSpecResponse'
        '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: {}
    post:
      tags:
      - Connection specs
      summary: Creates a new connection spec.
      description: Use this endpoint to create a new connection spec for your source.
      operationId: createConnectionSpec
      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
      requestBody:
        description: The following request creates a new connection spec for a new source.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateConnectionSpecRequest'
      responses:
        '201':
          description: Connection Spec Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectionSpecItemDTO'
              examples:
                success:
                  value:
                    id: 44c6e8ec-54e8-4813-a472-93c6cf29c3d7
                    createdAt: 1624299037286
                    updatedAt: 1624299037286
                    createdBy: acp_foundation_connectors@AdobeID
                    updatedBy: acp_foundation_connectors@AdobeID
                    createdClient: acp_foundation_connectors
                    updatedClient: acp_foundation_connectors
                    sandboxId: 6b36e130-c5d7-11e9-949c-0da8d50fcac1
                    sandboxName: prod
                    imsOrgId: 7DC732555AECDB4C0A494036@AdobeOrg
                    name: test1
                    providerId: 0ed90a81-07f4-4586-8190-b40eccef1c5a
                    version: '1.0'
                    authSpec:
                    - name: Basic Authentication for Dynamics-Online
                      type: BasicAuthentication
                      spec:
                        $schema: http://json-schema.org/draft-07/schema#
                        type: object
                        description: defines auth params required for connecting to dynamics-online
                        properties:
                          serviceUri:
                            type: string
                            description: The service URL of your Dynamics instance
                          username:
                            type: string
                            description: User name for the user account
                          password:
                            type: string
                            description: Password for the user account
                            format: password
                        required:
                        - username
                        - password
                        - serviceUri
                    sourceSpec:
                      spec:
                        $schema: http://json-schema.org/draft-07/schema#
                        type: object
                        description: Defines params required when dynamics-online connection is used as a source in flow.
                        properties:
                          tableName:
                            type: string
                            description: The input table from dynamics-online to pull data from.
                          columns:
                            type: array
                            items:
                              type: object
                              properties:
                                name:
                                  type: string
                                type:
                                  type: string
                                meta:
                                  type: object
                                  description: Defines meta information for each column.
                                  originalType:
                                    type: string
                              required:
                              - name
                              - type
                              - meta
                        required:
                        - tableName
                        - columns
                      attributes:
                        uiAttributes:
                          documentationLink: http://www.adobe.com/go/sources-dynamics-en
                          isSource: true
                          category:
                            key: crm
                          icon:
                            key: msDynamics
                          description:
                            key: microsoftDynamicsDescription
                          label:
                            key: microsoftDynamicsLabel
                    attributes:
                      category: CRM
                      isSource: true
                      documentationLink: http://www.adobe.com/go/data-connector-Microsoft-Dynamics-en
                      uiAttributes:
                        apiFeatures:
                          explorePaginationSupported: false
                    permissionsInfo:
                      manage:
                        '@type': lowLevel
                        name: EnterpriseSource
                        permissions:
                        - write
                      view:
                        '@type': lowLevel
                        name: EnterpriseSource
                        permissions:
                        - read
          headers:
            Location:
              description: Location of the newly created Connection Spec instance
              content:
                application/json:
                  schema:
                    $ref: '#/components/schemas/ConnectionSpecItemDTO'
        '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.
  /connectionSpecs/{CONNECTION_SPEC_ID}:
    get:
      tags:
      - Connection specs
      summary: Retrieve a connection spec
      description: Use this endpoint to retrieve a single instance of a connection spec.
      operationId: retrieveConnectionSpec
      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: CONNECTION_SPEC_ID
        in: path
        description: The ID of the connection specification that you want to retrieve.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful operation. A successful response returns details of specified connection specification that match the request parameters in JSON format.
          x-summary: Connection Specification Details Retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectionSpecResponse'
        '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: {}
    put:
      tags:
      - Connection specs
      summary: Updates an existing connection spec.
      description: Use this endpoint to update an existing connection spec.
      operationId: updateConnectionSpec
      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: CONNECTION_SPEC_ID
        in: path
        description: The ID of the connection spec that you want to update.
        required: true
        schema:
          type: string
      requestBody:
        description: The following request updates the information of the queried connection spec ID.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateConnectionSpecRequest'
      responses:
        '200':
          x-summary: Success
          description: Successful operation. A successful response returns the updated connection spec.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectionSpecItemDTO'
              examples:
                success:
                  value:
                    id: 44c6e8ec-54e8-4813-a472-93c6cf29c3d7
                    createdAt: 1624299037286
                    updatedAt: 1624299037286
                    createdBy: acp_foundation_connectors@AdobeID
                    updatedBy: acp_foundation_connectors@AdobeID
                    createdClient: acp_foundation_connectors
                    updatedClient: acp_foundation_connectors
                    sandboxId: 6b36e130-c5d7-11e9-949c-0da8d50fcac1
                    sandboxName: prod
                    imsOrgId: 7BA732555AECDB4C0A494036@AdobeOrg
                    name: test1
                    providerId: 0ed90a81-07f4-4586-8190-b40eccef1c5a
                    version: '1.0'
                    authSpec:
                    - name: Basic Authentication for Dynamics-Online
                      type: BasicAuthentication
                      spec:
                        $schema: http://json-schema.org/draft-07/schema#
                        type: object
                        description: Defines auth params required for connecting to dynamics-online.
                        properties:
                          serviceUri:
                            type: string
                            description: The service URL of your Dynamics instance
                          username:
                            type: string
                            description: User name for the user account
                          password:
                            type: string
                            description: Password for the user account
                            format: password
                        required:
                        - username
                        - password
                        - serviceUri
                    sourceSpec:
                      spec:
                        $schema: http://json-schema.org/draft-07/schema#
                        type: object
                        description: Defines params required when dynamics-online connection is used as a source in flow.
                        properties:
                          tableName:
                            type: string
                            description: The input table from dynamics-online to pull data from
                          columns:
                            type: array
                            items:
                              type: object
                              properties:
                                name:
                                  type: string
                                type:
                                  type: string
                                meta:
                                  type: object
                                  description: Defines meta information for each column.
                                  originalType:
                                    type: string
                              required:
                              - name
                              - type
                              - meta
                        required:
                        - tableName
                        - columns
                      attributes:
                        uiAttributes:
                          documentationLink: http://www.adobe.com/go/sources-dynamics-en
                          isSource: true
                          category:
                            key: crm
                          icon:
                            key: msDynamics
                          description:
                            key: microsoftDynamicsDescription
                          label:
                            key: microsoftDynamicsLabel
                    attributes:
                      category: CRM
                      isSource: true
                      documentationLink: http://www.adobe.com/go/data-connector-Microsoft-Dynamics-en
                      uiAttributes:
                        apiFeatures:
                          explorePaginationSupported: false
                    permissionsInfo:
                      manage:
                        '@type': lowLevel
                        name: EnterpriseSource
                        permissions:
                        - write
                      view:
                        '@type': lowLevel
                        name: EnterpriseSource
                        permissions:
                        - read
        '400':
          description: The request is invalid.
        '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.
  /connectionSpecs/{CONNECTION_SPEC_ID}/explore:
    get:
      tags:
      - Connection specs
      summary: Explore objects of a connection spec.
      description: Use this endpoint to explore the objects of a given connection spec.
      operationId: exploreByConnectionSpecId
      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: CONNECTION_SPEC_ID
        in: path
        description: The ID of the queried connection spec.
        required: true
        schema:
          type: string
      responses:
        '200':
          x-summary: Success
          description: Successful operation. A successful response returns the connection spec entity that corresponds to the queried ID.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExploreConnectionResponse'
              examples:
                success:
                  value:
                    items:
                    - columnName: name
                      columnType: string
                    - columnName: address
                      columnType: string
                    - columnName: dob
                      columnType: date
                    - columnName: phone
                      columnType: string
        '400':
          description: The request is invalid.
        '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.
  /connectionSpecs/{CONNECTION_SPEC_ID}/configs:
    get:
      tags:
      - Connection specs
      summary: Retrieve config options for a connection spec.
      description: Use this endpoint to retrieve the available config options for a given connection spec.
      operationId: configByConnectionSpecId
      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: CONNECTION_SPEC_ID
        in: path
        description: The ID of the queried connection spec.
        required: true
        schema:
          type: string
      responses:
        '200':
          x-summary: Success
          description: Successful operation. A successful response returns the config options for the field.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExploreConnectionResponse'
              examples:
                success:
                  value:
                    items:
                    - columnName: name
                      columnType: string
                    - columnName: address
                      columnType: string
                    - columnName: dob
                      columnType: date
                    - columnName: phone
                      columnType: string
        '400':
          description: The request is invalid.
        '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.
components:
  schemas:
    TargetSpecDTO:
      type: object
      properties:
        name:
          type: string
          description: The name of the type of the target.
          example: CloudStorage
        type:
          type: string
          description: The type of the target. This value is the same as the category assigned to the target.
          example: CloudStorage
        spec:
          type: object
          properties:
            schema:
              type: string
              example: http://json-schema.org/draft-07/schema#
            type:
              type: string
              example: object
            dataSetId:
              type: string
        attributes:
          type: object
          properties:
            uiAttributes:
              type: object
              properties:
                isDestination:
                  type: boolean
                  description: A boolean value that defines if the queried item is a destination.
                  example: true
                documentationLink:
                  type: string
                  description: A link to the documentation about a given destination.
                  example: http://www.adobe.com/go/sources-google-cloud-storage-en
                category:
                  type: string
                  description: The category that corresponds with the destination. Example categories include `social`, `cloudStorage`, `emailMarketing`.
                  example: cloudStorage
                icon:
                  type: string
                  description: The image that corresponds with a given destination when displayed on the destination catalog in the Experience Platform UI.
                  example: google
                description:
                  type: string
                  description: A brief description used to provide high-level information on a given destination.
                label:
                  type: string
                  description: The label or name of a destination displayed on th

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