> ## 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.

# Post and manage stories

> Post text, photo and video stories for a creator, list live and expired stories with likes and gifts, and delete a story through the Fanvue API.

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:

| Scope | Grants |
| - | - |
| `write:post` | Post and delete stories |
| `read:post` | List and read stories |
| `write:creator` | In addition, post and delete on the creator-scoped routes under `/creators/{creatorUserUuid}/stories` |
| `read:creator` | In addition, list and read on the creator-scoped routes |

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](https://api.fanvue.com/docs/mcp-server.md) 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/`.

| Action | Own account | Creator you manage |
| - | - | - |
| Post a story | `POST /stories` | `POST /creators/{creatorUserUuid}/stories` |
| List stories | `GET /stories` | `GET /creators/{creatorUserUuid}/stories` |
| Read a story | `GET /stories/{uuid}` | `GET /creators/{creatorUserUuid}/stories/{uuid}` |
| Delete a story | `DELETE /stories/{uuid}` | `DELETE /creators/{creatorUserUuid}/stories/{uuid}` |

## 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.

```bash theme={null}
curl -X POST https://api.fanvue.com/stories \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "X-Fanvue-API-Version: 2025-06-26" \
  -H "Content-Type: application/json" \
  -d '{ "audience": "subscribers", "text": "New set drops tonight at 8pm" }'
```

The `201` response carries the UUID of the story and the time it expires:

```json theme={null}
{
  "uuid": "e5d4c3b2-a1f0-4e9d-8c7b-6a5f4e3d2c1b",
  "expiresAt": "2026-11-17T10:30:00.000Z"
}
```

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](https://api.fanvue.com/docs/tutorials/uploading-media.md).
2. Poll `GET /media/{uuid}` until `status` is `ready`. See [Poll until ready](https://api.fanvue.com/docs/tutorials/uploading-media.md#step-5-poll-until-ready).
3. Post the story with the `mediaUuid`.

```bash theme={null}
curl -X POST https://api.fanvue.com/stories \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "X-Fanvue-API-Version: 2025-06-26" \
  -H "Content-Type: application/json" \
  -d '{ "audience": "followers-and-subscribers", "mediaUuid": "3c9e2a71-5b4d-4f0e-8a6c-1d2e3f4a5b6c" }'
```

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`:

```json theme={null}
{ "message": "You can have at most 100 live stories" }
```

| Status | `message` | Fix |
| - | - | - |
| `403` | `Stories are not enabled for this creator` | Only creators who have stories enabled can post |
| `400` | `A story is either a photo or video, or text, not both` | Send `text` or `mediaUuid` |
| `400` | `A story needs a photo, a video or text` | Send `text` or `mediaUuid` |
| `400` | `Story text cannot be empty` | Send text with at least one character that is not white space |
| `400` | `Story text can be at most 250 characters` | Shorten the text |
| `400` | `This story text contains prohibited language` | Change the text |
| `400` | `You can have at most 100 live stories` | Delete a live story, or wait until one expires |
| `400` | `A story can only be a photo or a video` | Send the `mediaUuid` of a photo or a video |
| `400` | `This media is still processing` | Poll `GET /media/{uuid}` until `status` is `ready`, then post again |
| `400` | `This media is no longer available` | The media was deleted. Upload it again |
| `400` | `A story video can be at most 60 seconds long` | Trim the video to 60 seconds or less, then upload it again |
| `403` | `A post can only contain media you own` | Send media from the media of the creator who posts the story |

## 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`.

```bash theme={null}
curl "https://api.fanvue.com/stories?status=live&size=20" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "X-Fanvue-API-Version: 2025-06-26"
```

The response is one page:

```json theme={null}
{
  "data": [
    {
      "uuid": "7b2f4c1e-9d3a-4e8b-a6f5-2c1d0e9b8a7f",
      "text": null,
      "mediaUuid": "3c9e2a71-5b4d-4f0e-8a6c-1d2e3f4a5b6c",
      "audience": "followers-and-subscribers",
      "publishedAt": "2026-11-16T10:30:00.000Z",
      "expiresAt": "2026-11-17T10:30:00.000Z",
      "status": "live",
      "likesCount": 12,
      "tips": { "count": 2, "totalGross": 1000, "totalNet": 800 }
    }
  ],
  "nextCursor": null,
  "total": null
}
```

| Field | Type | Description |
| - | - | - |
| `uuid` | string | UUID of the story |
| `text` | string \| null | Text of a text story. `null` on a photo or video story |
| `mediaUuid` | string \| null | UUID of the photo or video. `null` on a text story |
| `audience` | string | `subscribers` or `followers-and-subscribers` |
| `publishedAt` | string | When the story was posted, ISO 8601 |
| `expiresAt` | string | When the story expires, ISO 8601 |
| `status` | string | `live` until `expiresAt`, then `expired`. Fans see live stories only |
| `likesCount` | number | Number of likes on the story |
| `tips` | object | Gifts sent on the story: `count`, `totalGross` and `totalNet` in cents. `totalNet` is after platform fees |

### 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.

```bash theme={null}
curl -X DELETE https://api.fanvue.com/stories/7b2f4c1e-9d3a-4e8b-a6f5-2c1d0e9b8a7f \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "X-Fanvue-API-Version: 2025-06-26"
```

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](https://api.fanvue.com/docs/creator/payments.md).
* The legacy `tip.new` carries `context: "post"` and the story UUID in `postUuid`. See [Tip received webhook](https://api.fanvue.com/docs/webhooks/tip-received.md).

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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.