Download Document ZIPs

How to request cached ZIP archives for all or selected documents in organization, cluster, and location scopes.

Document ZIP downloads are prepared asynchronously by the background-jobs host. The first request usually returns a preparation status. When the archive is ready, the same request returns a temporary download URL.

Scope endpoints

Cluster documents:

GET /v1/spatial/clusters/{clusterId}/documents/zip/status
GET /v1/spatial/clusters/{clusterId}/documents/zip/download
POST /v1/spatial/clusters/{clusterId}/documents/zip/status
POST /v1/spatial/clusters/{clusterId}/documents/zip/download

Location documents:

GET /v1/spatial/locations/{locationId}/documents/zip/status
GET /v1/spatial/locations/{locationId}/documents/zip/download
POST /v1/spatial/locations/{locationId}/documents/zip/status
POST /v1/spatial/locations/{locationId}/documents/zip/download

Organization documents:

GET /v1/orgs/{organizationId}/documents/zip/status
GET /v1/orgs/{organizationId}/documents/zip/download
POST /v1/orgs/{organizationId}/documents/zip/status
POST /v1/orgs/{organizationId}/documents/zip/download

All documents

Call the GET download endpoint without folderPath, or call the POST download endpoint with {}.

POST /v1/spatial/locations/{locationId}/documents/zip/download
Content-Type: application/json

{}

If the ZIP is not ready, the API returns 202 Accepted with progress fields. Poll the matching status endpoint or repeat the download request.

Folder documents

Use the GET endpoints with folderPath when only one document folder should be archived.

GET /v1/spatial/locations/{locationId}/documents/zip/download?folderPath=permits/2026

ZIP entry names use logical document folder paths. If a document is moved from permits/2026 to archive/permits/2026, new archives use the new folder path even when the stored object key remains unchanged.

Selected documents

Use the POST endpoints with documentIds when the user chooses specific files.

{
  "documentIds": [
    "44444444-4444-4444-4444-444444444444",
    "55555555-5555-5555-5555-555555555555"
  ]
}

Every selected document must belong to the requested scope. Equivalent selections reuse the same active or completed archive even when IDs are sent in a different order.

Response

{
  "status": 3,
  "progressPercent": 100,
  "progressBytes": 123456,
  "totalBytes": 123456,
  "archiveSizeBytes": 98304,
  "preparedAtUtc": "2026-05-31T12:00:00Z",
  "statusUpdatedAtUtc": "2026-05-31T12:00:00Z",
  "downloadUrl": "https://storage.example.test/presigned",
  "expiresAt": "2026-05-31T12:15:00Z",
  "fileName": "site-a-selected-documents.zip",
  "error": null
}

status uses the shared ZIP preparation enum: 0 none, 1 queued, 2 preparing, 3 ready, and 4 failed.

Cached ZIP outputs are removed by the configured ZIP retention cleanup. Clients should treat downloadUrl as temporary and request the archive again when it expires.