Document Folders

API reference for creating and managing document folders.

A folder is scoped to a single owner — one folder per (ownerType, ownerId) pair — and tracks storage quota (byte limit and max file count) for everything uploaded into it. There is no folder hierarchy or nesting: create a document with folderId set to store it inside its owner's folder, and fixed storage enforces the owner's quota on every upload.

Create a folder

POST /api/v1/storage/fixed/folders

Scope: storage:upload

Idempotent: if a folder already exists for this (ownerType, ownerId) pair, its existing folderId is returned rather than creating a duplicate.

Request body

Field	Type	Required	Description
ownerType	string	Yes	ADMIN, AGENT, PARTNER, or SYSTEM
ownerId	string	Yes	ID of the owner within the calling service

Response

{
  "success": true,
  "data": {
    "folderId": "fld_abc123"
  }
}

Field	Type	Description
folderId	string	The new (or existing) folder's ID

Get a folder by owner

GET /api/v1/storage/fixed/folders?ownerType=&ownerId=

Returns the folder for a given owner, with its quota and current usage.

Scope: storage:upload (every /storage/* route requires it when the key has scopes)

Query parameters

Parameter	Type	Required	Description
ownerType	string	Yes	ADMIN, AGENT, PARTNER, or SYSTEM
ownerId	string	Yes	ID of the owner within the calling service

Get a folder by ID

GET /api/v1/storage/fixed/folders/:folderId

Returns the same folder shape as the owner lookup above, addressed by ID. Scoped to the authenticated caller service — a folder ID belonging to another tenant resolves to 404, never leaking cross-tenant folder metadata.

Scope: storage:upload (every /storage/* route requires it when the key has scopes)

Response (both GET endpoints)

{
  "success": true,
  "data": {
    "id": "fld_abc123",
    "ownerType": "AGENT",
    "ownerId": "agent_789",
    "callerService": "lettings",
    "storageLimitBytes": 104857600,
    "storageUsedBytes": 15728640,
    "maxFileCount": 50,
    "maxFileSizeBytes": 10485760,
    "allowedCategories": ["IDENTITY_DOCUMENT", "PROOF_OF_ADDRESS", "BUSINESS_REGISTRATION", "BANK_DOCUMENT", "PROFESSIONAL_CERT", "CONTRACT", "MANDATE_DOCUMENT", "TAX_DOCUMENT", "CORRESPONDENCE"],
    "documentCount": 12,
    "usagePercentage": 15,
    "remainingBytes": 89128960,
    "canUpload": true
  }
}

Field	Type	Description
id	string	Folder ID
ownerType	string	ADMIN, AGENT, PARTNER, or SYSTEM
ownerId	string	Owner ID within the calling service
callerService	string	The service that owns this folder (from the API key)
storageLimitBytes	number	Total storage quota for this owner
storageUsedBytes	number	Bytes currently used
maxFileCount	number	Maximum non-deleted documents allowed in this folder
maxFileSizeBytes	number	Maximum size for a single file uploaded into this folder
allowedCategories	string[]	Categories this owner type may upload — defaults are owner-type-specific (see below); pre-registered tenant categories add to this via the category registry
documentCount	number	Non-deleted documents currently in the folder
usagePercentage	number	storageUsedBytes / storageLimitBytes, rounded, as a percentage
remainingBytes	number	storageLimitBytes - storageUsedBytes
canUpload	boolean	false once remainingBytes <= 0 or documentCount >= maxFileCount

Default quota (overridable via FIXED_STORAGE_*_LIMIT_MB / FIXED_STORAGE_MAX_FILES / FIXED_STORAGE_MAX_FILE_SIZE_MB env vars, per owner type):

ownerType	Storage limit	Max files	Max file size
ADMIN	50 MB	50	10 MB
AGENT	100 MB	50	10 MB
PARTNER	100 MB	50	10 MB
SYSTEM	Uses the AGENT defaults	50	10 MB

Examples

Create a folder and check it can accept an upload

curl

curl -X POST https://api.platformxe.com/api/v1/storage/fixed/folders \
  -H "Content-Type: application/json" \
  -H "x-api-key: pxk_live_your_api_key_here" \
  -d '{
    "ownerType": "AGENT",
    "ownerId": "agent_789"
  }'

curl "https://api.platformxe.com/api/v1/storage/fixed/folders?ownerType=AGENT&ownerId=agent_789" \
  -H "x-api-key: pxk_live_your_api_key_here"

TypeScript SDK

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

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

const { folderId } = await px.documents.createFolder({
  ownerType: 'AGENT',
  ownerId: 'agent_789',
});

const folder = await px.documents.getFolderByOwner('AGENT', 'agent_789');
console.log(folder.canUpload, folder.remainingBytes);
// true 89128960

Python SDK

from platformxe import PlatformXeClient

px = PlatformXeClient(api_key="pxk_live_your_api_key_here")

result = px.documents.create_folder(owner_type="AGENT", owner_id="agent_789")
folder = px.documents.get_folder_by_owner(owner_type="AGENT", owner_id="agent_789")

print(folder["canUpload"], folder["remainingBytes"])
# True 89128960

Retrieve folder details by ID

const folder = await px.documents.getFolder('fld_abc123');
console.log(folder.documentCount, folder.usagePercentage);
// 12 15

Error responses

Code	Status	Description
BAD_REQUEST	400	Missing required fields (ownerType, ownerId)
VALIDATION_ERROR	400	ownerType is not one of ADMIN, AGENT, PARTNER, SYSTEM — the response names the field and lists the allowed values
NOT_FOUND	404	Folder does not exist for this owner, or belongs to another caller
FORBIDDEN	403	API key lacks required scope
RATE_LIMITED	429	Rate limit exceeded