Fanvue API Documentation

Every endpoint on /v1, the current URL version of the Fanvue API, follows the conventions below, and /v1 is the version to build new work on. Every request needs an access token and the version header, and Build your first app gets you a first authenticated call if you haven’t made one. The API speaks JSON over HTTPS. Every /v1 path carries the prefix:

https://api.fanvue.com/v1

A chat list is GET https://api.fanvue.com/v1/chats. The previous version drops the prefix and answers on https://api.fanvue.com/chats. The idempotency and agency scoping sections are shared with the previous version, so their paths omit the prefix; add /v1 when you call them. The OpenAPI 3.1 document for /v1 is served at /openapi-v1.json for client generators and request tools.

Authentication

Every endpoint requires a Bearer access token obtained through the OAuth 2.0 flow. Send it on every request.

Authorization: Bearer <access_token>

A missing or expired token returns 401. A token that lacks the scope an endpoint needs returns 403 with { "error": "Insufficient scopes" }. The authentication overview explains how your app obtains a token, and Scopes lists what each scope unlocks.

API versioning

Always send the X-Fanvue-API-Version header. The current version is 2025-06-26.

X-Fanvue-API-Version: 2025-06-26

The header is a date string that pins the response contract. A request without the header is served as 2025-06-26. A value the API does not recognise returns 400 with { "error": "Unsupported API version", "message": "..." }. A sunset version returns 410 with a nextVersion field naming the version to move to. The URL prefix (/v1/ or none) is a separate axis that selects the current or previous resource shapes. See API versioning.

App Store endpoints (/apps/*) exist only on the unversioned paths, so call them without a prefix even from a /v1 integration. The self-scoped /account-health and /account-health/flagged-media are also unversioned only; their creator-scoped counterparts exist at /v1/creators/{creatorUserUuid}/account-health.

Pagination

Every /v1 list is cursor-based. You pass an opaque cursor and a page-size parameter, and the response returns a nextCursor for the following page. Every list wraps its items in a top-level data array.

Query parameter	Type	Notes
`cursor`	string	Opaque. Omit on the first request. Pass the previous response’s `nextCursor` to get the next page.
`size`	number	Items per page on most lists. Range 1 to 50, default 15. The insights earnings, spending and subscribers lists declare no default.
`limit`	number	Items per page on chat messages and chat media (1 to 50, default 20), and on notifications, checkout-link payments, subscriptions, refund-requests and action-purchases (1 to 100, no default).

Send the page-size parameter the endpoint declares. The API ignores the other name and returns the default page size. Dynamic list members take cursor only, with no page-size parameter, and /v1/creators/{creatorUserUuid}/subscribers/online takes limit (default 50) with no cursor and returns { data, count }.

The standard envelope is { data, nextCursor, total }. nextCursor is null on the last page. total is present on about half the lists and is null where a count is not computed, so treat it as a hint and never page against it. The two message endpoints return { data, dateFilter } and page by sentBefore and receivedBefore instead of a cursor.

curl "https://api.fanvue.com/v1/insights/earnings?size=2" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Fanvue-API-Version: 2025-06-26"

{
  "data": [
    {
      "date": "2025-05-29T14:02:10Z",
      "gross": 1999,
      "net": 1599,
      "total": 2199,
      "currency": "USD",
      "source": "subscription"
    },
    {
      "date": "2025-05-29T09:41:55Z",
      "gross": 500,
      "net": 400,
      "total": 550,
      "currency": "USD",
      "source": "tip"
    }
  ],
  "nextCursor": "eyJpZCI6IjEyMyJ9"
}

To walk the full set, repeat the request with cursor set to the previous nextCursor until nextCursor is null. Keep the page size constant for the whole walk: a cursor is valid for the page size it was issued with.

curl "https://api.fanvue.com/v1/insights/earnings?size=2&cursor=eyJpZCI6IjEyMyJ9" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Fanvue-API-Version: 2025-06-26"

No /v1 endpoint accepts page. Moving to v1 shows how to convert a paging loop.

Every v1 list endpoint, generated from the spec on 2026-10-08

Endpoint	Page-size parameter	Envelope
`GET /v1/agencies/chats`	`size` (1 to 50, default 15)	`{ data, nextCursor }`
`GET /v1/agencies/earnings`	`size` (1 to 50, default 15)	`{ data, nextCursor, total }`
`GET /v1/agencies/followers-history`	`size` (1 to 50, default 15)	`{ data, nextCursor, total }`
`GET /v1/agencies/insights/demographics`	`size` (1 to 50, default 15)	`{ data, nextCursor, total }`
`GET /v1/agencies/subscribers`	`size` (1 to 50, default 15)	`{ data, nextCursor }`
`GET /v1/agencies/subscribers-history`	`size` (1 to 50, default 15)	`{ data, nextCursor, total }`
`GET /v1/chats`	`size` (1 to 50, default 15)	`{ data, nextCursor, total }`
`GET /v1/chats/lists/custom`	`size` (1 to 50, default 15)	`{ data, nextCursor, total }`
`GET /v1/chats/lists/custom/{uuid}`	`size` (1 to 50, default 15)	`{ data, nextCursor, total }`
`GET /v1/chats/lists/dynamic/{uuid}/members`	`cursor` only	`{ data, nextCursor, unavailable }`
`GET /v1/chats/lists/smart/{uuid}`	`size` (1 to 50, default 15)	`{ data, nextCursor, total }`
`GET /v1/chats/mass-messages`	`size` (1 to 50, default 15)	`{ data, nextCursor }`
`GET /v1/chats/templates`	`size` (1 to 50, default 15)	`{ data, nextCursor, total }`
`GET /v1/chats/templates/folders`	`size` (1 to 50, default 15)	`{ data, nextCursor, total }`
`GET /v1/chats/{userUuid}/media`	`limit` (1 to 50, default 20)	`{ data, nextCursor }`
`GET /v1/chats/{userUuid}/messages`	`limit` (1 to 50, default 20) and no `cursor`	`{ data, dateFilter }`
`GET /v1/checkout-links`	`size` (1 to 50, default 15)	`{ data, nextCursor }`
`GET /v1/collections`	`size` (1 to 50, default 15)	`{ data, nextCursor, total }`
`GET /v1/creators`	`size` (1 to 50, default 15)	`{ data, nextCursor, total }`
`GET /v1/creators/{creatorUserUuid}/account-health/flagged-media`	`size` (1 to 50, default 15)	`{ data, nextCursor, total }`
`GET /v1/creators/{creatorUserUuid}/blocks`	`size` (1 to 50, default 15)	`{ data, nextCursor, total }`
`GET /v1/creators/{creatorUserUuid}/chats`	`size` (1 to 50, default 15)	`{ data, nextCursor, total }`
`GET /v1/creators/{creatorUserUuid}/chats/lists/custom`	`size` (1 to 50, default 15)	`{ data, nextCursor, total }`
`GET /v1/creators/{creatorUserUuid}/chats/lists/custom/{uuid}`	`size` (1 to 50, default 15)	`{ data, nextCursor, total }`
`GET /v1/creators/{creatorUserUuid}/chats/lists/dynamic/{uuid}/members`	`cursor` only	`{ data, nextCursor, unavailable }`
`GET /v1/creators/{creatorUserUuid}/chats/lists/smart/{uuid}`	`size` (1 to 50, default 15)	`{ data, nextCursor, total }`
`GET /v1/creators/{creatorUserUuid}/chats/mass-messages`	`size` (1 to 50, default 15)	`{ data, nextCursor }`
`GET /v1/creators/{creatorUserUuid}/chats/templates`	`size` (1 to 50, default 15)	`{ data, nextCursor, total }`
`GET /v1/creators/{creatorUserUuid}/chats/templates/folders`	`size` (1 to 50, default 15)	`{ data, nextCursor, total }`
`GET /v1/creators/{creatorUserUuid}/chats/{userUuid}/media`	`limit` (1 to 50, default 20)	`{ data, nextCursor }`
`GET /v1/creators/{creatorUserUuid}/chats/{userUuid}/messages`	`limit` (1 to 50, default 20) and no `cursor`	`{ data, dateFilter }`
`GET /v1/creators/{creatorUserUuid}/checkout-links`	`size` (1 to 50, default 15)	`{ data, nextCursor }`
`GET /v1/creators/{creatorUserUuid}/checkout-links/payments`	`limit` (1 to 100, no default)	`{ data, nextCursor }`
`GET /v1/creators/{creatorUserUuid}/checkout-links/refund-requests`	`limit` (1 to 100, no default)	`{ data, nextCursor }`
`GET /v1/creators/{creatorUserUuid}/checkout-links/subscriptions`	`limit` (1 to 100, no default)	`{ data, nextCursor }`
`GET /v1/creators/{creatorUserUuid}/followers`	`size` (1 to 50, default 15)	`{ data, nextCursor }`
`GET /v1/creators/{creatorUserUuid}/insights/earnings`	`size` (1 to 50, no default)	`{ data, nextCursor }`
`GET /v1/creators/{creatorUserUuid}/insights/spending`	`size` (1 to 50, no default)	`{ data, nextCursor }`
`GET /v1/creators/{creatorUserUuid}/insights/subscribers`	`size` (1 to 50, no default)	`{ data, nextCursor }`
`GET /v1/creators/{creatorUserUuid}/insights/top-spenders`	`size` (1 to 50, default 15)	`{ data, nextCursor, total }`
`GET /v1/creators/{creatorUserUuid}/media`	`size` (1 to 50, default 15)	`{ data, nextCursor }`
`GET /v1/creators/{creatorUserUuid}/notifications`	`limit` (1 to 100, no default)	`{ data, nextCursor }`
`GET /v1/creators/{creatorUserUuid}/posts`	`size` (1 to 50, default 15)	`{ data, nextCursor, total }`
`GET /v1/creators/{creatorUserUuid}/posts/{uuid}/comments`	`size` (1 to 50, default 15)	`{ data, nextCursor }`
`GET /v1/creators/{creatorUserUuid}/posts/{uuid}/likes`	`size` (1 to 50, default 15)	`{ data, nextCursor }`
`GET /v1/creators/{creatorUserUuid}/posts/{uuid}/tips`	`size` (1 to 50, default 15)	`{ data, nextCursor }`
`GET /v1/creators/{creatorUserUuid}/subscribers`	`size` (1 to 50, default 15)	`{ data, nextCursor }`
`GET /v1/creators/{creatorUserUuid}/subscribers/online`	`limit` (1 to 50, default 50) and no `cursor`	`{ data, count }`
`GET /v1/creators/{creatorUserUuid}/tracking-links`	`limit` (no range or default declared)	`{ data, nextCursor }`
`GET /v1/creators/{creatorUserUuid}/tracking-links/{uuid}/impressions`	`size` (1 to 50, default 15)	`{ data, nextCursor, total }`
`GET /v1/creators/{creatorUserUuid}/tracking-links/{uuid}/users`	`limit` (no range or default declared)	`{ data, nextCursor }`
`GET /v1/creators/{creatorUserUuid}/vault/folders`	`size` (1 to 50, default 15)	`{ data, nextCursor }`
`GET /v1/creators/{creatorUserUuid}/vault/folders/{folderName}/media`	`size` (1 to 50, default 15)	`{ data, nextCursor, total }`
`GET /v1/experiences/{experienceUuid}/action-purchases`	`limit` (1 to 100, no default)	`{ data, nextCursor }`
`GET /v1/followers`	`size` (1 to 50, default 15)	`{ data, nextCursor }`
`GET /v1/insights/earnings`	`size` (1 to 50, no default)	`{ data, nextCursor }`
`GET /v1/insights/spending`	`size` (1 to 50, no default)	`{ data, nextCursor }`
`GET /v1/insights/subscribers`	`size` (1 to 50, no default)	`{ data, nextCursor }`
`GET /v1/insights/top-spenders`	`size` (1 to 50, default 15)	`{ data, nextCursor, total }`
`GET /v1/media`	`size` (1 to 50, default 15)	`{ data, nextCursor }`
`GET /v1/media-links`	`size` (1 to 50, default 15)	`{ data, nextCursor, total }`
`GET /v1/notifications`	`limit` (1 to 100, no default)	`{ data, nextCursor }`
`GET /v1/posts`	`size` (1 to 50, default 15)	`{ data, nextCursor, total }`
`GET /v1/posts/{uuid}/comments`	`size` (1 to 50, default 15)	`{ data, nextCursor }`
`GET /v1/posts/{uuid}/likes`	`size` (1 to 50, default 15)	`{ data, nextCursor }`
`GET /v1/posts/{uuid}/tips`	`size` (1 to 50, default 15)	`{ data, nextCursor }`
`GET /v1/subscribers`	`size` (1 to 50, default 15)	`{ data, nextCursor }`
`GET /v1/tracking-links`	`limit` (no range or default declared)	`{ data, nextCursor }`
`GET /v1/tracking-links/{uuid}/impressions`	`size` (1 to 50, default 15)	`{ data, nextCursor, total }`
`GET /v1/tracking-links/{uuid}/users`	`limit` (no range or default declared)	`{ data, nextCursor }`
`GET /v1/vault/folders`	`size` (1 to 50, default 15)	`{ data, nextCursor }`
`GET /v1/vault/folders/{folderName}/media`	`size` (1 to 50, default 15)	`{ data, nextCursor, total }`

Error responses

Errors use HTTP status codes with a JSON body. There is no single error envelope. The body shape depends on the status and the route family.

Status	Body	Meaning
`400`	`{ "errors": [...] }` or `{ "error", "message" }`	Request validation failed, or the version header is not recognised
`401`, `403`	`{ "error" }` or `{ "message" }`	Token missing or expired, a scope missing, or the resource belongs to another app or creator
`404`, `409`	`{ "message" }` or `{ "error", "message", "impact" }`	A referenced resource does not exist, a conflict such as a reused `Idempotency-Key`, or an experience change that needs a paid-impact acknowledgement
`429`	`{ "error" }` with `Retry-After`	Rate limit or concurrency limit reached
`502`, `503`	`{ "error" }` or `{ "message" }`	Upstream or database unavailable. A database-timeout `503` carries `Retry-After`; wait for it. `502` does not; retry with capped backoff

Error responses lists every body shape the API emits and what to do with each. Batch endpoints return 200 even when some items fail. A failed key carries a PerKeyError with error set to forbidden, not_found or internal, so a batch keeps its partial results instead of failing the whole request.

Rate limit headers

Each user your app acts for has a budget of 200 requests per 60 seconds, counted per OAuth client.

Header	Sent on	Value
`X-RateLimit-Limit`	Every rate-limited response	Points allowed in the current window for the limit that applied
`X-RateLimit-Remaining`	Every rate-limited response	Points left in the current window
`X-RateLimit-Reset`	Every rate-limited response	Unix timestamp in seconds when the window resets
`Retry-After`	`429`, and the database-timeout `503`	Seconds to wait before retrying

A second 429 body, { "error": "Too many concurrent requests" }, caps in-flight requests at 6 per caller. Rate limits has the per-endpoint limits, the concurrency cap and the retry pattern. Polling list endpoints for new messages or sales is the main cause of 429 responses. Subscribe to webhooks for new events instead, and use Efficient chat sync to catch up after downtime.

Idempotency

Three write endpoints are safe to retry, each in its own way.

Endpoint	Mechanism	Rule
`POST /chats/mass-messages` and `POST /creators/{creatorUserUuid}/chats/mass-messages`	Optional `Idempotency-Key` header, up to 255 characters	A mass send can outlive the request timeout with the campaign already committed, so a retry without a key can deliver the broadcast twice. Reuse the same key on a retry: once the first send finished, its result is replayed. A retry while the first send is still running returns `409`. A key reused for a different message returns `409`. Keys are scoped to your app and the sending creator and are kept for 24 hours.
`POST /experiences/{experienceUuid}/action-purchases`	Required `Idempotency-Key` header	The charge moves money, so the header is mandatory and a request without it returns `400`. Reuse the same key on a retry: a settled charge is replayed, a charge still running returns `409`, and a key reused for a different charge returns `409`. Keys are scoped to your app, the fan and the experience and are kept for 24 hours.
`POST /media/{uuid}/grant`	Body fields `source` and `sourceRef`	The same `source` and `sourceRef` pair always resolves to the same entitlement, so a retry returns the existing `entitlementId` with `status: "granted"` instead of creating a duplicate. `source` matches `^[a-z0-9_]+$` and is at most 100 characters; `sourceRef` is at most 255 characters. Requires `write:media`.

Pick a new key for every distinct send or charge. A UUID generated when the user confirms the action is a good key: it survives a retry of the same action and never collides with the next one.

Money figures and timestamps

Amounts are integers in minor units, USD cents unless a field says otherwise. Each money-bearing resource carries its own currency field. On earnings rows, gross is the creator’s price the earning is calculated from, net is the creator’s cut after Fanvue fees, and total is what the fan was charged including tax and the fan-side transaction fee. Whether a refunded or charged-back purchase is still counted is decided per field, not per endpoint. A reversal is written as its own row for the full original amount, never as an edit to the payment it reverses, and reversedTransactionOrderId pairs the two. Insights metrics holds the payment-source table and the field-by-field reversal reference. Timestamps are UTC in ISO 8601 format. Date-range query parameters such as startDate and endDate accept an ISO 8601 datetime with or without a timezone offset, and statistics aggregate by UTC day.

2025-05-29T14:02:10Z
2024-10-20T00:00:00+01:00

Some response fields use a date-only format (date) and others a full datetime (date-time). Each field documents its own format on the endpoint page. The underlying instant is UTC in both cases.

Agency creator scoping

Agency team members act on a managed creator through the creator-scoped twin of each endpoint under /creators/{creatorUserUuid}/.... A twin takes the same body, returns the same shape and needs the same scopes as the self-serve route, plus access to that creator. The creator-scoped routes are the high-volume path for agencies: each creator has its own rate-limit bucket on them. Agency-wide list endpoints under /agencies/* cover every creator the agency manages in one response. Every row carries a creatorUuid field naming the creator it belongs to, so you can group rows without a second lookup. Pass creatorUuids, a comma-separated list of up to 50 creator UUIDs, to narrow the response. A creatorUuids value that does not belong to the agency fails the whole request with 403. The /agencies/* endpoints need read:agency on top of the data scope, and read:agency is grantable by agency admins only.

curl "https://api.fanvue.com/v1/agencies/earnings?creatorUuids=<uuid1>,<uuid2>" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Fanvue-API-Version: 2025-06-26"

Overview

Popular endpoints

Account

Chats

Notifications

Posts

Creator tools

Insights and earnings

Experiences

Webhooks

Agency

Onboarding

Fanvue API conventions (v1)

Authentication

API versioning

Error responses

Rate limit headers

Idempotency

Money figures and timestamps

Agency creator scoping

​Authentication

​API versioning

​Pagination

​Error responses

​Rate limit headers

​Idempotency

​Money figures and timestamps

​Agency creator scoping

Authentication

API versioning

Pagination

Error responses

Rate limit headers

Idempotency

Money figures and timestamps

Agency creator scoping