Edit Post API: Edit a Draft or Scheduled Post
The Edit Post API uses PUT /v1/posts/{postId} to replace an editable post. If you need to edit scheduled post content, revise a draft, change text or media, or change its outcome, this operation covers all three outcomes: keep it as a draft, publish it right away, or set a future scheduled time. The mode is selected in the request body, and the full replacement body is sent in the request described in the Request body field map table.
Edit a draft or scheduled post
This endpoint replaces an editable post. Three outcomes are available through the body fields: a draft can stay a draft, go live immediately, or move to a scheduled time, and an already scheduled post can retain its existing schedule when scheduled mode is used. Send PUT to /v1/posts/{postId}, where postId is the required string path parameter identifying the post to replace. Before calling, confirm the postId, the full replacement content, the target platforms, and which outcome you intend: draft, immediate publish, or scheduled.
Authorization
Authenticate every request with the accessKey header named x-access-key. Place the token in the x-access-key header and set Content-Type to application/json for the request body.
Path Parameters
The path parameter postId is a required string and is the identifier of the post being edited. Use the exact identifier returned for the draft or scheduled post you intend to replace, and verify it against the post you retrieved before sending the PUT request.
Request Body
The request body is application/json and uses the PostPayload shape. The required fields are content, a string containing the post text body, and platforms, an array of target platform account objects. The optional mediaItems field is an array of media attachment objects for images, videos, and GIFs, and each item requires type and url, with optional altText and thumbnail. Each platforms item requires platform and accountId, and may include an optional per-platform content override and platformSpecificData for that platform. Drafts may be saved without an account, as stated in the platforms description. For safe retries, idempotencyKey is an optional string with length from 1 to 255, scoped per project, and a fresh key should be used for each distinct post. When scheduling, scheduledFor is an optional ISO 8601 date-time string and timezone is an optional IANA timezone string for the scheduled time, defaulting to UTC when omitted. The worked request example below shows the minimal captured shape with content and a single twitter platform entry. The full nested platformSpecificData fields for each platform variant are listed in the Platform-specific configuration table.
Choosing saveAsDraft, publishNow or scheduledFor
Choose exactly one outcome for the edited post. Set saveAsDraft=true to save without publishing or scheduling, and do not combine it with publishNow=true or scheduledFor. Set publishNow=true to publish immediately, noting that scheduledFor takes precedence when provided. Set scheduledFor to an ISO 8601 datetime to schedule the post for future publishing, optionally with timezone set to an IANA timezone such as America/New_York. If you need to edit a scheduled post without changing its schedule, keep the scheduled mode rather than switching to draft or immediate publish. The mode comparison table below summarizes precedence and the prohibition on combining saveAsDraft with the other two modes.
Response Body
A successful edit returns a JSON body with success, status, scheduledFor, postId, and a platforms array. Each platform result includes platform, success, platformPostUrl, error, and warningMessage. Check the top-level success and status first, then inspect each platform entry so a per-platform error or warning is not missed. Error responses use the shared shape with success and message. The status matrix below lists every documented status code, 200, 202, 400, 402, 403, 404, 409, and 503, with only the response shape shown in the source and no invented cause for any error status.
| Field | Type | Required | Constraints / Notes |
|---|---|---|---|
| content | string | Yes | Post text body |
| mediaItems | array<object> | No | Media attachments (images, videos, GIFs) |
| mediaItems[].type | string | Yes (per item) | "image" | "video" | "gif" | "document" |
| mediaItems[].url | string | Yes (per item) | Format: uri; publicly accessible URL fetchable without authentication |
| mediaItems[].altText | string | No | 1 <= length <= 1000 |
| mediaItems[].thumbnail | string | No | Format: uri |
| platforms | array<object> | Yes | Target platform accounts. Drafts may be saved without an account. |
| platforms[].platform | string | Yes (per item) | "twitter" | "instagram" | "youtube" | "tiktok" | "pinterest" | "linkedin" | "bluesky" | "facebook" | "threads" | "googlebusiness" |
| platforms[].accountId | string | Yes (per item) | Integration._id |
| platforms[].content | string | No | Optional per-platform text override; top-level content used when omitted |
| platforms[].platformSpecificData | object | No | Platform-specific configuration object for the selected platform; see Platform-specific configuration table |
| publishNow | boolean | No | Publish immediately. scheduledFor takes precedence when provided. |
| saveAsDraft | boolean | No | Save without publishing or scheduling. Cannot be combined with publishNow=true or scheduledFor. |
| scheduledFor | string | No | Format: date-time; ISO 8601 datetime to schedule the post for future publishing |
| timezone | string | No | IANA timezone for the scheduled time (e.g. America/New_York). Defaults to UTC. |
| idempotencyKey | string | No | 1 <= length <= 255; optional unique key to safely retry; scoped per project; reuse a fresh key for each distinct post |
Captured contract fields; nested platformSpecificData variants summarized by platform enum.
| Platform | platformSpecificData fields (type, required, constraints) |
|---|---|
| twitter (TwitterConfigurations) | communityId string?; shareWithFollowers boolean?; replyToTweetId string?; replySettings string? "following"|"mentionedUsers"|"subscribers"|"verified"; threadItems array<object>? with content string* and mediaItems array<object>? (type* "image"|"video"|"gif"|"document", url* uri, altText? 1-1000, thumbnail? uri); longPost boolean?; poll object? with options array<string>* 2-4 items and durationMinutes number* 5-10080 |
| instagram (InstagramConfigurations) | locationId string? ^\d+$; audioConfiguration object? with audioId string* ^\d+$, audioVolume integer? 1-100, videoVolume integer? 1-100; contentType string? "story"; isAiGenerated boolean?; shareToFeed boolean?; trialParams object? with graduationStrategy string* "MANUAL"|"SS_PERFORMANCE"; coverUrl string? uri; thumbOffset integer? >=0; audioName string? 1-100; collaborators array<string>? 1-3 items, each ^[A-Za-z0-9._]+$ 1-30 |
| youtube (YouTubeConfigurations) | title string? length<=100; tags array<string>?; visibility string? "public"|"private"|"unlisted"; madeForKids boolean?; containsSyntheticMedia boolean?; categoryId string?; playlistId string? length>=1; firstComment string? length<=10000 |
| tiktok (TikTokConfigurations) | privacyLevel string? "PUBLIC_TO_EVERYONE"|"MUTUAL_FOLLOW_FRIENDS"|"FOLLOWER_OF_CREATOR"|"SELF_ONLY"; disableComment boolean?; disableDuet boolean?; disableStitch boolean?; brandContentToggle boolean?; brandOrganicToggle boolean?; isAigc boolean?; videoCoverTimestampMs number? >=0; autoAddMusic boolean?; photoCoverIndex number? >=0; description string? length<=4000; draft boolean? |
| pinterest (PinterestConfigurations) | boardId string*; title string? length<=100; link string? uri; altText string? length<=500; dominantColor string?; coverImageUrl string? uri |
| linkedin (LinkedInConfigurations) | visibility string? "PUBLIC"|"CONNECTIONS"; mentions array<object>? items<=30 with text string* length>=1 and urn string* ^urn:li:organization:.+$; articleUrl string? uri; articleTitle string? length<=400; articleDescription string? length<=400; documentTitle string? length<=200 |
| bluesky (BlueskyConfigurations) | langs array<string>?; altText array<string>? |
| facebook (FacebookConfigurations) | contentType string? "reel"|"story"; link string? uri; isAiGenerated boolean?; published boolean?; videoThumbnailUrl string? uri |
| threads (ThreadsConfigurations) | replyControl string? "everyone"|"accounts_you_follow"|"mentioned_only"; altText array<string>? |
| googlebusiness (GoogleBusinessConfigurations) | topicType string? "STANDARD"|"EVENT"|"OFFER"; callToActionType string? "BOOK"|"ORDER"|"SHOP"|"LEARN_MORE"|"SIGN_UP"|"CALL"|"GET_OFFER"; callToActionUrl string? uri; eventTitle string?; eventStartDate string?; eventStartTime string?; eventEndDate string?; eventEndTime string?; offerCouponCode string?; offerRedeemOnlineUrl string? uri; offerTermsConditions string? |
Captured serialized contract graph fields; descriptions only where captured, no invented descriptions.
| Mode field | Result | Precedence and combinations |
|---|---|---|
| saveAsDraft=true | Drafts remain drafts; saved without publishing or scheduling | Cannot be combined with publishNow=true or scheduledFor |
| publishNow=true | Publish immediately | scheduledFor takes precedence when provided |
| scheduledFor=<ISO 8601 datetime> | Become scheduled for future publishing; scheduled posts keep their schedule | Takes precedence over publishNow; pair with timezone (IANA timezone, defaults to UTC) |
Decision criteria from captured field descriptions.
| Status | Response shape shown in source |
|---|---|
| 200 application/json | success, status, scheduledFor, postId, platforms[] with platform, success, platformPostUrl, error, warningMessage |
| 202 application/json | success, status, scheduledFor, postId, platforms[] with platform, success, platformPostUrl, error, warningMessage |
| 400 application/json | ErrorResponse: success (boolean, required), message (string, required) |
| 402 application/json | ErrorResponse: success (boolean, required), message (string, required) |
| 403 application/json | ErrorResponse: success (boolean, required), message (string, required) |
| 404 application/json | ErrorResponse: success (boolean, required), message (string, required) |
| 409 application/json | ErrorResponse: success (boolean, required), message (string, required) |
| 503 application/json | ErrorResponse: success (boolean, required), message (string, required) |
Only shapes shown in source; no invented error causes.
curl -X PUT "{{API_BASE_URL}}/v1/posts/{postId}" \
-H "Content-Type: application/json" \
-H "x-access-key: <token>" \
-d '{
"content": "string",
"platforms": [
{
"platform": "twitter",
"accountId": "string"
}
]
}'{
"success": true,
"status": "draft",
"scheduledFor": "2019-08-24T14:15:22Z",
"postId": "string",
"platforms": [
{
"platform": "twitter",
"success": true,
"platformPostUrl": "string",
"error": "string",
"warningMessage": "string"
}
]
}{
"success": true,
"message": "string"
}| Scope | Field | Type | Type reference | Required | Description | Constraints |
|---|---|---|---|---|---|---|
| body#1 | body | object | #/components/schemas/PostPayload | Yes | ||
| body#1 | body.content | string | __0 | Yes | Post text body | |
| body#1 | body.mediaItems | array<object> | __1 | No | Media attachments (images, videos, GIFs) | |
| body#1 | body.mediaItems[] | object | __2 | |||
| body#1 | body.mediaItems[].type | string | __3 | Yes | kind: schemaValueIn; value: "image" | "video" | "gif" | "document" | |
| body#1 | body.mediaItems[].url | string | __4 | Yes | Publicly accessible URL for the media file. the service or the platform provider must be able to fetch it without authentication. | kind: schemaFormat; value: uri |
| body#1 | body.mediaItems[].altText | string | __5 | No | Accessibility description for an image. Supported platforms forward it when publishing images; unsupported platforms and non-image media ignore it. | kind: schemaLength; value: 1 <= length <= 1000 |
| body#1 | body.mediaItems[].thumbnail | string | __6 | No | Thumbnail image URL for Facebook videos and YouTube regular videos (not Shorts). YouTube accepts JPEG, PNG, or GIF, max 2 MB, min 640 px wide. | kind: schemaFormat; value: uri |
| body#1 | body.platforms | array<object> | __7 | Yes | Target platform accounts. Drafts may be saved without an account. | |
| body#1 | body.platforms[] | object | __8 | |||
| body#1 | body.platforms[][variant1] | object | __8_extends:__9 | |||
| body#1 | body.platforms[][variant1].platform | string | __10 | Yes | kind: schemaValueIn; value: "twitter" | |
| body#1 | body.platforms[][variant1].accountId | string | __11 | Yes | Integration._id — find yours via GET /connect/integrations | |
| body#1 | body.platforms[][variant1].content | string | __12 | No | Optional per-platform text override. Use when you want to change the text for this platform because different platforms talk differently. When omitted, the top-level content is used. | |
| body#1 | body.platforms[][variant1].platformSpecificData | object | #/components/schemas/TwitterConfigurations | No | Pass this object in platformSpecificData when posting to Twitter/X, including Community post options. | |
| body#1 | body.platforms[][variant1].platformSpecificData.communityId | string | __13 | No | Community ID to publish this post into. | |
| body#1 | body.platforms[][variant1].platformSpecificData.shareWithFollowers | boolean | __14 | No | When posting to a Community, also share the post with followers. | |
| body#1 | body.platforms[][variant1].platformSpecificData.replyToTweetId | string | __15 | No | Tweet ID to reply to. | |
| body#1 | body.platforms[][variant1].platformSpecificData.replySettings | string | __16 | No | kind: schemaValueIn; value: "following" | "mentionedUsers" | "subscribers" | "verified" | |
| body#1 | body.platforms[][variant1].platformSpecificData.threadItems | array<object> | __17 | No | Additional tweets to chain as a thread. The root tweet uses post.content. | |
| body#1 | body.platforms[][variant1].platformSpecificData.threadItems[] | object | __18 | |||
| body#1 | body.platforms[][variant1].platformSpecificData.threadItems[].content | string | __19 | Yes | Text of this thread tweet (max 280 chars) | |
| body#1 | body.platforms[][variant1].platformSpecificData.threadItems[].mediaItems | array<object> | __20 | No | ||
| body#1 | body.platforms[][variant1].platformSpecificData.threadItems[].mediaItems[] | object | __21 | |||
| body#1 | body.platforms[][variant1].platformSpecificData.threadItems[].mediaItems[].type | string | __22 | Yes | kind: ; value: "image" | "video" | "gif" | "document" | |
| body#1 | body.platforms[][variant1].platformSpecificData.threadItems[].mediaItems[].url | string | __23 | Yes | Publicly accessible URL for the media file. the service or the platform provider must be able to fetch it without authentication. | kind: ; value: uri |
| body#1 | body.platforms[][variant1].platformSpecificData.threadItems[].mediaItems[].altText | string | __24 | No | Accessibility description for an image. Supported platforms forward it when publishing images; unsupported platforms and non-image media ignore it. | kind: ; value: 1 <= length <= 1000 |
| body#1 | body.platforms[][variant1].platformSpecificData.threadItems[].mediaItems[].thumbnail | string | __25 | No | Thumbnail image URL for Facebook videos and YouTube regular videos (not Shorts). YouTube accepts JPEG, PNG, or GIF, max 2 MB, min 640 px wide. | kind: ; value: uri |
| body#1 | body.platforms[][variant1].platformSpecificData.longPost | boolean | __26 | No | Opt in to long posts (over 280 characters). Skips the service's 280-character pre-check so X can accept up to 25,000 characters for eligible Premium / Premium+ accounts. If the connected account is not eligible, X rejects the post and the error is surfaced back. No extra API cost. | |
| body#1 | body.platforms[][variant1].platformSpecificData.poll | object | __27 | No | Cannot be combined with media or threadItems. | |
| body#1 | body.platforms[][variant1].platformSpecificData.poll.options | array<string> | __28 | Yes | 2–4 poll options. | kind: ; value: 2 <= items <= 4 |
| body#1 | body.platforms[][variant1].platformSpecificData.poll.options[] | string | __29 | |||
| body#1 | body.platforms[][variant1].platformSpecificData.poll.durationMinutes | number | __30 | Yes | Poll duration in minutes (5 min – 7 days). | kind: ; value: 5 <= value <= 10080 |
| body#1 | body.platforms[][variant2] | object | __8_extends:__31 | |||
| body#1 | body.platforms[][variant2].platform | string | __32 | Yes | kind: ; value: "instagram" | |
| body#1 | body.platforms[][variant2].accountId | string | __33 | Yes | Integration._id — find yours via GET /connect/integrations | |
| body#1 | body.platforms[][variant2].content | string | __34 | No | Optional per-platform text override. Use when you want to change the text for this platform because different platforms talk differently. When omitted, the top-level content is used. | |
| body#1 | body.platforms[][variant2].platformSpecificData | object | #/components/schemas/InstagramConfigurations | No | Pass this object in platformSpecificData when posting to Instagram. Use contentType to publish Stories; the remaining fields customize feed posts and Reels. | |
| body#1 | body.platforms[][variant2].platformSpecificData.locationId | string | __35 | No | Numeric Facebook Page ID with location data. Feed posts, Reels and whole carousels only; not Stories. | kind: ; value: ^\d+$ |
| body#1 | body.platforms[][variant2].platformSpecificData.audioConfiguration | object | __36 | No | Catalog audio for single-video Reels, requires Facebook Login. Volumes default to 100. Audio must remain available at publish time. | |
| body#1 | body.platforms[][variant2].platformSpecificData.audioConfiguration.audioId | string | __37 | Yes | kind: ; value: ^\d+$ | |
| body#1 | body.platforms[][variant2].platformSpecificData.audioConfiguration.audioVolume | integer | __38 | No | kind: ; value: 1 <= value <= 100 | |
| body#1 | body.platforms[][variant2].platformSpecificData.audioConfiguration.videoVolume | integer | __39 | No | kind: ; value: 1 <= value <= 100 | |
| body#1 | body.platforms[][variant2].platformSpecificData.contentType | string | __40 | No | Set to "story" to publish an Instagram Story. Omit for the existing behavior: images publish to Feed and videos publish as Reels. | kind: ; value: "story" |
| body#1 | body.platforms[][variant2].platformSpecificData.isAiGenerated | boolean | __41 | No | Self-discloses that the post contains AI-generated images or video so Instagram can show its AI info label. Applies to feed posts, Reels, Stories, and carousel parents; it does not describe AI-written captions. | |
| body#1 | body.platforms[][variant2].platformSpecificData.shareToFeed | boolean | __42 | No | Reels-only. When true (default), the Reel also appears in the account's main feed grid. Set false to publish to Reels only. | |
| body#1 | body.platforms[][variant2].platformSpecificData.trialParams | object | __43 | No | Reels-only. Publishes a single video as a Trial Reel, initially shown to non-followers. | |
| body#1 | body.platforms[][variant2].platformSpecificData.trialParams.graduationStrategy | string | __44 | Yes | Controls how a Trial Reel is shared with followers. MANUAL keeps graduation manual; SS_PERFORMANCE lets Instagram share it automatically when it performs well. | kind: ; value: "MANUAL" | "SS_PERFORMANCE" |
| body#1 | body.platforms[][variant2].platformSpecificData.coverUrl | string | __45 | No | Video-only. Public URL of an image Instagram will use as the cover frame for the Reel/video post. Ignored for image posts. | kind: ; value: uri |
| body#1 | body.platforms[][variant2].platformSpecificData.thumbOffset | integer | __46 | No | Video-only. Timestamp in milliseconds Instagram extracts as the cover frame. Ignored when coverUrl is set or for image posts. | kind: ; value: 0 <= value |
| body#1 | body.platforms[][variant2].platformSpecificData.audioName | string | __47 | No | Reels-only. Sets the name shown for the Reel audio. This only labels audio already in the video file. Use audioConfiguration to attach catalog audio through Facebook Login. | kind: ; value: 1 <= length <= 100 |
| body#1 | body.platforms[][variant2].platformSpecificData.collaborators | array<string> | __48 | No | Feed posts, carousels, and Reels only. Up to three Instagram usernames to invite as collaborators. Each account must accept the invitation in Instagram. | kind: ; value: 1 <= items <= 3 |
| body#1 | body.platforms[][variant2].platformSpecificData.collaborators[] | string | __49 | Instagram username without the leading @. | kind: ; value: ^[A-Za-z0-9._]+$ | kind: ; value: 1 <= length <= 30 | |
| body#1 | body.platforms[][variant3] | object | __8_extends:__50 | |||
| body#1 | body.platforms[][variant3].platform | string | __51 | Yes | kind: ; value: "youtube" | |
| body#1 | body.platforms[][variant3].accountId | string | __52 | Yes | Integration._id — find yours via GET /connect/integrations | |
| body#1 | body.platforms[][variant3].content | string | __53 | No | Optional per-platform text override. Use when you want to change the text for this platform because different platforms talk differently. When omitted, the top-level content is used. | |
| body#1 | body.platforms[][variant3].platformSpecificData | object | #/components/schemas/YouTubeConfigurations | No | Pass this object in platformSpecificData when posting to YouTube. | |
| body#1 | body.platforms[][variant3].platformSpecificData.title | string | __54 | No | Video title (max 100 chars, no < or >). Defaults to first 100 chars of content, or "Untitled Video". | kind: ; value: length <= 100 |
| body#1 | body.platforms[][variant3].platformSpecificData.tags | array<string> | __55 | No | Video tags. Total characters across all tags must be ≤500. | |
| body#1 | body.platforms[][variant3].platformSpecificData.tags[] | string | __56 | |||
| body#1 | body.platforms[][variant3].platformSpecificData.visibility | string | __57 | No | Who can see the video. Defaults to "public". Scheduled posts remain queued in the service and upload at the scheduled time using this visibility. | kind: ; value: "public" | "private" | "unlisted" |
| body#1 | body.platforms[][variant3].platformSpecificData.madeForKids | boolean | __58 | No | COPPA compliance flag. Setting to true permanently disables comments, notification bell, personalized ads, end screens, and cards on the video. Defaults to false. | |
| body#1 | body.platforms[][variant3].platformSpecificData.containsSyntheticMedia | boolean | __59 | No | AI-generated content disclosure. YouTube is increasingly enforcing this requirement. Defaults to false. | |
| body#1 | body.platforms[][variant3].platformSpecificData.categoryId | string | __60 | No | YouTube category ID. Defaults to "22" (People & Blogs). Common values: "1" Film & Animation, "10" Music, "20" Gaming, "22" People & Blogs, "27" Education, "28" Science & Technology. | |
| body#1 | body.platforms[][variant3].platformSpecificData.playlistId | string | __61 | No | Playlist to add the uploaded video to. Retrieve available IDs from the YouTube playlists endpoint. | kind: ; value: 1 <= length |
| body#1 | body.platforms[][variant3].platformSpecificData.firstComment | string | __62 | No | Auto-posted comment after upload. Max 10,000 characters. For publishNow posts: posted immediately after upload. For scheduled posts: posted after the upload at the scheduled time. | kind: ; value: length <= 10000 |
| body#1 | body.platforms[][variant4] | object | __8_extends:__63 | |||
| body#1 | body.platforms[][variant4].platform | string | __64 | Yes | kind: ; value: "tiktok" | |
| body#1 | body.platforms[][variant4].accountId | string | __65 | Yes | Integration._id — find yours via GET /connect/integrations | |
| body#1 | body.platforms[][variant4].content | string | __66 | No | Optional per-platform text override. Use when you want to change the text for this platform because different platforms talk differently. When omitted, the top-level content is used. | |
| body#1 | body.platforms[][variant4].platformSpecificData | object | #/components/schemas/TikTokConfigurations | No | Pass this object in platformSpecificData when posting to TikTok. | |
| body#1 | body.platforms[][variant4].platformSpecificData.privacyLevel | string | __67 | No | Who can see this post. Defaults to "PUBLIC_TO_EVERYONE". | kind: ; value: "PUBLIC_TO_EVERYONE" | "MUTUAL_FOLLOW_FRIENDS" | "FOLLOWER_OF_CREATOR" | "SELF_ONLY" |
| body#1 | body.platforms[][variant4].platformSpecificData.disableComment | boolean | __68 | No | Disable comments on this post. Defaults to false. | |
| body#1 | body.platforms[][variant4].platformSpecificData.disableDuet | boolean | __69 | No | Disable duet for this video. Videos only. Defaults to false. | |
| body#1 | body.platforms[][variant4].platformSpecificData.disableStitch | boolean | __70 | No | Disable stitch for this video. Videos only. Defaults to false. | |
| body#1 | body.platforms[][variant4].platformSpecificData.brandContentToggle | boolean | __71 | No | Mark as branded content (paid partnership). Defaults to false. | |
| body#1 | body.platforms[][variant4].platformSpecificData.brandOrganicToggle | boolean | __72 | No | Mark as organic brand promotion. Defaults to false. | |
| body#1 | body.platforms[][variant4].platformSpecificData.isAigc | boolean | __73 | No | AI-generated content disclosure for photo and video posts. Defaults to false. | |
| body#1 | body.platforms[][variant4].platformSpecificData.videoCoverTimestampMs | number | __74 | No | Timestamp in milliseconds to use as the video cover frame. Videos only. | kind: ; value: 0 <= value |
| body#1 | body.platforms[][variant4].platformSpecificData.autoAddMusic | boolean | __75 | No | Automatically add background music to photo carousels. Photo posts only. Defaults to true. | |
| body#1 | body.platforms[][variant4].platformSpecificData.photoCoverIndex | number | __76 | No | 0-indexed position of the cover image in a photo carousel. Photo posts only. Defaults to 0. | kind: ; value: 0 <= value |
| body#1 | body.platforms[][variant4].platformSpecificData.description | string | __77 | No | Separate description for a TikTok photo or carousel post. Max 4,000 characters. When omitted, the post content is also used as the description. Photo posts only. | kind: ; value: length <= 4000 |
| body#1 | body.platforms[][variant4].platformSpecificData.draft | boolean | __78 | No | When true, sends content to the creator's TikTok inbox as a draft. Defaults to false (publishes immediately via DIRECT_POST). | |
| body#1 | body.platforms[][variant5] | object | __8_extends:__79 | |||
| body#1 | body.platforms[][variant5].platform | string | __80 | Yes | kind: ; value: "pinterest" | |
| body#1 | body.platforms[][variant5].accountId | string | __81 | Yes | Integration._id — find yours via GET /connect/integrations | |
| body#1 | body.platforms[][variant5].content | string | __82 | No | Optional per-platform text override. Use when you want to change the text for this platform because different platforms talk differently. When omitted, the top-level content is used. | |
| body#1 | body.platforms[][variant5].platformSpecificData | object | #/components/schemas/PinterestConfigurations | No | Pass this object in platformSpecificData when posting to Pinterest. | |
| body#1 | body.platforms[][variant5].platformSpecificData.boardId | string | __83 | Yes | Target board ID. Retrieve available boards via GET /v1/pinterest/boards. | |
| body#1 | body.platforms[][variant5].platformSpecificData.title | string | __84 | No | Pin title. Max 100 characters. Defaults to first line of content. | kind: ; value: length <= 100 |
| body#1 | body.platforms[][variant5].platformSpecificData.link | string | __85 | No | HTTPS destination URL when the pin is clicked. Important for driving traffic. | kind: ; value: uri |
| body#1 | body.platforms[][variant5].platformSpecificData.altText | string | __86 | No | Accessible image description. Max 500 characters. | kind: ; value: length <= 500 |
| body#1 | body.platforms[][variant5].platformSpecificData.dominantColor | string | __87 | No | Hex color for the loading placeholder (e.g. "#6E7874"). | |
| body#1 | body.platforms[][variant5].platformSpecificData.coverImageUrl | string | __88 | No | Custom cover image URL for video pins. | kind: ; value: uri |
| body#1 | body.platforms[][variant6] | object | __8_extends:__89 | |||
| body#1 | body.platforms[][variant6].platform | string | __90 | Yes | kind: ; value: "linkedin" | |
| body#1 | body.platforms[][variant6].accountId | string | __91 | Yes | Integration._id — find yours via GET /connect/integrations | |
| body#1 | body.platforms[][variant6].content | string | __92 | No | Optional per-platform text override. Use when you want to change the text for this platform because different platforms talk differently. When omitted, the top-level content is used. | |
| body#1 | body.platforms[][variant6].platformSpecificData | object | #/components/schemas/LinkedInConfigurations | No | Pass this object in platformSpecificData when posting to LinkedIn. | |
| body#1 | body.platforms[][variant6].platformSpecificData.visibility | string | __93 | No | Post visibility. "PUBLIC" = visible to everyone, "CONNECTIONS" = visible to connections only. Defaults to "PUBLIC". | kind: ; value: "PUBLIC" | "CONNECTIONS" |
| body#1 | body.platforms[][variant6].platformSpecificData.mentions | array<object> | __94 | No | Tag company pages in the post text. Each entry maps an exact substring of content to the organization URN to mention; LinkedIn renders it as a clickable @mention. Only company pages can be mentioned, not personal profiles. | kind: ; value: items <= 30 |
| body#1 | body.platforms[][variant6].platformSpecificData.mentions[] | object | __95 | |||
| body#1 | body.platforms[][variant6].platformSpecificData.mentions[].text | string | __96 | Yes | Exact substring within the post content to turn into a clickable mention (e.g. "Acme Corp"). Case-sensitive, must appear exactly once in content. | kind: ; value: 1 <= length |
| body#1 | body.platforms[][variant6].platformSpecificData.mentions[].urn | string | __97 | Yes | LinkedIn URN of the company page to mention, e.g. "urn:li:organization:12345". LinkedIn's API only supports mentioning organization/company pages, not personal profiles. | kind: ; value: ^urn:li:organization:.+$ |
| body#1 | body.platforms[][variant6].platformSpecificData.articleUrl | string | __98 | No | URL for an article/link post. When provided, the post becomes a link share with a preview card. | kind: ; value: uri |
| body#1 | body.platforms[][variant6].platformSpecificData.articleTitle | string | __99 | No | Title for the article preview card. Max 400 characters. | kind: ; value: length <= 400 |
| body#1 | body.platforms[][variant6].platformSpecificData.articleDescription | string | __100 | No | Description for the article preview card. Max 400 characters. | kind: ; value: length <= 400 |
| body#1 | body.platforms[][variant6].platformSpecificData.documentTitle | string | __101 | No | Title shown on the document card when posting a PDF. Required by LinkedIn when a document media item is included. | kind: ; value: length <= 200 |
| body#1 | body.platforms[][variant7] | object | __8_extends:__102 | |||
| body#1 | body.platforms[][variant7].platform | string | __103 | Yes | kind: ; value: "bluesky" | |
| body#1 | body.platforms[][variant7].accountId | string | __104 | Yes | Integration._id — find yours via GET /connect/integrations | |
| body#1 | body.platforms[][variant7].content | string | __105 | No | Optional per-platform text override. Use when you want to change the text for this platform because different platforms talk differently. When omitted, the top-level content is used. | |
| body#1 | body.platforms[][variant7].platformSpecificData | object | #/components/schemas/BlueskyConfigurations | No | Pass this object in platformSpecificData when posting to Bluesky. | |
| body#1 | body.platforms[][variant7].platformSpecificData.langs | array<string> | __106 | No | BCP-47 language tags for the post (e.g. ["en"], ["en-US", "es"]). Defaults to ["en"]. | |
| body#1 | body.platforms[][variant7].platformSpecificData.langs[] | string | __107 | |||
| body#1 | body.platforms[][variant7].platformSpecificData.altText | array<string> | __108 | No | Alt text for each image, in the same order as mediaItems. Strongly encouraged for accessibility. | |
| body#1 | body.platforms[][variant7].platformSpecificData.altText[] | string | __109 | |||
| body#1 | body.platforms[][variant8] | object | __8_extends:__110 | |||
| body#1 | body.platforms[][variant8].platform | string | __111 | Yes | kind: ; value: "facebook" | |
| body#1 | body.platforms[][variant8].accountId | string | __112 | Yes | Integration._id — find yours via GET /connect/integrations | |
| body#1 | body.platforms[][variant8].content | string | __113 | No | Optional per-platform text override. Use when you want to change the text for this platform because different platforms talk differently. When omitted, the top-level content is used. | |
| body#1 | body.platforms[][variant8].platformSpecificData | object | #/components/schemas/FacebookConfigurations | No | Pass this object in platformSpecificData when posting to Facebook Pages. | |
| body#1 | body.platforms[][variant8].platformSpecificData.contentType | string | __114 | No | Set to "reel" to publish exactly one video as a Facebook Page Reel, or "story" to publish exactly one image or video as a Story. Omit for a feed post. Stories expire after 24 hours; captions, links, and custom thumbnails are ignored. published: false is not supported for Stories. | kind: ; value: "reel" | "story" |
| body#1 | body.platforms[][variant8].platformSpecificData.link | string | __115 | No | When provided on a text-only post, Facebook renders a link preview card from this URL's Open Graph tags. Ignored when mediaItems are attached. | kind: ; value: uri |
| body#1 | body.platforms[][variant8].platformSpecificData.isAiGenerated | boolean | __116 | No | Self-discloses that the uploaded video is AI-generated. Supported for Facebook Page feed videos, Reels, and video Stories; it is not applied to text, photo, or carousel posts. | |
| body#1 | body.platforms[][variant8].platformSpecificData.published | boolean | __117 | No | When false, the post is created on the Page in unpublished/draft state — useful for staging or scheduling via Facebook's own composer. Defaults to true. | |
| body#1 | body.platforms[][variant8].platformSpecificData.videoThumbnailUrl | string | __118 | No | Video posts only. Optional Facebook-specific override for mediaItems[].thumbnail. Applied as a follow-up call after publish — if the upload fails, the post still succeeds (Facebook just auto-picks a frame). Ignored when no video is attached. | kind: ; value: uri |
| body#1 | body.platforms[][variant9] | object | __8_extends:__119 | |||
| body#1 | body.platforms[][variant9].platform | string | __120 | Yes | kind: ; value: "threads" | |
| body#1 | body.platforms[][variant9].accountId | string | __121 | Yes | Integration._id — find yours via GET /connect/integrations | |
| body#1 | body.platforms[][variant9].content | string | __122 | No | Optional per-platform text override. Use when you want to change the text for this platform because different platforms talk differently. When omitted, the top-level content is used. | |
| body#1 | body.platforms[][variant9].platformSpecificData | object | #/components/schemas/ThreadsConfigurations | No | Pass this object in platformSpecificData when posting to Threads. | |
| body#1 | body.platforms[][variant9].platformSpecificData.replyControl | string | __123 | No | Who can reply to this thread. Defaults to "everyone" when omitted. | kind: ; value: "everyone" | "accounts_you_follow" | "mentioned_only" |
| body#1 | body.platforms[][variant9].platformSpecificData.altText | array<string> | __124 | No | Alt text for each image, in the same order as mediaItems. Strongly encouraged for accessibility. | |
| body#1 | body.platforms[][variant9].platformSpecificData.altText[] | string | __125 | |||
| body#1 | body.platforms[][variant10] | object | __8_extends:__126 | |||
| body#1 | body.platforms[][variant10].platform | string | __127 | Yes | kind: ; value: "googlebusiness" | |
| body#1 | body.platforms[][variant10].accountId | string | __128 | Yes | Integration._id — find yours via GET /connect/integrations | |
| body#1 | body.platforms[][variant10].content | string | __129 | No | Optional per-platform text override. Use when you want to change the text for this platform because different platforms talk differently. When omitted, the top-level content is used. | |
| body#1 | body.platforms[][variant10].platformSpecificData | object | #/components/schemas/GoogleBusinessConfigurations | No | Pass this object in platformSpecificData when posting to Google Business Profile. Posts appear on Google Search and Maps. | |
| body#1 | body.platforms[][variant10].platformSpecificData.topicType | string | __130 | No | Post type. Defaults to STANDARD. Use EVENT for event posts, OFFER for promotional offer posts. | kind: ; value: "STANDARD" | "EVENT" | "OFFER" |
| body#1 | body.platforms[][variant10].platformSpecificData.callToActionType | string | __131 | No | Call-to-action button shown on the post. | kind: ; value: "BOOK" | "ORDER" | "SHOP" | "LEARN_MORE" | "SIGN_UP" | "CALL" | "GET_OFFER" |
| body#1 | body.platforms[][variant10].platformSpecificData.callToActionUrl | string | __132 | No | URL for the call-to-action. Required for all CTA types except CALL. | kind: ; value: uri |
| body#1 | body.platforms[][variant10].platformSpecificData.eventTitle | string | __133 | No | Event title. Required when topicType is EVENT. | |
| body#1 | body.platforms[][variant10].platformSpecificData.eventStartDate | string | __134 | No | Event start date in YYYY-MM-DD format. Required when topicType is EVENT. | |
| body#1 | body.platforms[][variant10].platformSpecificData.eventStartTime | string | __135 | No | Event start time in HH:MM (24-hour) format. Required when topicType is EVENT. | |
| body#1 | body.platforms[][variant10].platformSpecificData.eventEndDate | string | __136 | No | Event end date in YYYY-MM-DD format. Required when topicType is EVENT. | |
| body#1 | body.platforms[][variant10].platformSpecificData.eventEndTime | string | __137 | No | Event end time in HH:MM (24-hour) format. Required when topicType is EVENT. | |
| body#1 | body.platforms[][variant10].platformSpecificData.offerCouponCode | string | __138 | No | Coupon code for OFFER posts. | |
| body#1 | body.platforms[][variant10].platformSpecificData.offerRedeemOnlineUrl | string | __139 | No | Online redemption URL for OFFER posts. | kind: ; value: uri |
| body#1 | body.platforms[][variant10].platformSpecificData.offerTermsConditions | string | __140 | No | Terms and conditions text for OFFER posts. | |
| body#1 | body.publishNow | boolean | __141 | No | Publish immediately. scheduledFor takes precedence when provided. | |
| body#1 | body.saveAsDraft | boolean | __142 | No | Save without publishing or scheduling. Cannot be combined with publishNow=true or scheduledFor. | |
| body#1 | body.scheduledFor | string | __143 | No | ISO 8601 datetime to schedule the post for future publishing | kind: ; value: date-time |
| body#1 | body.timezone | string | __144 | No | IANA timezone for the scheduled time (e.g. America/New_York). Defaults to UTC. | |
| body#1 | body.idempotencyKey | string | __145 | No | Optional unique key to safely retry this request. If a post was already created with the same key for this project, the original result is returned instead of creating or publishing a duplicate. Scoped per project; reuse a fresh key for each distinct post. | kind: ; value: 1 <= length <= 255 |
| response#2 | response | object | #/components/schemas/ErrorResponse | |||
| response#2 | response.success | boolean | __0 | Yes | ||
| response#2 | response.message | string | __1 | Yes |