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.
| Field | Type | Required | Description |
|---|---|---|---|
| content | string | Yes | The text body of your post |
| publishNow | boolean | Yes* | Set to true to publish immediately |
| saveAsDraft | boolean | No | Set to true to save without publishing or scheduling; cannot be combined with publishNow: true or scheduledFor |
| scheduledFor | string | No | ISO 8601 datetime for scheduled posts |
| timezone | string | No | IANA timezone (default: "UTC") |
| idempotencyKey | string | No | Unique key to safely retry the request |
- publishNow is required when neither scheduledFor nor saveAsDraft: true is supplied. Request/response examples have not been executed.
| Field | Type | Required | Description |
|---|---|---|---|
| platform | string | Yes | One of the supported platform values |
| accountId | string | Yes | Integration ID from /v1/connect/integrations |
| content | string | No | Per-platform text override; replaces top-level content for this platform only |
| platformSpecificData | object | No | Platform-specific options |
Exact captured field/status contract; example requests and responses are unexecuted. Draft account requiredness has a private cross-reference conflict.
| Field | Type | Required | Description |
|---|---|---|---|
| type | string | Yes | "image", "video", or "gif" |
| url | string | Yes | Public URL to the media file |
| altText | string | No | Image accessibility description, 1–1,000 characters; forwarded to Instagram and Facebook only |
| thumbnail | string | No | Video thumbnail URL (Facebook and YouTube) |
Captured request/response contract, with diagnostic actions added where shown. Not a runtime test result.
| Code | Meaning | Client action |
|---|---|---|
| 200 | Idempotent replay — the original post for this idempotencyKey is returned | Treat as the original result; do not create a new post |
| 202 | Post accepted — pending, publishing, published, scheduled, partial, or failed | Read status and per-platform results; poll GET /v1/posts/{postId} if publishing |
| 400 | Validation error (bad request body) | Fix the request fields and resend |
| 402 | Not enough credits | Stop publishing attempts until credit availability changes |
| 403 | Forbidden | Check access/permissions before retrying |
| 503 | Publishing or scheduling unavailable | Retry later with the same idempotencyKey |
Captured request/response contract, with diagnostic actions added where shown. Not a runtime test result.
| Response state | Meaning | platformPostUrl available? | Client action |
|---|---|---|---|
| published | Worker finished within the wait window; targets succeeded | Use each returned URL; do not invent a missing value | Store each platformPostUrl |
| publishing (202) | Worker still processing when the wait window expired | May not yet be available; poll for final results | Poll GET /v1/posts/{postId} for final URLs and errors |
| scheduled (202) | Post accepted for a future scheduledFor time | Check results after scheduled processing | Read the post later to confirm publication |
| partial (202) | Some platforms succeeded, others failed | Use the URLs returned for successful targets | Inspect per-platform error values; retry failed targets |
| failed (202) | Post accepted but publishing failed | Inspect returned errors; do not infer a published URL | Inspect per-platform errors and retry |
Captured request/response contract, with diagnostic actions added where shown. Not a runtime test result.
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
}'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
}'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
}'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"
}'{
"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"
}
]
}{
"success": true,
"status": "publishing",
"postId": "post_abc123",
"platforms": [
{ "platform": "twitter", "success": true },
{ "platform": "instagram", "success": true }
]
}{
"success": true,
"status": "partial",
"postId": "post_abc123",
"platforms": [
{ "platform": "twitter", "success": true, "platformPostUrl": "..." },
{
"platform": "instagram",
"success": false,
"error": "Image URL is not publicly accessible"
}
]
}