Overview

The Direct File Download endpoint retrieves the metadata required to download file contents directly from third-party storage providers. This is the recommended approach over the legacy Merge Processed File Download endpoint.

How it works

This endpoint does not return the file content itself - it returns the request metadata (URL, HTTP method, and headers) needed for you to fetch the file directly from the third-party provider.

Endpoints

• GET /files/download/request-meta: Retrieves download metadata for multiple files.

• GET /files/{id}/download/request-meta: Retrieves download metadata for a specific file

Request parameters

You can find the full list of supported query parameters in the API reference. A few notable ones:

1. ids: If provided, only returns objects with the given file IDs (Merge ID). This is particularly useful for retrieving metadata for multiple files in a single API call.

2. mime_type & mime_types: If supported by the third-party provider, the file(s) will be returned in the specified MIME type. See the Supported Export MIME Types section for more details.

Request example with ids param

To retrieve metadata for two files, a sample request URL would be:

https://api.merge.dev/api/filestorage/v1/files/download/request-meta?ids={file_id_1},{file_id_2}

Response structure

The response contains the metadata required to download the contents of each requested file. Each object in the response includes:

1. id: The Merge ID of the file.

2. method: The HTTP method to use when making the download request (e.g. GET).

3. url: The request URL to call to download the file content.

4. headers: An object containing the headers required for the download request, which may include:

   • Authorization: The bearer token needed for authentication

Example response

"results": [
    {
      "id": "40c7e334-b6ee-4d2c-b7f1-1562f80d7636",
      "method": "GET",
      "url": "https://www.googleapis.com/drive/v3/files/1sWKWlUjn_bct5fscXJu4XaLjSp28e4xi?alt=media",
      "headers": {
        "Authorization": "Bearer 1234"
      }
    },
    {
      "id": "657095d2-959c-4600-9646-79a5dd8a48aa",
      "method": "GET",
      "url": "https://docs.google.com/feeds/download/documents/export/Export?id=1Kiq61VvPXW9HansOzgPTzNsxBOVc0p5ZFYhhkNhSCco&exportFormat=pdf",
      "headers": {
        "Authorization": "Bearer 5678"
      }
    }
  ]

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:

1. 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.

2. 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

When requesting file exports, you are able to use a 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).

Depending on which endpoint you're using, use one of the below query parameters:

• /files/{file_id}/download/request-meta: mime_type

• /files/download/request-meta: mime_types

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).

Sharepoint & OneDrive