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 provider's storage, 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.
Retrieve Download Request Metadata
For a specific file:
GET https://api.merge.dev/api/filestorage/v1/files/{file_id}/download/request-meta
Retrieves request metadata required to download a specific file directly from the file storage provider.
For a list of files (with pagination):
GET https://api.merge.dev/api/filestorage/v1/files/download/request-meta
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.
Supported Export MIME types by Integration
At the moment, Google Drive, Sharepoint, and OneDrive are the only integrations that we support specifying document export formats for. Other integrations are coming soon.
When requesting file exports, use the mime_types query parameter to specify a list of desired MIME types. If a file does not support any of the provided MIME types, the file will be returned in the integration’s default format. Valid MIME types vary by integration (see list below).
Google Drive
The exported content is limited to 10MB, see Google API docs.
If an export mime type is not specified, and the file is exportable, then it will be exported as a PDF document by default.
The document requested for export must be one of the following Google Workspace documents: Google Docs (MIME type application/vnd.google-apps.document), Google Sheets (MIME type application/vnd.google-apps.spreadsheet), Google Slides (application/vnd.google-apps.presentation), Google Drawings (MIME type application/vnd.google-apps.drawing).
Document Type | Format | Supported mime_type parameter values |
Google Documents | Microsoft Word | docx |
| OpenDocument | odt |
| Rich Text | rtf |
| ||
| Plain Text | txt |
| Web Page (HTML) | zip |
| EPUB | epub |
Google Spreadsheets | Microsoft Excel | xlsx |
| OpenDocument | ods |
| ||
| Web Page (HTML) | zip |
| Comma Separated Values (first-sheet only) | csv |
| Tab Separated Values (first-sheet only) | tsv |
Google Presentations | Microsoft PowerPoint | pptx |
| ODP | odp |
| ||
| Plain Text | txt |
Google Drawings | ||
| JPEG | jpg |
| PNG | png |
| Scalable Vector Graphics | svg |
Sharepoint & OneDrive
Format | Supported mime_type parameter values |
csv, doc, docx, odp, ods, odt, pot, potm, potx, pps, ppsx, ppsxm, ppt, pptm, pptx, rtf, xls, xlsx | |
loop, fluid, wbtx | html |