Core API — Workspaces Module#
Praemunio API • Version 1 • Developer DocumentationThe Workspaces module handles the creation, Drive root structuring, status lifecycle, and storage quota management of Praemunio storage environments.| 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 | workspaces:read, workspaces:write, workspaces:delete |
Table of contents#
1. Overview & Storage Model#
A Workspace is a dedicated drive and storage vault owned by a team. All folders and documents live within a workspace. Workspaces enforce byte storage limits (storageLimit) and status controls (active, inactive, suspended).
2. Endpoints Reference#
POST /workspaces/create#
Initializes a new storage workspace for a team.Scope Required: workspaces:write
Request Body#
{
"teamId": "e4a9d1b0-7c2e-4f3a-8b1d-9e0f2a4c6b8d",
"name": "Q4 Audit Vault",
"description": "Secure workspace for Q4 compliance files",
"storageLimit": 107374182400
}
| Field | Type | Required | Description |
|---|
teamId | string (UUID) | Yes | Target team UUID |
name | string | Yes | Min 2 characters |
description | string | No | Workspace description |
storageLimit | number | No | Storage quota in bytes (e.g. 100 GB = 107374182400) |
Response (201 Created)#
{
"success": true,
"message": "Workspace created successfully",
"result": {
"id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
"teamId": "e4a9d1b0-7c2e-4f3a-8b1d-9e0f2a4c6b8d",
"name": "Q4 Audit Vault",
"description": "Secure workspace for Q4 compliance files",
"status": "active",
"storageUsed": 0,
"storageLimit": 107374182400,
"createdAt": "2026-09-30T11:00:00.000Z"
},
"errors": null,
"except": null
}
GET /workspaces/drive#
Retrieves the global Drive overview for the caller's account, including total account storage metrics and available workspace trees.Scope Required: workspaces:read
Response (200 OK)#
{
"success": true,
"message": "Drive overview retrieved successfully",
"result": {
"totalStorageUsed": 524288000,
"totalStorageLimit": 1099511627776,
"workspacesCount": 3,
"workspaces": [
{
"id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
"name": "Q4 Audit Vault",
"status": "active",
"storageUsed": 262144000
}
]
},
"errors": null,
"except": null
}
GET /workspaces/details#
Fetches workspace metadata and detailed storage statistics by workspace ID.Scope Required: workspaces:read
Query Parameter: workspace_id (required UUID)
cURL Example#
GET /workspaces/content#
Lists top-level (root) folders and documents within a workspace.Scope Required: workspaces:read
Query Parameter: workspace_id (required UUID)
Response (200 OK)#
{
"success": true,
"message": "Workspace content retrieved successfully",
"result": {
"folders": [
{
"id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
"name": "Contracts 2026",
"parentFolderId": null
}
],
"documents": [
{
"id": "d4e5f6a7-b8c9-0123-def0-456789012345",
"name": "Master_Agreement.pdf",
"status": "completed",
"sizeBytes": 1048576
}
]
},
"errors": null,
"except": null
}
GET /workspaces/teams#
Lists all workspaces owned by a given team ID.Scope Required: workspaces:read
Query Parameter: teamId (required UUID)
PUT /workspaces/update#
Updates workspace details or status (active, inactive, suspended).Scope Required: workspaces:write
Request Body#
{
"id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
"name": "Q4 Global Compliance Vault",
"status": "active"
}
DELETE /workspaces/delete#
Deletes a workspace and purges associated directory structures.Scope Required: workspaces:delete
HTTP Code: 204 No Content
Request Body#
{
"workspace_id": "b2c3d4e5-f6a7-8901-bcde-f23456789012"
}
3. Workspace Lifecycle State Machine#
4. Client Integration Example#
5. Error Reference#
| HTTP Status | Code | Cause | Action |
|---|
400 Bad Request | invalid_request | Invalid UUID or unknown status enum | Verify request parameters |
403 Forbidden | insufficient_scopes | Missing workspaces:read or workspaces:write | Check API key permissions |
404 Not Found | workspace_not_found | Workspace ID does not exist | Verify workspace ID |
Support#
Modified at 2026-09-30 10:45:25
