API reference

Update the creator’s public profile

Partial update of the creator's public profile — send only the fields that change; `null` clears a field. Returns the whole profile.

View as MarkdownUpdated Oct 26, 2026

PATCH/api/external/profileNew

Partial update of the creator's public profile — send only the fields that change; null clears a field. Returns the whole profile.

Same rules as the dashboard: every text field runs the prohibited-word filter, usernames must be free (the old one is kept in the account's history), and unknown fields are refused, not ignored. avatarUrl / bannerUrl take a public https image URL: Dropfans downloads, stores and moderates it, so a new image shows once approved (watch avatarModerationStatus). This changes what fans see on Dropfans — only call it when the creator asked for it.

Authentication

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

An agency's own key can call this for a creator it manages by adding X-Dropfans-Account: <account id> (needs canEditProfile). See Agencies.

Request body

Content type: application/json

Name	Type	Required	Description
`username`	string	Optional	New @handle: 3–30 of lowercase letters, digits, `_` and `-`. Pattern: `^[a-z0-9_-]{3,30}$`
`displayName`	string	Optional	Display name. Cannot be empty or null. Max length: 80
`bio`	string \| null	Optional	Profile bio. Max length: 2000
`profileVisible`	boolean	Optional	Show or hide the public profile.
`location`	string \| null	Optional	Free-text location. Max length: 120
`websiteUrl`	string \| null	Optional	Website link. Max length: 300
`twitterHandle`	string \| null	Optional	X / Twitter handle. Max length: 100
`instagramHandle`	string \| null	Optional	Instagram handle. Max length: 100
`tiktokHandle`	string \| null	Optional	TikTok handle. Max length: 100
`snapchatHandle`	string \| null	Optional	Snapchat handle. Max length: 100
`threadsHandle`	string \| null	Optional	Threads handle. Max length: 100
`youtubeHandle`	string \| null	Optional	YouTube handle. Max length: 100
`telegramHandle`	string \| null	Optional	Telegram handle. Max length: 100
`whatsappNumber`	string \| null	Optional	WhatsApp number. Max length: 40
`imessageHandle`	string \| null	Optional	iMessage handle. Max length: 100
`primaryContactPlatform`	string \| null	Optional	Which contact platform the profile highlights. Max length: 40
`avatarUrl`	string \| null	Optional	Public https URL of the new profile image (Dropfans fetches and moderates it). null removes the image. Format: uri
`bannerUrl`	string \| null	Optional	Public https URL of the new banner image. null removes it. Format: uri

New bio and avatar

{
  "bio": "Your favourite AI muse ✨",
  "avatarUrl": "https://cdn.example.com/luna/avatar.jpg"
}

Responses

200The updated profile.

Name	Type	Description
`id`	string	The account’s user id.
`username`	string \| null	Public @handle, without the @.
`displayName`	string \| null	Display name.
`bio`	string \| null	Profile bio.
`profileVisible`	boolean	Whether the public profile is visible.
`location`	string \| null	Free-text location.
`websiteUrl`	string \| null	Website link.
`twitterHandle`	string \| null	X / Twitter handle.
`instagramHandle`	string \| null	Instagram handle.
`tiktokHandle`	string \| null	TikTok handle.
`snapchatHandle`	string \| null	Snapchat handle.
`threadsHandle`	string \| null	Threads handle.
`youtubeHandle`	string \| null	YouTube handle.
`telegramHandle`	string \| null	Telegram handle.
`whatsappNumber`	string \| null	WhatsApp number.
`imessageHandle`	string \| null	iMessage handle.
`primaryContactPlatform`	string \| null	Which contact platform the profile highlights.
`avatarUrl`	string \| null	Profile image. Signed URL, valid 24 hours — do not store it. Format: uri
`bannerUrl`	string \| null	Banner image. Signed URL, valid 24 hours — do not store it. Format: uri
`avatarModerationStatus`	string \| null	PENDING, APPROVED, REJECTED or FLAGGED for the profile image (a new image shows once approved); null when there is none.
`bannerModerationStatus`	string \| null	PENDING, APPROVED, REJECTED or FLAGGED for the banner image; null when there is none.

Example response

{
  "id": "cmh4v2q8k0003xy9z7w6v5u4t",
  "username": "luna_ai",
  "displayName": "Luna",
  "bio": "Your favourite AI muse ✨",
  "profileVisible": true,
  "location": null,
  "websiteUrl": null,
  "twitterHandle": null,
  "instagramHandle": "luna.ai",
  "tiktokHandle": null,
  "snapchatHandle": null,
  "threadsHandle": null,
  "youtubeHandle": null,
  "telegramHandle": "luna_ai",
  "whatsappNumber": null,
  "imessageHandle": null,
  "primaryContactPlatform": "telegram",
  "avatarUrl": "https://cdn.dropfans.io/luna_ai/profile.jpg?token=…",
  "bannerUrl": null,
  "avatarModerationStatus": "APPROVED",
  "bannerModerationStatus": null
}

Errors

Status	Body	When
400	`{"error":"Unknown profile field(s): nickname","code":"unknown_field","field":"nickname"}`	A field that is not in the list above.
400	`{"error":"bio is at most 2000 characters.","code":"invalid_field","field":"bio"}`	Wrong type, too long, an empty displayName, or an image URL that is not https.
400	`{"error":"Field \"bio\" contains a prohibited word: \"…\"","code":"prohibited_word","field":"bio"}`	A text field tripped the word filter.
400	`{"error":"Username must be 3–30 characters: lowercase letters, digits, underscores, hyphens.","code":"invalid_username","field":"username"}`	Malformed or reserved username.
400	`{"error":"avatarUrl could not be fetched as an image.","code":"image_unreachable","field":"avatarUrl"}`	The image URL did not return an image. Earlier fields in the same call are already saved.
400	`{"error":"Body must be a JSON object"}`	The body is not a JSON object.
401	`{"error":"Unauthorized","code":"unauthorized"}`	Missing or invalid API key.
403	`{"error":"Profile editing is restricted for this account.","code":"profile_locked"}`	Profile editing is locked for this account.
409	`{"error":"Username is already taken.","code":"username_taken","field":"username"}`	Another account has that username.
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.
403	`{"error":"This key cannot act for that account.","code":"account_not_managed"}`	`X-Dropfans-Account` names an account this key cannot act for: not an agency’s own key, no ACCEPTED management, or the agency or account 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":"canEditProfile"}`	With `X-Dropfans-Account`: the agency lacks `canEditProfile` on that account.

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 -X PATCH "https://www.dropfans.io/api/external/profile" \
  -H "Authorization: Bearer $DROPFANS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "bio": "Your favourite AI muse ✨",
  "avatarUrl": "https://cdn.example.com/luna/avatar.jpg"
}'

const res = await fetch(`https://www.dropfans.io/api/external/profile`, {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${process.env.DROPFANS_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "bio": "Your favourite AI muse ✨",
    "avatarUrl": "https://cdn.example.com/luna/avatar.jpg"
  }),
});
console.log(await res.json());

import os
import requests

res = requests.patch(
    "https://www.dropfans.io/api/external/profile",
    headers={"Authorization": f"Bearer {os.environ['DROPFANS_API_KEY']}"},
    json={
        "bio": "Your favourite AI muse ✨",
        "avatarUrl": "https://cdn.example.com/luna/avatar.jpg",
    },
)
print(res.json())

Notes

Images are applied last: when avatarUrl or bannerUrl fails with image_unreachable, the other fields in the same request have already been saved.

← Previous

Read the creator’s public profile

Read the creator’s timezone

Questions? [email protected]