1. CORE
PRAEMUNIO API
  • Praemunio API - v1
  • AUTHENTICATION
    • API KEY Authentification
      POST
  • CORE
    • Teams
      • Members
        • Get Team Members
        • Add Team Member
        • Add Team Member Copy
      • Get Account Teams
      • Create Team
      • Get Team Details
      • Update Team Data
      • Delete Team
      • Get Team Data
      • Get Team workspaces
      • Get Team logs
    • Workspaces
      • Get Account Drive
      • Get Workspaces By Team
      • Create New Workspace
      • Get Workspace Details
      • Get Team Workspaces
      • Update workspace
      • Delete workspace
    • Folders
      • Get Folders
      • Create Folder
      • Get Folder Details
      • Get Folder Content
      • Update Folder
      • Delete Folder
      • Move Folder
    • Documents
      • Get Document Info
      • Get Document By Workspace
      • Update Document
      • Delete Document
      • Archive Document
      • Restore Document
      • Move Document
      • Stream Document
      • Stream Document Copy
      • Upload Document
  1. CORE

Documents

Core API — Documents Module#

Praemunio API • Version 1 • Developer Documentation
The Documents module provides complete management for file assets: multipart upload, status state transitions, secure payload streaming, pre-signed download URLs, metadata updates, archiving/restoration, moving/renaming, and public sharing links.
KeyValue
Base URLhttps://api.praemunio.org/api/v1
FormatJSON / Multipart Form-Data
AuthenticationBearer Token (Authorization: Bearer <access_token>)
Required Scopesdocuments:read, documents:write, documents:delete, documents:share

Table of contents#

1.
Overview & Document Lifecycle
2.
Ingestion & Retrieval Endpoints
POST /documents/upload
GET /documents/details
GET /documents
GET /documents/stream
GET /documents/download
POST /documents/public-link
3.
Lifecycle & Modification Endpoints
PUT /documents/update
POST /documents/rename
POST /documents/move
POST /documents/status
POST /documents/status/batch
POST /documents/archive
POST /documents/restore
DELETE /documents/delete
4.
Client Integration Example
5.
Error Handling Reference

1. Overview & Document Lifecycle#

A Document transitions through distinct statuses during its lifecycle:
StatusDescription
draftFile payload registered, waiting for complete transmission
pendingUploaded, queued for virus scanning and cryptographic anchoring
processingIn-flight calculation of cryptographic hashes
completedSuccessfully stored and anchored
failedProcessing failed due to validation or storage error
archivedMoved to cold archive storage
deletedMarked for deletion

2. Ingestion & Retrieval Endpoints#

POST /documents/upload#

Uploads one or more binary files to a workspace and optional folder using multipart/form-data.
Scope Required: documents:write
Query Parameters: workspace_id (required UUID), folder_id (optional UUID)

cURL Example#

Response (200 OK)#

{
  "success": true,
  "message": "Document uploaded successfully",
  "result": {
    "id": "d4e5f6a7-b8c9-0123-def0-456789012345",
    "name": "contract.pdf",
    "sizeBytes": 1048576,
    "status": "pending",
    "workspaceId": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
    "folderId": "c3d4e5f6-a7b8-9012-cdef-345678901234",
    "createdAt": "2026-09-30T11:30:00.000Z"
  },
  "errors": null,
  "except": null
}

GET /documents/details#

Fetches metadata for a document by ID.
Scope Required: documents:read
Query Parameter: document_id (required UUID)

GET /documents#

Lists all documents in a workspace.
Scope Required: documents:read
Query Parameter: workspace_id (required UUID)

GET /documents/stream#

Streams the document binary file directly over HTTP.
Scope Required: documents:read
Query Parameter: document_id (required UUID)

GET /documents/download#

Generates a secure, pre-signed download URL with a configurable Time-To-Live (TTL).
Scope Required: documents:read
Query Parameters: document_id (required UUID), ttl (seconds, default 3600)

Response (200 OK)#

{
  "success": true,
  "message": "Signed URL generated successfully",
  "result": {
    "downloadUrl": "https://storage.praemunio.io/vault/d4e5f6a7-b8c9?token=exp_1700000",
    "expiresAt": "2026-09-30T12:30:00.000Z",
    "ttlSeconds": 3600
  },
  "errors": null,
  "except": null
}

POST /documents/public-link#

Generates a public sharing URL for third-party access without requiring API key authorization.
Scope Required: documents:share
Query Parameter: document_id (required UUID)

Request Body#

{
  "ttlSeconds": 604800
}

Response (200 OK)#

{
  "success": true,
  "message": "Public link generated successfully",
  "result": {
    "shareUrl": "https://share.praemunio.io/d/pub_8f9a0b1c2d3e",
    "expiresAt": "2026-10-07T11:30:00.000Z"
  },
  "errors": null,
  "except": null
}

3. Lifecycle & Modification Endpoints#

PUT /documents/update#

Updates document title, description, or folder.
Scope Required: documents:write

POST /documents/rename#

Renames a document.
Scope Required: documents:write

Request Body#

{
  "documentId": "d4e5f6a7-b8c9-0123-def0-456789012345",
  "newName": "Final_Executed_Contract_2026.pdf"
}

POST /documents/move#

Moves a document to a different folder or workspace.
Scope Required: documents:write

Request Body#

{
  "documentId": "d4e5f6a7-b8c9-0123-def0-456789012345",
  "folderId": "e5f6a7b8-c9d0-1234-ef01-567890123456"
}

POST /documents/status#

Updates a document's status.
Scope Required: documents:write

Request Body#

{
  "documentId": "d4e5f6a7-b8c9-0123-def0-456789012345",
  "status": "completed"
}

POST /documents/status/batch#

Updates statuses for multiple documents in a single request.
Scope Required: documents:write

Request Body#

{
  "documentIds": [
    "d4e5f6a7-b8c9-0123-def0-456789012345",
    "f6a7b8c9-d0e1-2345-f012-678901234567"
  ],
  "status": "archived"
}

POST /documents/archive#

Archives a document.
Scope Required: documents:write

Request Body#

{
  "documentId": "d4e5f6a7-b8c9-0123-def0-456789012345",
  "reason": "Retention policy limit reached"
}

POST /documents/restore#

Restores an archived document.
Scope Required: documents:write

Request Body#

{
  "documentId": "d4e5f6a7-b8c9-0123-def0-456789012345"
}

DELETE /documents/delete#

Deletes a document.
Scope Required: documents:delete
HTTP Code: 204 No Content

Request Body#

{
  "document_id": "d4e5f6a7-b8c9-0123-def0-456789012345"
}

4. Client Integration Example#

5. Error Handling Reference#

HTTP StatusCodeCauseAction
400 Bad Requestinvalid_requestInvalid status transition or missing UUIDCheck status lifecycle rules
403 Forbiddeninsufficient_scopesScope missing for operationCheck documents:read/write/share
404 Not Founddocument_not_foundDocument ID not foundVerify document ID

Support#

Visit docs.praemunio.io.
Modified at 2026-09-30 10:46:40
Previous
Move Folder
Next
Get Document Info
Built with