Rename an AI persona
Changes an active persona's `username` (same rules as a creator's own username change; the old handle is kept in its history).
/api/external/agency/personas/{id}NewChanges an active persona's username (same rules as a creator's own username change; the old handle is kept in its history).
Everything else on the persona's profile goes through PATCH /api/external/profile with X-Dropfans-Account.
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.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The persona’s account id (id from GET /api/external/agency/creators). |
Request body
Content type: application/json
| Name | Type | Required | Description |
|---|---|---|---|
username | string | Required | The new username. Pattern: ^[a-z0-9_-]{3,30}$ |
{
"username": "luna_official"
}Responses
| Name | Type | Description |
|---|---|---|
id | string | The persona’s account id. |
username | string | The username now in effect. |
{
"id": "cmh4v2q8k0003xy9z7w6v5u4t",
"username": "luna_official"
}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. |
| 400 | {"error":"Username must be 3–30 characters: lowercase letters, digits, underscores, hyphens."} | Missing, malformed or reserved username. |
| 404 | {"error":"Persona not found."} | Not an active persona of this agency. |
| 409 | {"error":"Username is already taken.","code":"username_taken"} | Another account has that username. |
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/agency/personas/$ACCOUNT_ID" \
-H "Authorization: Bearer $DROPFANS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"username": "luna_official"
}'const accountId = '…'; // from an earlier response
const res = await fetch(`https://www.dropfans.io/api/external/agency/personas/${accountId}`, {
method: 'PATCH',
headers: {
Authorization: `Bearer ${process.env.DROPFANS_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"username": "luna_official"
}),
});
console.log(await res.json());import os
import requests
account_id = "…" # from an earlier response
res = requests.patch(
f"https://www.dropfans.io/api/external/agency/personas/{account_id}",
headers={"Authorization": f"Bearer {os.environ['DROPFANS_API_KEY']}"},
json={
"username": "luna_official",
},
)
print(res.json())Questions? [email protected]