Skip to content

Create Post API: Publish, Schedule and Save Drafts

The Create Post API accepts one request for immediate publishing, scheduled delivery or draft storage across selected social accounts. Use POST {{API_BASE_URL}}/v1/posts with shared content, platform targets and optional media. The field maps explain required values; worked requests and response examples show how to handle asynchronous completion, safe retries and partial failures.

Endpoint and publication modes

Send POST {{API_BASE_URL}}/v1/posts with x-access-key: YOUR_API_KEY and Content-Type: application/json. Set publishNow: true for immediate publication, use scheduledFor for a future datetime, or set saveAsDraft: true for draft storage. Draft mode cannot be combined with publishNow: true or scheduledFor. In this guide’s contract, a draft requires content or media plus at least one platform target, is stored without consuming credits. To update or publish it afterward, use PUT /v1/posts/:postId.

Top-level request body

Use the Top-level request fields table to check names, types and conditional requirements. content is the post’s text. publishNow is required when neither scheduledFor nor saveAsDraft: true is supplied. scheduledFor is an ISO 8601 datetime, and timezone uses an IANA identifier with "UTC" as the default. idempotencyKey is optional and protects retries of the same logical post. Validate the intended mode before choosing example payloads; do not combine incompatible draft and publication options.

Select targets in platforms

platforms is a required array with a minimum of one target in this narrative contract. Each entry identifies platform and accountId; obtain the latter from /v1/connect/integrations. Supported platform values are "twitter", "instagram", "youtube", "tiktok", "pinterest", "linkedin", "bluesky", "facebook", "threads" and "googlebusiness". An entry’s content replaces shared top-level text for that entry only. platformSpecificData holds options for its own destination, not other entries.

Attach shared media with mediaItems

mediaItems is optional. Each attachment needs a type of "image", "video" or "gif" and a publicly accessible url. altText is an optional accessibility description of 1–1,000 characters; this contract forwards it to Instagram and Facebook and ignores it on other platforms. thumbnail supplies an optional video thumbnail URL for Facebook and YouTube. Confirm the final public file URL before sending rather than relying on a URL that only works while signed in.

Worked request: publish now

The publish-now cURL example sends one shared caption and image to Twitter and Instagram. Replace the account identifiers and media URL while retaining the field names and nesting. After sending, read status and the per-platform results; accepting a request does not prove every target published.

Worked request: cross-post to multiple platforms

The cross-post example shares one video between Twitter and YouTube. The YouTube entry adds title and visibility through platformSpecificData. Keep those options within that entry so a platform-specific setting does not become a top-level request field.

Worked request: per-platform content override

The content-override example supplies shared text at the top level and a longer content value on the LinkedIn entry. Twitter uses the shared value because its entry has no override. This makes caption differences explicit while retaining a single request for the related posts.

Read completion and response states

If the publishing worker finishes within the request wait window, the response includes final platform results and available platformPostUrl values. If work is still running when the window ends, HTTP 202 returns the saved postId with status "publishing". Poll GET /v1/posts/{postId}, or list posts, for final URLs and errors. The Response states table separates pending work, scheduled delivery and completed outcomes; an accepted HTTP request is not proof of publication on every destination.

HTTP status and client action

Read HTTP status together with body status and per-platform outcomes. HTTP 200 represents an idempotent replay; HTTP 202 covers accepted posts, including pending, publishing, published, scheduled, partial or failed states. HTTP 400, 402, 403 and 503 identify validation, credit, permission and availability problems respectively. The Status codes table adds the next diagnostic action while retaining each original status meaning.

Retry safely with idempotencyKey

A slow publish request can outlast a client timeout, leaving the client uncertain whether the post was created. Give each logical post a unique idempotencyKey and keep that same value when retrying that post. A repeated key skips another publication and returns the original result with HTTP 200 instead of HTTP 202, without additional credits. Keys are scoped to the project and do not expire. Reusing a key for different content still retrieves the first attached post; generate a fresh key for a genuinely new post. Omitting this optional field removes that duplicate-publication protection.

Recover from partial failures

When some destinations publish and others fail, HTTP 202 can return status "partial" with individual platform results. Store each successful platformPostUrl and inspect error on failed entries. A failed destination does not consume credits. Correct the failed input—such as an inaccessible image URL—and retry the failed targets rather than duplicating destinations that already published. The partial response example shows why a top-level success flag cannot replace per-platform checks.

Top-level request fields
FieldTypeRequiredDescription
contentstringYesThe text body of your post
publishNowbooleanYes*Set to true to publish immediately
saveAsDraftbooleanNoSet to true to save without publishing or scheduling; cannot be combined with publishNow: true or scheduledFor
scheduledForstringNoISO 8601 datetime for scheduled posts
timezonestringNoIANA timezone (default: "UTC")
idempotencyKeystringNoUnique key to safely retry the request
  • publishNow is required when neither scheduledFor nor saveAsDraft: true is supplied. Request/response examples have not been executed.
platforms[] entry fields
FieldTypeRequiredDescription
platformstringYesOne of the supported platform values
accountIdstringYesIntegration ID from /v1/connect/integrations
contentstringNoPer-platform text override; replaces top-level content for this platform only
platformSpecificDataobjectNoPlatform-specific options

Exact captured field/status contract; example requests and responses are unexecuted. Draft account requiredness has a private cross-reference conflict.

mediaItems[] entry fields
FieldTypeRequiredDescription
typestringYes"image", "video", or "gif"
urlstringYesPublic URL to the media file
altTextstringNoImage accessibility description, 1–1,000 characters; forwarded to Instagram and Facebook only
thumbnailstringNoVideo thumbnail URL (Facebook and YouTube)

Captured request/response contract, with diagnostic actions added where shown. Not a runtime test result.

Status codes
CodeMeaningClient action
200Idempotent replay — the original post for this idempotencyKey is returnedTreat as the original result; do not create a new post
202Post accepted — pending, publishing, published, scheduled, partial, or failedRead status and per-platform results; poll GET /v1/posts/{postId} if publishing
400Validation error (bad request body)Fix the request fields and resend
402Not enough creditsStop publishing attempts until credit availability changes
403ForbiddenCheck access/permissions before retrying
503Publishing or scheduling unavailableRetry later with the same idempotencyKey

Captured request/response contract, with diagnostic actions added where shown. Not a runtime test result.

Response states
Response stateMeaningplatformPostUrl available?Client action
publishedWorker finished within the wait window; targets succeededUse each returned URL; do not invent a missing valueStore each platformPostUrl
publishing (202)Worker still processing when the wait window expiredMay not yet be available; poll for final resultsPoll GET /v1/posts/{postId} for final URLs and errors
scheduled (202)Post accepted for a future scheduledFor timeCheck results after scheduled processingRead the post later to confirm publication
partial (202)Some platforms succeeded, others failedUse the URLs returned for successful targetsInspect per-platform error values; retry failed targets
failed (202)Post accepted but publishing failedInspect returned errors; do not infer a published URLInspect per-platform errors and retry

Captured request/response contract, with diagnostic actions added where shown. Not a runtime test result.

Publish now — cURL (illustrative, unexecuted)
curl -X POST "{{API_BASE_URL}}/v1/posts" \
  -H "x-access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "A short example update.",
    "platforms": [
      { "platform": "twitter", "accountId": "abc123" },
      { "platform": "instagram", "accountId": "def456" }
    ],
    "mediaItems": [
      { "type": "image", "url": "https://example.com/image.png" }
    ],
    "publishNow": true
  }'
Cross-post to multiple platforms — cURL (illustrative, unexecuted)
curl -X POST "{{API_BASE_URL}}/v1/posts" \
  -H "x-access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "A short example update.",
    "platforms": [
      { "platform": "twitter", "accountId": "tw_123" },
      { "platform": "youtube", "accountId": "yt_456", "platformSpecificData": { "title": "Our Latest Video", "visibility": "public" } }
    ],
    "mediaItems": [
      { "type": "video", "url": "https://example.com/video.mp4" }
    ],
    "publishNow": true
  }'
Per-platform content override — cURL (illustrative, unexecuted)
curl -X POST "{{API_BASE_URL}}/v1/posts" \
  -H "x-access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "A short example update.",
    "platforms": [
      {
        "platform": "twitter",
        "accountId": "tw_123"
      },
      {
        "platform": "linkedin",
        "accountId": "li_789",
        "content": "A short example update."
      }
    ],
    "publishNow": true
  }'
Idempotent publish — cURL (illustrative, unexecuted)
curl -X POST "{{API_BASE_URL}}/v1/posts" \
  -H "x-access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "A short example update.",
    "platforms": [
      { "platform": "twitter", "accountId": "abc123" }
    ],
    "publishNow": true,
    "idempotencyKey": "launch-2026-08-29-tweet"
  }'
Published response example
{
	"success": true,
	"status": "published",
	"postId": "post_abc123",
	"platforms": [
		{
			"platform": "twitter",
			"success": true,
			"platformPostUrl": "https://twitter.com/you/status/123456"
		},
		{
			"platform": "instagram",
			"success": true,
			"platformPostUrl": "https://instagram.com/p/abc123"
		}
	]
}
Publishing response example
{
	"success": true,
	"status": "publishing",
	"postId": "post_abc123",
	"platforms": [
		{ "platform": "twitter", "success": true },
		{ "platform": "instagram", "success": true }
	]
}
Partial response example
{
	"success": true,
	"status": "partial",
	"postId": "post_abc123",
	"platforms": [
		{ "platform": "twitter", "success": true, "platformPostUrl": "..." },
		{
			"platform": "instagram",
			"success": false,
			"error": "Image URL is not publicly accessible"
		}
	]
}