Skip to content

App Files ​

Give a marketplace app somewhere to keep its files. The app (the first one is the CRM) stores documents, attachments and exports in the workspace it was enabled for, through the same API it already uses for Messages. Your users' browsers can upload straight to storage, the app never has to manage a storage path, and the workspace is billed only for what is actually kept.

OperationEndpointScope
Reserve a file and get an upload linkPOST /api/v1/filesfiles:write
Confirm the uploadPOST /api/v1/files/{id}/completefiles:write
Read one file, with a download linkGET /api/v1/files/{id}files:read
List filesGET /api/v1/filesfiles:read
Delete a fileDELETE /api/v1/files/{id}files:write

Every path is under https://<your-workspace>-api.perfox.ai.

Only the app's own key can call this API

files:read and files:write are given only to the key Perfox manages for an app you enabled from the App Marketplace. You can't tick them on a key you create on API Keys, and any other key is refused with 403 app_key_required. Agents can't call these operations as tools either.

Where a file lives ​

You never name a storage path. Perfox works out which app is calling from its key, and every file goes into that app's own folder in the workspace. One app can't see or touch another app's files.

  • name is your label for the file. It is shown back exactly as you sent it and is never used as a path.
  • folder is a grouping label you can filter on later, such as deals/2026 or exports. Use lower-case letters, digits, _, - and /, start with a letter or digit, and keep it to 128 characters, with no empty, . or .. segments.

Storing a file: reserve, upload, complete ​

1. Reserve the file ​

bash
curl -X POST "https://<your-workspace>-api.perfox.ai/api/v1/files" \
  -H "Authorization: Bearer sk_…" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "quote-4182.pdf",
    "mime_type": "application/pdf",
    "size_bytes": 482113,
    "folder": "deals/4182",
    "customer_id": "01a0…",
    "metadata": { "deal_id": "4182" },
    "idempotency_key": "quote-4182-v1"
  }'
FieldValues
nameRequired, 1–255 characters. Your label for the file.
mime_typeRequired, as type/subtype. The exact Content-Type your upload will send.
size_bytesRequired, from 1 up to 209,715,200 (200 MB). The exact length your upload will send.
folderOptional grouping label (see above).
customer_idOptional. A customer in your workspace this file belongs to (see Erasure).
metadataOptional. Up to 20 string tags: keys 1–64 characters, values up to 512. Returned exactly as sent.
idempotency_keyOptional, 1–64 characters. Makes the call safe to retry (see Retrying).

The answer is 201:

json
{
  "file": {
    "id": "01a1…",
    "status": "pending",
    "name": "quote-4182.pdf",
    "mime_type": "application/pdf",
    "size_bytes": 482113,
    "folder": "deals/4182",
    "customer_id": "01a0…",
    "metadata": { "deal_id": "4182" },
    "created_at": "2026-11-11T09:30:00.000Z",
    "updated_at": "2026-11-11T09:30:00.000Z",
    "ready_at": null
  },
  "upload_url": "https://…",
  "upload_expires_at": "2026-11-11T10:30:00.000Z",
  "upload_headers": { "Content-Type": "application/pdf", "Content-Length": "482113" }
}

2. Upload the bytes ​

PUT the file to upload_url with exactly the upload_headers you were given:

bash
curl -X PUT "<upload_url>" \
  -H "Content-Type: application/pdf" \
  -H "Content-Length: 482113" \
  --data-binary @quote-4182.pdf

The declared size and type are part of the link's signature, so send exactly what you declared. You have 1 hour from the reserve; the link stops working when that hour is up.

Upload from the browser

The link can be used directly from your app's own web address (https://<your-workspace>.<app>.perfox.ai), so a user's browser can send a large file straight to storage without it passing through your server. Uploading from your app's backend needs nothing extra.

3. Confirm it ​

bash
curl -X POST "https://<your-workspace>-api.perfox.ai/api/v1/files/01a1…/complete" \
  -H "Authorization: Bearer sk_…"

Perfox checks what actually arrived and answers 200 with the file, now "status": "ready". From here it can be downloaded, and it counts towards the workspace's storage bill. Confirming a file that is already ready simply returns it again.

AnswerWhat it meansWhat to do
409 upload_incompleteNothing has been uploaded yet.Upload, then confirm again.
422 upload_mismatchThe bytes don't match the declared size and type. The upload is discarded and the file becomes expired.Reserve again with the right size and type.
410 upload_expiredMore than 70 minutes have passed since the reserve.Start a new upload.
503 storage_unavailableStorage couldn't be reached.Try again.

Retrying a reserve ​

Send an idempotency_key and a retried reserve is safe. While the first file is still pending and inside its hour, the same key returns the same file with a fresh upload link, never a second file. Once that file has moved on (ready, expired or deleted), the key answers 409 idempotency_key_used.

The type has to match the name ​

If the file name's extension implies a different type from the mime_type you declared, the reserve is refused with 422 mime_mismatch. A file called report.html can't be declared as application/pdf.

File statuses ​

StatusMeaning
pendingUpload link issued, not confirmed yet. An upload that is never confirmed is cleaned up automatically after its window.
readyConfirmed. Downloadable, and billed.
expiredNever confirmed in time, or the upload didn't match what was declared.
deletedRemoved.

Every file is returned as: id, status, name, mime_type, size_bytes, folder (or null), customer_id (or null), metadata, created_at, updated_at and ready_at (or null).

Reading a file ​

bash
curl "https://<your-workspace>-api.perfox.ai/api/v1/files/01a1…?download_expires_in=600" \
  -H "Authorization: Bearer sk_…"
json
{
  "file": { "id": "01a1…", "status": "ready", "…": "…" },
  "download_url": "https://…",
  "download_expires_at": "2026-11-11T09:50:00.000Z"
}
  • download_url is included only when the file is ready. A pending file comes back without one.
  • download_expires_in sets how long the link works, from 60 to 86,400 seconds. The default is 3,600 (one hour).
  • An expired or deleted file, or an id that isn't your app's, is 404 file_not_found.

Listing files ​

bash
curl "https://<your-workspace>-api.perfox.ai/api/v1/files?folder=deals/4182&limit=50" \
  -H "Authorization: Bearer sk_…"

Returns { "files": [ … ], "next_cursor": "…" }, newest first.

ParameterValues
folderExact folder label.
statuspending, ready, expired or deleted. Without it, you get only files that exist (pending and ready).
customer_idFiles tied to that customer.
limit1–200, default 50.
cursorThe next_cursor from the previous page. No next_cursor means there are no more.

Deleting a file ​

bash
curl -X DELETE "https://<your-workspace>-api.perfox.ai/api/v1/files/01a1…" \
  -H "Authorization: Bearer sk_…"

Returns { "ok": true }. The bytes are removed and billing for the file stops. Deleting a file that is already deleted succeeds too, so a retry is always safe.

Tie a file to a customer ​

Set customer_id when a file belongs to one of your customers: a signed contract, an ID document, a call summary. The id must be a customer in your workspace, otherwise the reserve is 404 customer_not_found. When that customer's data is erased under a data-subject erasure request (see Compliance), their files are deleted with it, so nothing personal is left behind in an app's storage.

What the app's status allows ​

App statusReadUploadDelete
Active, or Cancelling✓✓✓
Lapsed (renewal unpaid)✓403 app_read_only✓
Suspended403 app_suspended403 app_suspended403 app_suspended
Being set up, or set-up failed403 app_not_ready403 app_not_ready403 app_not_ready
CancelledThe key is revoked: 401 revoked_api_key

A lapsed app can still delete, because the workspace keeps paying for whatever it holds.

Limits ​

LimitValueWhen it's reached
One file200 MB (209,715,200 bytes)400 invalid_request
Everything one app stores in your workspace50 GB413 storage_quota_exceeded
CreditsAn empty balance stops new uploads only. Reading and deleting keep working.402 out_of_credits

Any request that doesn't match the fields above is 400 invalid_request, naming what is wrong.

Billing ​

Only ready files are billed. Once a day, the workspace is charged for what the app holds, at its storage rate in credits per GB a month (a day is charged as 1/30 of a month). The rate, the current size and the monthly cost at that size are on the app's page in the Studio, and every daily charge is a row in your transactions. See Apps.

After the app is cancelled ​

The app's files are kept for 30 days after it ends, then deleted for good. Enabling the app again before then keeps them.

You can now … ​

  • Store an app's files in your workspace without the app ever choosing a storage path
  • Upload large files straight from a user's browser, and confirm them in one call
  • Retry any step safely: reserve with an idempotency key, confirm and delete as often as needed
  • Hand out a download link that lasts as long as you choose, from one minute to a day
  • Tie a file to a customer, so erasing that customer also erases their files