{
  "swagger": "2.0",
  "info": {
    "description": "The Bulk Data Insertion API (BDIA) allows clients to upload server call data into Adobe Analytics in batches of files. \n\n The `https://analytics-collection.adobe.io` host automatically routes calls to the best region for processing. If you are legally required to process data in a specific region, use `https://analytics-collection-us.adobe.io` (US) or `https://analytics-collection-eu.adobe.io` (Europe). \n\n Note: Adobe can add optional fields to API requests and responses at any time, without notice or a version change. Build your integration to ignore fields it doesn't recognize so that these additions don't break it. Adobe doesn't remove fields or add required fields without first announcing the change in release notes.",
    "version": "1.0",
    "title": "Bulk Data Insertion API (BDIA)"
  },
  "host": "analytics-collection.adobe.io",
  "basePath": "/aa/collect/v1",
  "tags": [
    {
      "name": "Events"
    }
  ],
  "parameters": {
    "authorization": {
      "name": "Authorization",
      "in": "header",
      "description": "The access token from your OAuth Server-to-Server credential, prefixed with \"Bearer \".",
      "required": true,
      "type": "string"
    },
    "x-api-key": {
      "name": "x-api-key",
      "in": "header",
      "description": "The Client ID (API key) from your OAuth Server-to-Server credential in the Adobe Developer Console.",
      "required": true,
      "type": "string"
    }
  },
  "schemes": [
    "https"
  ],
  "paths": {
    "/events": {
      "post": {
        "tags": [
          "Events"
        ],
        "summary": "Upload file for processing",
        "description": "Upload a batch file to Analytics for processing. Uploaded files must:\n * Be 100 MB or less compressed (using gzip)\n* Follow the CSV formatting rules and include the required fields as specified in the documentation",
        "operationId": "filePost",
        "consumes": [
          "multipart/form-data"
        ],
        "produces": [
          "application/json"
        ],
        "parameters": [
          {
            "$ref": "#/parameters/authorization"
          },
          {
            "$ref": "#/parameters/x-api-key"
          },
          {
            "name": "x-adobe-vgid",
            "in": "header",
            "description": "Visitor Group ID. A visitor group represents a bucketed group of visitor IDs that are separate from any other visitor group set. The Group ID is a string of any valid value, but must be consistent across files. See [Visitor groups](https://developer.adobe.com/analytics-collection-apis/endpoints/bulk-data-insertion/visitor-groups/) for more information.",
            "required": true,
            "type": "string"
          },
          {
            "name": "x-adobe-idempotency-key",
            "in": "header",
            "description": "Optional. A client-generated unique reference for the upload, used for duplication protection when a request does not return a response. If omitted, it defaults to the generated file_id.",
            "required": false,
            "type": "string"
          },
          {
            "name": "file",
            "in": "formData",
            "description": "Gzip compressed CSV file sent with request",
            "required": true,
            "type": "file"
          },
          {
            "name": "debug",
            "in": "query",
            "description": "Store debug information for the first 10 hits of the file",
            "required": false,
            "type": "boolean",
            "default": false
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "schema": {
              "$ref": "#/definitions/UploadedFileInfo"
            }
          },
          "400": {
            "description": "Request Error",
            "schema": {
              "$ref": "#/definitions/ApiError"
            }
          },
          "401": {
            "description": "Unauthorized Access",
            "schema": {
              "$ref": "#/definitions/ApiUnauthorizedError"
            }
          }
        }
      }
    },
    "/events/validate": {
      "post": {
        "tags": [
          "Events"
        ],
        "summary": "Upload file for validation",
        "description": "Upload a batch file for Analytics validation. This file is not stored on the server or processed into Analytics. Validation is only for testing file format.",
        "operationId": "fileValidatePost",
        "consumes": [
          "multipart/form-data"
        ],
        "produces": [
          "application/json"
        ],
        "parameters": [
          {
            "$ref": "#/parameters/authorization"
          },
          {
            "$ref": "#/parameters/x-api-key"
          },
          {
            "name": "x-adobe-vgid",
            "in": "header",
            "description": "Visitor Group ID. See [Visitor groups](https://developer.adobe.com/analytics-collection-apis/endpoints/bulk-data-insertion/visitor-groups/) for more information.",
            "required": true,
            "type": "string"
          },
          {
            "name": "file",
            "in": "formData",
            "description": "Gzip compressed CSV file sent with request",
            "required": true,
            "type": "file"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "schema": {
              "$ref": "#/definitions/ValidationResult"
            }
          },
          "400": {
            "description": "Request Error",
            "schema": {
              "$ref": "#/definitions/ApiError"
            }
          },
          "401": {
            "description": "Unauthorized Access",
            "schema": {
              "$ref": "#/definitions/ApiUnauthorizedError"
            }
          }
        }
      }
    },
    "/events/key/{idempotency_key}": {
      "get": {
        "tags": [
          "Events"
        ],
        "summary": "Look up a file by idempotency key",
        "description": "Verify whether a file was received by Adobe. Use this endpoint when a POST to the events endpoint does not return a response, to check whether the upload was received before resubmitting it.",
        "operationId": "idempotencyKeyLookup",
        "produces": [
          "application/json"
        ],
        "parameters": [
          {
            "name": "idempotency_key",
            "in": "path",
            "description": "The idempotency key supplied with the original upload (the x-adobe-idempotency-key value), or the generated file_id if no key was supplied.",
            "required": true,
            "type": "string"
          },
          {
            "$ref": "#/parameters/authorization"
          },
          {
            "$ref": "#/parameters/x-api-key"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "schema": {
              "$ref": "#/definitions/IdempotencyLookupResult"
            }
          },
          "401": {
            "description": "Unauthorized Access",
            "schema": {
              "$ref": "#/definitions/ApiUnauthorizedError"
            }
          },
          "404": {
            "description": "File not found",
            "schema": {
              "$ref": "#/definitions/ApiError"
            }
          }
        }
      }
    }
  },
  "definitions": {
    "ApiError": {
      "type": "object",
      "properties": {
        "error": {
          "type": "string",
          "example": "File not found",
          "description": "A general request error message"
        }
      }
    },
    "ApiUnauthorizedError": {
      "type": "object",
      "properties": {
        "error": {
          "type": "string",
          "example": "Invalid token (1)",
          "description": "Error during authentication"
        }
      }
    },
    "ValidationResult": {
      "type": "object",
      "properties": {
        "success": {
          "type": "string",
          "example": "File is valid",
          "description": "A success message for validation requests"
        },
        "error": {
          "type": "string",
          "example": "File has 2 rows that do not conform to the required CSV format! (Ex: row #59)",
          "description": "The reason a file failed validation"
        }
      }
    },
    "IdempotencyLookupResult": {
      "type": "object",
      "properties": {
        "file_id": {
          "type": "string",
          "example": "22eea6b6-eecf-4d13-b70f-abbb8a81efa2",
          "description": "The file ID as a GUID"
        },
        "size": {
          "type": "integer",
          "format": "int64",
          "example": 1687458,
          "description": "The size of the compressed file in bytes"
        },
        "received_date": {
          "type": "integer",
          "format": "int64",
          "example": 1650323049,
          "description": "The date the file was received, in unix epoch time"
        },
        "rows": {
          "type": "integer",
          "format": "int64",
          "example": 10212,
          "description": "The number of rows in the file"
        },
        "idempotency_key": {
          "type": "string",
          "description": "The idempotency key used to look up the file"
        }
      }
    },
    "UploadedFileInfo": {
      "type": "object",
      "properties": {
        "file_id": {
          "type": "string",
          "example": "9c99f999-fca9-999c-9c99-b99aaec99e99",
          "description": "The file ID as a GUID"
        },
        "visitor_group_id": {
          "type": "string",
          "example": "myvisitorgroup1",
          "description": "The visitor group of the file"
        },
        "size": {
          "type": "integer",
          "format": "int64",
          "example": 355600,
          "description": "The size of the compressed file in bytes"
        },
        "received_date": {
          "type": "integer",
          "format": "int64",
          "example": 1506999999,
          "description": "The date the file was uploaded in unix epoch time."
        },
        "rows": {
          "type": "integer",
          "format": "int64",
          "example": 10000,
          "description": "The number of rows in the file"
        },
        "invalid_rows": {
          "type": "integer",
          "format": "int64",
          "example": 42,
          "description": "The number of rows not submitted to analytics for being invalid"
        },
        "upload_name": {
          "type": "string",
          "example": "myfile1.gz",
          "description": "The file name as it was uploaded"
        },
        "status": {
          "type": "string",
          "description": "The status of the file"
        },
        "status_code": {
          "type": "string",
          "example": "UPLOADED",
          "description": "The status of the file as a short name",
          "enum": [
            "REJECTED",
            "UPLOADED",
            "PROCESSING",
            "COMPLETE",
            "ERROR"
          ]
        },
        "processing_log": {
          "type": "string",
          "description": "A log of errors produced while processing the file"
        },
        "idempotency_key": {
          "type": "string",
          "description": "Either the value of the x-adobe-idempotency-key if supplied, or the file_id"
        },
        "error": {
          "type": "string",
          "example": "File not in GZIP format",
          "description": "An error message for unsuccessful requests"
        }
      }
    }
  }
}