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
- Create the media asset with asset.create using
purpose: "story", and upload the file bytes using the returned upload instructions. - Call this endpoint with the
assetId(and an optionalcaption).
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: chat-v1.json
Request
Responses
- 200
- 400
- 401
- 403
- 405
- 500
The story was posted.
Bad request. Common causes:
- Missing or malformed
assetId - Asset not found, or not owned by the authenticated user
- Asset was not created with
purpose: "story" - Asset is still processing (retry shortly) or failed processing
- Asset would expire before the story's 24-hour lifetime ends (post within about 23 hours of creating the asset)
- Media is not a photo or video
captionexceeds 2,048 characters
Presented invalid authentication credentials.
Forbidden. An organization token was used (stories require a personal access
token), or the token lacks the chat:send_message/chat:write scope.
An unsupported method was requested.
An internal error occurred.