openapi: 3.2.0
info:
  title: Data Access Files 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: Files
  description: Retrieve headers containing metadata for a file specified by ID.
paths:
  /files/{dataSetFileId}:
    get:
      tags:
      - Files
      summary: Retrieve a file
      description: Returns either a complete file or a directory of chunked data that makes up the file. The response contains a data array that may contain a single entry or a list of files belonging to that directory.
      operationId: retrieveDatasetFile
      parameters:
      - name: dataSetFileId
        in: path
        description: The ID of the dataset file you are retrieving.
        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'
      - name: Range
        in: header
        description: 'The range of bytes requested. For example: `Range: bytes=0-100000`'
        schema:
          type: string
      - $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 has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/metadata'
            application/octet-stream:
              schema:
                $ref: '#/components/schemas/metadata'
        206:
          description: The request has succeeded, returning only partial content. The body will contain the requested range of data.
          headers:
            Content-Range:
              description: 'The range of bytes sent by the server. Can be different from what user requested. For example: `Content-Range: bytes 0-100/124000`'
              schema:
                type: string
            Content-Length:
              description: The size of payload in the response in bytes.
              schema:
                type: integer
          content: {}
        401:
          description: Access is unauthorized.
          content: {}
        404:
          description: The requested file was not found.
          content: {}
        500:
          description: An internal server error has ocurred.
          content: {}
    head:
      tags:
      - Files
      summary: Retrieve a file's headers
      operationId: retrieveDatasetFileHeaders
      parameters:
      - name: dataSetFileId
        in: path
        description: The ID of the dataset file you are retrieving.
        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'
      - name: path
        in: query
        description: 'The full name of the file identified. For example: `path=profiles.csv`'
        required: true
        schema:
          type: string
      responses:
        200:
          description: The request was successful.
          headers:
            Accept-Ranges:
              description: 'The unit of range for the file. For example: `bytes`'
              schema:
                type: string
            Content-Length:
              description: The size of the file in bytes.
              schema:
                type: integer
            Content-Type:
              description: 'The Content-Type of the returned file. For example: `application/csv`'
              schema:
                type: string
          content: {}
        401:
          description: Access is unauthorized.
          content: {}
        404:
          description: The dataset file was not found.
          content: {}
        500:
          description: An internal server error has ocurred.
          content: {}
components:
  schemas:
    metadata:
      type: object
      properties:
        path:
          type: string
          example: F1.json
  parameters:
    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
    limit:
      name: limit
      in: query
      description: 'A paging parameter to specify the number of results per page. For example: `limit=10`'
      schema:
        type: string
    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
    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
    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-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