API reference

List the creators and personas you manage

Every creator and AI persona the agency manages, with the account `id` to send as `X-Dropfans-Account` and the permissions the agency holds on each.

View as MarkdownUpdated Oct 26, 2026

GET/api/external/agency/creatorsNew

Every creator and AI persona the agency manages, with the account id to send as X-Dropfans-Account and the permissions the agency holds on each.

Call it with the agency's own key. Then act for any account by sending the same key plus X-Dropfans-Account: <id> to the regular endpoints — see Agencies: one key for every creator. active tells you whether the header works for that account right now.

By default only ACCEPTED relationships come back. ?status=all adds ended creators and retired personas, e.g. to find a persona to reactivate.

Authentication

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

Needs the agency's own key, sent without X-Dropfans-Account.

Query parameters

Name	Type	Required	Description
`status`	string	Optional	Pass `all` to include ended and retired accounts. Omit for active (ACCEPTED) only. One of: `all`

Responses

200The agency and its managed accounts.

Name Type Description

agency

object

The agency holding the key.

Show child attributes

`id`	string	The agency’s user id.
`username`	string \| null	The agency’s @handle.
`name`	string \| null	The agency’s display name.

creators

AgencyCreator[]

Managed creators and AI personas, oldest relationship first.

Show child attributes

id string The account’s user id — the value for X-Dropfans-Account.

managedCreatorId string Id of the management relationship (not an account id — never send it as X-Dropfans-Account).

username string | null Public @handle, without the @.

name string | null Display name.

image

string | null

Profile image URL.

Format: uri

kind

string

ai_persona = an AI persona the agency runs; creator = a real creator who accepted the agency.

One of: creator, ai_persona

status

string

Relationship status. Only ACCEPTED accounts are returned unless you pass ?status=all; a retired persona is DEPARTED, an ended creator REVOKED or DEPARTED.

One of: INVITE_SENT, INVITE_EXPIRED, ACCEPTED, REVOKED, DEPARTED

active boolean True when X-Dropfans-Account works for this account right now: ACCEPTED, and the account is not suspended, banned or deleted.

kycCoveredByAgency boolean True when the account’s ID check rides on the agency’s (AI personas).

sellerStatus string Internal seller state, for support.

permissions

AgencyPermissions

What the agency may do on this account. Each API route needs one of these when called with X-Dropfans-Account.

Show child attributes

`canEditProfile`	boolean	Profile, timezone, subscription tier and Telegram notification settings.
`canManageDrops`	boolean	Drops, orders and posts.
`canManageVault`	boolean	Vault media, folders, tags and video uploads.
`canViewStats`	boolean	Earnings, tips, balance and subscription reads.
`canManageCoPerformers`	boolean	Co-performer management (dashboard only — no API endpoint uses it yet).

profileUrl

string | null

Public profile URL. Null until the account has a username.

Format: uri

since

string | null

When the relationship was accepted.

Format: date-time

Example response

{
  "agency": {
    "id": "cmh1agc0q0001ab7k2p9q4r8s",
    "username": "starlight_agency",
    "name": "Starlight Agency"
  },
  "creators": [
    {
      "id": "cmh4v2q8k0003xy9z7w6v5u4t",
      "managedCreatorId": "cmh4v2q8k0004mc1relation",
      "username": "luna_ai",
      "name": "Luna",
      "image": "https://cdn.dropfans.io/luna_ai/profile.jpg",
      "kind": "ai_persona",
      "status": "ACCEPTED",
      "active": true,
      "kycCoveredByAgency": true,
      "sellerStatus": "VERIFIED_CREATOR",
      "permissions": {
        "canEditProfile": true,
        "canManageDrops": true,
        "canManageVault": true,
        "canViewStats": true,
        "canManageCoPerformers": false
      },
      "profileUrl": "https://www.dropfans.io/u/luna_ai",
      "since": "2026-10-01T09:00:00.000Z"
    },
    {
      "id": "cmh3k9p2a0002cd5e6f7g8h9j",
      "managedCreatorId": "cmh3k9p2a0005mc2relation",
      "username": "valeria",
      "name": "Valeria",
      "image": null,
      "kind": "creator",
      "status": "ACCEPTED",
      "active": true,
      "kycCoveredByAgency": false,
      "sellerStatus": "VERIFIED_CREATOR",
      "permissions": {
        "canEditProfile": false,
        "canManageDrops": true,
        "canManageVault": true,
        "canViewStats": true,
        "canManageCoPerformers": false
      },
      "profileUrl": "https://www.dropfans.io/u/valeria",
      "since": "2026-09-12T14:30:00.000Z"
    }
  ]
}

Errors

Status	Body	When
400	`{"error":"Agency endpoints act as the agency itself — send them without X-Dropfans-Account.","code":"account_header_not_allowed"}`	The request carried `X-Dropfans-Account`. Agency endpoints always act as the agency.
401	`{"error":"Unauthorized","code":"unauthorized"}`	Missing or invalid API key.
403	`{"error":"This endpoint needs a verified agency's own API key.","code":"agency_key_required"}`	The key is not a verified agency’s own key — a creator’s key, or a key an agency minted for one of its creators.

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/agency/creators" \
  -H "Authorization: Bearer $DROPFANS_API_KEY"

const res = await fetch(`https://www.dropfans.io/api/external/agency/creators`, {
  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/agency/creators",
    headers={"Authorization": f"Bearer {os.environ['DROPFANS_API_KEY']}"},
)
print(res.json())

← Previous

The creator’s payout balance

Create an AI persona

Questions? [email protected]