/v1 paths and walks lists with cursors instead of page numbers. For most endpoints that means adding the prefix and nothing else; the work is in list endpoints, where envelopes, cursors, page-size parameters and filters change. You need the list of unversioned paths your code calls today, so you can check each one against the endpoint mapping.
Two separate things are versioned on the Fanvue API, and they move independently.
/v1 is the current URL version. The unversioned paths (/chats, /posts and so on) are the previous version. They keep working and stay in the reference, where the version selector in the top bar moves between v1 and v0.
Why move
Previous-version lists page withpage and size, as described in API conventions (previous version). The database scans past every earlier row to reach page 40, so a deep crawl gets slower the further it goes, and a page above 25 costs more than one rate-limit point.
/v1 lists page with a cursor. Each page starts where the previous one ended, so page 400 costs the same as page 1, and every request costs one point.
What changes
For most endpoints,/v1/<path> takes the same path, request body, response fields and OAuth scopes as <path>, so you prefix the path and the call works. The changes concentrate in list endpoints.
Cursor pagination replaces page and size
nextCursor you were given as the cursor of the next request, and stop when nextCursor is null.
totalis not always there. About half of the/v1lists don’t carry the field, and some that do returnnullwhere the count is too expensive. The endpoint mapping shows the envelope per endpoint.hasMoreis gone, andnextCursor === nullis the end of the collection.- Keep the page size constant for the whole walk. A cursor is valid for the page size it was issued with. Changing it mid-walk moves the page boundary.
- A cursor is opaque. Don’t parse it, store it long term or build one yourself. Pass back exactly what you were given.
Page-size parameters and defaults differ
Most/v1 lists take size with a range of 1 to 50 and a default of 15. API conventions (v1) lists every /v1 list with its parameter and envelope; these are the exceptions:
The two message endpoints change more
GET /v1/chats/{userUuid}/messages and GET /v1/creators/{creatorUserUuid}/chats/{userUuid}/messages don’t use the 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 didn’t, for example search and filter on /v1/agencies/chats, and a date range and sort on /v1/creators/{creatorUserUuid}/subscribers. The additions are optional. The endpoint mapping lists the exact set per endpoint.
Endpoints with no v1
App Store endpoints (/apps/*) have no /v1 path and don’t 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, while the creator-scoped pair has a /v1 form listed in the endpoint mapping.
Endpoint mapping
Every endpoint absent from this table is unchanged apart from the prefix, so call/v1/<path> exactly as you call <path>.
/checkout-links, /collections, /media-links, /creators/{creatorUserUuid}/checkout-links and /creators/{creatorUserUuid}/vault/folders accept page and size on the previous version even though its reference never listed them, which is why their rows show no page to remove. On /v1 the cursor parameters are declared, so what you see is what the endpoint accepts.
Migration checklist
1
Prefix the paths
Change
<path> to /v1/<path>. Keep the X-Fanvue-API-Version header exactly as it is.2
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 the page size constant for the whole walk.3
Stop reading pagination and hasMore
Read
nextCursor instead. Depend on total only where you have checked it is not null for the endpoint you are calling.4
Check the page-size parameter and default
Send
size or limit as the endpoint declares. Set it explicitly on lists with no default.5
Handle the two message endpoints separately
They take
limit, sentBefore and receivedBefore and return { data, dateFilter }.6
Leave the endpoints with no v1 alone
Calls listed under Endpoints with no v1 stay on the unversioned path. The creator-scoped account-health endpoints move to
/v1.