---
title: "Post story"
method: POST
path: "/story.post"
---

# Post story

`POST /story.post`

Posts a story to your Roam. Stories are short photo or video updates that appear
above your profile picture for your teammates, and expire 24 hours after posting.

## Posting Flow

1. Create the media asset with [asset.create](/docs/roam-api/create-asset) using
   `purpose: "story"`, and upload the file bytes using the returned upload instructions.
2. Call this endpoint with the `assetId` (and an optional `caption`).

The media must be a photo or a video (videos up to 2.5 minutes; media is optimized
to portrait 1080×1920). If the upload is still processing — typical for videos in
the first seconds after upload — this endpoint returns a 400 with a "still
processing" message; retry after a short delay.

The media must outlive the story's 24-hour lifetime, so post within about 23 hours
of creating the asset (story assets expire about 48 hours after creation); older
assets are rejected and must be recreated.

**Access:** Personal only. Stories are always posted as the authenticated user —
a story appears above *your* profile picture, and there is no bot persona surface
for stories — so organization tokens are rejected.

**Required scope:** `chat:send_message` or `chat:write` (the same permission that
gates sending a chat message)

---

**OpenAPI Spec:** [openapi.json](https://developer.ro.am/openapi.json)

## Request body

- object
  - `assetId` string, uuid, required — ID of a processed asset created via [asset.create](/docs/roam-api/create-asset) with `purpose: "story"`. The asset must be owned by the authenticated user.
  - `caption` string — Optional caption displayed with the story.

## Response `200`

The story was posted.

- object
  - `itemId` string, uuid — ID of the created story item.
  - `chatId` string, uuid — ID of the Roam's story chat the story was posted into.
  - `expiresAt` string, date-time — When the story expires (24 hours after posting).

## Other responses

- `400`
- `401`
- `403`
- `405`
- `500` — An internal error occured.

---

[API](https://skmtc.net/ro/apis/roam-hq-api.md) · [All operations](https://skmtc.net/ro/apis/roam-hq-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/ro/roam-hq-api/versions/5acda723f971/schema)