Core API — Folders Module#
Praemunio API • Version 1 • Developer DocumentationThe Folders module manages directory tree structures, nested folder hierarchies, directory relocation, and batch folder operations within Praemunio Workspaces.| Key | Value |
|---|
| Base URL | https://api.praemunio.org/api/v1 |
| Format | JSON (Content-Type: application/json) |
| Authentication | Bearer Token (Authorization: Bearer <access_token>) |
| Required Scopes | folders:read, folders:write, folders:delete |
Table of contents#
1. Overview & Hierarchy Mechanics#
Folders allow structured directory nesting inside a workspace. A folder at the root level has parentFolderId: null. Setting parentFolderId to another folder ID creates a child subfolder.
2. Endpoints Reference#
POST /folders/create#
Creates a new folder inside a workspace or parent folder.Scope Required: folders:write
Request Body#
{
"workspaceId": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
"name": "Audit Reports",
"description": "Folder for annual audit reports",
"parentFolderId": "c3d4e5f6-a7b8-9012-cdef-345678901234"
}
| Field | Type | Required | Description |
|---|
workspaceId | string (UUID) | Yes | Target workspace UUID |
name | string | Yes | Folder name (Min 1 char) |
description | string | No | Optional description |
parentFolderId | string (UUID) | No | Parent folder UUID (omit or null for root level) |
Response (201 Created)#
{
"success": true,
"message": "Folder created successfully",
"result": {
"id": "e5f6a7b8-c9d0-1234-ef01-567890123456",
"workspaceId": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
"name": "Audit Reports",
"parentFolderId": "c3d4e5f6-a7b8-9012-cdef-345678901234",
"createdAt": "2026-09-30T11:15:00.000Z"
},
"errors": null,
"except": null
}
GET /folders/details#
Fetches metadata for a specific folder.Scope Required: folders:read
Query Parameter: folder_id (required UUID)
GET /folders#
Lists all folders belonging to a workspace.Scope Required: folders:read
Query Parameter: workspace_id (required UUID)
GET /folders/content#
Retrieves child folders and documents contained inside a target folder.Scope Required: folders:read
Query Parameter: folder_id (required UUID)
Response (200 OK)#
{
"success": true,
"message": "Folder content retrieved successfully",
"result": {
"folder": {
"id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
"name": "Contracts 2026"
},
"subfolders": [
{
"id": "e5f6a7b8-c9d0-1234-ef01-567890123456",
"name": "Audit Reports"
}
],
"documents": [
{
"id": "d4e5f6a7-b8c9-0123-def0-456789012345",
"name": "Financial_Statement.pdf"
}
]
},
"errors": null,
"except": null
}
PUT /folders/update#
Updates folder metadata (name or description).Scope Required: folders:write
Request Body#
{
"id": "e5f6a7b8-c9d0-1234-ef01-567890123456",
"name": "Q4 Audit Reports & Exhibits",
"description": "Updated folder title"
}
POST /folders/move#
Relocates a single folder to a new parent folder or workspace.Scope Required: folders:write
Request Body#
{
"folderId": "e5f6a7b8-c9d0-1234-ef01-567890123456",
"parentFolderId": "f6a7b8c9-d0e1-2345-f012-678901234567"
}
PATCH /folders/batch#
Performs batch updates or batch moves on multiple folders simultaneously.Scope Required: folders:write
Request Body#
{
"folderIds": [
"e5f6a7b8-c9d0-1234-ef01-567890123456",
"a1b2c3d4-e5f6-7890-1234-567890abcdef"
],
"parentFolderId": "f6a7b8c9-d0e1-2345-f012-678901234567"
}
DELETE /folders/delete#
Deletes a folder and its nested content.Scope Required: folders:delete
HTTP Code: 204 No Content
Request Body#
{
"folder_id": "e5f6a7b8-c9d0-1234-ef01-567890123456"
}
3. Folder Tree Diagram#
4. Client Integration Example#
5. Error Reference#
| HTTP Status | Code | Cause | Action |
|---|
400 Bad Request | invalid_request | Invalid UUID or self-referential parent move | Correct destination ID |
403 Forbidden | insufficient_scopes | Missing folders:read or folders:write | Update key permissions |
404 Not Found | folder_not_found | Target folder ID not found | Verify folder UUID |
Support#
Modified at 2026-09-30 10:44:50
