API Overview

Version 1.0 · Developer Guide & Platform Index

Welcome to the developer documentation for the Praemunio Public API. Praemunio is a multi-tenant document management platform: organize documents in teams, workspaces and folders, control access with granular permissions, and react to platform events in real time through signed webhooks.

	Production	Sandbox
Base URL	`https://api.praemunio.io/api/v1`	`https://sandbox.api.praemunio.io/api/v1`
API keys	`pk_live_…` / `sk_live_…`	`pk_test_…` / `sk_test_…`


Format	JSON (`application/json`) and multipart uploads (`multipart/form-data`)
Authentication	API key pair → JWT Bearer token
Documentation	docs.praemunio.io

Where to start

Platform overview

Documentation modules

Global conventions

Quick start

Errors

Security & compliance

Support

1. Where to start

I want to…	Go to
Get my first API call working	Quick start
Create API keys, manage tokens and scopes	Authentication & Webhooks
Receive real-time event notifications	Authentication & Webhooks → Webhooks
Understand how resources relate to each other	Core Overview
Upload, download or share documents	Documents
Manage teams, members and permissions	Teams

2. Platform overview

Documentation map

Resource hierarchy

Every resource belongs to the level above it. Access is always evaluated from the top of the hierarchy down.

Resource	Description
Account	The tenant that owns everything: billing, API keys, webhooks
Team	A group of members (`individual` or `legal_entity`) with permission templates
Workspace	An isolated storage space with its own quota (`storageLimit`, in bytes)
Folder	A directory, nestable through `parentFolderId`
Document	A file with its metadata, status and sharing settings

Document lifecycle

Documents in the completed state are ready to be streamed, downloaded and shared.

3. Documentation modules

Authentication & Webhooks

Authentication & Webhooks Reference

API keys (publicKey + secretKey), scopes, rate limits and pagination

Access tokens (JWT, 15 minutes) and single-use refresh tokens (7 days), with reuse detection

Signed webhooks: event catalog, payload schema, retries, idempotency and signature verification

Core platform

Core Overview & Resource Hierarchy

Entity model, entity-relationship diagrams and resource identifiers

Response envelope standards (ApiResponse<T>, PaginatedApiResponse<T>)

Offset-based pagination (page, limit, meta)

Cross-module scopes and permissions matrix

Resource modules

Module	What you can do	Key endpoints
Teams	Create teams, invite members with workspace and folder access rules (`accessConfig`), manage permission templates, read metrics and audit logs	`GET /teams/dashboard`, `GET /teams/logs`
Workspaces	Create workspaces, allocate and enforce storage quotas, manage status (`active`, `inactive`, `suspended`), browse top-level content	`GET /workspaces/drive`, `GET /workspaces/content`
Folders	Build nested directory trees, list folder content, move one or several folders	`POST /folders/move`, `PATCH /folders/batch`
Documents	Upload files, stream or download them, generate public links, rename, move, archive and restore, update status in batch	`POST /documents/upload`, `GET /documents/stream`, `GET /documents/download`, `POST /documents/public-link`

4. Global conventions

Response envelopes

Every endpoint returns a JSON envelope.

Single resource — ApiResponse<T>

{
  "success": true,
  "message": "Operation executed successfully",
  "result": {
    "id": "a3f8e9d2-1a4b-4c7e-9f3a-2b8c6d4e1f0a",
    "name": "Production Workspace"
  },
  "errors": null,
  "except": null
}

Paginated list — PaginatedApiResponse<T>

{
  "success": true,
  "message": "Resources retrieved successfully",
  "result": {
    "data": [],
    "meta": {
      "total": 100,
      "per_page": 20,
      "current_page": 1,
      "last_page": 5,
      "first_page": 1,
      "total_pages": 5,
      "has_next": true,
      "has_prev": false,
      "from": 1,
      "to": 20
    }
  },
  "errors": null,
  "except": null
}

Field	Description
`success`	`true` if the request succeeded
`message`	Human-readable summary
`result`	The resource, or `{ data, meta }` for lists; `null` on error
`errors`	On failure, an object with a machine-readable `code` (see Errors); otherwise `null`

Pagination

List endpoints accept page (default 1) and limit (default 20, maximum 100). Pagination state is returned in result.meta.

GET /api/v1/webhooks?page=2&limit=50

Rate limits and quotas

Each API key enforces an hourly rate limit and a daily quota (defaults: 1,000 requests per hour, 10,000 per day). Every response includes:

When a limit is exceeded the API returns 429 Too Many Requests with the code rate_limit_exceeded. Pause requests until X-RateLimit-Reset (Unix timestamp, in seconds). See Authentication & Webhooks for details.

Scopes

Permissions are granted to API keys as resource:action scopes (for example document:read, document:write). A request without the required scope returns 403 with the code insufficient_scopes. The complete matrix is in the Core Overview.

5. Quick start

This walkthrough authenticates, creates a team and a workspace, uploads a document and generates a download link. It needs curl and jq.

Use the sandbox base URL and pk_test_ / sk_test_ keys while experimenting.

Step 1 — Authenticate

The access token is valid for 15 minutes. See token refresh to renew it.

Step 2 — Create a team

Step 3 — Create a workspace

storageLimit is expressed in bytes (107374182400 = 100 GiB).

Step 4 — Upload a document

Step 5 — Generate a pre-signed download URL

ttl is the lifetime of the link, in seconds.

Next steps

Subscribe to events with webhooks.

Explore each module in section 3.

6. Errors

Failed requests return the standard envelope with success: false and a machine-readable errors.code.

{
  "success": false,
  "message": "Insufficient scopes",
  "result": null,
  "errors": { "code": "insufficient_scopes" },
  "statusCode": 403
}

HTTP status	`errors.code`	Meaning	Recommended action
`200 OK`	—	Request succeeded	Process the response body
`201 Created`	—	Resource created	Store the returned resource `id`
`400 Bad Request`	`invalid_request`	Malformed JSON or invalid parameter	Check the request against the schema
`401 Unauthorized`	see Authentication errors	Invalid credentials, or invalid / expired token	Re-authenticate or refresh the token
`403 Forbidden`	`insufficient_scopes`	The key lacks the required scope	Add the scope to the API key
`404 Not Found`	`not_found`	The resource does not exist	Verify the resource identifier
`409 Conflict`	`resource_conflict`	A unique property is already in use	Use a different name or value
`429 Too Many Requests`	`rate_limit_exceeded`	Hourly or daily limit exceeded	Wait until `X-RateLimit-Reset`
`500 Internal Server Error`	`internal_error`	Unexpected server error	Retry with exponential backoff; contact support if it persists

7. Security & compliance

Short-lived tokens. Access tokens expire after 15 minutes; refresh tokens are single-use and reuse is detected and revoked.

Least privilege. Scopes restrict each API key to the resources and actions it needs.

Signed webhooks. Every delivery carries an HMAC-SHA256 signature (X-Webhook-Signature) computed with your whsec_… secret.

Tenant isolation. Workspaces and folders cannot be accessed across teams without explicit authorization.

Encryption in transit. All production traffic is served over HTTPS/TLS.

See Security best practices for recommendations on handling keys and secrets.

8. Support

Resource	Link
Documentation	docs.praemunio.io
Contact support	docs.praemunio.io/support

Praemunio API - v1

API Overview

Table of contents

1. Where to start

2. Platform overview

Documentation map

Resource hierarchy

Document lifecycle

3. Documentation modules

Authentication & Webhooks

Core platform

Resource modules

4. Global conventions

Response envelopes

Rate limits and quotas

Scopes

5. Quick start

6. Errors

7. Security & compliance

8. Support

Praemunio API - v1

API Overview#

Table of contents#

1. Where to start#

2. Platform overview#

Documentation map#

Resource hierarchy#

Document lifecycle#

3. Documentation modules#

Authentication & Webhooks#

Core platform#

Resource modules#

4. Global conventions#

Response envelopes#

Pagination#

Rate limits and quotas#

Scopes#

5. Quick start#

6. Errors#

7. Security & compliance#

8. Support#

API Overview

Table of contents

1. Where to start

2. Platform overview

Documentation map

Resource hierarchy

Document lifecycle

3. Documentation modules

Authentication & Webhooks

Core platform

Resource modules

4. Global conventions

Response envelopes

Pagination

Rate limits and quotas

Scopes

5. Quick start

6. Errors

7. Security & compliance

8. Support