> ## Documentation Index
> Fetch the complete documentation index at: https://www.dropfans.io/developers/llms.txt
> Use this file to discover all available pages before exploring further.

# Post to the For You feed

> Text, image and drop posts from a script or an agent — with the same moderation and daily cap as the composer.

- Source: https://www.dropfans.io/developers/guides/post-to-feed
- Section: Guides
- OpenAPI: https://www.dropfans.io/developers/openapi.json

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:

```bash
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?" }'
```

| Field | Type | Notes |
| --- | --- | --- |
| `caption` | string | Post text, up to 2000 characters. Required for a text post. |
| `kind` | string | `"TEXT"` (default), `"MEDIA"`, `"SUBSCRIPTION"` or `"COMMUNITY"`. |
| `media[]` | array | Required for MEDIA. Up to 10 items: `{ vaultItemId, isPaid, price, order }`. |
| `productId` | string | Attach one of your approved drops. Forces kind DROP. |
| `scheduledAt` | ISO date | Publish later — at least 1 minute ahead, at most 30 days. |

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](https://www.dropfans.io/developers/build-with-ai/agent-prompt.md) 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):

```bash
# 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 }
    ]
  }'
```

> [!NOTE]
> Paid images posted through the API get a standard blur. To hand-tune the teaser blur, use the composer in the dashboard.

## 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:

```bash
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](https://www.dropfans.io/developers/guides/earnings-and-balance.md) or [Agent prompt](https://www.dropfans.io/developers/build-with-ai/agent-prompt.md).

---

Previous: [Links & Telegram deep links](https://www.dropfans.io/developers/guides/links-and-deep-links.md) · Next: [Earnings & balance](https://www.dropfans.io/developers/guides/earnings-and-balance.md) · All pages: [llms.txt](https://www.dropfans.io/developers/llms.txt)