API reference

Create a vault folder

Creates a folder. Names are unique per creator (case-sensitive) and at most 50 characters.

View as MarkdownUpdated Aug 19, 2026

POST/api/external/vault/folders

Creates 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.

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

Create a folder

{
  "name": "Beach set"
}

Responses

200Created — the bare folder object.

Name	Type	Description
`id`	string	Folder id.
`name`	string	Folder name — unique per creator.
`itemCount`	integer	Items in the folder. NOTE: GET /api/external/vault counts only items visible at that call’s moderation filter, while GET /api/external/vault/folders counts every non-hidden item regardless of moderation status — the same folder can report two different counts.

Example response

{
  "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.

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/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/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/vault/folders",
    headers={"Authorization": f"Bearer {os.environ['DROPFANS_API_KEY']}"},
    json={
        "name": "Beach set",
    },
)
print(res.json())

← Previous

List vault folders

Delete a vault folder

Questions? [email protected]