Sign in

v1

latestOpenAPI 3.0.02026-08-069339.5 KB

Post story

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

post/story.post

Request body

assetIdstring uuid required

ID of a processed asset created via asset.create with purpose: "story". The asset must be owned by the authenticated user.

captionstring

Optional caption displayed with the story.

Response

The story was posted.

itemIdstring uuid

ID of the created story item.

chatIdstring uuid

ID of the Roam's story chat the story was posted into.

expiresAtstring date-time

When the story expires (24 hours after posting).