API reference

List your posts and their moderation status

Your posts, newest first, plus the current posting limits — read `limits` from the response rather than hardcoding numbers.

View as MarkdownUpdated Aug 19, 2026

GET/api/external/v1/postsalso served at /api/external/posts

Your posts, newest first, plus the current posting limits — read limits from the response rather than hardcoding numbers.

The status filter takes one moderation state; unrecognised values are silently ignored (you get the unfiltered list, not an error).

Authentication

Send the creator's API key as a bearer token: Authorization: Bearer dpfn_…. See Authentication & API keys.

For a creator you manage or onboarded

GET /api/external/v1/creators/{creatorId}/posts — an agency's own key for a creator or AI persona it manages (needs canManageDrops), or your app owner's own key for an account your app onboarded. The X-Dropfans-Account header still works but is deprecated. See Acting for a creator.

Query parameters

Name	Type	Required	Description
`page`	integer	Optional	Page number, 1-based. Default: `1`
`limit`	integer	Optional	Posts per page (default 20, cap 50 — larger values clamped). Default: `20` Max: 50
`status`	string	Optional	Filter by moderation state (case-insensitive). Unrecognised values are ignored. One of: `PENDING`, `APPROVED`, `REJECTED`, `FLAGGED`

Responses

200Your posts, newest first, plus the current limits.

Name Type Description

posts

Post[]

Your posts, newest first.

Show child attributes

id string Post id.

kind

string

Post shape. DROP is derived from productId at creation — it is not an accepted request value.

One of: TEXT, DROP, SUBSCRIPTION, COMMUNITY, MEDIA

caption string | null Post text. Null for caption-less media posts.

status

string

Moderation state. PENDING is normal for media posts and is not an error — poll until it becomes APPROVED.

One of: PENDING, APPROVED, REJECTED, FLAGGED

live boolean True only when the post is APPROVED and its publish time has passed.

scheduledAt

string | null

When the post is scheduled to go live, or null for immediate posts.

Format: date-time

publishedAt

string

Effective publish time.

Format: date-time

createdAt

string

Creation time.

Format: date-time

productId string | null The attached drop, for kind=DROP. Null otherwise.

likes integer Like count.

comments integer Comment count.

media

PostMedia[]

Media entries in display order. Empty for TEXT posts.

Show child attributes

`id`	string	Post-media row id.
`vaultItemId`	string	The source vault item.
`isPaid`	boolean	True for PPV items shown blurred until unlocked.
`order`	integer	Display position (0-based).
`type`	string	Media kind (image/video).

pagination

Pagination

Paging info (nested style — the vault list uses top-level fields instead).

Show child attributes

`page`	integer	Echoed page (1-based).
`limit`	integer	Echoed page size.
`total`	integer	Total rows matching the filter.
`hasMore`	boolean	True when more pages exist.

limits

PostLimits

The current posting limits, so a client never hardcodes them.

Show child attributes

`postsPerDay`	integer	Posts per creator per rolling 24 hours (currently 5).
`maxCaptionChars`	integer	Caption length cap (currently 2000).
`maxMediaPerPost`	integer	Media items per post (currently 10).
`maxScheduleDays`	integer	How far ahead a post can be scheduled, in days (currently 30).
`minPaidPrice`	integer	Minimum USD price of a paid media item (currently 5).

Example response

{
  "posts": [
    {
      "id": "clxp0st000001feed",
      "kind": "MEDIA",
      "caption": "rate my fit 1-10",
      "status": "APPROVED",
      "live": true,
      "scheduledAt": null,
      "publishedAt": "2026-08-18T19:00:00.000Z",
      "createdAt": "2026-08-18T18:59:40.000Z",
      "productId": null,
      "likes": 14,
      "comments": 3,
      "media": [
        {
          "id": "clxpm3d1a0001post",
          "vaultItemId": "clxv1a2b30001item",
          "isPaid": false,
          "order": 0,
          "type": "image"
        }
      ]
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 63,
    "hasMore": true
  },
  "limits": {
    "postsPerDay": 5,
    "maxCaptionChars": 2000,
    "maxMediaPerPost": 10,
    "maxScheduleDays": 30,
    "minPaidPrice": 5
  }
}

Errors

Status	Body	When
401	`{"error":"Unauthorized","code":"unauthorized"}`	Missing or invalid API key.
400	`{"error":"X-Dropfans-Account must be an account id (from GET /api/external/agency/creators), not a username.","code":"invalid_account_header"}`	`X-Dropfans-Account` is not an account id.
400	`{"error":"X-Dropfans-Account names a different account than the path — send one or the other.","code":"account_mismatch"}`	Called under /v1/creators/{creatorId}/ with an `X-Dropfans-Account` naming another account.
403	`{"error":"This key cannot act for that account.","code":"account_not_managed"}`	The creator in the path (or `X-Dropfans-Account`) is one this key cannot act for: no ACCEPTED management by your agency and not an account your app onboarded (or it no longer holds a key bound to your app), a key minted for one creator, or someone is suspended, banned or deleted. An unknown id gets the same answer.
403	`{"error":"The agency does not have permission for this on that account.","code":"permission_denied","permission":"canManageDrops"}`	For a managed creator: the agency lacks `canManageDrops` on that account.
403	`{"error":"This app does not have the posts API category enabled. Contact support to enable it.","code":"api_category_disabled","category":"posts"}`	Your app has the For You posts [API category](/developers/concepts/api-categories) switched off.

Rate limiting

Every response carries the X-RateLimit-Tier header and, on limited tiers, the per-minute and per-day trios — read X-RateLimit-Remaining and X-RateLimit-Reset instead of hardcoding limits. Details in Rate limits.

Code samples

curl "https://www.dropfans.io/api/external/v1/posts" \
  -H "Authorization: Bearer $DROPFANS_API_KEY"

const res = await fetch(`https://www.dropfans.io/api/external/v1/posts`, {
  headers: {
    Authorization: `Bearer ${process.env.DROPFANS_API_KEY}`,
  },
});
console.log(await res.json());

import os
import requests

res = requests.get(
    "https://www.dropfans.io/api/external/v1/posts",
    headers={"Authorization": f"Bearer {os.environ['DROPFANS_API_KEY']}"},
)
print(res.json())

← Previous

Publish a post to the For You feed

Check one post’s moderation status

Questions? support@dropfans.io