List your vault items — the source of media for posts
Returns APPROVED items by default. Use an item's `id` as `vaultItemId` when creating a MEDIA post. Pass includePending=true to also see items still in moderation (their media is stripped).
/api/external/v1/vaultalso served at /api/external/vaultReturns APPROVED items by default. Use an item's id as vaultItemId when creating a MEDIA post. Pass includePending=true to also see items still in moderation (their media is stripped).
Every drop and every MEDIA post is built from vault item ids, so this list is the starting point of almost every flow. Items are newest first. The response also carries all of the creator's folders — but note the folders' itemCount here respects the moderation filter, while GET /api/external/v1/vault/folders counts every non-hidden item, so the two can disagree for the same folder.
Authentication
Send the creator's API key as a bearer token: Authorization: Bearer dpfn_…. See Authentication & API keys.
For a creator you manage or onboarded
GET /api/external/v1/creators/{creatorId}/vault — an agency's own key for a creator or AI persona it manages (needs canManageVault), or your app owner's own key for an account your app onboarded. The X-Dropfans-Account header still works but is deprecated. See Acting for a creator.
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
page | integer | Optional | Page number, 1-based. Default: 1 |
limit | integer | Optional | Items per page. Hard cap 50 — larger values are clamped, not rejected. Default: 50Max: 50 |
folderId | string | Optional | "all" (default), "unfiled", or a folder id from the folders list. |
includePending | boolean | Optional | Pass the literal string true to also get PENDING and FLAGGED items (REJECTED never appears). Those items come back with filePath: "" and downloadUrl: null — thumbnail only — and each item gains a moderationStatus field.Default: false |
Responses
| Name | Type | Description | |||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
items | VaultItem[] | The requested page, newest first.Show child attributes
| |||||||||||||||||||||||||||||||||||||||
folders | Folder[] | All of the creator’s folders (unpaginated), with counts under the current moderation filter.Show child attributes
| |||||||||||||||||||||||||||||||||||||||
hasMore | boolean | True when more pages exist for the current filter. | |||||||||||||||||||||||||||||||||||||||
total | integer | Total items matching the filter. | |||||||||||||||||||||||||||||||||||||||
page | integer | Echoed page number (1-based). | |||||||||||||||||||||||||||||||||||||||
limit | integer | Echoed page size. |
{
"items": [
{
"id": "clxv1a2b30001item",
"fileName": "beach-set-01.jpg",
"filePath": "https://cdn.dropfans.io/valeria/vault/1721990000-ab12cd.jpg",
"thumbnailPath": "https://cdn.dropfans.io/valeria/thumbnails/1721990000-ab12cd.jpg",
"fileType": "image",
"fileSize": 482113,
"durationSeconds": null,
"bunnyStreamId": null,
"createdAt": "2026-08-01T10:15:00.000Z",
"folderId": "clxf0ld3r0001abcd",
"contentTags": [
"beach",
"bikini"
],
"downloadUrl": null
}
],
"folders": [
{
"id": "clxf0ld3r0001abcd",
"name": "Beach set",
"itemCount": 12
}
],
"hasMore": true,
"total": 128,
"page": 1,
"limit": 50
}Errors
| Status | Body | When |
|---|---|---|
| 401 | {"error":"Unauthorized","code":"unauthorized"} | Missing or invalid API key. |
| 500 | {"error":"Failed to fetch vault items"} | Query failed — retry later. |
| 400 | {"error":"X-Dropfans-Account must be an account id (from GET /api/external/agency/creators), not a username.","code":"invalid_account_header"} | `X-Dropfans-Account` is not an account id. |
| 400 | {"error":"X-Dropfans-Account names a different account than the path — send one or the other.","code":"account_mismatch"} | Called under /v1/creators/{creatorId}/ with an `X-Dropfans-Account` naming another account. |
| 403 | {"error":"This key cannot act for that account.","code":"account_not_managed"} | The creator in the path (or `X-Dropfans-Account`) is one this key cannot act for: no ACCEPTED management by your agency and not an account your app onboarded (or it no longer holds a key bound to your app), a key minted for one creator, or someone is suspended, banned or deleted. An unknown id gets the same answer. |
| 403 | {"error":"The agency does not have permission for this on that account.","code":"permission_denied","permission":"canManageVault"} | For a managed creator: the agency lacks `canManageVault` on that account. |
| 403 | {"error":"This app does not have the vault API category enabled. Contact support to enable it.","code":"api_category_disabled","category":"vault"} | Your app has the Vault [API category](/developers/concepts/api-categories) switched off. |
Rate limiting
Every response carries the X-RateLimit-Tier header and, on limited tiers, the per-minute and per-day trios — read X-RateLimit-Remaining and X-RateLimit-Reset instead of hardcoding limits. Details in Rate limits.
Code samples
curl "https://www.dropfans.io/api/external/v1/vault?page=1&folderId=all" \
-H "Authorization: Bearer $DROPFANS_API_KEY"const res = await fetch(`https://www.dropfans.io/api/external/v1/vault?page=1&folderId=all`, {
headers: {
Authorization: `Bearer ${process.env.DROPFANS_API_KEY}`,
},
});
console.log(await res.json());import os
import requests
res = requests.get(
"https://www.dropfans.io/api/external/v1/vault",
headers={"Authorization": f"Bearer {os.environ['DROPFANS_API_KEY']}"},
params={"page": 1, "folderId": "all"},
)
print(res.json())Notes
Signed URLs in the response (downloadUrl, audio filePath) are valid ~12 hours — re-list rather than caching them longer. downloadUrl is the only fetchable video source (the Stream filePath is DRM-locked); it is null for videos uploaded before dual-store existed. filePath is the empty string "" for any non-APPROVED item.
Questions? support@dropfans.io