---
source_url: https://www.pubnub.com/docs/data-storage/files/overview
title: Files
updated_at: 2026-09-30T07:20:08.000Z
---

# Files

## Documentation index

To discover more PubNub resources:

1. Fetch [PubNub's llms.txt](https://www.pubnub.com/llms-full.txt) for a list of available pages in Markdown format.
2. Identify relevant URLs from that index.
3. Fetch the target pages.

Do not assume a path exists, always check the index first.

File Sharing stores binary files uploaded to a channel and delivers a real-time event to subscribers when an upload completes. You enable it on your keyset in the Admin Portal, then upload and download files through the SDK. It is a separate storage system from [Message Persistence](https://www.pubnub.com/docs/data-storage/message-history/overview.md) and [App Context](https://www.pubnub.com/docs/data-storage/metadata/overview.md), enabled per keyset, and priced independently.

## How file delivery works

When a client uploads a file, PubNub stores the file and publishes a file event to all subscribers on that channel. The event carries the file ID, the file name, and a download URL. It also carries any text message attached to the upload and the uploading client's [User ID](https://www.pubnub.com/docs/architecture/core-concepts.md#user-id).

File events have message type `4`. Subscribers receive them on the same channel listener used for regular messages. No separate subscription is required. For the full event payload, see [File events](https://www.pubnub.com/docs/architecture/events.md#file).

A successful upload returns a [timetoken](https://www.pubnub.com/docs/architecture/core-concepts.md#timetoken), the same 17-digit value PubNub assigns to published messages. This timetoken identifies the file event in the channel's timeline.

## Message Persistence

If [Message Persistence](https://www.pubnub.com/docs/data-storage/message-history/overview.md) is enabled on the keyset, PubNub stores file events alongside regular messages. They appear in history with message type `4` and can be retrieved using the same `fetchMessages` API used for text messages.

File Sharing and Message Persistence have independent retention settings. If your app links file uploads to messages on the same channel, align the two retention periods. A file event in history that points to a file already deleted from File Sharing storage creates a broken reference.

## Configuration

Enable File Sharing for your keyset in the [Admin Portal](https://admin.pubnub.com). The two settings that govern storage behavior are:

**Bucket region.** PubNub stores all files for a keyset in one geographic region. You choose the region when you enable the feature. The region cannot be changed after saving. Plan your data-residency requirements before enabling.

**Retention.** How long PubNub keeps uploaded files before deleting them. The available options and limits are:

| Function | Limit | Notes |
| --- | --- | --- |
| File size | 5 MB | To raise it, contact [support@pubnub.com](mailto:support@pubnub.com). |
| File retention | File retention is 1 or 7 days on the Free plan, 30 days on Starter, and Unlimited on Pro. | Set it per keyset in the [Admin Portal](https://admin.pubnub.com/). |
| Files per list call | A single list-files call returns up to 100 files for a channel. |  |

Retention applies to the file itself. The file event in Message Persistence history follows the Message Persistence retention setting for that keyset, not the File Sharing retention setting.

## Encryption

PubNub encrypts files with AES-256 when a cipher key is set. Set a cipher key in the SDK client configuration to encrypt all files automatically, or pass a cipher key per request to encrypt individual uploads. Any client that downloads the file must use the same key. For where the key lives and what happens without it, refer to [Encryption](https://www.pubnub.com/docs/security/encryption/overview.md).

## Access Manager

When [Access Manager](https://www.pubnub.com/docs/security/access-control/overview.md) is enabled on your keyset, file operations require channel-level permissions:

| Operation | Required permission |
| --- | --- |
| Upload a file | `write` |
| List or download files | `read` |
| Delete a file | `delete` |

These use the same channel permissions as messaging. A token that grants `write` on a channel authorizes both message publishing and file uploads on that channel.

Last updated at: 2026-09-30T07:20:08.000Z