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.
| Operation | Endpoint | Scope |
|---|---|---|
| Reserve a file and get an upload link | POST /api/v1/files | files:write |
| Confirm the upload | POST /api/v1/files/{id}/complete | files:write |
| Read one file, with a download link | GET /api/v1/files/{id} | files:read |
| List files | GET /api/v1/files | files:read |
| Delete a file | DELETE /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.
nameis your label for the file. It is shown back exactly as you sent it and is never used as a path.folderis a grouping label you can filter on later, such asdeals/2026orexports. 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"
}'| Field | Values |
|---|---|
name | Required, 1–255 characters. Your label for the file. |
mime_type | Required, as type/subtype. The exact Content-Type your upload will send. |
size_bytes | Required, from 1 up to 209,715,200 (200 MB). The exact length your upload will send. |
folder | Optional grouping label (see above). |
customer_id | Optional. A customer in your workspace this file belongs to (see Erasure). |
metadata | Optional. Up to 20 string tags: keys 1–64 characters, values up to 512. Returned exactly as sent. |
idempotency_key | Optional, 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.pdfThe 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.
| Answer | What it means | What to do |
|---|---|---|
409 upload_incomplete | Nothing has been uploaded yet. | Upload, then confirm again. |
422 upload_mismatch | The 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_expired | More than 70 minutes have passed since the reserve. | Start a new upload. |
503 storage_unavailable | Storage 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
| Status | Meaning |
|---|---|
pending | Upload link issued, not confirmed yet. An upload that is never confirmed is cleaned up automatically after its window. |
ready | Confirmed. Downloadable, and billed. |
expired | Never confirmed in time, or the upload didn't match what was declared. |
deleted | Removed. |
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_urlis included only when the file isready. Apendingfile comes back without one.download_expires_insets how long the link works, from 60 to 86,400 seconds. The default is 3,600 (one hour).- An
expiredordeletedfile, or an id that isn't your app's, is 404file_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.
| Parameter | Values |
|---|---|
folder | Exact folder label. |
status | pending, ready, expired or deleted. Without it, you get only files that exist (pending and ready). |
customer_id | Files tied to that customer. |
limit | 1–200, default 50. |
cursor | The 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 status | Read | Upload | Delete |
|---|---|---|---|
| Active, or Cancelling | ✓ | ✓ | ✓ |
| Lapsed (renewal unpaid) | ✓ | 403 app_read_only | ✓ |
| Suspended | 403 app_suspended | 403 app_suspended | 403 app_suspended |
| Being set up, or set-up failed | 403 app_not_ready | 403 app_not_ready | 403 app_not_ready |
| Cancelled | The key is revoked: 401 revoked_api_key |
A lapsed app can still delete, because the workspace keeps paying for whatever it holds.
Limits
| Limit | Value | When it's reached |
|---|---|---|
| One file | 200 MB (209,715,200 bytes) | 400 invalid_request |
| Everything one app stores in your workspace | 50 GB | 413 storage_quota_exceeded |
| Credits | An 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