Manage Files

API reference for listing, retrieving, deleting, and reordering files.

Manage your stored files with endpoints for listing, retrieving details, deleting, and reordering.

List files

Retrieve a paginated list of files in your organization's storage.

GET /api/v1/storage/media/files

Scope: storage:read

Query parameters

Parameter	Type	Required	Description
folder	string	No	Filter by folder path
tags	string	No	Comma-separated tags to filter by
access	string	No	Filter by access level: public, authenticated, private
page	number	No	Page number. Default: 1
limit	number	No	Results per page (max 100). Default: 20
sort	string	No	Sort field: createdAt, size, name. Default: createdAt
order	string	No	Sort order: asc or desc. Default: desc

Response

{
  "success": true,
  "data": {
    "files": [
      {
        "fileId": "file_abc123def456",
        "url": "https://cdn.platformxe.com/org_123/products/photo.jpg",
        "filename": "photo.jpg",
        "format": "jpeg",
        "size": 154320,
        "width": 1200,
        "height": 800,
        "folder": "products",
        "access": "public",
        "tags": ["product", "featured"],
        "createdAt": "2026-04-05T14:30:00.000Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 142,
      "totalPages": 8
    }
  }
}

curl

curl -G https://api.platformxe.com/api/v1/storage/media/files \
  -H "x-api-key: pxk_live_your_api_key_here" \
  -d "folder=products" \
  -d "limit=10" \
  -d "sort=createdAt" \
  -d "order=desc"

SDK

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

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

const result = await px.storage.files.list({
  folder: 'products',
  limit: 10,
  sort: 'createdAt',
  order: 'desc',
});

console.log(result.data.files.length);
// 10

console.log(result.data.pagination.total);
// 142

---

Get a single file

Retrieve metadata for a specific file.

GET /api/v1/storage/media/files/:fileId

Scope: storage:read

Response

{
  "success": true,
  "data": {
    "fileId": "file_abc123def456",
    "url": "https://cdn.platformxe.com/org_123/products/photo.jpg",
    "filename": "photo.jpg",
    "format": "jpeg",
    "size": 154320,
    "width": 1200,
    "height": 800,
    "folder": "products",
    "access": "public",
    "tags": ["product", "featured"],
    "versions": 3,
    "createdAt": "2026-04-05T14:30:00.000Z",
    "updatedAt": "2026-04-05T16:00:00.000Z"
  }
}

curl

curl https://api.platformxe.com/api/v1/storage/media/files/file_abc123def456 \
  -H "x-api-key: pxk_live_your_api_key_here"

---

Delete a file

Permanently delete a file from storage.

DELETE /api/v1/storage/media/files/:fileId

Scope: storage:delete

Response

{
  "success": true,
  "data": {
    "fileId": "file_abc123def456",
    "deleted": true
  }
}

curl

curl -X DELETE https://api.platformxe.com/api/v1/storage/media/files/file_abc123def456 \
  -H "x-api-key: pxk_live_your_api_key_here"

---

Reorder files

Update the display order of files within a folder. Useful for gallery or carousel ordering.

POST /api/v1/storage/media/files/reorder

Scope: storage:read

Request body

Field	Type	Required	Description
folder	string	Yes	The folder whose files to reorder
order	Array<string>	Yes	Ordered array of file IDs

Request example

{
  "folder": "products/gallery",
  "order": [
    "file_third_item",
    "file_first_item",
    "file_second_item"
  ]
}

Response

{
  "success": true,
  "data": {
    "folder": "products/gallery",
    "reordered": 3
  }
}

SDK

await px.storage.files.reorder({
  folder: 'products/gallery',
  order: ['file_third_item', 'file_first_item', 'file_second_item'],
});

Error responses

Code	Description
NOT_FOUND	File or folder does not exist
FORBIDDEN	API key does not have the required scope
RATE_LIMITED	Rate limit exceeded for this API key