Publishing guide
Use this guide when your integration is ready to create posts through the UniPost API. It covers the shared publish path for hosted URLs, local media uploads, async publishing results, and the handoff to platform-specific options.
Choose input mode
UniPost accepts the same two media input patterns across supported platforms. Use media_urls when your asset is already hosted, or use media_ids when your app starts from local file bytes. Platform pages still define which media counts, formats, surfaces, and options are valid for each destination.
Use this when your image or video already has a public URL. Pass hosted assets in platform_posts[].media_urls.
Use this when your app has raw file bytes. Reserve media, PUT the bytes, poll until uploaded, then publish with platform_posts[].media_ids.
Local file flow
The diagram and table show the same path: reserve media, upload to storage, confirm the media is ready, publish, then read or receive the asynchronous result.
| Step | API call | Purpose |
|---|---|---|
| 1 | POST/v1/oauth/connect | Connect the platform account, then list accounts to keep its account_id. |
| 2 | POST/v1/media | Reserve a media row and receive a presigned upload_url. |
| 3 | PUT upload_url | Upload the raw image or video bytes directly to storage. |
| 4 | GET/v1/media/:media_id | Poll until status is uploaded or attached. |
| 5 | POST/v1/posts/validate | Optional preflight check for platform media rules, required metadata, and account state. |
| 6 | POST/v1/posts | Create the post with platform_posts[].media_ids and any required platform_options. |
| 7 | GET/v1/posts/:post_id | Get the async publishing status and result. You can also receive final status through webhooks; see Publishing Result. |
End-to-end local file example
These examples use Instagram feed publishing as the concrete surface. Change platform, account_id, and platform_options to match the platform-specific guide you are implementing.
Publishing result
POST/v1/posts accepts immediate publish requests asynchronously and returns once UniPost has queued the work.
Poll
GET/v1/posts/:post_id when your UI needs to show a live status.
Push
Subscribe to developer webhooks when your backend should receive final outcomes without polling.
The aggregate post status tells you whether the whole request is still pending, succeeded, partially succeeded, or failed. Inspect per-destination results when a cross-post includes multiple platform accounts.
Platform-specific payloads
The publish flow is shared, but payload details are still platform-specific. For example, Instagram uses platform_options.mediaType to select feed, reels, stories, or carousel publishing; YouTube uses upload metadata and privacy options; TikTok has video and photo-post constraints.