Fanvue API Documentation

Two separate things are versioned on the Fanvue API, and they move independently.

	What it selects	How you set it
Date version	The response contract	`X-Fanvue-API-Version` header, currently `2025-06-26`. See Versioning Overview.
URL version	The shape of the endpoint itself	The `/v1` prefix on the path. This page.

/v1 is the current URL version. The unversioned paths you call today (/chats, /posts, and so on) and their explicit /v0 twins are the previous version. They keep working, and they are still in this reference: use the version selector in the top bar of the API Reference to move between v1 and v0.

The date version and the URL version are independent. Keep sending X-Fanvue-API-Version: 2025-06-26 when you move to /v1.

Why move

Legacy lists page with page and size. The database has to scan past every earlier row to reach page 40, so a deep crawl gets slower the further it goes and costs the platform work proportional to depth. /v1 lists page with a cursor. Each page starts exactly where the previous one ended, so page 400 costs the same as page 1.

Rate limits on the legacy endpoints will be reduced for performance reasons. The date and the new limits are still to be confirmed and will be announced here and to integrators before they take effect. Limits on /v1 are not changing.

What actually changes

Most of the surface does not change at all. For the large majority of endpoints, /v1/<path> is the same path, the same request body, the same response fields and the same OAuth scopes as <path>. Prefix the path and you are done. The changes are concentrated in list endpoints.

Cursor pagination replaces page and size

curl "https://api.fanvue.com/posts?page=1&size=20" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "X-Fanvue-API-Version: 2025-06-26"

curl "https://api.fanvue.com/v1/posts?size=20" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "X-Fanvue-API-Version: 2025-06-26"

The envelope changes with it:

{
  "data": [],
  "pagination": { "page": 1, "size": 20, "hasMore": true }
}

{
  "data": [],
  "nextCursor": "eyJpZCI6IjEyMyJ9",
  "total": 148
}

Not every v1 list carries total. Many return only data and nextCursor:

{
  "data": [],
  "nextCursor": "eyJpZCI6IjEyMyJ9"
}

To walk a collection, pass the nextCursor you were given as the cursor of the next request, and stop when nextCursor is null.

curl "https://api.fanvue.com/v1/posts?size=20&cursor=eyJpZCI6IjEyMyJ9" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "X-Fanvue-API-Version: 2025-06-26"

Three things to watch:

total is not always there. Roughly half of the v1 lists do not carry the field at all, and some of those that do return it as null where the count is too expensive to compute. The mapping table below shows which envelope each endpoint returns; read it rather than assuming. hasMore is gone; nextCursor === null is the end of the collection.
Keep size constant for the whole walk. A cursor is only valid for the page size it was issued with. Changing size mid-walk moves the page boundary.
A cursor is opaque. Do not parse it, store it long term, or build one yourself. Pass back exactly what you were given.

The two message endpoints change more

GET /v1/chats/{userUuid}/messages and GET /v1/creators/{creatorUserUuid}/chats/{userUuid}/messages do not use the standard cursor envelope. They take limit, sentBefore and receivedBefore in place of page, size, startDate and endDate, and answer with { data, dateFilter }.

Some lists gain filters

A few v1 lists accept filters their predecessor did not, for example search and filter on /v1/agencies/chats and a date range and sort on /v1/creators/{creatorUserUuid}/subscribers. These are additive. See the mapping below for the exact set per endpoint.

Endpoints with no v1

App Store endpoints (/apps/*) have no /v1 path, so they do not appear under v1 in the reference. Keep calling them on the unversioned path. Account health is split rather than absent. The self-scoped /account-health and /account-health/flagged-media are v0 only, but the creator-scoped pair does have a v1 form and is listed in the mapping below.

Endpoint mapping

Every endpoint not listed below is unchanged apart from the prefix: call /v1/<path> exactly as you call <path> today.

/checkout-links, /collections, /media-links, /creators/{creatorUserUuid}/checkout-links and /creators/{creatorUserUuid}/vault/folders accept page and size on the legacy version even though the legacy reference never listed them. On /v1 the cursor parameters are declared, so what you see is what the endpoint accepts.

Legacy	v1	Query parameters	Response envelope
`/agencies/chats`	`/v1/agencies/chats`	removes `page`, adds `cursor`, `filter`, `search`	`{ data, pagination }` to `{ data, nextCursor }`
`/agencies/earnings`	`/v1/agencies/earnings`	removes `page`, adds `cursor`	`{ data, pagination }` to `{ data, nextCursor, total }`
`/agencies/followers-history`	`/v1/agencies/followers-history`	removes `page`, adds `cursor`	`{ data, pagination }` to `{ data, nextCursor, total }`
`/agencies/subscribers`	`/v1/agencies/subscribers`	removes `page`, adds `cursor`	`{ data, pagination }` to `{ data, nextCursor }`
`/agencies/subscribers-history`	`/v1/agencies/subscribers-history`	removes `page`, adds `cursor`	`{ data, pagination }` to `{ data, nextCursor, total }`
`/chats`	`/v1/chats`	removes `page`, adds `cursor`	`{ data, pagination }` to `{ data, nextCursor, total }`
`/chats/lists/custom`	`/v1/chats/lists/custom`	removes `page`, adds `cursor`	`{ data, pagination }` to `{ data, nextCursor, total }`
`/chats/lists/custom/{uuid}`	`/v1/chats/lists/custom/{uuid}`	removes `page`, adds `cursor`	`{ data, pagination }` to `{ data, nextCursor, total }`
`/chats/lists/smart/{uuid}`	`/v1/chats/lists/smart/{uuid}`	removes `page`, adds `cursor`	`{ data, pagination }` to `{ data, nextCursor, total }`
`/chats/mass-messages`	`/v1/chats/mass-messages`	removes `page`, adds `cursor`	`{ data, pagination }` to `{ data, nextCursor }`
`/chats/templates`	`/v1/chats/templates`	removes `page`, adds `cursor`	`{ data, pagination }` to `{ data, nextCursor, total }`
`/chats/templates/folders`	`/v1/chats/templates/folders`	removes `page`, adds `cursor`	`{ data, pagination }` to `{ data, nextCursor, total }`
`/chats/{userUuid}/messages`	`/v1/chats/{userUuid}/messages`	removes `beforeMessageUuid`, `endDate`, `page`, `size`, `startDate`, adds `limit`, `receivedBefore`, `sentBefore`	`{ data, pagination }` to `{ data, dateFilter }`
`/checkout-links`	`/v1/checkout-links`	adds `cursor`, `size`	`{ data, pagination }` to `{ data, nextCursor }`
`/collections`	`/v1/collections`	adds `cursor`, `size`	`{ data, pagination }` to `{ data, nextCursor, total }`
`/creators`	`/v1/creators`	removes `page`, adds `cursor`	`{ data, pagination }` to `{ data, nextCursor, total }`
`/creators/{creatorUserUuid}/account-health/flagged-media`	`/v1/creators/{creatorUserUuid}/account-health/flagged-media`	removes `page`, adds `cursor`	`{ data, pagination }` to `{ data, nextCursor, total }`
`/creators/{creatorUserUuid}/blocks`	`/v1/creators/{creatorUserUuid}/blocks`	removes `page`, adds `cursor`	`{ data, pagination }` to `{ data, nextCursor, total }`
`/creators/{creatorUserUuid}/chats`	`/v1/creators/{creatorUserUuid}/chats`	removes `page`, adds `cursor`	`{ data, pagination }` to `{ data, nextCursor, total }`
`/creators/{creatorUserUuid}/chats/lists/custom`	`/v1/creators/{creatorUserUuid}/chats/lists/custom`	removes `page`, adds `cursor`, `search`	`{ data, pagination }` to `{ data, nextCursor, total }`
`/creators/{creatorUserUuid}/chats/lists/custom/{uuid}`	`/v1/creators/{creatorUserUuid}/chats/lists/custom/{uuid}`	removes `page`, adds `cursor`	`{ data, pagination }` to `{ data, nextCursor, total }`
`/creators/{creatorUserUuid}/chats/lists/smart/{uuid}`	`/v1/creators/{creatorUserUuid}/chats/lists/smart/{uuid}`	removes `page`, adds `cursor`	`{ data, pagination }` to `{ data, nextCursor, total }`
`/creators/{creatorUserUuid}/chats/mass-messages`	`/v1/creators/{creatorUserUuid}/chats/mass-messages`	removes `page`, adds `cursor`	`{ data, pagination }` to `{ data, nextCursor }`
New in v1	`/v1/creators/{creatorUserUuid}/chats/templates`	adds `cursor`, `folderName`, `size`	`{ data, nextCursor, total }`
New in v1	`/v1/creators/{creatorUserUuid}/chats/templates/folders`	adds `cursor`, `size`	`{ data, nextCursor, total }`
New in v1	`/v1/creators/{creatorUserUuid}/chats/templates/{templateUuid}`	no query change	`{ folderName, folderUuid, mediaPreviewUuid, mediaUuids, name, price, text, uuid }`
`/creators/{creatorUserUuid}/chats/{userUuid}/messages`	`/v1/creators/{creatorUserUuid}/chats/{userUuid}/messages`	removes `page`, `size`, adds `limit`, `receivedBefore`, `sentBefore`	`{ data, pagination }` to `{ data, dateFilter }`
`/creators/{creatorUserUuid}/checkout-links`	`/v1/creators/{creatorUserUuid}/checkout-links`	adds `cursor`, `size`	`{ data, pagination }` to `{ data, nextCursor }`
`/creators/{creatorUserUuid}/followers`	`/v1/creators/{creatorUserUuid}/followers`	removes `page`, adds `cursor`	`{ data, pagination }` to `{ data, nextCursor }`
`/creators/{creatorUserUuid}/insights/top-spenders`	`/v1/creators/{creatorUserUuid}/insights/top-spenders`	removes `page`, adds `cursor`	`{ data, pagination }` to `{ data, nextCursor, total }`
`/creators/{creatorUserUuid}/media`	`/v1/creators/{creatorUserUuid}/media`	removes `page`, adds `cursor`	`{ data, pagination }` to `{ data, nextCursor }`
`/creators/{creatorUserUuid}/posts`	`/v1/creators/{creatorUserUuid}/posts`	removes `page`, adds `cursor`	`{ data, pagination }` to `{ data, nextCursor, total }`
`/creators/{creatorUserUuid}/posts/{uuid}/comments`	`/v1/creators/{creatorUserUuid}/posts/{uuid}/comments`	removes `page`, adds `cursor`	`{ data, pagination }` to `{ data, nextCursor }`
`/creators/{creatorUserUuid}/posts/{uuid}/likes`	`/v1/creators/{creatorUserUuid}/posts/{uuid}/likes`	removes `page`, adds `cursor`	`{ data, pagination }` to `{ data, nextCursor }`
`/creators/{creatorUserUuid}/posts/{uuid}/tips`	`/v1/creators/{creatorUserUuid}/posts/{uuid}/tips`	removes `page`, adds `cursor`	`{ data, pagination }` to `{ data, nextCursor }`
`/creators/{creatorUserUuid}/subscribers`	`/v1/creators/{creatorUserUuid}/subscribers`	removes `page`, adds `endDate`, `sortDirection`, `sortField`, `startDate`	`{ data, pagination }` to `{ data, nextCursor }`
`/creators/{creatorUserUuid}/vault/folders`	`/v1/creators/{creatorUserUuid}/vault/folders`	adds `cursor`, `mediaName`, `size`	`{ data, pagination }` to `{ data, nextCursor }`
`/creators/{creatorUserUuid}/vault/folders/{folderName}/media`	`/v1/creators/{creatorUserUuid}/vault/folders/{folderName}/media`	removes `page`, adds `cursor`, `endDate`, `mediaType`, `name`, `order`, `sort`, `startDate`, `variants`	`{ data, pagination }` to `{ data, nextCursor, total }`
`/followers`	`/v1/followers`	removes `page`, adds `cursor`	`{ data, pagination }` to `{ data, nextCursor }`
`/insights/top-spenders`	`/v1/insights/top-spenders`	removes `page`, adds `cursor`	`{ data, pagination }` to `{ data, nextCursor, total }`
`/media`	`/v1/media`	removes `page`, adds `cursor`	`{ data, pagination }` to `{ data, nextCursor }`
`/media-links`	`/v1/media-links`	adds `cursor`, `size`	`{ data, pagination }` to `{ data, nextCursor, total }`
`/posts`	`/v1/posts`	removes `page`, adds `cursor`	`{ data, pagination }` to `{ data, nextCursor, total }`
`/posts/{uuid}/comments`	`/v1/posts/{uuid}/comments`	removes `page`, adds `cursor`	`{ data, pagination }` to `{ data, nextCursor }`
`/posts/{uuid}/likes`	`/v1/posts/{uuid}/likes`	removes `page`, adds `cursor`	`{ data, pagination }` to `{ data, nextCursor }`
`/posts/{uuid}/tips`	`/v1/posts/{uuid}/tips`	removes `page`, adds `cursor`	`{ data, pagination }` to `{ data, nextCursor }`
`/subscribers`	`/v1/subscribers`	removes `page`	`{ data, pagination }` to `{ data, nextCursor }`
`/vault/folders`	`/v1/vault/folders`	removes `page`, adds `cursor`	`{ data, pagination }` to `{ data, nextCursor }`
`/vault/folders/{folderName}/media`	`/v1/vault/folders/{folderName}/media`	removes `page`, adds `cursor`	`{ data, pagination }` to `{ data, nextCursor, total }`

Migration checklist

Prefix the paths

Change <path> to /v1/<path>. Keep the X-Fanvue-API-Version header exactly as it is.

Replace page loops with cursor loops

Stop incrementing page. Read nextCursor from each response, pass it as cursor on the next request, and stop when it is null. Hold size constant for the whole walk.

Stop reading pagination and hasMore

Read nextCursor instead. Only depend on total where you have checked it is not null for the endpoint you are calling.

Handle the two message endpoints separately

They take limit, sentBefore and receivedBefore and return { data, dateFilter }.

Check the endpoints with no v1

/apps/* stays on the unversioned path, as do the self-scoped /account-health and /account-health/flagged-media. The creator-scoped account-health endpoints do move to /v1.

Get Started

Core Concepts

Tutorials

Moving to v1

Why move

What actually changes

The two message endpoints change more

Some lists gain filters

Endpoints with no v1

Endpoint mapping

Migration checklist

​Why move

​What actually changes

​Cursor pagination replaces page and size

​The two message endpoints change more

​Some lists gain filters

​Endpoints with no v1

​Endpoint mapping

​Migration checklist

Why move

What actually changes

Cursor pagination replaces page and size

The two message endpoints change more

Some lists gain filters

Endpoints with no v1

Endpoint mapping

Migration checklist