Create post
Creates a UniPost post resource using the same payload shape as POST/v1/posts/validate. Immediate publish requests are accepted and queued asynchronously; background workers perform the actual platform delivery. Use scheduling or draft mode when you want creation without immediate dispatch.
Authorization
AuthorizationBearer <token>In header
Workspace API key.
Content-Typeapplication/jsonIn header
Request body format.
Idempotency-Key?stringIn header
Optional alternative to the body field. Max 64 chars, 24 hour replay window.
Request Body
caption?string
Shared caption sent to every target account. Required unless platform_posts is set.
account_ids?string[]
Target social account IDs when the same caption/media should fan out everywhere.
platform_posts?array
Recommended per-account request shape for multi-platform publishing.
media_urls?string[]
Public URLs for hosted media. Ignored when platform_posts overrides are used.
media_ids?string[]
Media library IDs returned by POST/v1/media. Use these for local files and larger videos after GET/v1/media/:media_id reports uploaded.
scheduled_at?string
ISO-8601 timestamp. If present, UniPost stores the post in scheduled state and the scheduler enqueues delivery later.
idempotency_key?string
Optional body-level key for scheduled posts. While a matching post is still scheduled, UniPost returns the existing scheduled post for the same payload and returns 409 for a different payload.
status?"draft"
Save without dispatching any platform jobs. Omit the field entirely for immediate publish. Drafts are published later via POST/v1/posts/:post_id/publish.
Valuesdraft
platform_posts[]
platform_posts[].account_idstring
Connected social account to publish to.
platform_posts[].caption?string
Account-specific caption override.
platform_posts[].media_urls?string[]
Account-specific hosted asset URLs.
platform_posts[].media_ids?string[]
Account-specific media library asset IDs. Pending uploads fail pre-publish validation with media_not_uploaded.
platform_posts[].thread_position?integer
1-indexed thread slot. Supported for X and Bluesky thread publishing.
platform_posts[].first_comment?string
Optional first reply/comment after publish. Supported on X, LinkedIn, and Instagram.
platform_posts[].platform_options?object
Platform-specific options such as Instagram media type or YouTube metadata.
Response Body
202
idstring
UniPost post ID.
execution_modestring
Immediate publish enqueues delivery jobs and returns before platform dispatch finishes.
Valuesasync
captionstring | null
Top-level shared caption when one exists.
statusstring
Initial lifecycle state for the accepted post. Immediate creates usually start as queued or publishing, then converge to a final aggregate state.
Valuesqueued | publishing | published | partial | failed | draft | scheduled | cancelled
queued_results_countinteger
How many per-account delivery results were queued for background processing.
active_job_countinteger
How many queue jobs are currently active for this post.
created_atstring
Creation timestamp.
scheduled_atstring | null
Scheduled publish timestamp when queued.
published_atstring | null
Final publish timestamp when at least one result was published.
resultsarray
Initial per-account result rows created at enqueue time.
results[].social_account_idstring
Destination account ID.
results[].platformstring
Normalized platform name.
Valuestwitter | linkedin | instagram | facebook | threads | youtube | tiktok | bluesky | pinterest
results[].statusstring
Initial per-account state. Rows move through in-flight values first, then settle on final result values.
Valuesqueued | publishing | processing | published | failed
results[].external_idstring | null
Platform-native post identifier when available after delivery completes.
results[].error_messagestring | null
Platform-specific failure reason when delivery eventually fails.
request_idstring
Request identifier for debugging and support.
201
idstring
UniPost post ID.
statusstring
Created resource state for non-immediate creates.
Valuesscheduled | draft
created_atstring
Creation timestamp.
scheduled_atstring | null
Scheduled publish time when the post was created as scheduled content.
request_idstring
Request identifier for debugging and support.
400
error.codestring
Machine-readable error code.
error.normalized_codestring
Lowercase compatibility alias for the error code.
error.messagestring
Human-readable error message.
error.issues?array
Structured pre-publish validation issues such as media_not_uploaded.
request_idstring
Request identifier for debugging and support.
401
error.codestring
Machine-readable error code.
error.normalized_codestring
Lowercase compatibility alias for the error code.
error.messagestring
Human-readable error message.
error.issues?array
Structured pre-publish validation issues such as media_not_uploaded.
request_idstring
Request identifier for debugging and support.
402
error.codestring
Machine-readable error code.
error.normalized_codestring
Lowercase compatibility alias for the error code.
error.messagestring
Human-readable error message.
error.issues?array
Structured pre-publish validation issues such as media_not_uploaded.
request_idstring
Request identifier for debugging and support.
422
error.codestring
Machine-readable error code.
error.normalized_codestring
Lowercase compatibility alias for the error code.
error.messagestring
Human-readable error message.
error.issues?array
Structured pre-publish validation issues such as media_not_uploaded.
request_idstring
Request identifier for debugging and support.
500
error.codestring
Machine-readable error code.
error.normalized_codestring
Lowercase compatibility alias for the error code.
error.messagestring
Human-readable error message.
error.issues?array
Structured pre-publish validation issues such as media_not_uploaded.
request_idstring
Request identifier for debugging and support.
Publishing Result
Poll Model: immediate publish returns 202 after UniPost accepts and queues delivery. Poll GET/v1/posts/:post_id to read the final publishing result.
Push Model: create a webhook subscription with POST/v1/webhooks to receive final publishing events from UniPost.