Skip to main content
By the end of this page you’ll have a story live for a creator, a list of the creator’s stories with their likes and gifts, and a way to delete one. A story is a text, a photo or a video that stays live for 24 hours. Its 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

Send audience and text. audience is subscribers or followers-and-subscribers. Fanvue trims the text, and the trimmed text must be 1 to 250 characters long.
The 201 response carries the UUID of the story and the time it expires:
Fanvue checks story text for prohibited language before it posts the story. Text that fails the check returns 400.

Post a photo or video story

A photo or video story takes the mediaUuid of a creator’s upload that has finished processing. Send text or mediaUuid, not both.
  1. Upload the file to the creator’s media. See Upload media in parts.
  2. Poll GET /media/{uuid} until status is ready. See Poll until ready.
  3. Post the story with the mediaUuid.
A video can be at most 60 seconds long. The response has the same shape as for a text story. Fans see a photo or video story only while it is live and after its media clears moderation. If moderation removes the photo or video, GET /stories stops listing the story.

Handle a refused story

Fanvue refuses a story that breaks a rule, and the body names the rule in message:

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.
The response is one page:

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.
Both routes return 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.succeeded carries source: "tip", tip_context: "post" and the story UUID in post_uuid. See Creator payment events.
  • The legacy tip.new carries context: "post" and the story UUID in postUuid. See Tip received webhook.
To tell a story gift from a post tip, call 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.