Files API

Upload, download, and manage files and folders. Get storage usage statistics.

15 endpoints

Endpoints

POST

/api/v1/files/list

List user files. Optional params: folderId (filter by folder, use "root" for root level), conversationId, sortBy ("uploadedAt", "size", "fileName"), sortOrder ("asc", "desc"), limit, offset. Returns {files[], total}.

Parameters

`conversationId`	string	Filter by conversation ID
`folderId`	string	Filter by folder ID. Use "root" for root level
`sortBy`	string	Sort field: "uploadedAt", "size", or "fileName"
`sortOrder`	string	Sort order: "asc" or "desc"
`limit`	number	Max files to return (1-100, default: 50)
`offset`	number	Number of files to skip for pagination

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/files/list \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "conversationId": "example",
  "folderId": "example",
  "sortBy": "example"
}'

POST

/api/v1/files/get

Get a specific file by ID

Parameters

fileId

stringrequired

File ID from list

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/files/get \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "fileId": "example"
}'

POST

/api/v1/files/getDownloadUrl

Get a presigned download URL for a file (1 hour expiry)

Parameters

fileId

stringrequired

File ID from list

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/files/getDownloadUrl \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "fileId": "example"
}'

POST

/api/v1/files/delete

Delete a file (move to trash)

Parameters

fileId

stringrequired

File ID to delete

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/files/delete \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "fileId": "example"
}'

POST

/api/v1/files/rename

Rename a file

Parameters

`fileId`	stringrequired	File ID to rename
`newName`	stringrequired	New file name

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/files/rename \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "fileId": "example",
  "newName": "example"
}'

POST

/api/v1/files/move

Move a file to a different folder

Parameters

`fileId`	stringrequired	File ID to move
`folderId`	stringrequired	Target folder ID, or null for root

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/files/move \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "fileId": "example",
  "folderId": "example"
}'

POST

/api/v1/files/listFolders

List folders. Optional param "parentId" (null for root level folders). Returns array with id, name, parentId.

Parameters

parentId

string

Parent folder ID, or null for root level

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/files/listFolders \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "parentId": "example"
}'

POST

/api/v1/files/createFolder

Create a new folder

Parameters

`name`	stringrequired	Folder name
`parentId`	string	Parent folder ID, or null for root

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/files/createFolder \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "example",
  "parentId": "example"
}'

POST

/api/v1/files/renameFolder

Rename a folder

Parameters

`folderId`	stringrequired	Folder ID to rename
`newName`	stringrequired	New folder name

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/files/renameFolder \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "folderId": "example",
  "newName": "example"
}'

POST

/api/v1/files/deleteFolder

Delete an empty folder

Parameters

folderId

stringrequired

Folder ID to delete. Folder must be empty.

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/files/deleteFolder \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "folderId": "example"
}'

POST

/api/v1/files/getUsage

Get storage stats. No params. Returns {totalSize (bytes), fileCount}.

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/files/getUsage \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{}'

POST

/api/v1/files/setAccessRules

Set access rules for a file. Controls who can create/read/delete files in published apps.

Parameters

`fileId`	stringrequired	File ID from list
`accessRules`	objectrequired	Access rules per operation
`trackCreator`	boolean	Whether to track who uploads each file (default: true)

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/files/setAccessRules \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "fileId": "example",
  "accessRules": {},
  "trackCreator": true
}'

POST

/api/v1/files/getAccessRules

Get access rules for a file

Parameters

fileId

stringrequired

File ID from list

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/files/getAccessRules \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "fileId": "example"
}'

POST

/api/v1/files/getQuota

Get storage quota info. Returns usedBytes, limitBytes, availableBytes, maxFileSizeBytes, percentUsed. Call BEFORE upload to check available space.

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/files/getQuota \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{}'

POST

/api/v1/files/upload

Upload a file. Content must be base64 encoded. Check getQuota first for available space.

Parameters

`fileName`	stringrequired	Original file name with extension
`content`	stringrequired	Base64 encoded file content
`mimeType`	string	MIME type (auto-detected if not provided)
`folderId`	string	Target folder ID, or null for root

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/files/upload \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "fileName": "example",
  "content": "example",
  "mimeType": "example"
}'