API v1 overview
Base URL, versions, cursor and page paging, acting for a creator as an agency, error shapes, rate limits, money and ids for API v1 with OAuth tokens.
API v1 serves creators’ accounts, audience, insights, vault media, posts, tracking links, webhooks and chat to OAuth apps. Every request carries Authorization: Bearer <access token>. The base URL is https://api.dropfans.io.
Paths and paging#
| Prefix | Paging | List response |
|---|---|---|
/v1/… | cursor + limit | {"data": […], "nextCursor": "…" | null} |
/v0/… and unprefixed (/users/me) | page (from 1) + size | {"data": […], "pagination": {"page": 1, "size": 20, "hasMore": true}} |
The three prefixes serve the same operations; pick one style and keep it. On /v1, pass nextCursor back as cursor until it is null. A cursor is opaque: do not build or edit one.
Version header#
Send the API version in a request header whose name ends in -API-Version, for example X-Dropfans-API-Version: 2025-06-26. Without one you get 2025-06-26, the current version. An unknown version is 400 {"error": "Unsupported API version", "message": "…"}.
Acting for a creator (agencies)#
A token acts for the account that authorized it. An agency’s token can also act for each creator it manages: prefix the path with /creators/{creatorUserUuid}, for example GET /v1/creators/{creatorUserUuid}/posts. Which operations have this form, and the extra scopes it needs (usually read:creator), is in the resource list. The agency needs the matching permission on that creator; otherwise the call is 403 {"message": "Forbidden"}. GET /v1/creators lists the creators your token can act for.
Errors#
| Status | Body | When |
|---|---|---|
| 400 | {"errors": ["…"]} | Validation failed (one message per problem) |
| 400 | {"message": "Invalid UUID format …"} | A path parameter is not a UUID |
| 401 | {"error": "Unauthorized"} | Token missing, expired or revoked |
| 403 | {"error": "Insufficient scopes"} | The token lacks a scope the operation needs |
| 403 | {"message": "Forbidden"} | A creator path you cannot act for |
| 404 | {"message": "Resource not found"} | Unknown path, an id that is not yours, or a category that is off for your app |
| 429 | {"error": "Too many requests"} + Retry-After | Rate limit reached |
Rate limits#
200 requests per 60 seconds per (account, app); a call in the /creators/{creatorUserUuid} form counts against that creator’s own budget as well, so one busy creator does not starve the rest of a roster. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset.
Money, ids and times#
- Money is an integer number of USD cents (
1999= $19.99). - Ids are UUIDs: accounts, posts, media, chats and every other object. Internal ids never appear.
- Times are ISO 8601 in UTC.
Onboarding creators#
POST /v1/onboarding/creators creates a creator account and returns kycUrl. Send the creator to it in their own browser: they accept the Dropfans Terms of Service there, and the acceptance is recorded with their IP address and user agent, never your server’s. Then they continue to ID verification.
If your app already showed the Terms and collected the acceptance in the creator’s browser, you may add acceptedFromIp and acceptedUserAgent (that browser’s IP address and user agent) to the request body. The acceptance is then recorded at once and kycUrl goes straight to ID verification.
Chat#
The chat operations (/chats/**, /agencies/chats/**, online subscribers) and the chat webhook topics are available once chat is enabled for your app. Until then they answer 404 {"message": "Resource not found"}, like any path that does not exist.
Next: Resource list · Webhooks.
Questions? [email protected]