API reference overview
Base URL, authentication, conventions and the shape of every response — read this before the endpoint pages.
https://www.dropfans.ioEvery endpoint lives under /api/external/ on that host. This page collects the conventions the endpoint pages assume.
The whole contract is also published as OpenAPI 3.1 — ready to feed to a client generator, Postman, or a coding agent. See Build with AI.
Authentication#
Every request carries Authorization: Bearer dpfn_…. A key is bound to one creator and grants the full surface — details in Authentication & API keys.
Requests#
JSON bodies with Content-Type: application/json everywhere except the two upload endpoints (upload a vault item, attach previews), which take multipart/form-data. Malformed JSON returns 400 { "error": "Invalid JSON body" }.
Ids and timestamps#
Ids are opaque strings (cuid format, e.g. cmawq81x40001lb04xyz12abc) — treat them as text, never parse them. Timestamps are ISO-8601 in UTC, e.g. 2026-08-19T12:00:00.000Z.
Pagination#
Two styles, both page/limit based: vault lists put hasMore/total/page/limit at the top level (limit defaults to the max, 50); post lists nest them under pagination (default 20). Iterate on hasMore, not on short pages. Two batch endpoints truncate oversized id arrays silently — details and caps in Pagination & batch limits.
Errors#
Baseline { "error": "…" } prose; gateway errors add a stable code (unauthorized, app_suspended, rate_limited); the word filter adds matchedWord (posts, 422) or field + matchedWord (drops, 400). The full catalogue — including the three success envelopes — is in Errors. Each endpoint page lists its exact error rows.
Rate-limit headers#
Every response reports the budget:
| Header | Meaning |
|---|---|
X-RateLimit-Tier | personal, app or first_party |
X-RateLimit-Limit / -Remaining / -Reset | the minute window |
X-RateLimit-Limit-Day / -Remaining-Day / -Reset-Day | the UTC-day window |
Retry-After | on 429, seconds to wait |
Tiers and defaults: Rate limits.
Units#
Prices go in as USD dollars (drops: 0 or 5–750); earnings and sales come out as integer cents; balance is dollars. The per-endpoint table is in Money & units.
Versioning#
Changes are additive — new fields and new endpoints, announced in the changelog. There is no version header. Ignore fields you do not recognise, and never assume a response has exactly the fields listed today.
Next: Get current creator or Errors.
Questions? [email protected]