Document folder

Create a document folder

POST /{instanceName}/api/v1/{locale}/document/folder

Creates a folder on the owning entity. Omit parentFolderId to create at top level. Duplicate sibling names are permitted, matching the platform. 201 with a Location header.

Request body

application/json → DocumentFolderCreateDto

Responses

Example

curl -X POST "https://api.visena.example/acme/api/v1/en/document/folder" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "entityType": "Company",
    "entityId": "bQ4wR8",
    "name": "Contracts"
  }'

List an owning entity's document folders

GET /{instanceName}/api/v1/{locale}/document/folder

Returns the owner's folder tree as a flat list ordered so a parent always precedes its children, which is all a caller needs to rebuild the tree from parentId. A top-level folder reports parentId: null; the internal system folder is never included. An owner that has no folders yet answers an empty list — the read never creates one.

Parameters

Responses

Example

curl "https://api.visena.example/acme/api/v1/en/document/folder?entityType=Company&entityId=bQ4wR8" \
  -H "Authorization: Bearer $TOKEN"

Rename a document folder

PUT /{instanceName}/api/v1/{locale}/document/folder/{folderId}

Renames the folder. The owning entity's internal system folder cannot be renamed.

Parameters

Request body

application/json → DocumentFolderRenameDto

Responses

Example

curl -X PUT "https://api.visena.example/acme/api/v1/en/document/folder/fR5sK1" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Contracts 2026"
  }'

Move a document folder under a new parent

PUT /{instanceName}/api/v1/{locale}/document/folder/{folderId}/move

Re-parents the folder. A null destinationFolderId moves it to top level. Source and destination must belong to the same owning entity, and a folder cannot be moved into itself or into one of its own descendants — that is rejected with 409 rather than silently ignored.

Parameters

Request body

application/json → DocumentFolderMoveDto

Responses

Example

curl -X PUT "https://api.visena.example/acme/api/v1/en/document/folder/fR5sK1/move" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "destinationFolderId": "fR5sK1"
  }'

Download a folder's documents as a zip bundle

GET /{instanceName}/api/v1/{locale}/document/folder/{folderId}/content

Streams the folder's documents as a single zip, reproducing the folder structure so an unpacked bundle mirrors the tree. The owning entity's internal system folder cannot be bundled, and a tree deeper than 32 levels or holding more than 5000 documents is refused with 413 before any bytes are streamed. recursive defaults to true (the whole subtree); pass false for the folder's own documents only. Which was served is stated in the Content-Disposition file name.

Authorization is per folder, by the declared owning entity: the folder must belong to entityType/entityId, and the bundle then contains every document placed in it. It is not filtered document by document, so a bundle is all-or-nothing rather than a partial result. Two documents resolving to the same entry name are both included under distinct names, and same-named sibling folders are kept apart — nothing is silently dropped or merged. Empty folders appear as directory entries.

Parameters

Responses

Example

curl "https://api.visena.example/acme/api/v1/en/document/folder/fR5sK1/content?recursive=true" \
  -H "Authorization: Bearer $TOKEN"

Delete a document folder and its subtree

DELETE /{instanceName}/api/v1/{locale}/document/folder/{folderId}

Deletes the folder, its sub-folders, and the documents placed in them.

This destroys documents, and its effect reaches outside the folder. A document whose primary placement is in the deleted subtree is deleted outright, which also removes every shortcut placement of it — including placements under other owning entities. Only a shortcut placement inside the subtree is removed on its own, leaving the document intact elsewhere.

Because of that, a delete whose extent is not placement-only answers 409 whose detail states how many documents would be destroyed and how many shortcut placements would go with them, and nothing is deleted. Re-send with acknowledgeCascade=true to proceed. A folder whose subtree holds nothing, or only shortcut placements, deletes straight away. The owning entity's internal system folder cannot be deleted.

Parameters

Responses

Example

curl -X DELETE "https://api.visena.example/acme/api/v1/en/document/folder/fR5sK1" \
  -H "Authorization: Bearer $TOKEN"