Documents

API reference for creating, managing, and organizing fixed-storage documents.

The Documents service provides fixed storage for structured documents -- contracts, identity documents, policies, invoices, and other files that need access control, versioning, and retention management. Unlike media storage (for images and transient files), fixed storage is designed for documents with compliance and governance requirements.

Base URL

All document endpoints are under /api/v1/storage/fixed/documents.

Scope: storage:read for reads, storage:upload for creates, storage:delete for deletes.

Create a document

POST /api/v1/storage/fixed/documents

Request body

Field	Type	Required	Description
`title`	`string`	Yes	Document title
`description`	`string`	No	Document description
`category`	`string`	Yes	Document category (see categories below)
`fileType`	`string`	Yes	File type: `MD`, `PDF`, `DOCX`, `XLSX`, `IMAGE`, or `OTHER`
`space`	`string`	Yes	`PERSONAL` or `INTERNAL`
`folderId`	`string`	No	ID of the folder to place the document in
`content`	`string`	No	Markdown content (for `MD` file type)
`fileUrl`	`string`	No	URL of the uploaded file
`fileName`	`string`	No	Original filename
`fileMimeType`	`string`	No	MIME type of the file
`fileSize`	`number`	No	File size in bytes
`entityType`	`string`	No	Related entity type (e.g., `BOOKING`, `PROPERTY`)
`entityId`	`string`	No	Related entity ID
`accessLevel`	`string`	No	Access level: `SUPER_ADMIN`, `MANAGEMENT`, `FINANCE`, `HR`, `OPERATIONS`, or `ALL`. Default: `ALL`
`visibility`	`string`	No	Visibility: `PRIVATE`, `SHARED`, or `PORTAL`. Default: `PRIVATE`
`allowedGroups`	`string[]`	No	Groups that can access this document
`allowedEntities`	`string[]`	No	Specific entity IDs with access
`retentionType`	`string`	No	`NONE`, `STANDARD`, `EXTENDED`, `LEGAL`, or `PERMANENT`. Default: `STANDARD`
`retentionUntil`	`string`	No	ISO 8601 date for retention expiry
`deletableBy`	`string`	No	Who can delete: `OWNER`, `ADMIN`, `SUPER_ADMIN`, or `NONE`

Document categories

IDENTITY_DOCUMENT, CONTRACT, INVOICE, RECEIPT, POLICY, REPORT, CERTIFICATE, LICENSE, INSURANCE, TAX_DOCUMENT, BANK_DOCUMENT, PAYSLIP, OFFER_LETTER, NDA, MEMO, TRAINING_MATERIAL, SOP, MEETING_NOTES, LEGAL, COMPLIANCE, OTHER

Response

{
  "success": true,
  "data": {
    "id": "doc_abc123",
    "title": "Employment Contract - Ade Bakare",
    "category": "CONTRACT",
    "fileType": "PDF",
    "space": "INTERNAL",
    "accessLevel": "HR",
    "visibility": "SHARED",
    "version": 1,
    "retentionType": "LEGAL",
    "deletableBy": "SUPER_ADMIN",
    "isLatest": true,
    "canDelete": false,
    "deletionRequiresOverride": true,
    "createdAt": "2026-04-05T10:00:00.000Z",
    "updatedAt": "2026-04-05T10:00:00.000Z"
  }
}

List documents

GET /api/v1/storage/fixed/documents

Query parameters

Parameter	Type	Description
`ownerType`	`string`	Filter by owner type: `ADMIN`, `AGENT`, `PARTNER`, `SYSTEM`
`ownerId`	`string`	Filter by owner ID
`space`	`string`	Filter by space: `PERSONAL` or `INTERNAL`
`category`	`string`	Filter by document category
`fileType`	`string`	Filter by file type
`visibility`	`string`	Filter by visibility
`folderId`	`string`	Filter by folder
`search`	`string`	Full-text search on title and description
`page`	`number`	Page number (default: 1)
`limit`	`number`	Results per page (default: 20, max: 100)

Response

{
  "success": true,
  "data": {
    "documents": [...],
    "total": 42,
    "page": 1,
    "limit": 20,
    "totalPages": 3
  }
}

Get a document

GET /api/v1/storage/fixed/documents/:documentId

Returns the full document record including metadata, access counts, and retention information.

Update a document

PATCH /api/v1/storage/fixed/documents/:documentId

Request body

Field	Type	Description
`title`	`string`	Updated title
`description`	`string`	Updated description
`category`	`string`	Updated category
`content`	`string`	Updated markdown content (MD files)
`accessLevel`	`string`	Updated access level
`visibility`	`string`	Updated visibility
`retentionType`	`string`	Updated retention type
`retentionUntil`	`string`	Updated retention expiry
`isArchived`	`boolean`	Archive or unarchive the document

All fields are optional. Only provided fields are updated.

Delete a document

DELETE /api/v1/storage/fixed/documents/:documentId

Performs a soft delete. Documents with deletableBy: "NONE" or restricted deletableBy settings may require a deletion override before deletion is permitted.

Examples

Create a contract document

curl

curl -X POST https://api.platformxe.com/api/v1/storage/fixed/documents \
  -H "Content-Type: application/json" \
  -H "x-api-key: pxk_live_your_api_key_here" \
  -d '{
    "title": "Employment Contract - Ade Bakare",
    "category": "CONTRACT",
    "fileType": "PDF",
    "space": "INTERNAL",
    "fileUrl": "https://cdn.platformxe.com/org_123/contracts/ade-bakare.pdf",
    "fileName": "ade-bakare-contract.pdf",
    "fileMimeType": "application/pdf",
    "fileSize": 245760,
    "accessLevel": "HR",
    "visibility": "SHARED",
    "retentionType": "LEGAL",
    "deletableBy": "SUPER_ADMIN"
  }'

TypeScript SDK

import { PlatformXe } from '@caldera/platformxe-sdk';

const px = new PlatformXe({ apiKey: 'pxk_live_your_api_key_here' });

const doc = await px.documents.create({
  title: 'Employment Contract - Ade Bakare',
  category: 'CONTRACT',
  fileType: 'PDF',
  space: 'INTERNAL',
  fileUrl: 'https://cdn.platformxe.com/org_123/contracts/ade-bakare.pdf',
  fileName: 'ade-bakare-contract.pdf',
  fileMimeType: 'application/pdf',
  fileSize: 245760,
  accessLevel: 'HR',
  visibility: 'SHARED',
  retentionType: 'LEGAL',
  deletableBy: 'SUPER_ADMIN',
});

console.log(doc.id);
// "doc_abc123"

Python SDK

from platformxe import PlatformXe

px = PlatformXe(api_key="pxk_live_your_api_key_here")

doc = px.documents.create({
    "title": "Employment Contract - Ade Bakare",
    "category": "CONTRACT",
    "fileType": "PDF",
    "space": "INTERNAL",
    "fileUrl": "https://cdn.platformxe.com/org_123/contracts/ade-bakare.pdf",
    "accessLevel": "HR",
    "visibility": "SHARED",
    "retentionType": "LEGAL",
    "deletableBy": "SUPER_ADMIN"
})

List documents in a folder

const result = await px.documents.list({
  folderId: 'fld_contracts',
  category: 'CONTRACT',
  page: 1,
  limit: 50,
});

console.log(result.total);
// 12

Search documents

curl "https://api.platformxe.com/api/v1/storage/fixed/documents?search=employment&category=CONTRACT" \
  -H "x-api-key: pxk_live_your_api_key_here"

Update access level

await px.documents.update('doc_abc123', {
  accessLevel: 'MANAGEMENT',
  visibility: 'PORTAL',
});

Error responses

Code	Description
`BAD_REQUEST`	Missing required fields or invalid category/file type
`NOT_FOUND`	Document does not exist or has been deleted
`FORBIDDEN`	API key lacks required scope or access level is insufficient
`DELETION_REQUIRES_OVERRIDE`	Document cannot be deleted without an approved override
`RATE_LIMITED`	Rate limit exceeded