Skip to main content
Publish a feed post, save its ID, and read that same post until its media is ready. Choose a story when you want to share one image instead.

Before you start

Ask the user to authorize your app with posts:write to publish and posts:read to read the post. These scopes are the permissions your app needs. Select a linked account. Install the TypeScript SDK version 4. Create a client on your server:
Choose media already saved in the account’s Vault, or upload a new file. Use its Vault ID or completed upload reference in the request. See Media references for both formats.

Publish posts

Follow Create a post to build the request body. To publish a free post with media from the Vault, call client.access.posts.create(). Replace 789 with your media ID:
Save created.id before the next step. The response also includes text, rawText, media, mediaCount, postedAt, and isMediaReady. The post now exists, but its attachments may still be processing. Create a post and save its ID. Read that same post until its media is ready, then display it. If you do not know whether the request succeeded, check for the post before sending it again. Follow V3 error recovery. To wait for media, read the existing post instead of creating another one.

Read posts

Read the saved ID with client.access.posts.get(). This example reads the same post up to six times, five seconds apart:
When isMediaReady is true, follow Display media to show an attachment. For example, the console result can be { postId: 987654, text: "New set is available.", isMediaReady: true }. The returned text can include formatting. If isMediaReady is still false, keep the post ID and check again later. The six checks limit how long this example waits. Processing can take longer. A failed read does not delete the post. To find existing posts, read /v3/access/posts?limit=20&sortBy=publish_date&sortDirection=desc. Lists use { items, page }. Read posts from items. If page.hasMore is true, send page.nextCursor as the next request’s cursor. Keep the same filters. Use the API reference for media filters, sorting, and cursor formats.

Manage existing content

Check canEdit and canDelete in the response before showing edit or delete actions. Follow Create a post for updates and deletion. Updates accept the same fields as creation. Send the full post you want to keep. Fields you leave out can return to their defaults. To keep attachments, use numeric Vault IDs. A used upload reference cannot be used again. For scheduled posts, read /v3/access/queue/posts to check the schedule. A scheduled post can have ready media before it appears on the feed.

Publish image stories

Use stories:write and follow Post a story for the complete story workflow and result checks. Story creation accepts exactly one image: a Vault image ID or a finalized image upload reference. Edit the image before uploading it. Stories do not accept videos, GIFs, media URLs, canvas settings, questions, or image edits in the request. After publication, use earnings and analytics to measure performance. Use Realtime events for publication activity and the API reference for comments, viewers, statistics, and other content actions.