Files
Customers send photos and documents, and your team sends files back from the Inbox. Every such file has an id, which you see in the attachments of a message. With an API key you can download any file of your workspace by its id: to show a customer's photo in your own app, or to save a document in your CRM.
Base URL: https://peki.ai/api
Auth: Authorization: Bearer psk_…, Read only or Read and write (Authentication)
To upload a file from your user into a session, see Upload a file in the Sessions API.
Download a file
GET /files/{id}
| Parameter | Where | Description |
|---|---|---|
id | path | The file id from a message's attachments[].id, or from an upload response. |
curl https://peki.ai/api/files/671ca1c4a1b2c3d4e5f60730 \
-H "Authorization: Bearer $PEKI_API_KEY" \
-o damaged-box.jpg
const res = await fetch(`https://peki.ai/api/files/${fileId}`, {
headers: { Authorization: `Bearer ${process.env.PEKI_API_KEY}` },
});
if (!res.ok) throw new Error(`Peki API ${res.status}`);
const bytes = Buffer.from(await res.arrayBuffer());
const type = res.headers.get('content-type'); // e.g. "image/jpeg"
Response 200 with the file's bytes.
| Header | Value |
|---|---|
Content-Type | The file's type, checked from its content when it was uploaded, like image/png or application/pdf. Text files add ; charset=utf-8. |
Content-Length | Size in bytes. |
Content-Disposition | inline for photos, attachment for documents, with the original file name. |
Cache-Control | private, max-age=300. |
X-Content-Type-Options | nosniff. |
Content-Security-Policy | default-src 'none'; img-src 'self'; sandbox. |
The last two headers stop a browser from running anything inside a file, so files are always safe to open.
Find file ids
Files appear on messages:
{
"id": "671ca0a1a1b2c3d4e5f60720",
"role": "customer",
"text": "The box arrived damaged",
"status": "done",
"createdAt": "2026-10-26T14:05:40.102Z",
"attachments": [
{ "id": "671ca1c4a1b2c3d4e5f60730", "name": "damaged-box.jpg", "contentType": "image/jpeg", "size": 284113 }
]
}
| Field | Description |
|---|---|
id | Use it with GET /files/{id}. |
name | The original file name. |
contentType | The file's type. |
size | Size in bytes. |
You get messages from GET /sessions/{id}/messages.
What you can download
Any file of your workspace: files your users sent through the API, website chat and Telegram, files your team sent from the Inbox, and files in records. A file id from another workspace returns 404.
| File types | |
|---|---|
| Photos | JPEG, PNG, WebP, GIF |
| Documents | PDF, TXT, Markdown, CSV |
Files are at most 10 MB each.
Errors
| Status | Body | Why |
|---|---|---|
401 | Invalid API key | Missing, wrong or revoked key. |
404 | { "message": "File not found", "code": "file_missing" } | The id is wrong, the file belongs to another workspace, or it was deleted. |
How long files are kept
- A file sent with a message stays as long as its conversation does.
- An upload that is never sent with a message is deleted after 24 hours.
- Deleting an agent deletes the files of its conversations and knowledge. Deleting the workspace deletes all of its files.
See Data and privacy.
Files are customer data. If you show them in your own app, check that the signed-in user may see that conversation: the API key can reach every file in your workspace.