Document Folders

API reference for creating and managing document folders.

Folders provide hierarchical organization for documents in fixed storage. A folder can contain documents and other folders (nested up to 5 levels deep).

Create a folder

POST /api/v1/storage/fixed/folders

Scope: storage:upload

Request body

Field	Type	Required	Description
name	string	Yes	Folder name
parentId	string	No	Parent folder ID for nesting. Omit for a root-level folder
description	string	No	Folder description

Response

{
  "success": true,
  "data": {
    "id": "fld_abc123",
    "name": "HR Contracts",
    "parentId": null,
    "description": "Employment contracts and offer letters",
    "documentCount": 0,
    "createdAt": "2026-04-05T10:00:00.000Z",
    "updatedAt": "2026-04-05T10:00:00.000Z"
  }
}

Field	Type	Description
id	string	Unique folder ID
name	string	Folder name
parentId	string or null	Parent folder ID (null for root folders)
description	string or null	Folder description
documentCount	number	Number of documents directly in this folder
createdAt	string	ISO 8601 creation timestamp
updatedAt	string	ISO 8601 last-update timestamp

Get a folder

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

Returns the folder metadata including the count of documents it contains. Use the list documents endpoint with folderId to retrieve the actual documents.

Scope: storage:read

Examples

Create a folder hierarchy

curl

# Create root folder
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 '{
    "name": "HR Documents",
    "description": "All HR-related documents"
  }'

# Create subfolder
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 '{
    "name": "Contracts 2026",
    "parentId": "fld_abc123",
    "description": "Employment contracts for 2026"
  }'

TypeScript SDK

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

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

// Create root folder
const root = await px.documents.createFolder({
  name: 'HR Documents',
  description: 'All HR-related documents',
});

// Create subfolder
const sub = await px.documents.createFolder({
  name: 'Contracts 2026',
  parentId: root.id,
  description: 'Employment contracts for 2026',
});

console.log(sub.parentId);
// "fld_abc123"

Python SDK

from platformxe import PlatformXe

px = PlatformXe(api_key="pxk_live_your_api_key_here")

root = px.documents.create_folder({
    "name": "HR Documents",
    "description": "All HR-related documents"
})

sub = px.documents.create_folder({
    "name": "Contracts 2026",
    "parentId": root["id"]
})

Retrieve folder details

const folder = await px.documents.getFolder('fld_abc123');
console.log(folder.name, folder.documentCount);
// "HR Documents" 15

Error responses

Code	Description
BAD_REQUEST	Missing folder name or nesting depth exceeds 5 levels
NOT_FOUND	Parent folder does not exist
FORBIDDEN	API key lacks required scope
RATE_LIMITED	Rate limit exceeded