status is live until expiresAt, then expired.
Posting is available to creators who have stories enabled. For any other creator, a post request returns 403 with { "message": "Stories are not enabled for this creator" }. Listing, reading and deleting work for every creator.
You need an access token with these scopes:
On the creator-scoped routes, an agency team member also needs the permission for the action on that creator:
post:write to post, post:read to list and read, post:delete to delete. The MCP server exposes the same routes as tools.
Pick the route
The routes under/stories act on the creator the access token belongs to. An agency calls the creator-scoped twin, with the UUID of the managed creator in {creatorUserUuid}. The v1 API has the same routes under /v1/.
Post a text story
Sendaudience and text. audience is subscribers or followers-and-subscribers. Fanvue trims the text, and the trimmed text must be 1 to 250 characters long.
201 response carries the UUID of the story and the time it expires:
400.
Post a photo or video story
A photo or video story takes themediaUuid of a creator’s upload that has finished processing. Send text or mediaUuid, not both.
- Upload the file to the creator’s media. See Upload media in parts.
- Poll
GET /media/{uuid}untilstatusisready. See Poll until ready. - Post the story with the
mediaUuid.
GET /stories stops listing the story.
Handle a refused story
Fanvue refuses a story that breaks a rule, and the body names the rule inmessage:
List stories
GET /stories returns the creator’s stories newest first, live and expired together. A deleted story is not listed. To get only one kind, pass status=live or status=expired.
Page through the list
size is 1 to 50, and the default is 15. To get the next page, send nextCursor as cursor, with the same status and size as the first page. nextCursor is null on the last page, and total is null on this list.
A cursor works only on the list it came from. A cursor sent with a different status or for a different creator returns 400 with { "message": "Invalid cursor" }.
Read or delete a story
GET /stories/{uuid} returns one story, with the same fields as a list item. DELETE /stories/{uuid} deletes the story and returns 204 with no body.
404 for the UUID of a post, a story of another creator, or a deleted story.
The post routes do not act on stories. DELETE /posts/{uuid} refuses a story with 400 and This action is not available for stories, as do the post routes that edit, pin or repost. GET /posts/{uuid} returns 404 for a story, and GET /posts does not list stories.
Match a gift to its story
A fan can send a gift on a live story. The gift arrives as a tip on a post, with the UUID of the story in the post field:creator.payment.succeededcarriessource: "tip",tip_context: "post"and the story UUID inpost_uuid. See Creator payment events.- The legacy
tip.newcarriescontext: "post"and the story UUID inpostUuid. See Tip received webhook.
GET /stories/{uuid} with that UUID. A 200 means the tip was a gift on a story. GET /posts/{uuid} returns 404 for a story.