Files API

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

19 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 download URL for a file, made for you and valid for 10 minutes

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/copy

Copy a file. The copy starts private.

Parameters

`fileId`	stringrequired	File ID to copy
`withoutPassword`	boolean	Must be true to copy a file that has a password: the copy leaves the password behind (it opens to no one but your workspace).
`folderId`	string	Folder for the copy, or null for root. Left out = the original's folder.
`name`	string	The copy's file name with extension. Left out = the original's name.

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/files/copy \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "fileId": "example",
  "withoutPassword": true,
  "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 (create/read/delete) — each a Condition (rule, legacy array, or { all \| any \| not } group with operators/function) — plus optional metadata (password/expiresAt/allowDownload).
`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/getFolderAccessRules

Get access rules for a folder (derived from files inside)

Parameters

folderId

stringrequired

Folder ID

Example Request

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

POST

/api/v1/files/setFolderAccessRules

Set access rules for all files in a folder. Files uploaded or moved into the folder (or its subfolders) later inherit these rules automatically unless the file has rules of its own.

Parameters

`folderId`	stringrequired	Folder ID
`accessRules`	objectrequired	Access rules to apply to all files in the folder (same Condition shape as files.setAccessRules).

Example Request

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

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/createUploadTicket

Get a one-shot URL to upload a file to, so the bytes never pass through the conversation as base64. Returns { uploadUrl, ticketId, expiresAt, method, headers } — send the raw file body with PUT. Refused up front (with availableBytes) if the file will not fit, so you never upload and then find out.

Parameters

`fileName`	stringrequired	File name with extension
`sizeBytes`	integerrequired	Exact byte length of the file you are about to send. Checked against the plan and remaining storage NOW, and the upload is refused if the body does not match it.
`mimeType`	string	MIME type (auto-detected from the extension if omitted)
`folderId`	string	Target folder ID, or null for root

Example Request

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

POST

/api/v1/files/upload

Upload a file, either as base64 `content` or by giving a `sourceUrl` for the server to fetch. Prefer sourceUrl — it keeps the bytes out of the conversation. Check getQuota first for available space.

Parameters

`fileName`	stringrequired	Original file name with extension
`content`	string	Base64 encoded file content. Every byte travels through the caller — for anything already reachable over HTTPS use sourceUrl instead.
`sourceUrl`	string	HTTPS URL to fetch the file FROM, server-side. Use this instead of content whenever the bytes exist at a URL: nothing is base64-encoded through the caller, so a 1.7MB PDF costs a URL rather than ~600K tokens of transport. Same extension, size, quota and folder rules as a base64 upload.
`mimeType`	string	MIME type (auto-detected if not provided; a sourceUrl response Content-Type is used when it is not given)
`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",
  "sourceUrl": "example"
}'