Overview
The Direct File Download endpoint allows you to retrieve files directly from third-party API providers instead of downloading files through Merge's API.
How It Works
When you request a file’s download metadata from Merge, the API returns the complete request details, including:
Merge ID of the file
HTTP method (GET, POST, etc.)
Download URL with query parameters attached
Required headers (including authentication)
This enables you to make the request directly to the third-party storage provider, bypassing Merge’s servers and reducing latency.
You can now pass a MIME type as a query parameter to the Direct File Download endpoint, allowing you to specify the file format during download—just like our legacy File Download endpoint. For details, refer to our File Export and Download Specification. Note: This feature is currently only supported by Google Drive.
Retrieve Download Request Metadata
For a specific file:
Retrieves request metadata required to download a specific file directly from the file storage provider.
For a list of files (with pagination):
Retrieves request metadata required to download files directly from the file storage provider.
Example API response for /files/{file_id}/download/request-meta
{
"id": "460b4c28-fdfb-4f91-8110-7d271aace02a",
"method": "GET",
"url": "https://www.googleapis.com/drive/v3/files/11GSD44ifq3u00TCn2ZPdMZ3oG6Mb50ci?alt=media",
"headers": {
"Authorization": "Bearer TOKEN,
"email_address": "[email protected]"
}
}
Making a Direct File Request
Once you have the request metadata, you can fetch the file or files directly from the third-party provider using standard HTTPS requests. This will be available in Merge SDKs in the coming weeks.
Example Python Code:
import requests
API_KEY = "your_api_key"
ACCOUNT_TOKEN = "your_account_token"
BASE_URL = "https://api.merge.dev"
# Retrieve download metadata
response = requests.get(
f"{BASE_URL}/api/filestorage/v1/files/your_file_id/download/request-meta",
headers={
"Authorization": f"Bearer {API_KEY}",
"X-Account-Token": ACCOUNT_TOKEN,
"Accept": "application/json"
}
)
data = response.json()
# Use metadata to fetch the file directly
file_response = requests.get(
url=data["url"],
headers=data["headers"],
)
Error Handling
The request metadata endpoint will return a 400 error when a file’s request metadata is unavailable. This can happen for two reasons:
If the file has not been synced by Merge since the Direct File Download endpoint was introduced on 02/12/25, the error message will be:
“This object’s download request metadata is not yet populated. Please wait for syncing to complete.”To handle this, we recommend falling back to the legacy File Download endpoint.If the file cannot be downloaded from the third party, the error message will be:
“This object does not support file download.”. This may be due to file type limitations, permissions restrictions, or security policies.