Document Library Management

Document libraries exist at organization, cluster, and location scope. A document is stored as a FileArtifact and can be listed, downloaded, versioned, zipped, searched, commented on, and opened in collaboration flows when the file type is supported.

Core Flow

List documents from the scope the user is viewing:

GET /v1/spatial/documents
GET /v1/spatial/clusters/{clusterId}/documents
GET /v1/spatial/locations/{locationId}/documents
GET /v1/orgs/{organizationId}/documents

Use GET /v1/spatial/documents for documents attached directly to all readable clusters, or add clusterIds to limit the response to selected clusters. The route accepts repeated query values and comma-separated values. It does not include location documents.

Use search, sortBy, sortDir, versionFilter, documentTypes, offset, and limit to keep large libraries navigable. Set linkType=file, linkType=small, or linkType=medium only when the current view needs immediate download or thumbnail URLs.

Use folderPath to show one folder and recursive=true when a view should include descendants. Omit folderPath for the whole library, or send folderPath= for root-level documents only.

Folders

Folder APIs exist for organization, cluster, and location libraries:

GET /v1/spatial/locations/{locationId}/documents/folders
POST /v1/spatial/locations/{locationId}/documents/folders
PATCH /v1/spatial/locations/{locationId}/documents/folders/{folderId}
DELETE /v1/spatial/locations/{locationId}/documents/folders/{folderId}
PATCH /v1/spatial/documents/{documentId}/folder

Cluster and organization scopes use the same /documents/folders pattern under their own routes. Folder list responses include direct document count, descendant document count, child folder count, and whether the folder was explicitly created or only inferred from document paths.

Renaming a folder moves the logical subtree and updates document folderPath values. It does not rewrite object-storage keys. Deleting a folder requires it to be empty.

Comments

When a user opens a document detail or preview surface, load comments with:

GET /v1/spatial/documents/{documentId}/comments?offset=0&limit=50

Each comment includes author identity fields for rendering:

{
  "id": "77777777-7777-7777-7777-777777777777",
  "documentId": "44444444-4444-4444-4444-444444444444",
  "authorUserId": "11111111-1111-1111-1111-111111111111",
  "authorUsername": "pascal",
  "authorDisplayName": "Pascal",
  "authorProfilePicture": null,
  "body": "Please verify permit revision 3 before handover.",
  "createdAtUtc": "2026-05-31T15:00:00Z",
  "updatedAtUtc": null,
  "canEdit": true,
  "canDelete": true
}

Create comments with:

POST /v1/spatial/documents/{documentId}/comments

{
  "body": "Please verify permit revision 3 before handover."
}

Edit and delete use the comment id:

PATCH /v1/spatial/documents/{documentId}/comments/{commentId}
DELETE /v1/spatial/documents/{documentId}/comments/{commentId}

Read access to the document is enough to list comments. Current write access is required to create, edit, or delete comments. Users can edit or delete only their own comments.