Publish a post
Publish text or submit a media post to your connected social accounts.
curl -X POST "https://example.com/api/v1/posts" \ -H "Content-Type: application/json" \ -d '{ "accountIds": [ "11111111-1111-4111-8111-111111111111" ], "posts": [ "Hello from the Posteady API!" ] }'{ "results": [ { "accountId": "11111111-1111-4111-8111-111111111111", "provider": "threads", "username": "your_brand", "success": true, "postIds": [ "18000000000000001" ] } ], "summary": { "succeeded": 1, "failed": 0 }}Publish text to Threads, X, or LinkedIn, or submit a media publishing job to TikTok, Instagram, YouTube or Facebook. Choose a request example for your target platform. All account IDs must belong to the API key's workspace.
Choose a publishing mode
- Text: use
accountIdsandposts. Multiple posts form a thread on Threads or X; LinkedIn accepts a single post. - Images: add
mediaIdsto a Threads, X, or LinkedIn text request. The images go on the first post: Threads takes 1–20 (2 or more as a carousel), X takes 1–4, and LinkedIn takes 1–20. Replies stay text. With several platforms, the smallest limit applies. To put images on replies in a Threads or X thread, sendmediaIdsByPostinstead, with one list per post. - Videos: Threads takes videos in
mediaIdsandmediaIdsByPost: MP4 or MOV, up to 5 minutes and 1 GiB, alone or mixed with images in a carousel. A LinkedIn post takes one MP4 or MOV video of up to 30 minutes and 500 MiB on its own. A request with a video cannot include X accounts. A Threads post that starts with a video and a LinkedIn post with a video are published in the background; check the returnedjobId. - TikTok: use
postsandvideotogether, with one account and one caption. - Instagram, YouTube and Facebook: use the matching platform object with exactly one account. Omit
postsand all other publishing-mode objects. - Media: upload and confirm files before using their
mediaId. Choose images or videos appropriate to the selected format.
Links in X posts
For X, Posteady automatically removes links from the first post (posts[0]), including http://, https://, www., and bare domains such as foo.com or foo.io/path with any path, query string, or fragment. Links in replies (posts[1] onward) remain, and other platforms in the same request receive the original text. To share a link on X, include it in a reply; links are not moved there automatically. To keep the links in the first post, set xOptions.keepFirstPostLink to true; if X recognizes a kept link, the post is charged as a post with a link. X character limits are checked after removal. An empty or whitespace-only first X post after removal rejects the entire request with VALIDATION_ERROR (HTTP 422), before any account publishes. See the X guide for input and published-text examples.
Credits for X
Publishing to X uses the organization's credits: 2 credits for each post and 20 credits for each post that contains a link. Each post in a thread counts separately, and links removed from the first post don't count. Posteady charges for every X account in the request before anything is published. If the organization doesn't have enough credits, the request fails with INSUFFICIENT_CREDITS (HTTP 402) and nothing is published. Credits for posts that aren't published are refunded.
Check the result
Text publishing returns per-account results. Check each success value, even when the response is HTTP 200. An accepted asynchronous job returns HTTP 202 and results[0].jobId. Here success: true means accepted; use GET /api/v1/publish-jobs/{id} to confirm publication. A Threads thread with more than one post publishes its first post during the request and the rest in the background, about 10 seconds per post. That account's result has the first post in postIds, status: processing, and a jobId, and the response is HTTP 202. An X thread whose replies carry images (mediaIdsByPost) works the same way. Other X threads are published during the request. When the first Threads post carries a video, nothing is published during the request: Threads processes the video in the background, so that account's result has empty postIds, status: processing, and a jobId, and the response is HTTP 202.
Retry a media request
Reuse the same UUID requestId and unchanged input to retrieve the existing job. A different payload with the same ID returns REQUEST_CONFLICT. Facebook returns HTTP 202 while a job is active and HTTP 200 for terminal replays, including failed, canceled and unknown results with success: false. Other media providers return HTTP 502 for unsuccessful terminal replays. Text requests do not provide this idempotency guarantee.
Authorization
apiKey In: header
Request body
application/json
TypeScript definitions
Use the request body type in TypeScript.
Publish text to Threads, X, or LinkedIn; include video for one public TikTok video or tiktokPhoto for one TikTok photo post; include instagram for one Instagram media post; include youtube for one YouTube video; or include facebook for one Facebook Page post. TikTok uses posts with video or tiktokPhoto. Instagram, YouTube, and Facebook are self-contained modes and cannot be combined with other write modes. A Threads, X, or LinkedIn text request can add mediaIds to attach library images to the first post (Threads and LinkedIn also take videos), or mediaIdsByPost to attach media to each post of a Threads or X thread. Text requests can add threadsOptions, xOptions, and linkedinOptions. Each applies to the accounts of that platform in accountIds, and the request fails if accountIds has none.
Publish text to Threads, X, or LinkedIn; include video for one public TikTok video or tiktokPhoto for one TikTok photo post; include instagram for one Instagram media post; include youtube for one YouTube video; or include facebook for one Facebook Page post. TikTok uses posts with video or tiktokPhoto. Instagram, YouTube, and Facebook are self-contained modes and cannot be combined with other write modes. A Threads, X, or LinkedIn text request can add mediaIds to attach library images to the first post (Threads and LinkedIn also take videos), or mediaIdsByPost to attach media to each post of a Threads or X thread. Text requests can add threadsOptions, xOptions, and linkedinOptions. Each applies to the accounts of that platform in accountIds, and the request fails if accountIds has none.
Response body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json