openapi: 3.2.0
info:
  title: Data Access API
  description: "Data Access supports limited data egress from Adobe Experience Platform for very particular synchronous use cases. \nThis API has a 60-second response time limit. For large data exports or regular data integration, you should use \ndataset export destinations.\n\n- **Related documentation**:\n  - [Data Access documentation](https://www.adobe.com/go/data-access-overview-en)\n\n- **Visualize API calls with Postman (a free, third-party software)**:\n  - [Data Access API Postman collection on GitHub](https://github.com/adobe/experience-platform-postman-samples/blob/master/apis/experience-platform/Data%20Access%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.getpostman.com/docs/postman/collection_runs/using_environments_in_collection_runs/)\n\n- **API paths**:\n  - PLATFORM Gateway URL: https://<span>platform.adobe.io/\n  - Base path for this API: /data/foundation/export\n  - Example of a complete path: https://<span>platform.adobe.io/data/foundation/export/batches/{batchId}/files\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#faq), [API status codes](https://experienceleague.adobe.com/docs/experience-platform/landing/troubleshooting.html#api-status-codes), and [request header errors](https://experienceleague.adobe.com/docs/experience-platform/landing/troubleshooting.html#request-header-errors)."
  version: 1.0.0
servers:
- url: https://{environment}.adobe.io/data/foundation/export
  description: Adobe IO gateway endpoint
  variables:
    environment:
      default: platform
      enum:
      - platform
      - platform-stage
tags:
- name: Data Access
  description: Configure data access and egress for Experience Platform.
paths:
  /batches/{batchId}/files:
    get:
      tags:
      - Data Access
      summary: List a batch's dataset files
      description: By default, 100 dataset files are shown. Additionally, 100 dataset files is the maximum number of files that can be returned in a single API request.
      operationId: listDatasetFiles
      parameters:
      - name: batchId
        in: path
        description: The batch ID.
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/authorization'
      - $ref: '#/components/parameters/x-api-key'
      - $ref: '#/components/parameters/x-gw-ims-org-id'
      - $ref: '#/components/parameters/x-sandbox-name'
      - $ref: '#/components/parameters/start'
      - $ref: '#/components/parameters/limit'
      responses:
        200:
          description: The request was successful.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dataSetFiles'
        401:
          description: Access is unauthorized.
          content: {}
        500:
          description: An internal server error has ocurred.
          content: {}
  /batches/{batchId}/failed:
    get:
      tags:
      - Data Access
      summary: Retrieve a failed batch's dataset files
      description: By default, 100 failed files are shown. Additionally, 100 failed files is the maximum number of files that can be returned in a single API request.
      operationId: retrieveFailedBatch
      parameters:
      - name: batchId
        in: path
        description: The ID of the batch.
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/authorization'
      - $ref: '#/components/parameters/x-api-key'
      - $ref: '#/components/parameters/x-gw-ims-org-id'
      - $ref: '#/components/parameters/x-sandbox-name'
      - $ref: '#/components/parameters/start'
      - $ref: '#/components/parameters/limit'
      - name: path
        in: query
        description: 'The full name of the file. The contents of the file would be downloaded if this parameter is provided. For example: `path=profiles.csv`'
        schema:
          type: string
      responses:
        200:
          description: The request was successful.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/files'
        401:
          description: Access is unauthorized.
          content: {}
        500:
          description: An internal server error has ocurred.
          content: {}
  /batches/{batchId}/meta:
    get:
      tags:
      - Data Access
      summary: Retrieve a batch's meta files
      description: "Lists files under a batch's meta directory or download a specific file under it. The files under a batch's meta directory may include the following: \n - row_errors: A directory containing 0 or more files with parsing, conversion, and/or validation errors found at the row level.\n - input_files: A directory containing metadata for 1 or more input files submitted with the batch.\n - row_errors_sample.json: A root level file containing the sampled set of row errors for the UX.\n\n By default, 100 meta files are shown. Additionally, 100 meta files is the maximum number of files that can be returned in a single API request."
      operationId: retrieveBatchMeta
      parameters:
      - name: batchId
        in: path
        description: The ID of the batch.
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/authorization'
      - $ref: '#/components/parameters/x-api-key'
      - $ref: '#/components/parameters/x-gw-ims-org-id'
      - $ref: '#/components/parameters/x-sandbox-name'
      - $ref: '#/components/parameters/start'
      - $ref: '#/components/parameters/limit'
      - name: path
        in: query
        description: "The full name of the file. The contents of the file would be downloaded if this parameter is provided. For example: `path=row_error_samples.json`\n Possible values for this query include the following: \n - `row_errors`\n - `input_files`\n - `row_errors_sample.json`"
        schema:
          type: string
      responses:
        200:
          description: The request was successful.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/metadata'
        401:
          description: Access is unauthorized.
          content: {}
        404:
          description: The path is not found.
          content: {}
        500:
          description: An internal service error has ocurred.
          content: {}
components:
  schemas:
    dataSetFiles.data.item.links:
      type: object
      properties:
        self:
          $ref: '#/components/schemas/dataSetFiles.data.item.links.self'
    metadata:
      type: object
      properties:
        path:
          type: string
          example: F1.json
    dataSetFiles.links:
      type: object
      properties:
        next:
          $ref: '#/components/schemas/dataSetFiles.links.next'
        page:
          $ref: '#/components/schemas/dataSetFiles.links.page'
    files.links:
      type: object
      properties:
        next:
          $ref: '#/components/schemas/files.links.next'
        page:
          $ref: '#/components/schemas/files.links.page'
    files.data.item.links:
      type: object
      properties:
        self:
          $ref: '#/components/schemas/files.data.item.links.self'
    dataSetFiles.links.page:
      type: object
      properties:
        href:
          type: string
        templated:
          type: boolean
    files.data.item.links.self:
      type: object
      properties:
        href:
          type: string
    files.data.item:
      type: object
      properties:
        name:
          type: string
        length:
          type: string
        _links:
          $ref: '#/components/schemas/files.data.item.links'
    dataSetFiles:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/dataSetFiles.data.item'
        _page:
          $ref: '#/components/schemas/dataSetFiles.page'
        _links:
          $ref: '#/components/schemas/dataSetFiles.links'
    files.links.page:
      type: object
      properties:
        href:
          type: string
        templated:
          type: boolean
    files.links.next:
      type: object
      properties:
        href:
          type: string
    dataSetFiles.data.item:
      type: object
      properties:
        dataSetFileId:
          type: string
        dataSetViewId:
          type: string
        version:
          type: string
        created:
          type: string
        updated:
          type: string
        records:
          type: string
        size:
          type: string
        isValid:
          type: boolean
        _links:
          $ref: '#/components/schemas/dataSetFiles.data.item.links'
    files.page:
      type: object
      properties:
        limit:
          type: integer
        count:
          type: integer
    dataSetFiles.page:
      type: object
      properties:
        limit:
          type: integer
        count:
          type: integer
    files:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/files.data.item'
        _page:
          $ref: '#/components/schemas/files.page'
        _links:
          $ref: '#/components/schemas/files.links'
    dataSetFiles.links.next:
      type: object
      properties:
        href:
          type: string
    dataSetFiles.data.item.links.self:
      type: object
      properties:
        href:
          type: string
  parameters:
    start:
      name: start
      in: query
      description: 'A paging parameter to specify the start of the page of results. For example: `page=1`'
      schema:
        type: string
    authorization:
      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, see the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en).
      required: true
      schema:
        type: string
    x-gw-ims-org-id:
      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, see the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en).
      required: true
      schema:
        type: string
    x-api-key:
      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
    limit:
      name: limit
      in: query
      description: 'A paging parameter to specify the number of results per page. For example: `limit=10`'
      schema:
        type: string
    x-sandbox-name:
      name: x-sandbox-name
      in: header
      description: The name of the sandbox in which the operation will take place. See the [sandboxes overview documentation](https://adobe.com/go/sandbox-overview-en) for more information.
      required: true
      schema:
        type: string