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/v1/ on that host. The unversioned paths (/api/external/… without v1) are permanent aliases of the same endpoints, so existing integrations keep working. 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 acts for one account and grants the full surface — details in Authentication & API keys.
An agency’s own key (for a creator or AI persona it manages) and your app owner’s own key (for an account your app onboarded) may call any endpoint outside the Agencies and CRM groups under /api/external/v1/creators/{creatorId}/… to act for that account; the older X-Dropfans-Account: <account id> header still works but is deprecated. Every response echoes the account acted on in the X-Dropfans-Account response header. See Acting for a creator.
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? support@dropfans.io