Create a vault folder
Creates a folder. Names are unique per creator (case-sensitive) and at most 50 characters.
/api/external/v1/vault/foldersalso served at /api/external/vault/foldersCreates a folder. Names are unique per creator (case-sensitive) and at most 50 characters.
The response is the bare folder object — not wrapped in {success} or {folder} like most other write endpoints.
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
POST /api/external/v1/creators/{creatorId}/vault/folders — 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.
Request body
Content type: application/json
| Name | Type | Required | Description |
|---|---|---|---|
name | string | Required | Folder name, trimmed, 1–50 chars, unique per creator. Max length: 50 |
{
"name": "Beach set"
}Responses
| Name | Type | Description |
|---|---|---|
id | string | Folder id. |
name | string | Folder name — unique per creator. |
itemCount | integer | Items in the folder. NOTE: GET /api/external/v1/vault counts only items visible at that call’s moderation filter, while GET /api/external/v1/vault/folders counts every non-hidden item regardless of moderation status — the same folder can report two different counts. |
{
"id": "clxf0ld3r0001abcd",
"name": "Beach set",
"itemCount": 0
}Errors
| Status | Body | When |
|---|---|---|
| 400 | {"error":"Invalid JSON body"} | The body is not valid JSON. |
| 400 | {"error":"Folder name is required"} | `name` missing or not a string. |
| 400 | {"error":"Folder name cannot be empty"} | `name` is whitespace only. |
| 400 | {"error":"Folder name must be 50 characters or less"} | Longer than 50 characters. |
| 401 | {"error":"Unauthorized","code":"unauthorized"} | Missing or invalid API key. |
| 409 | {"error":"A folder with this name already exists"} | Duplicate name (also returned on a create race). |
| 500 | {"error":"Failed to create vault folder"} | Write 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 -X POST "https://www.dropfans.io/api/external/v1/vault/folders" \
-H "Authorization: Bearer $DROPFANS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Beach set"
}'const res = await fetch(`https://www.dropfans.io/api/external/v1/vault/folders`, {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.DROPFANS_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"name": "Beach set"
}),
});
console.log(await res.json());import os
import requests
res = requests.post(
"https://www.dropfans.io/api/external/v1/vault/folders",
headers={"Authorization": f"Bearer {os.environ['DROPFANS_API_KEY']}"},
json={
"name": "Beach set",
},
)
print(res.json())Questions? support@dropfans.io