Fanvue API Documentation

Every endpoint on the previous, unversioned Fanvue API follows the conventions below. You call these paths when you maintain an integration built before /v1, or when you need an endpoint that has no /v1 form; new work belongs on the current version. 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. Paths on this version carry no prefix:

https://api.fanvue.com

A chat list is GET https://api.fanvue.com/chats, called exactly as written. The current version adds the /v1 prefix and answers on https://api.fanvue.com/v1/chats. The OpenAPI 3.1 document for this version is served at /openapi.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.

Some endpoints live only on this version. App Store endpoints (/apps/*) have no /v1 form, and neither do the self-scoped /account-health and /account-health/flagged-media. Call those on the unversioned paths even from a /v1 integration.

Pagination

List endpoints on this version use one of two styles. Both wrap their items in a top-level data array.

Send the page-size parameter the endpoint declares. The API ignores the other name and returns the default page size. Page-based lists take size. Lists that page by cursor take limit, except the insights lists, /agencies/insights/demographics and both tracking-link impressions lists, which take size.

Page-based
Cursor-based

Most lists on this version page with a 1-based page number and a size, and return a pagination object.

Query parameter	Type	Notes
`page`	number	Page number, starts at 1. Default 1.
`size`	number	Items per page. Range 1 to 50. Default 15.

The envelope is data plus pagination with page, size and hasMore. Increment page while hasMore is true. A page above 25 costs more than one rate-limit point; see Concurrency and deep pages.

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

{
  "data": [
    { "isRead": false, "unreadMessagesCount": 3 },
    { "isRead": true, "unreadMessagesCount": 0 }
  ],
  "pagination": {
    "page": 1,
    "size": 2,
    "hasMore": true
  }
}

/checkout-links, /collections, /media-links, /creators/{creatorUserUuid}/checkout-links and /creators/{creatorUserUuid}/vault/folders accept page and size even though their reference pages do not list them.

High-volume and append-only lists page with an opaque cursor and return a nextCursor. nextCursor is null on the last page.

Query parameter	Type	Notes
`cursor`	string	Opaque. Omit on the first request. Pass the previous response’s `nextCursor` to get the next page.
`limit` or `size`	number	Items per page. The range and default vary by endpoint; see the table.

curl "https://api.fanvue.com/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.

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

The cursor-based lists on this version, generated from the spec on 2026-10-08:

Endpoint	Page-size parameter	Envelope
`GET /agencies/insights/demographics`	`size` (1 to 50, default 15)	`{ data, nextCursor, total }`
`GET /apps/{appUuid}/payments`	`limit` (1 to 100, no default)	`{ data, nextCursor }`
`GET /apps/{appUuid}/payments/me`	`limit` (1 to 100, no default)	`{ data, nextCursor }`
`GET /chats/{userUuid}/media`	`limit` (1 to 50, default 20)	`{ data, nextCursor }`
`GET /creators/{creatorUserUuid}/chats/{userUuid}/media`	`limit` (1 to 50, default 20)	`{ data, nextCursor }`
`GET /creators/{creatorUserUuid}/checkout-links/payments`	`limit` (1 to 100, no default)	`{ data, nextCursor }`
`GET /creators/{creatorUserUuid}/checkout-links/refund-requests`	`limit` (1 to 100, no default)	`{ data, nextCursor }`
`GET /creators/{creatorUserUuid}/checkout-links/subscriptions`	`limit` (1 to 100, no default)	`{ data, nextCursor }`
`GET /creators/{creatorUserUuid}/insights/earnings`	`size` (1 to 50, no default)	`{ data, nextCursor }`
`GET /creators/{creatorUserUuid}/insights/spending`	`size` (1 to 50, no default)	`{ data, nextCursor }`
`GET /creators/{creatorUserUuid}/insights/subscribers`	`size` (1 to 50, no default)	`{ data, nextCursor }`
`GET /creators/{creatorUserUuid}/notifications`	`limit` (1 to 100, no default)	`{ data, nextCursor }`
`GET /creators/{creatorUserUuid}/subscribers/online`	`limit` (1 to 50, default 50) and no `cursor`	`{ data, count }`
`GET /creators/{creatorUserUuid}/tracking-links`	`limit` (no range or default declared)	`{ data, nextCursor }`
`GET /creators/{creatorUserUuid}/tracking-links/{uuid}/impressions`	`size` (1 to 50, default 15)	`{ data, nextCursor, total }`
`GET /creators/{creatorUserUuid}/tracking-links/{uuid}/users`	`limit` (no range or default declared)	`{ data, nextCursor }`
`GET /experiences/{experienceUuid}/action-purchases`	`limit` (1 to 100, no default)	`{ data, nextCursor }`
`GET /insights/earnings`	`size` (1 to 50, no default)	`{ data, nextCursor }`
`GET /insights/spending`	`size` (1 to 50, no default)	`{ data, nextCursor }`
`GET /insights/subscribers`	`size` (1 to 50, no default)	`{ data, nextCursor }`
`GET /notifications`	`limit` (1 to 100, no default)	`{ data, nextCursor }`
`GET /tracking-links`	`limit` (no range or default declared)	`{ data, nextCursor }`
`GET /tracking-links/{uuid}/impressions`	`size` (1 to 50, default 15)	`{ data, nextCursor, total }`
`GET /tracking-links/{uuid}/users`	`limit` (no range or default declared)	`{ data, nextCursor }`

Every list on /v1 is cursor-based. Moving to v1 shows how to convert a paging loop.

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/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

Apps

Webhooks

Agency

Onboarding

Account health

Fanvue API conventions (previous version)

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