Create Post API
The Create Post API creates a post that can be saved as a draft, published immediately, or scheduled for future publishing. It uses POST /v1/posts/ with an x-access-key header, a required content string, a required platforms array, optional mediaItems, and publishing-mode fields that control whether the post is drafted, published now, or scheduled with scheduledFor.
Create Post API operation summary
Use POST /v1/posts/ to create, publish, or schedule a post. Set saveAsDraft to true to save without accounts or credits, set publishNow to true to publish immediately, or provide scheduledFor to schedule the post. The request body is application/json and the operation returns application/json responses. Before sending a request, confirm the access key, the target account identifiers, the media URLs, and the publishing mode you intend to use, because those choices determine whether the result is a draft, an immediate publish, or a scheduled post.
Authorization
Send the access key in the x-access-key header. The header name is accessKey in the captured authorization description and the wire header is x-access-key. Include Content-Type: application/json for the JSON request body. If the header is missing or invalid, treat the request as not ready to send and correct the credential before retrying, rather than changing the endpoint path or field names.
Request body field map
The top-level request requires content as a string and platforms as an array of objects. Optional top-level fields are mediaItems, publishNow, saveAsDraft, scheduledFor, timezone, and idempotencyKey. Each mediaItems entry requires type and url, with type limited to image, video, gif, or document, url formatted as a URI, optional altText from 1 to 1000 characters, and optional thumbnail formatted as a URI. Each platforms entry requires platform and accountId, allows an optional per-platform content override, and allows optional platformSpecificData whose fields depend on the selected platform. When per-platform content is omitted, the top-level content is used for that platform. The platforms description states that drafts may be saved without an account, while the typed contract marks platforms and each entry's accountId as required.
Publishing mode, scheduling and idempotency
Choose exactly one publishing intent. Use saveAsDraft true for a draft, publishNow true for immediate publishing, or scheduledFor for future publishing. scheduledFor takes precedence when provided alongside publishNow. saveAsDraft cannot be combined with publishNow true or scheduledFor. For scheduled posts, scheduledFor must be an ISO 8601 date-time string and timezone may be an IANA timezone such as America/New_York, defaulting to UTC when omitted. For safe retries, provide idempotencyKey between 1 and 255 characters; if a post was already created with the same key for the same project, the original result is returned instead of creating or publishing a duplicate, and a fresh key should be used for each distinct post.
Platform targeting and platformSpecificData
Target one or more platform accounts through the platforms array. Each entry selects a platform value and an accountId, which is the integration identifier found through the integrations listing operation referenced in the contract. Add platformSpecificData only for the platform you are targeting, because the configuration object changes by platform. Examples include Twitter community, reply, thread, long-post and poll settings, where threadItems entries require content and poll requires options and durationMinutes; Instagram story, audio, trial, cover and collaborator settings, where audioConfiguration requires audioId and trialParams requires graduationStrategy; YouTube title, tags, visibility and category settings; TikTok privacy and draft settings; Pinterest board settings, where boardId is required; LinkedIn visibility, mentions and article settings, where each mentions entry requires text and urn; Bluesky language and alt-text settings; Facebook content type and publishing settings; Threads reply control and alt-text settings; and Google Business topic, call-to-action, event and offer settings. Keep required fields for the chosen variant and do not copy fields from another platform variant into the wrong entry.
Worked HTTP example
The worked HTTP example in the Create Post API request example section shows the exact POST method, the /v1/posts/ path with {{API_BASE_URL}} as the origin, the x-access-key header, and a minimal JSON body with content, one twitter platform target, and publishNow set to true. Replace the token and accountId placeholders with your own values before use. Check the request before sending: content is present, platforms contains the intended account, media URLs are publicly accessible URIs when mediaItems are included, and only one publishing mode is selected.
Response body and status codes
Read the response by status code and by shape. The captured success shape for 200 and 202 contains success, status, scheduledFor, postId, and a platforms array whose entries contain platform, success, platformPostUrl, error, and warningMessage. The captured message shape for 400, 402, 403, and 503 contains success and message. After a successful call, inspect each platform entry separately: a top-level success does not remove the need to check per-platform success, platformPostUrl, error, and warningMessage fields. For error statuses, use the message field as the returned explanation and do not assume additional fields that are not in the captured shape.
Failure checks before implementation
Before treating this reference as a working integration, verify the exact endpoint, header, field names, requiredness, enums, and status shapes against the implementation you are building. The most common failure checks are a missing or wrong x-access-key header, a missing content or platforms field, an invalid mediaItems type or non-URI url, combining saveAsDraft with publishNow or scheduledFor, reusing an idempotencyKey for a different post, and copying platformSpecificData fields across different platform variants. Correct the request field or mode rather than changing the documented method or path.
| Field | Type | Required | Constraints and notes |
|---|---|---|---|
| content | string | required | Post text body |
| mediaItems | array<object> | optional | Media attachments (images, videos, GIFs) |
| mediaItems[].type | string | required | "image" | "video" | "gif" | "document" |
| mediaItems[].url | string | required | Format: uri; publicly accessible URL |
| mediaItems[].altText | string | optional | 1 <= length <= 1000 |
| mediaItems[].thumbnail | string | optional | Format: uri |
| platforms | array<object> | required | Target platform accounts. Drafts may be saved without an account. |
| platforms[].platform | string | required | One platform variant value, such as "twitter" |
| platforms[].accountId | string | required | Integration identifier for the target account |
| platforms[].content | string | optional | Per-platform text override; top-level content is used when omitted |
| platforms[].platformSpecificData | object | optional | Per-platform configuration for the selected platform |
| publishNow | boolean | optional | Publish immediately. scheduledFor takes precedence when provided. |
| saveAsDraft | boolean | optional | Save without publishing or scheduling. Cannot be combined with publishNow=true or scheduledFor. |
| scheduledFor | string | optional | Format: date-time; ISO 8601 datetime to schedule the post for future publishing |
| timezone | string | optional | IANA timezone for the scheduled time (e.g. America/New_York). Defaults to UTC. |
| idempotencyKey | string | optional | 1 <= length <= 255; scoped per project; reuse a fresh key for each distinct post |
Exact captured request contract; platformSpecificData variants are summarized in the platform configuration table.
| Mode field | Value | Effect | Compatibility |
|---|---|---|---|
| saveAsDraft | true | Save without publishing or scheduling | Cannot be combined with publishNow=true or scheduledFor |
| publishNow | true | Publish immediately | scheduledFor takes precedence when provided |
| scheduledFor | ISO 8601 date-time string | Schedule for future publishing | Takes precedence over publishNow |
| timezone | IANA timezone string | Timezone for scheduledFor | Defaults to UTC |
| idempotencyKey | string, 1-255 chars | Safe retry; original result returned for same project and key | Use a fresh key for each distinct post |
Captured precedence and incompatibility rules preserved exactly.
| Platform value | platformSpecificData fields | Required within variant | Notable constraints |
|---|---|---|---|
| "twitter" | communityId, shareWithFollowers, replyToTweetId, replySettings, threadItems, longPost, poll | threadItems[].content when threadItems used; poll.options and poll.durationMinutes when poll used | replySettings: "following" | "mentionedUsers" | "subscribers" | "verified"; poll.options 2-4 items; poll.durationMinutes 5-10080; poll cannot be combined with media or threadItems |
| "instagram" | locationId, audioConfiguration, contentType, isAiGenerated, shareToFeed, trialParams, coverUrl, thumbOffset, audioName, collaborators | audioConfiguration.audioId when audioConfiguration used; trialParams.graduationStrategy when trialParams used | contentType: "story"; graduationStrategy: "MANUAL" | "SS_PERFORMANCE"; collaborators 1-3 items; audioVolume/videoVolume 1-100 |
| "youtube" | title, tags, visibility, madeForKids, containsSyntheticMedia, categoryId, playlistId, firstComment | None listed as required in the variant summary | visibility: "public" | "private" | "unlisted"; title length <= 100; firstComment length <= 10000 |
| "tiktok" | privacyLevel, disableComment, disableDuet, disableStitch, brandContentToggle, brandOrganicToggle, isAigc, videoCoverTimestampMs, autoAddMusic, photoCoverIndex, description, draft | None listed as required in the variant summary | privacyLevel: "PUBLIC_TO_EVERYONE" | "MUTUAL_FOLLOW_FRIENDS" | "FOLLOWER_OF_CREATOR" | "SELF_ONLY"; description length <= 4000 |
| "pinterest" | boardId, title, link, altText, dominantColor, coverImageUrl | boardId | title length <= 100; altText length <= 500; link and coverImageUrl are URIs |
| "linkedin" | visibility, mentions, articleUrl, articleTitle, articleDescription, documentTitle | mentions[].text and mentions[].urn when mentions are used | visibility: "PUBLIC" | "CONNECTIONS"; mentions items <= 30; urn matches ^urn:li:organization:.+$ |
| "bluesky" | langs, altText | None listed as required in the variant summary | langs and altText are arrays of strings |
| "facebook" | contentType, link, isAiGenerated, published, videoThumbnailUrl | None listed as required in the variant summary | contentType: "reel" | "story"; link and videoThumbnailUrl are URIs |
| "threads" | replyControl, altText | None listed as required in the variant summary | replyControl: "everyone" | "accounts_you_follow" | "mentioned_only" |
| "googlebusiness" | topicType, callToActionType, callToActionUrl, eventTitle, eventStartDate, eventStartTime, eventEndDate, eventEndTime, offerCouponCode, offerRedeemOnlineUrl, offerTermsConditions | None listed as required in the variant summary | topicType: "STANDARD" | "EVENT" | "OFFER"; callToActionType: "BOOK" | "ORDER" | "SHOP" | "LEARN_MORE" | "SIGN_UP" | "CALL" | "GET_OFFER" |
Variant summary from captured typed contract; full field-level detail remains in the immutable contract sheet.
| Status | Captured response shape | Fields | Qualification |
|---|---|---|---|
| 200 | application/json success shape | success, status, scheduledFor, postId, platforms[] with platform, success, platformPostUrl, error, warningMessage | Captured example shape retained |
| 202 | application/json success shape | success, status, scheduledFor, postId, platforms[] with platform, success, platformPostUrl, error, warningMessage | Captured example appears identical to 200; ambiguity flagged |
| 400 | application/json message shape | success, message | Meaning beyond code and shape not supplied |
| 402 | application/json message shape | success, message | Meaning beyond code and shape not supplied; no credit or offer claims included |
| 403 | application/json message shape | success, message | Meaning beyond code and shape not supplied |
| 503 | application/json message shape | success, message | Meaning beyond code and shape not supplied |
Factual hold: captured examples for 200 and 202 appear identical, while the typed contract graph defines a success/message response; no semantics invented.
Frequently asked questions
How do I save a post as a draft instead of publishing it?
Set saveAsDraft to true to save without publishing or scheduling. That mode cannot be combined with publishNow set to true or with scheduledFor. The platforms field is required, each platforms entry requires platform and accountId, and the field description states that drafts may be saved without an account.
How does scheduling work with scheduledFor and timezone?
Provide scheduledFor as an ISO 8601 date-time string and, when needed, timezone as an IANA timezone such as America/New_York. The timezone defaults to UTC. When scheduledFor is provided, it takes precedence over publishNow.
How can I safely retry a Create Post API request?
Provide an idempotencyKey from 1 to 255 characters long. If a post was already created with the same key for the same project, the original result is returned instead of creating or publishing a duplicate. Use a fresh key for each distinct post.
What fields are required for mediaItems?
Include mediaItems as an array of objects. Each item requires type, one of image, video, gif or document, and url as a URI. Optional altText is 1 to 1000 characters and thumbnail is a URI.
Where do I put platform-specific settings?
Add platformSpecificData to the relevant platforms entry. The available fields depend on the platform value, such as twitter, instagram, youtube, tiktok, pinterest, linkedin, bluesky, facebook, threads or googlebusiness, and each variant has its own required and optional fields, including nested objects such as poll, audioConfiguration, trialParams, threadItems and mentions.
curl -X POST "{{API_BASE_URL}}/v1/posts/" \
-H "Content-Type: application/json" \
-H "x-access-key: <token>" \
-d '{
"content": "A short example update.",
"platforms": [
{
"platform": "twitter",
"accountId": "<your-account-id>"
}
],
"publishNow": true
}'{
"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 | __0 | Yes | ||
| body#1 | body.content | string | __1 | Yes | Post text body | |
| body#1 | body.mediaItems | array<object> | __2 | No | Media attachments (images, videos, GIFs) | |
| body#1 | body.mediaItems[] | object | __3 | |||
| body#1 | body.mediaItems[].type | string | __4 | Yes | kind: schemaValueIn; value: "image" | "video" | "gif" | "document" | |
| body#1 | body.mediaItems[].url | string | __5 | 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 | __6 | 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 | __7 | 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> | __8 | Yes | Target platform accounts. Drafts may be saved without an account. | |
| body#1 | body.platforms[] | object | __9 | |||
| body#1 | body.platforms[][variant1] | object | __9_extends:__10 | |||
| body#1 | body.platforms[][variant1].platform | string | __11 | Yes | kind: schemaValueIn; value: "twitter" | |
| body#1 | body.platforms[][variant1].accountId | string | __12 | Yes | Integration._id — find yours via GET /connect/integrations | |
| body#1 | body.platforms[][variant1].content | string | __13 | 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 | __14 | No | Community ID to publish this post into. | |
| body#1 | body.platforms[][variant1].platformSpecificData.shareWithFollowers | boolean | __15 | No | When posting to a Community, also share the post with followers. | |
| body#1 | body.platforms[][variant1].platformSpecificData.replyToTweetId | string | __16 | No | Tweet ID to reply to. | |
| body#1 | body.platforms[][variant1].platformSpecificData.replySettings | string | __17 | No | kind: schemaValueIn; value: "following" | "mentionedUsers" | "subscribers" | "verified" | |
| body#1 | body.platforms[][variant1].platformSpecificData.threadItems | array<object> | __18 | No | Additional tweets to chain as a thread. The root tweet uses post.content. | |
| body#1 | body.platforms[][variant1].platformSpecificData.threadItems[] | object | __19 | |||
| body#1 | body.platforms[][variant1].platformSpecificData.threadItems[].content | string | __20 | Yes | Text of this thread tweet (max 280 chars) | |
| body#1 | body.platforms[][variant1].platformSpecificData.threadItems[].mediaItems | array<object> | __21 | No | ||
| body#1 | body.platforms[][variant1].platformSpecificData.threadItems[].mediaItems[] | object | __22 | |||
| body#1 | body.platforms[][variant1].platformSpecificData.threadItems[].mediaItems[].type | string | __23 | Yes | kind: ; value: "image" | "video" | "gif" | "document" | |
| body#1 | body.platforms[][variant1].platformSpecificData.threadItems[].mediaItems[].url | string | __24 | 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 | __25 | 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 | __26 | 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 | __27 | 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 | __28 | No | Cannot be combined with media or threadItems. | |
| body#1 | body.platforms[][variant1].platformSpecificData.poll.options | array<string> | __29 | Yes | 2–4 poll options. | kind: ; value: 2 <= items <= 4 |
| body#1 | body.platforms[][variant1].platformSpecificData.poll.options[] | string | __30 | |||
| body#1 | body.platforms[][variant1].platformSpecificData.poll.durationMinutes | number | __31 | Yes | Poll duration in minutes (5 min – 7 days). | kind: ; value: 5 <= value <= 10080 |
| body#1 | body.platforms[][variant2] | object | __9_extends:__32 | |||
| body#1 | body.platforms[][variant2].platform | string | __33 | Yes | kind: ; value: "instagram" | |
| body#1 | body.platforms[][variant2].accountId | string | __34 | Yes | Integration._id — find yours via GET /connect/integrations | |
| body#1 | body.platforms[][variant2].content | string | __35 | 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 | __36 | 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 | __37 | 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 | __38 | Yes | kind: ; value: ^\d+$ | |
| body#1 | body.platforms[][variant2].platformSpecificData.audioConfiguration.audioVolume | integer | __39 | No | kind: ; value: 1 <= value <= 100 | |
| body#1 | body.platforms[][variant2].platformSpecificData.audioConfiguration.videoVolume | integer | __40 | No | kind: ; value: 1 <= value <= 100 | |
| body#1 | body.platforms[][variant2].platformSpecificData.contentType | string | __41 | 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 | __42 | 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 | __43 | 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 | __44 | 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 | __45 | 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 | __46 | 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 | __47 | 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 | __48 | 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> | __49 | 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 | __50 | Instagram username without the leading @. | kind: ; value: ^[A-Za-z0-9._]+$ | kind: ; value: 1 <= length <= 30 | |
| body#1 | body.platforms[][variant3] | object | __9_extends:__51 | |||
| body#1 | body.platforms[][variant3].platform | string | __52 | Yes | kind: ; value: "youtube" | |
| body#1 | body.platforms[][variant3].accountId | string | __53 | Yes | Integration._id — find yours via GET /connect/integrations | |
| body#1 | body.platforms[][variant3].content | string | __54 | 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 | __55 | 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> | __56 | No | Video tags. Total characters across all tags must be ≤500. | |
| body#1 | body.platforms[][variant3].platformSpecificData.tags[] | string | __57 | |||
| body#1 | body.platforms[][variant3].platformSpecificData.visibility | string | __58 | 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 | __59 | 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 | __60 | No | AI-generated content disclosure. YouTube is increasingly enforcing this requirement. Defaults to false. | |
| body#1 | body.platforms[][variant3].platformSpecificData.categoryId | string | __61 | 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 | __62 | 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 | __63 | 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 | __9_extends:__64 | |||
| body#1 | body.platforms[][variant4].platform | string | __65 | Yes | kind: ; value: "tiktok" | |
| body#1 | body.platforms[][variant4].accountId | string | __66 | Yes | Integration._id — find yours via GET /connect/integrations | |
| body#1 | body.platforms[][variant4].content | string | __67 | 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 | __68 | 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 | __69 | No | Disable comments on this post. Defaults to false. | |
| body#1 | body.platforms[][variant4].platformSpecificData.disableDuet | boolean | __70 | No | Disable duet for this video. Videos only. Defaults to false. | |
| body#1 | body.platforms[][variant4].platformSpecificData.disableStitch | boolean | __71 | No | Disable stitch for this video. Videos only. Defaults to false. | |
| body#1 | body.platforms[][variant4].platformSpecificData.brandContentToggle | boolean | __72 | No | Mark as branded content (paid partnership). Defaults to false. | |
| body#1 | body.platforms[][variant4].platformSpecificData.brandOrganicToggle | boolean | __73 | No | Mark as organic brand promotion. Defaults to false. | |
| body#1 | body.platforms[][variant4].platformSpecificData.isAigc | boolean | __74 | No | AI-generated content disclosure for photo and video posts. Defaults to false. | |
| body#1 | body.platforms[][variant4].platformSpecificData.videoCoverTimestampMs | number | __75 | 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 | __76 | No | Automatically add background music to photo carousels. Photo posts only. Defaults to true. | |
| body#1 | body.platforms[][variant4].platformSpecificData.photoCoverIndex | number | __77 | 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 | __78 | 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 | __79 | 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 | __9_extends:__80 | |||
| body#1 | body.platforms[][variant5].platform | string | __81 | Yes | kind: ; value: "pinterest" | |
| body#1 | body.platforms[][variant5].accountId | string | __82 | Yes | Integration._id — find yours via GET /connect/integrations | |
| body#1 | body.platforms[][variant5].content | string | __83 | 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 | __84 | Yes | Target board ID. Retrieve available boards via GET /v1/pinterest/boards. | |
| body#1 | body.platforms[][variant5].platformSpecificData.title | string | __85 | No | Pin title. Max 100 characters. Defaults to first line of content. | kind: ; value: length <= 100 |
| body#1 | body.platforms[][variant5].platformSpecificData.link | string | __86 | No | HTTPS destination URL when the pin is clicked. Important for driving traffic. | kind: ; value: uri |
| body#1 | body.platforms[][variant5].platformSpecificData.altText | string | __87 | No | Accessible image description. Max 500 characters. | kind: ; value: length <= 500 |
| body#1 | body.platforms[][variant5].platformSpecificData.dominantColor | string | __88 | No | Hex color for the loading placeholder (e.g. "#6E7874"). | |
| body#1 | body.platforms[][variant5].platformSpecificData.coverImageUrl | string | __89 | No | Custom cover image URL for video pins. | kind: ; value: uri |
| body#1 | body.platforms[][variant6] | object | __9_extends:__90 | |||
| body#1 | body.platforms[][variant6].platform | string | __91 | Yes | kind: ; value: "linkedin" | |
| body#1 | body.platforms[][variant6].accountId | string | __92 | Yes | Integration._id — find yours via GET /connect/integrations | |
| body#1 | body.platforms[][variant6].content | string | __93 | 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 | __94 | 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> | __95 | 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 | __96 | |||
| body#1 | body.platforms[][variant6].platformSpecificData.mentions[].text | string | __97 | 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 | __98 | 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 | __99 | 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 | __100 | No | Title for the article preview card. Max 400 characters. | kind: ; value: length <= 400 |
| body#1 | body.platforms[][variant6].platformSpecificData.articleDescription | string | __101 | No | Description for the article preview card. Max 400 characters. | kind: ; value: length <= 400 |
| body#1 | body.platforms[][variant6].platformSpecificData.documentTitle | string | __102 | 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 | __9_extends:__103 | |||
| body#1 | body.platforms[][variant7].platform | string | __104 | Yes | kind: ; value: "bluesky" | |
| body#1 | body.platforms[][variant7].accountId | string | __105 | Yes | Integration._id — find yours via GET /connect/integrations | |
| body#1 | body.platforms[][variant7].content | string | __106 | 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> | __107 | 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 | __108 | |||
| body#1 | body.platforms[][variant7].platformSpecificData.altText | array<string> | __109 | No | Alt text for each image, in the same order as mediaItems. Strongly encouraged for accessibility. | |
| body#1 | body.platforms[][variant7].platformSpecificData.altText[] | string | __110 | |||
| body#1 | body.platforms[][variant8] | object | __9_extends:__111 | |||
| body#1 | body.platforms[][variant8].platform | string | __112 | Yes | kind: ; value: "facebook" | |
| body#1 | body.platforms[][variant8].accountId | string | __113 | Yes | Integration._id — find yours via GET /connect/integrations | |
| body#1 | body.platforms[][variant8].content | string | __114 | 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 | __115 | 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 | __116 | 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 | __117 | 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 | __118 | 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 | __119 | 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 | __9_extends:__120 | |||
| body#1 | body.platforms[][variant9].platform | string | __121 | Yes | kind: ; value: "threads" | |
| body#1 | body.platforms[][variant9].accountId | string | __122 | Yes | Integration._id — find yours via GET /connect/integrations | |
| body#1 | body.platforms[][variant9].content | string | __123 | 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 | __124 | 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> | __125 | No | Alt text for each image, in the same order as mediaItems. Strongly encouraged for accessibility. | |
| body#1 | body.platforms[][variant9].platformSpecificData.altText[] | string | __126 | |||
| body#1 | body.platforms[][variant10] | object | __9_extends:__127 | |||
| body#1 | body.platforms[][variant10].platform | string | __128 | Yes | kind: ; value: "googlebusiness" | |
| body#1 | body.platforms[][variant10].accountId | string | __129 | Yes | Integration._id — find yours via GET /connect/integrations | |
| body#1 | body.platforms[][variant10].content | string | __130 | 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 | __131 | 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 | __132 | 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 | __133 | 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 | __134 | No | Event title. Required when topicType is EVENT. | |
| body#1 | body.platforms[][variant10].platformSpecificData.eventStartDate | string | __135 | No | Event start date in YYYY-MM-DD format. Required when topicType is EVENT. | |
| body#1 | body.platforms[][variant10].platformSpecificData.eventStartTime | string | __136 | No | Event start time in HH:MM (24-hour) format. Required when topicType is EVENT. | |
| body#1 | body.platforms[][variant10].platformSpecificData.eventEndDate | string | __137 | No | Event end date in YYYY-MM-DD format. Required when topicType is EVENT. | |
| body#1 | body.platforms[][variant10].platformSpecificData.eventEndTime | string | __138 | No | Event end time in HH:MM (24-hour) format. Required when topicType is EVENT. | |
| body#1 | body.platforms[][variant10].platformSpecificData.offerCouponCode | string | __139 | No | Coupon code for OFFER posts. | |
| body#1 | body.platforms[][variant10].platformSpecificData.offerRedeemOnlineUrl | string | __140 | No | Online redemption URL for OFFER posts. | kind: ; value: uri |
| body#1 | body.platforms[][variant10].platformSpecificData.offerTermsConditions | string | __141 | No | Terms and conditions text for OFFER posts. | |
| body#1 | body.publishNow | boolean | __142 | No | Publish immediately. scheduledFor takes precedence when provided. | |
| body#1 | body.saveAsDraft | boolean | __143 | No | Save without publishing or scheduling. Cannot be combined with publishNow=true or scheduledFor. | |
| body#1 | body.scheduledFor | string | __144 | No | ISO 8601 datetime to schedule the post for future publishing | kind: ; value: date-time |
| body#1 | body.timezone | string | __145 | No | IANA timezone for the scheduled time (e.g. America/New_York). Defaults to UTC. | |
| body#1 | body.idempotencyKey | string | __146 | 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 | __0 | |||
| response#2 | response.success | boolean | __1 | Yes | ||
| response#2 | response.message | string | __2 | Yes |