Post to the For You feed

One endpoint, one API key. Publish text and image posts to the creator’s Dropfans feed from a script, a scheduler, or an AI assistant — content runs the same moderation as the composer, so nothing skips review.

Publish a post#

The smallest useful call is a text post:

curl -X POST "https://www.dropfans.io/api/external/posts" \
  -H "Authorization: Bearer $DROPFANS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "caption": "im 5 min away, wyd?" }'

A 201 returns { id, status, pending, scheduledAt, url } — status: "APPROVED" means it is already live; "PENDING" means it is waiting on review.

Caption house style: short (under ~80 characters), lowercase, second person, present tense, almost no emoji — ending on a cheap question works best. See the agent prompt for the same rules in paste-into-an-assistant form.

Images from your vault#

Image posts reference content already in the vault, so nothing is uploaded twice. List the vault, pick an item whose moderationStatus is APPROVED, and reference its id. Mark an item paid to turn it into a blurred PPV unlock (minimum $5):

# 1. find an approved image in your vault
curl "https://www.dropfans.io/api/external/vault?limit=5" \
  -H "Authorization: Bearer $DROPFANS_API_KEY"

# 2. post it — free teaser first, paid unlock second
curl -X POST "https://www.dropfans.io/api/external/posts" \
  -H "Authorization: Bearer $DROPFANS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "MEDIA",
    "caption": "can i show you??",
    "media": [
      { "vaultItemId": "VAULT_ITEM_A", "isPaid": false, "order": 0 },
      { "vaultItemId": "VAULT_ITEM_B", "isPaid": true, "price": 10, "order": 1 }
    ]
  }'

Moderation#

Nothing here bypasses review. Captions run the prohibited-word filter on the way in, and images ride the NSFW pipeline. Anything still in review comes back PENDING and goes live by itself once it clears — a normal outcome, not an error. Poll until it flips:

curl "https://www.dropfans.io/api/external/posts?status=PENDING" \
  -H "Authorization: Bearer $DROPFANS_API_KEY"

Handle the two rejections precisely:

• 422 { "error": …, "matchedWord": "…" } — the caption tripped the word filter. Rewrite the caption and retry once.
• 429 — the daily cap of 5 posts per rolling 24 hours (the composer’s cap, enforced here too). The Retry-After header says how many seconds to wait. Stop; never retry a 429 in a loop. Bursts inside the day are fine — only volume is capped.

Scheduling#

Pass scheduledAt (ISO-8601, at least 1 minute ahead, at most 30 days out) and the post publishes itself — moderation runs at submit time, so a clean scheduled post flips to live exactly on time. Cancel a scheduled post with DELETE /posts/{id} before it publishes.

Next: Earnings & balance or Agent prompt.