# Dropfans API Documentation

> Sell drops, manage a creator’s vault, post to the For You feed and read
> earnings from any software, with one dpfn_ API key per creator. Every page
> below has a Markdown twin — fetch the .md URL for a clean, plain-text edition.

## Get started

- [Dropfans API](https://www.dropfans.io/developers/get-started/overview.md): Sell drops, manage a creator’s vault, post to the For You feed and read earnings from any software, with one dpfn_ API key per creator.
- [Make your first call](https://www.dropfans.io/developers/get-started/first-call.md): One authenticated request to GET /api/external/me that proves your key works.
- [Connect a creator to your app](https://www.dropfans.io/developers/get-started/connect-a-creator.md): How a third-party app obtains and safely stores a creator’s Dropfans API key.
- [Testing without a sandbox](https://www.dropfans.io/developers/get-started/testing.md): There is no sandbox — test against a creator account you control, with free drops and pending content.

## Concepts

- [Authentication & API keys](https://www.dropfans.io/developers/concepts/authentication.md): Every request carries Authorization: Bearer dpfn_… — a key is bound to one creator and grants the full surface.
- [Apps & approval](https://www.dropfans.io/developers/concepts/apps-and-approval.md): Personal keys work immediately; apps that connect other people’s creator accounts need a one-time approval.
- [Rate limits](https://www.dropfans.io/developers/concepts/rate-limits.md): Fixed per-minute and per-day windows per key, by tier — read the X-RateLimit-* headers rather than hardcoding.
- [Errors](https://www.dropfans.io/developers/concepts/errors.md): HTTP status meanings and the (deliberately honest) catalogue of body shapes you will see.
- [Pagination & batch limits](https://www.dropfans.io/developers/concepts/pagination.md): Two page styles, one cap of 50, and two batch endpoints that truncate silently — chunk client-side.
- [Moderation & statuses](https://www.dropfans.io/developers/concepts/moderation-and-statuses.md): Nothing posted through the API skips review — every status enum and lifecycle in one place.
- [Money & units](https://www.dropfans.io/developers/concepts/money-and-units.md): Prices go in as USD dollars; earnings and sales come out as integer cents; balance is dollars — per endpoint.
- [Agencies](https://www.dropfans.io/developers/concepts/agencies.md): Agency accounts hold one key per managed creator; everything else about the API is identical.

## Guides

- [Sell a drop end-to-end](https://www.dropfans.io/developers/guides/sell-a-drop.md): From approved vault items to a paid sale: create the drop, share the link, poll for the sale, read the earnings.
- [Upload images, audio and video](https://www.dropfans.io/developers/guides/upload-media.md): Small files go through one multipart call; videos go straight to the CDN with a three-step TUS flow.
- [Links & Telegram deep links](https://www.dropfans.io/developers/guides/links-and-deep-links.md): Canonical profile, tip, subscribe and buy URLs for a creator — on the web and inside the Dropfans Telegram Mini App.
- [Post to the For You feed](https://www.dropfans.io/developers/guides/post-to-feed.md): Text, image and drop posts from a script or an agent — with the same moderation and daily cap as the composer.
- [Earnings & balance](https://www.dropfans.io/developers/guides/earnings-and-balance.md): Mirror the creator’s dashboard numbers and payout buckets inside your own product.

## Webhooks

- [Webhooks (coming soon) & polling today](https://www.dropfans.io/developers/webhooks/overview.md): Outbound webhooks for third-party apps are planned; until then, these polling patterns cover sales, video processing and moderation.

## Build with AI

- [Build with AI](https://www.dropfans.io/developers/build-with-ai/overview.md): Feed an agent the whole API in one shot: llms.txt, llms-full.txt, openapi.json, and a Markdown twin of every page.
- [Agent prompt](https://www.dropfans.io/developers/build-with-ai/agent-prompt.md): Copy-paste prompts that make an assistant post to the feed or sell drops correctly.

## API reference

- [API reference overview](https://www.dropfans.io/developers/reference/overview.md): Base URL, authentication, conventions and the shape of every response — read this before the endpoint pages.
- [Which creator this API key belongs to](https://www.dropfans.io/developers/reference/get-me.md): GET /api/external/me — Returns the creator account behind the key, plus metadata about the key itself.
- [Read the creator’s timezone](https://www.dropfans.io/developers/reference/get-timezone.md): GET /api/external/timezone — Returns the creator's IANA timezone, defaulting to `"UTC"` when they never set one.
- [Set the creator’s timezone](https://www.dropfans.io/developers/reference/update-timezone.md): PUT /api/external/timezone — Sets the creator's timezone — the same setting their dashboard uses for day bucketing.
- [The creator’s payout balance](https://www.dropfans.io/developers/reference/get-balance.md): GET /api/external/balance — The creator's payout balance buckets — the same numbers their Payouts page shows.
- [List your vault items — the source of media for posts](https://www.dropfans.io/developers/reference/list-vault.md): GET /api/external/vault — Returns APPROVED items by default. Use an item's `id` as `vaultItemId` when creating a MEDIA post. Pass includePending=true to also see items still in moderation (their media is stripped).
- [Upload an image, small video or voice message](https://www.dropfans.io/developers/reference/upload-vault-item.md): POST /api/external/vault — Uploads one file into the creator's vault as `multipart/form-data`.
- [Delete (hide) a vault item](https://www.dropfans.io/developers/reference/delete-vault-item.md): DELETE /api/external/vault/{id} — Soft-deletes a vault item you own: nothing is removed from storage, the item is hidden and disappears from every list.
- [Move a vault item to a folder](https://www.dropfans.io/developers/reference/move-vault-item.md): PATCH /api/external/vault/{id}/folder — Files a vault item into a folder, or unfiles it back to "All".
- [Replace a vault item’s content tags](https://www.dropfans.io/developers/reference/set-vault-item-tags.md): PATCH /api/external/vault/{id}/tags — Replaces (not merges) the content tags on a vault item. Send the full list every time.
- [List vault folders](https://www.dropfans.io/developers/reference/list-folders.md): GET /api/external/vault/folders — Every folder the creator has, alphabetically. **Unpaginated** — you always get the full list.
- [Create a vault folder](https://www.dropfans.io/developers/reference/create-folder.md): POST /api/external/vault/folders — Creates a folder. Names are unique per creator (case-sensitive) and at most 50 characters.
- [Delete a vault folder](https://www.dropfans.io/developers/reference/delete-folder.md): DELETE /api/external/vault/folders/{folderId} — Deletes a folder you own. **Non-empty folders are allowed**: the items inside are preserved and fall back to "All" (unfiled) — nothing is removed from storage. System folders (compliance archives) cannot be deleted.
- [Start a video upload (step 1 of 3)](https://www.dropfans.io/developers/reference/start-video-upload.md): POST /api/external/vault/video-upload — Starts a direct-to-CDN video upload and returns presigned TUS credentials.
- [Finish a video upload (step 3 of 3)](https://www.dropfans.io/developers/reference/complete-video-upload.md): POST /api/external/vault/video-upload/complete — Registers a finished TUS upload as a vault item and kicks moderation.
- [Check video transcoding status (batch)](https://www.dropfans.io/developers/reference/video-status.md): POST /api/external/vault/video-status — Transcoding status + duration for a batch of video GUIDs (`bunnyStreamId` values from your vault items).
- [Create a sellable drop from vault items](https://www.dropfans.io/developers/reference/create-drop.md): POST /api/external/drops — Packages up to 10 vault items into a drop and returns a checkout URL.
- [Read back a drop](https://www.dropfans.io/developers/reference/get-drop.md): GET /api/external/drops/{id} — One drop you created: price, moderation status (overall and per media item), checkout URL, whether previews are attached, and a sales summary.
- [Attach baked blur previews to a drop](https://www.dropfans.io/developers/reference/attach-drop-previews.md): POST /api/external/drops/{id}/previews — Uploads pre-blurred ("baked") JPEG teasers for a drop's media, so the checkout page shows the exact same blur your app showed the buyer elsewhere.
- [Check which drops sold (batch)](https://www.dropfans.io/developers/reference/check-drop-status.md): POST /api/external/drops/check-status — Sale info for a batch of product ids — the polling half of sale tracking.
- [Publish a post to the For You feed](https://www.dropfans.io/developers/reference/create-post.md): POST /api/external/posts — Rate limit: 5 posts per creator per rolling 24 hours. Bursts are fine — only the daily volume is capped. Exceeding it returns 429 with a Retry-After header.
- [List your posts and their moderation status](https://www.dropfans.io/developers/reference/list-posts.md): GET /api/external/posts — Your posts, newest first, plus the current posting limits — read `limits` from the response rather than hardcoding numbers.
- [Check one post’s moderation status](https://www.dropfans.io/developers/reference/get-post.md): GET /api/external/posts/{id} — One post, as a **bare object** (not wrapped). The polling endpoint after a PENDING create: check `status` and `live`.
- [Delete a post (or cancel a scheduled one)](https://www.dropfans.io/developers/reference/delete-post.md): DELETE /api/external/posts/{id} — Hard-deletes one of your posts. Deleting a scheduled post before it goes live cancels it.
- [Earnings stats, chart and recent transactions](https://www.dropfans.io/developers/reference/get-earnings.md): GET /api/external/earnings — The same revenue the creator sees on their own dashboard: drop sales + tips + subscription payments, refunds and chargebacks excluded, bucketed by day in the caller's timezone.
- [Canonical profile, tip, subscribe and buy links](https://www.dropfans.io/developers/reference/get-links.md): GET /api/external/links — Every shareable link for the creator behind the key, in one call — never template Dropfans URLs by hand.
- [Read the Telegram notification status](https://www.dropfans.io/developers/reference/get-notifications.md): GET /api/external/notifications — Where the creator's sale notifications currently go: their saved handle, whether a personal chat is connected, and whether a group/channel is connected.
- [Update Telegram notification settings](https://www.dropfans.io/developers/reference/update-notifications.md): PUT /api/external/notifications — An action-dispatch endpoint — the `action` field picks one of three operations:
- [Register the creator’s personal notification chat](https://www.dropfans.io/developers/reference/register-telegram-chat.md): POST /api/external/register-telegram-chat — Stores a Telegram chat id as the creator's **personal** notification target — the DM their sale notifications go to.

## Resources

- [Changelog](https://www.dropfans.io/developers/changelog.md): Dated, additive changes to the API and these docs.
- [API terms & acceptable use](https://www.dropfans.io/developers/api-terms.md): What you may and may not do with a creator’s API key.

## Apply

- [Apply for API access](https://www.dropfans.io/developers/apply): Building an app for other people's creators? Apply here (requires a Dropfans login); approved apps appear in every creator's key picker.

## OpenAPI Specs

- [OpenAPI 3.1 spec](https://www.dropfans.io/developers/openapi.json): Every operation, schema, error body and code sample, machine-readable.

## Optional

- [Complete documentation in one file](https://www.dropfans.io/developers/llms-full.txt): Every page of these docs concatenated — ingest this for full context.
- [Dropfans site guide](https://www.dropfans.io/llms.txt): The wider Dropfans platform in one file.