Core API Overview & Resource Hierarchy

Praemunio API • Version 1 • Developer Documentation

The Praemunio Core API provides the structural foundation for multi-tenant enterprise document governance, team collaboration, workspace isolation, directory organization, and cryptographic asset management.

Key	Value
Base URL	`https://api.praemunio.org/api/v1`
Format	JSON (`Content-Type: application/json`)
Authentication	Bearer Token (`Authorization: Bearer <access_token>`)
Documentation	docs.praemunio.io

Architectural Overview

Resource Hierarchy & Data Model

Global Request & Response Format

Pagination Standard

Authentication & Scopes Matrix

Core Webhook Events

Global Errors Reference

Module Navigation

1. Architectural Overview

The Praemunio Core ecosystem is built around four primary structural entities that work together to guarantee strict data segregation, fine-grained access delegation, and immutable auditability.

Core Entities

Account: The primary identity (user or organization) holding credentials, billing configurations, global settings, and API keys.

Team: A collaborative group of users sharing permission templates, member roles, invitations, and workspace access rules.

Workspace: A dedicated work and storage environment bound to a team, featuring configurable storage quotas and drive properties.

Folder: A directory node within a workspace enabling tree structures, path inheritance, and single/batch asset organization.

Document: The atomic file asset managed by Praemunio, featuring cryptographic proofing, status state machine, pre-signed downloads, streaming, and public link sharing.

2. Resource Hierarchy & Data Model

The entity relationships follow a strict parent-child relational model with full cascading governance and isolated permission evaluation.

Resource Identifiers

All Core resource IDs (team_id, workspace_id, folder_id, document_id, account_id) are globally unique UUIDv4 strings (e.g. a3f8e9d2-1a4b-4c7e-9f3a-2b8c6d4e1f0a).

3. Global Request & Response Format

All API requests accepting a JSON payload must include the Content-Type: application/json header. Standard API responses are always wrapped in a unified envelope structure (ApiResponse<T>).

Standard Success Envelope (`200 OK` / `201 Created`)

{
  "success": true,
  "message": "Operation executed successfully",
  "result": {
    "id": "a3f8e9d2-1a4b-4c7e-9f3a-2b8c6d4e1f0a",
    "name": "Production Workspace",
    "created_at": "2026-09-30T10:00:00.000Z"
  },
  "errors": null,
  "except": null
}

Standard Error Envelope (`4xx` / `5xx`)

{
  "success": false,
  "message": "Validation failed or resource unavailable",
  "result": null,
  "errors": "Invalid parameter 'workspace_id': Must be a valid UUIDv4 string",
  "except": {
    "code": "invalid_request",
    "status": 400
  }
}

4. Pagination Standard

Endpoints returning lists of resources support standardized offset-based pagination via query parameters:

Query Parameter	Type	Default	Description
`page`	integer	`1`	Page number to retrieve (1-indexed)
`limit`	integer	`20`	Maximum items per page (Max: `100`)

Paginated Response Envelope (`PaginatedApiResponse<T>`)

{
  "success": true,
  "message": "Resources retrieved successfully",
  "result": {
    "data": [
      {
        "id": "a3f8e9d2-1a4b-4c7e-9f3a-2b8c6d4e1f0a",
        "name": "Legal Documents"
      }
    ],
    "meta": {
      "total": 45,
      "per_page": 20,
      "current_page": 1,
      "last_page": 3,
      "first_page": 1,
      "total_pages": 3,
      "has_next": true,
      "has_prev": false,
      "from": 1,
      "to": 20
    }
  },
  "errors": null,
  "except": null
}

5. Authentication & Scopes Matrix

Access to Core API endpoints requires an HTTP Authorization header containing a valid JWT access token generated via the /auth/api-key endpoint:

Scope Requirements Matrix

Resource	Scope	Permitted Actions
Teams	`teams:read`	View team profile, member lists, invitations, permission templates, audit logs
	`teams:write`	Create/update teams, send invitations, create/update permission templates
	`teams:delete`	Delete team, revoke invitations, remove team members
Workspaces	`workspaces:read`	List workspaces, view Drive overview, inspect workspace details and root content
	`workspaces:write`	Create and update workspaces, update workspace status or storage limits
	`workspaces:delete`	Delete workspace and purge workspace storage
Folders	`folders:read`	Inspect folder metadata, list workspace folders, retrieve folder child content
	`folders:write`	Create folders, update name/description, move folders, batch update folders
	`folders:delete`	Delete folder and purge sub-tree
Documents	`documents:read`	Inspect document metadata, list workspace files, stream binary payload, get download URLs
	`documents:write`	Upload files, update metadata, update status, rename, move, archive, restore
	`documents:delete`	Soft-delete or permanently remove document
	`documents:share`	Generate public sharing links with expiration TTLs

6. Core Webhook Events

Praemunio dispatches real-time HMAC-SHA256 signed webhook payloads when Core resources change state:

Event Name	Trigger Condition
`team.created`	A new team has been created
`team.member_added`	An invited user accepted membership
`workspace.created`	A new workspace was initialized
`folder.created`	A folder was added to a workspace
`folder.moved`	A folder or batch of folders was relocated
`document.uploaded`	A new file was successfully uploaded
`document.status_changed`	Document status transitioned (e.g. `pending` -> `completed`)
`document.archived`	A document was moved to archive
`document.restored`	A document was restored from archive

7. Global Errors Reference

HTTP Code	Error Code	Description	Recommended Action
`400 Bad Request`	`invalid_request`	Query/Body parameter malformed or missing required UUID	Check request payload and schema
`401 Unauthorized`	`invalid_credentials`	Missing or expired JWT access token	Renew access token via `/auth/refresh-token`
`403 Forbidden`	`insufficient_scopes`	Access token missing required resource scope	Request a token with appropriate scope
`404 Not Found`	`not_found`	Target resource ID does not exist	Verify UUID parameter
`409 Conflict`	`resource_conflict`	Unique constraint violation (e.g. duplicate team name)	Choose a unique resource name
`429 Too Many Requests`	`rate_limit_exceeded`	Hourly request quota exhausted	Honor `X-RateLimit-Reset` header
`500 Internal Error`	`internal_error`	Server processing failure	Retry with exponential backoff

Explore detailed API references for each Core module:

Teams API Documentation

Workspaces API Documentation

Folders API Documentation

Documents API Documentation

Support

For technical inquiries or API support, contact the Praemunio Engineering Team via docs.praemunio.io.

CORE

Core API Overview & Resource Hierarchy

Table of contents

1. Architectural Overview

Core Entities

2. Resource Hierarchy & Data Model

Resource Identifiers

3. Global Request & Response Format

Standard Success Envelope (`200 OK` / `201 Created`)

Standard Error Envelope (`4xx` / `5xx`)

Paginated Response Envelope (`PaginatedApiResponse<T>`)

5. Authentication & Scopes Matrix

Scope Requirements Matrix

6. Core Webhook Events

7. Global Errors Reference

8. Module Navigation

Support

CORE

Core API Overview & Resource Hierarchy#

Table of contents#

1. Architectural Overview#

Core Entities#

2. Resource Hierarchy & Data Model#

Resource Identifiers#

3. Global Request & Response Format#

Standard Success Envelope (200 OK / 201 Created)#

Standard Error Envelope (4xx / 5xx)#

4. Pagination Standard#

Paginated Response Envelope (PaginatedApiResponse<T>)#

5. Authentication & Scopes Matrix#

Scope Requirements Matrix#

6. Core Webhook Events#

7. Global Errors Reference#

8. Module Navigation#

Support#

Core API Overview & Resource Hierarchy

Table of contents

1. Architectural Overview

Core Entities

2. Resource Hierarchy & Data Model

Resource Identifiers

3. Global Request & Response Format

Standard Success Envelope (`200 OK` / `201 Created`)

Standard Error Envelope (`4xx` / `5xx`)

4. Pagination Standard

Paginated Response Envelope (`PaginatedApiResponse<T>`)

5. Authentication & Scopes Matrix

Scope Requirements Matrix

6. Core Webhook Events

7. Global Errors Reference

8. Module Navigation

Support