📁 DataHub API Endpoints -- Data Files

These endpoints provide access to data files either individually or in a paginated list format.

📄 1. Get a Specific File

Endpoint:

GET https://d17fc0a885.execute-api.ap-southeast-2.amazonaws.com/dev/api/data-files/{id}

🔹 Path Parameters

Name Type Required Description
id string ✅ Yes The unique identifier of the file to fetch.

🔹 Query Parameters

Name Type Required Description
includeMetadata boolean ❌ No If true, returns file metadata.
includeRaw boolean ❌ No If true and the file is a CSV/TSV under 7MB, returns the raw content.

🧾 Accept Headers

Header Description
Accept: application/json Returns detailed file metadata. (Default)
Accept: text/plain Returns only a presigned URL as plain text (no JSON wrapper)

✅ Response (application/json)

{
  "fileName": "example.csv",
  "fileType": "text/csv",
  "fileSize": 654321,
  "presignedUrl": "https://s3.amazonaws.com/bucket/key?signature...",
  "metaData": { /* optional metadata */ },
  "rawContent": "column1,column2\nvalue1,value2" // Optional
}

✅ Response (text/plain)

https://s3.amazonaws.com/bucket/key?signature...

Node.js Example 
const axios = require('axios');

// Replace the following with your credentials from the Datahub sidebar
const CUSTOMER_ID = '<your-customer-id>';  // e.g. 3958461203958
const API_KEY = '<your-api-key>';          // e.g. 1f83a294be7...

const fileId = '<your-file-id-here>'; // File you'd like to fetch

// Optional query parameters
const params = {
  includeMetadata: true,
  includeRaw: true
};

axios.get(`https://d17fc0a885.execute-api.ap-southeast-2.amazonaws.com/dev/api/data-files/${fileId}`, {
  headers: {
    'X-Customer-ID': CUSTOMER_ID,
    'Authorization': `Bearer ${API_KEY}`,
    'Accept': 'application/json' // or 'text/plain' for just download URL
  },
  params
}).then(res => {
  console.log(res.data);
}).catch(err => {
  console.error('Error fetching file:', err.response?.data || err.message);
});
Python Example 
import requests

# Replace the following with your credentials from the Datahub sidebar
CUSTOMER_ID = '<your-customer-id>'  # e.g. 3958461203958
API_KEY = '<your-api-key>'          # e.g. 1f83a294be7...

headers = {
    'X-Customer-ID': CUSTOMER_ID,
    'Authorization': f'Bearer {API_KEY}',
    'Accept': 'application/json'  # or 'text/plain' for just download URL
}

# File ID you'd like to fetch
file_id = 'abc123xyz'

# Optional query parameters
params = {
    'includeMetadata': 'true',
    'includeRaw': 'false'
}

url = f'https://d17fc0a885.execute-api.ap-southeast-2.amazonaws.com/dev/api/data-files/{file_id}'

response = requests.get(url, headers=headers, params=params)

if response.ok:
    print(response.json())
else:
    print(f"Error: {response.status_code} - {response.text}")

📚 2. List Files

Endpoint:

GET https://d17fc0a885.execute-api.ap-southeast-2.amazonaws.com/dev/api/data-files

🔹 Query Parameters

Name Type Required Description
page integer ❌ No Page number (default: 1).
limit integer ❌ No Number of files per page (default: 10).
includeMetadata boolean ❌ No If true, includes metadata for each file.

🧾 Accept Header

Accept: application/json

✅ Response

{
  "data": [
    {
      "id": "676210bc47ec2f9a2282c2e6",
      "fileName": "12345_daily_pressure_metadata",
      "metaData": { /* optional metadata */ }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "totalResults": 47,
    "totalPages": 5
  }
}
Node.js Example 
const axios = require('axios');

// Replace the following with your credentials from the Datahub sidebar
const CUSTOMER_ID = '<your-customer-id>';  // e.g. 3958461203958
const API_KEY = '<your-api-key>';          // e.g. 1f83a294be7...

// Optional query parameters
const params = {
  page: 1,               // Page number (default: 1)
  limit: 10,             // Number of files per page (default: 10)
  includeMetadata: true  // Whether to include metadata for each file
};

const url = 'https://d17fc0a885.execute-api.ap-southeast-2.amazonaws.com/dev/api/data-files';

axios.get(url, {
  headers: {
    'X-Customer-ID': CUSTOMER_ID,
    'Authorization': `Bearer ${API_KEY}`,
    'Accept': 'application/json'
  },
  params
})
.then(response => {
  const data = response.data;
  console.log('List of files:', data.data);
  console.log('Pagination info:', data.pagination);
})
.catch(error => {
  if (error.response) {
    console.error('Request failed with status:', error.response.status);
    console.error('Response data:', error.response.data);
  } else if (error.request) {
    console.error('No response received:', error.request);
  } else {
    console.error('Error setting up request:', error.message);
  }
});
Python Example 
import requests

# Replace with your credentials from the Datahub sidebar
CUSTOMER_ID = '<your-customer-id>'  # e.g. 3958461203958
API_KEY = '<your-api-key>'          # e.g. 1f83a294be7...

# Optional query parameters
params = {
    'page': 1,               # Page number (default 1)
    'limit': 10,             # Number of files per page (default 10)
    'includeMetadata': 'true' # Include metadata for each file (optional)
}

headers = {
    'X-Customer-ID': CUSTOMER_ID,
    'Authorization': f'Bearer {API_KEY}',
    'Accept': 'application/json'
}

url = 'https://d17fc0a885.execute-api.ap-southeast-2.amazonaws.com/dev/api/data-files'

response = requests.get(url, headers=headers, params=params)

if response.ok:
    data = response.json()
    print("List of files:", data.get('data', []))
    print("Pagination info:", data.get('pagination', {}))
else:
    print(f"Error: {response.status_code} - {response.text}")

🔐 Authentication

All API requests require two headers:

Header Example Value Description
X-Customer-ID 3958461203958 Your unique customer ID, found in the Datahub website sidebar.
Authorization Bearer YOUR_API_KEY Your API key prefixed with Bearer . Also found in the Datahub sidebar.

⚠️ Keep your API Key secret. Never expose it in frontend code or public repositories.

🔑 Where to Find Credentials

You can find your Customer ID and API Key in the sidebar of the Datahub web interface after logging in.

  • Customer ID uniquely identifies your organization.

  • API Key grants secure access to your data.

🔁 Example Header Format

X-Customer-ID: 3958461203958
Authorization: Bearer 1f83a294be7f2e98cd0e87ad3caeaf70aa3d63b4a120cb6da8d79c3fc6c1e112

🔢 HTTP Status Codes and Error Handling

Every API response includes a standard HTTP status code, and in case of an error, a structured JSON payload with a descriptive error code and message.

✅ 200 OK

Returned when the request is successful. The response format depends on the Accept header.

⚠️ 400 Bad Request

These errors occur when the request is malformed or invalid.

Error Code Description
INVALID_ACCEPT_HEADER Accept header must be application/json or text/plain.
MISSING_CUSTOMER_ID X-Customer-ID header is required.
MISSING_DATA_FILE_ID Missing dataFileId path parameter.
ORDER_NOT_APPROVED Associated Shopify order is not fulfilled.
DATA_FILE_TOO_OLD File is no longer available for download.
INVALID_DATA_FILE_ID Not a valid MongoDB ObjectId.
UNSUPPORTED_ACCEPT_HEADER Fallback if header format isn't supported.

🔐 401 Unauthorized

These errors indicate authentication issues.

Error Code Description
MISSING_AUTH_HEADER Authorization header is missing.
INVALID_API_KEY API key is incorrect or expired.

❌ 404 Not Found

Returned when a resource cannot be located.

Error Code Description
NO_ORDERS_FOUND No orders found for this customer.
DATA_FILE_NOT_FOUND The dataFileId wasn't in any order.
DATA_FILE_NOT_FOUND_IN_DB File not present in the database.

💥 500 Internal Server Error

Unexpected failures during file processing.

Error Code Description
FILE_METADATA_ERROR Could not fetch file metadata.
FILE_DOWNLOAD_ERROR Failed to stream or retrieve the file.