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 canvas messaging layer.

The demo canvas 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.