curl --request PATCH \
--url https://api.onlyx.ai/v1/fans/{fanId} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"customName": "Mike (birthday 14 May)",
"muted": false,
"notes": "Tips on Fridays."
}
'import requests
url = "https://api.onlyx.ai/v1/fans/{fanId}"
payload = {
"customName": "Mike (birthday 14 May)",
"muted": False,
"notes": "Tips on Fridays."
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.patch(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PATCH',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({customName: 'Mike (birthday 14 May)', muted: false, notes: 'Tips on Fridays.'})
};
fetch('https://api.onlyx.ai/v1/fans/{fanId}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"avatarUrl": null,
"conversationId": "cnv_3d9e7b1a5c2f4e8d6a0b",
"createdAt": "2026-03-02T18:21:07.000Z",
"creatorId": "cre_8f2c1a9b0d7e4c3f2a1b",
"customName": "Mike (birthday 14 May)",
"displayName": "Mike",
"id": "fan_6b2e8d4a1c9f3e7b5d0a",
"lastActiveAt": "2026-09-25T21:40:12.000Z",
"lastPurchaseAt": "2026-09-24T22:03:55.000Z",
"lists": [
{
"id": "lst_9c1d2e3f4a5b6c7d8e9f",
"name": "VIP"
}
],
"muted": false,
"notes": "Likes lingerie sets. Tips on Fridays.",
"paidMessagesCents": 36500,
"renewOn": true,
"salesOptOut": false,
"subscribed": true,
"subscribedAt": "2026-03-02T18:21:07.000Z",
"subscriptionExpiresAt": "2026-10-02T18:21:07.000Z",
"subscriptionPriceCents": 999,
"tipsCents": 12000,
"totalSpentCents": 48500,
"username": null
}Update a fan
Sets your team’s own fields on a fan: a customName, free-text notes, and the muted flag. Send only the fields you want to change; an empty string or null clears a text field. These fields live only in OnlyX: nothing is sent to the fan, and muting never mutes or blocks anyone on OnlyFans. Any other field (the AI’s own settings for a fan included) is refused with 400 VALIDATION_ERROR.
Scope: requires fans:write.
Rate limit: the general limit of 120 requests per 60 seconds per credential.
Idempotency: send an Idempotency-Key header to make retries safe: a replay within 24 hours returns the original response with Idempotent-Replayed: true.
curl --request PATCH \
--url https://api.onlyx.ai/v1/fans/{fanId} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"customName": "Mike (birthday 14 May)",
"muted": false,
"notes": "Tips on Fridays."
}
'import requests
url = "https://api.onlyx.ai/v1/fans/{fanId}"
payload = {
"customName": "Mike (birthday 14 May)",
"muted": False,
"notes": "Tips on Fridays."
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.patch(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PATCH',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({customName: 'Mike (birthday 14 May)', muted: false, notes: 'Tips on Fridays.'})
};
fetch('https://api.onlyx.ai/v1/fans/{fanId}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"avatarUrl": null,
"conversationId": "cnv_3d9e7b1a5c2f4e8d6a0b",
"createdAt": "2026-03-02T18:21:07.000Z",
"creatorId": "cre_8f2c1a9b0d7e4c3f2a1b",
"customName": "Mike (birthday 14 May)",
"displayName": "Mike",
"id": "fan_6b2e8d4a1c9f3e7b5d0a",
"lastActiveAt": "2026-09-25T21:40:12.000Z",
"lastPurchaseAt": "2026-09-24T22:03:55.000Z",
"lists": [
{
"id": "lst_9c1d2e3f4a5b6c7d8e9f",
"name": "VIP"
}
],
"muted": false,
"notes": "Likes lingerie sets. Tips on Fridays.",
"paidMessagesCents": 36500,
"renewOn": true,
"salesOptOut": false,
"subscribed": true,
"subscribedAt": "2026-03-02T18:21:07.000Z",
"subscriptionExpiresAt": "2026-10-02T18:21:07.000Z",
"subscriptionPriceCents": 999,
"tipsCents": 12000,
"totalSpentCents": 48500,
"username": null
}Authorizations
An API key (onx_sk_…) created in OnlyX under Settings → API & MCP, or an OAuth access token (onx_at_…) issued to a connected app. Send it as Authorization: Bearer <credential>. API keys may also be sent as X-API-Key: <key>.
Headers
Optional. A unique value (8 to 64 letters, digits, - or _; a UUID is ideal) that makes a retry safe: the same key with the same request within 24 hours returns the stored response, with Idempotent-Replayed: true, instead of doing the work twice. The same key with a different request is 409 IDEMPOTENCY_KEY_REUSED; while the first request still runs it is 409 IDEMPOTENCY_IN_PROGRESS. A malformed key is 400 VALIDATION_ERROR.
8 - 64^[A-Za-z0-9_-]{8,64}$Path Parameters
The fan id (fan_…), from GET /v1/fans.
40Body
Only your team's own fields. Anything else — including any AI setting — is refused.
A name your team recognizes, shown instead of the OnlyFans name in OnlyX. "" or null clears it.
160Your team's mute flag. It never mutes or blocks the fan on OnlyFans.
Free-text notes for your team (up to 4,000 characters). "" or null clears them.
4000Response
The updated fan.
The fan's OnlyFans avatar, when known.
The conversation with this fan, or null if there is none yet.
When OnlyX first saw this fan.
The creator this fan subscribes (or subscribed) to.
The name your team gave this fan in OnlyX. Only your team sees it.
The fan's OnlyFans display name.
The fan id (fan_…). A fan belongs to one creator.
The fan's last activity OnlyX saw (a message or a purchase).
The fan's last purchase.
The creator's fan lists this fan is on.
Show child attributes
Show child attributes
Your team's mute flag in OnlyX. It never mutes or blocks the fan on OnlyFans.
Your team's notes on this fan.
Paid-message purchases, in cents.
Whether auto-renew is on. null when OnlyFans has not said.
true when the fan asked not to be sold to. Paid messages to this fan are refused with 409 SALES_OPTED_OUT, and the AI does not sell to them.
true while the subscription is active.
When the current (or last) subscription started.
When the current subscription ends or ended.
What the fan pays per period, in cents. 0 on a free page.
Tips, in cents.
Everything the fan has spent on this creator, in cents.
The fan's OnlyFans username, when known.