Skip to main content
Publish a story with exactly one image and save its returned ID. If the image is already in the account’s Vault, use its numeric media ID and skip uploading. For a local file, complete the upload before creating the story.

Before you start

Ask the user to authorize your app with stories:write, which lets your app publish stories. Use the returned token and select a linked account the user shared. For new uploads, also request vault:write. The API base URL is https://api.ofauth.com.

Post an existing Vault image

Install the TypeScript SDK version 4. Replace 789 with the numeric ID of an image from Vault media:
The response contains the created story. Save its id. For example, these fields identify the story and its owner:
This excerpt omits the story’s other fields. Check the response’s media fields to see whether processing has finished. See the create-story reference.

Upload a new image and create the story

Follow Upload media with the image’s original filename and file type. That guide uploads every part and finalizes the upload. Its mediaItem value is either an existing numeric Vault ID or a completed upload reference. Pass that value to story creation:
Finalize a new upload even when it has only one part. The upload reference works for one successful story. To post another story, start a new upload or use a reusable Vault image ID.

Add release forms

The optional releaseForms object accepts numeric user IDs in users, partners, and guests arrays. Include releaseForms with mediaItems when needed.

Image requirements

Use a numeric Vault image ID, a numeric string, or a finalized upload: reference. Story creation accepts one image and rejects GIFs and videos. Crop, rotate, or arrange the image before uploading it. The request accepts mediaItems and optional releaseForms. It does not accept canvas dimensions, questions, or image editor settings.

Handle a failed request

Check the response’s recovery action. If the network fails after submission, check whether the story was created before repeating the request. A completed upload reference works once. You can reuse an existing Vault image ID. Next, upload media or consult the create-story reference.