Message API/docs/components/batch-export/single-download

Single Download

POST one export identifier and receive either the file stream or the exported URL.

Endpoint

This route resolves one export and returns either the file or the exported URL.

Method: `POST`
Path: `/viewer/exports/download`
Content-Type: `application/json`
Auth header: `x-api-key: CLIENT_API_KEY` when the backend protects export routes. If you need to issue or manage that client key, see API Key Management Overview.
Base URL example: `https://db-backend-domain/api`

Request Body

Send `sourceFileUrl` in the body.

Request examples

{
  "sourceFileUrl": "https://example.com/original.pdf"
}

Route Examples

Call the same route in one of two ways depending on the response you need.

Without responseType

POST https://db-backend-domain/api/viewer/exports/download

With responseType=urls

POST https://db-backend-domain/api/viewer/exports/download?responseType=urls

Response Modes

The same route supports binary download mode and JSON URL mode.

Default: backend returns the actual file stream.
URL mode: `POST /viewer/exports/download?responseType=urls` returns JSON.
URL response shape: `{ "success": true, "exportedUrl": "https://..." }`

Frontend Handling

Do not use the same response parsing logic for both modes.

Default mode: read the response as a blob and trigger browser download.
URL mode: read the response as JSON.
Filename source: prefer `Content-Disposition` when the backend provides it.
Fallback: only use a generic client-side default such as `canvas-export` when the header is missing or unreadable.

Client Example

Use separate client examples for the default download response and the URL-only response.

Without responseType

async function downloadSingleExport(sourceFileUrl) {
  const response = await fetch('https://db-backend-domain/api/viewer/exports/download', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': CLIENT_API_KEY,
    },
    body: JSON.stringify({ sourceFileUrl }),
  });

  if (!response.ok) {
    throw new Error(`Single export failed with status ${response.status}.`);
  }

  const blob = await response.blob();
  const header = response.headers.get('content-disposition');
  const match = header?.match(/filename\*?=(?:UTF-8''|")?([^;"]+)/i);
  const fileName = match?.[1] ? decodeURIComponent(match[1]) : 'canvas-export';
  const objectUrl = URL.createObjectURL(blob);

  try {
    const anchor = document.createElement('a');
    anchor.href = objectUrl;
    anchor.download = fileName;
    document.body.appendChild(anchor);
    anchor.click();
    anchor.remove();
  } finally {
    URL.revokeObjectURL(objectUrl);
  }
}

With responseType=urls

async function fetchSingleExportUrl(sourceFileUrl) {
  const response = await fetch(
    'https://db-backend-domain/api/viewer/exports/download?responseType=urls',
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'x-api-key': CLIENT_API_KEY,
      },
      body: JSON.stringify({ sourceFileUrl }),
    },
  );

  if (!response.ok) {
    throw new Error(`Single export URL request failed with status ${response.status}.`);
  }

  return response.json();
}