> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ofauth.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Media and Vault

> Browse media, organize Vault lists, and upload new files

The Vault is a creator’s OnlyFans media library. Choose an existing file or upload a new one, then attach it to a post, message, or story. Vault lists are folders for files. To group message recipients, use user lists.

## Before you start

Use `vault:read` to browse media. Uploading and changing Vault lists require `vault:write`. Complete [authorization](https://docs.ofauth.com/v3/guides/link.md) and select a [linked account](https://docs.ofauth.com/v3/api-reference/account/linked-accounts.md). Install the [TypeScript SDK](https://docs.ofauth.com/v3/sdk/typescript.md) version 4. Create a client on your server:

```typescript theme={null}
import { OFAuthClient } from "@ofauth/onlyfans-sdk"

const client = new OFAuthClient({
	accessToken: process.env.ACCESS_TOKEN!,
	linkedAccountId: process.env.LINKED_ACCOUNT_ID!
})
```

Scopes are the permissions your app requests when the user authorizes it. The [API reference](https://docs.ofauth.com/v3/api-reference.md) lists the permissions for each request.

## Browse Vault media

```typescript theme={null}
const media = await client.access.vault.media.list({ limit: 20 })
```

List responses use `{ items, page }`. Read the results from `items`. If `page.hasMore` is `true`, send `page.nextCursor` as the next request’s `cursor`. Keep the same filters.

### Vault query parameters

| Parameter | Meaning |
| - | - |
| `limit` | Number of items to return (1-40, default: 24) |
| `cursor` | Value from `page.nextCursor` in the previous response. |
| `sortBy` | Values: `recent`, `most-liked`, `highest-tips`. Sort media by: recent, most-liked, or highest-tips |
| `sortDirection` | Values: `asc`, `desc`. Sort direction |
| `query` | Text to search for |
| `mediaType` | Values: `photo`, `video`, `audio`. Filter by media type |
| `beforePublishDate` | Only return media published before this date |

Read one item with `GET /v3/access/vault/media/789`. Media includes its numeric ID and type. Check the response fields for the request you use: list responses use fields such as `ready`, `error`, and `urls`, while some responses to create or update requests use `isReady`, `hasError`, and `files`. These field names are not the same for every request.

## Organize Vault lists

| Method | Route |
| - | - |
| `GET` | `/v3/access/vault/lists` |
| `POST` | `/v3/access/vault/lists` |
| `GET` | `/v3/access/vault/lists/:listId` |
| `PATCH` | `/v3/access/vault/lists/:listId` |
| `DELETE` | `/v3/access/vault/lists/:listId` |
| `GET` | `/v3/access/vault/lists/:listId/media` |
| `POST` | `/v3/access/vault/lists/:listId/media` |
| `DELETE` | `/v3/access/vault/lists/:listId/media` |

Create a list with `{ "name": "Campaign assets" }`. Add media with `POST /v3/access/vault/lists/101/media` and `{ "mediaIds": [789, 790] }`. You can add 1 to 100 IDs. Each ID must be a positive whole number. To remove media from the list, send `DELETE` to the same route with a `mediaIds` body. This removes the media from the folder. To delete retained copies, use [Vault+ deletion](https://docs.ofauth.com/v3/guides/media-storage.md#delete-retained-media).

The list response uses `items` and `page`. You can request up to 40 lists per page. Media in a list uses the same filters as Vault media. To group fans for messages, use [user lists](https://docs.ofauth.com/v3/guides/fans.md).

## Upload new files

Follow [Upload media](https://docs.ofauth.com/v3/guides/how-to/upload-media.md) to calculate the file hash, upload each part, and mark the upload complete. Use [Media references](https://docs.ofauth.com/v3/guides/media-items.md) to attach the result to content.

Save a numeric Vault media ID if you want to use the file again. A temporary `upload:` reference works for one successful post, message, or story.

## Display and retain media

API media URLs expire. Use the returned URLs to display media. To get a new URL, read the post, message, or Vault item again.

[Vault+](https://docs.ofauth.com/v3/guides/media-storage.md) is optional. It makes the OnlyFans Vault easier to use in your platform: load saved media faster, find it by media ID, and show thumbnails without managing expiring OnlyFans URLs. This also works for saved files that are not attached to a post, message, or story. Add or sync the media you need before querying it.

![Browse the OnlyFans Vault directly, or use optional Vault+ to load saved files and thumbnails by media ID, even before they are attached to content.](https://mintcdn.com/ofauth/VVqOdSxbrh7mDF0M/images/v3/vault-and-retained-media.svg?fit=max\&auto=format\&n=VVqOdSxbrh7mDF0M\&q=85\&s=302bc81cb867e5b5d13b96dd11443d8c)

Stories accept one image and reject GIFs and videos. A file that works in a post or message may not work in a story. Edit the image before uploading it.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.