> ## Documentation Index
> Fetch the complete documentation index at: https://api.fanvue.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Moving to v1
> The /v1 URL prefix: what changes between the legacy endpoints and their v1 equivalents, the endpoint-by-endpoint mapping, and why to migrate.
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](/docs/versions/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/` is the same path, the same request body, the same response fields and the same OAuth scopes as ``. Prefix the path and you are done.
The changes are concentrated in list endpoints.
### Cursor pagination replaces page and size
```bash Legacy theme={null}
curl "https://api.fanvue.com/posts?page=1&size=20" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "X-Fanvue-API-Version: 2025-06-26"
```
```bash v1 theme={null}
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:
```json Legacy theme={null}
{
"data": [],
"pagination": { "page": 1, "size": 20, "hasMore": true }
}
```
```json v1 theme={null}
{
"data": [],
"nextCursor": "eyJpZCI6IjEyMyJ9",
"total": 148
}
```
Not every v1 list carries `total`. Many return only `data` and `nextCursor`:
```json v1, no total theme={null}
{
"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`.
```bash theme={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/` exactly as you call `` 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
Change `` to `/v1/`. Keep the `X-Fanvue-API-Version` header exactly as it is.
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.
Read `nextCursor` instead. Only depend on `total` where you have checked it is not `null` for the endpoint you are calling.
They take `limit`, `sentBefore` and `receivedBefore` and return `{ data, dateFilter }`.
`/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`.