REST API

These are the four route variants the frontend can call.

• Single default: file stream
• Single URL mode: JSON with `exportedUrl`
• Batch default: zip stream
• Batch URL mode: JSON with `exportedUrls` and `skipped`
• Auth header: protected integrations send `x-api-key` with the client API key.

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

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

The single route accepts one `sourceFileUrl`. The batch route accepts an array of source file URLs.

When backend key protection is enabled, every request should include `x-api-key` alongside `Content-Type`.

• Single route: send exactly one `sourceFileUrl` in the body.
• Batch route: send an `items` array.
• Batch items: each item contains one `sourceFileUrl`.

type SingleExportDownloadRequest = {
  sourceFileUrl: string;
};

type BatchExportItem = {
  sourceFileUrl: string;
};

type BatchExportDownloadRequest = {
  items: BatchExportItem[];
};

Response parsing depends on whether `responseType=urls` is present.

• Binary default: do not parse default responses as JSON.
• Filename rule: use the backend `Content-Disposition` filename first.
• Single fallback: use a generic fallback such as `canvas-export` if the header is missing or unreadable.
• Batch fallback: use `canvas-exports.zip` only if the header is missing.
• Batch duplicate names: backend makes duplicate zip entry names unique automatically.

type SingleExportUrlResponse = {
  success: true;
  exportedUrl: string;
};

type BatchExportUrlsResponse = {
  success: true;
  exportedUrls: string[];
  skipped: unknown[];
};

Handle these statuses explicitly in the frontend instead of assuming every response is a valid download.

• 400 Bad Request: request body does not contain usable identifiers.
• 404 Not Found: backend could not resolve a matching export.
• 401/403: auth failure when protected routes are enabled.
• 5xx: backend export download or zip generation failure.

These routes belong in your backend service layer, not in the viewer messaging layer.

The demo viewer supports both blob downloads and `responseType=urls`, so the docs here map directly to the implemented overlay behavior.

If the frontend cannot read `Content-Disposition` in a cross-origin setup, it will fall back to its own generic filename.

The current demo overlay includes an `x-api-key` field in Backend Export Download and forwards that header to both single and batch endpoints.