Platform settings & conditional validation

The create and update endpoints accept an optional settings object per platform. Which ones are required depends on the platforms of your selectedAccounts and whether a designId is attached.

General content rule: a post must have either a non-empty postContent caption or a designId.

instagramPostSettings

{
  "postType": "carousel | image | reel",
  "postAsStory": true   // boolean, required
}

tiktokPostSettings

{
  "postType": "carousel | reel",
  "privacyLevel": "PUBLIC_TO_EVERYONE | MUTUAL_FOLLOW_FRIENDS | SELF_ONLY", // required when SCHEDULED
  "canComment": true,            // boolean, required
  "canDuet": true,               // boolean, required for reel (non-carousel)
  "canStitch": true,             // boolean, required for reel (non-carousel)
  "autoAddMusic": true,          // boolean, required for carousel
  "postTitle": "string | null",
  "isBrandedContent": false,     // boolean, required
  "isYourBrand": false,          // boolean, required
  "isThirdPartyBrand": false,    // boolean, required
  "isAIGeneratedContent": false  // boolean, required
}

Cross-field rules (enforced when status = "SCHEDULED"):

• If isBrandedContent is true, at least one of isYourBrand / isThirdPartyBrand must be true.
• isBrandedContent cannot be true when privacyLevel = "SELF_ONLY".

linkedinPostSettings

{
  "postType": "carousel | document | image | reel",
  "postTitle": "string | null"  // required (5–90 chars) when postType=document and SCHEDULED
}

For LinkedIn, a designId is required when status = "SCHEDULED" — text-only LinkedIn posts can only be saved as drafts, not scheduled.

threadsPostSettings

{
  "postType": "carousel | image | reel"
}

facebookPostSettings

Facebook accounts are Pages (accountType: "page" in social accounts).

{
  "postType": "carousel | link_carousel | image | reel",
  "linkUrl": "https://example.com", // link_carousel only; required when SCHEDULED
  "callToAction": "LEARN_MORE",     // link_carousel only; optional, see values below
  "showEndCard": true,              // link_carousel only; optional, default true
  "useSlideTitles": false,          // link_carousel only; optional, default false
  "useSlideDescriptions": false     // link_carousel only; optional, default false
}

For Facebook, a designId is required when status = "SCHEDULED". The link_carousel fields are ignored for other post types.

link_carousel rules:

• linkUrl must be an absolute http(s) URL with a real domain, for example https://example.com. It’s required when scheduling; drafts can be saved without it, but a value that is sent must be valid.
• The design needs 2 to 10 slides. Facebook shows up to 5 cards and chooses which ones.
• Each card uses its slide as the image. Facebook only accepts custom card images for links on a domain the Page’s business has verified in Meta Business Settings; otherwise publishing fails with a message saying so. Use carousel for designs linking elsewhere.
• useSlideTitles / useSlideDescriptions set each card’s headline and description from the slide’s title and description. When off, or when a slide has no title or description, Facebook uses the link’s own.
• showEndCard controls Facebook’s final card linking to the Page.

callToAction values (omit or send null for no button): BOOK_TRAVEL, BUY_NOW, CALL_NOW, DOWNLOAD, GET_DIRECTIONS, GET_QUOTE, INSTALL_APP, INSTALL_MOBILE_APP, LEARN_MORE, LIKE_PAGE, LISTEN_MUSIC, MESSAGE_PAGE, NO_BUTTON, OPEN_LINK, PLAY_GAME, SHOP_NOW, SIGN_UP, SUBSCRIBE, USE_APP, USE_MOBILE_APP, WATCH_MORE, WATCH_VIDEO. Some of these are meant for ads, and Facebook may reject them on organic Page posts.

reel rules: the design must be between 16:9 (landscape) and 9:16 (vertical). Reels also use postSettings for their render settings.

pinterestPostSettings

Pinterest accounts are boards (accountType: "board" in social accounts). Each board you connect is its own account, so the Pin goes to whichever boards are in selectedAccounts; there is no board field here.

{
  "postType": "carousel | image | reel",
  "title": "string | null",               // optional, max 100 characters
  "link": "https://example.com"           // optional destination URL
}

For Pinterest, a designId is required when status = "SCHEDULED". The caption (postContent.pinterest, or common) is published as the Pin description; only the first 800 characters are used.

Rules:

• title is optional and at most 100 characters.
• link is optional. When sent, it must be an absolute http(s) URL with a real domain, for example https://example.com. On a carousel Pin every image links to it.
• A carousel needs 2 to 5 slides. A 1-slide design is published as an image Pin; more than 5 slides fails at publish time.
• Any design size works except ultra-wide (wider than 21:9). 2:3 is recommended.
• reel Pins also use postSettings for their render settings.

postSettings

Applies when any selected platform’s postType resolves to "reel" — it carries the reel’s music.

{
  "backgroundMusicId": "string"    // optional, media id of an audio track
}

A reel plays its design’s motion and runs as long as it does, as the video did when it was made (Length), so its length isn’t yours to set. videoDuration is still accepted, so requests that send it keep working, but it’s ignored. This is the same backgroundMusicId the generate and import endpoints take in videoSettings, so a track carries straight over from creating a video to scheduling it.

audioId, the field’s older name, is still accepted. Send backgroundMusicId or audioId, not both. videoDuration, backgroundMusicId and audioId are the only accepted keys; anything else returns a 422. That includes backgroundMusicVolume: a reel takes no volume.

backgroundMusicId is a media id, not a URL. List the workspace’s tracks with the Audio API to find one. It is verified when you make the request: the media must exist, belong to your API key’s workspace, and be an audio file. Note that deleting a track is refused while a scheduled post still references it.

You can omit it

For a reel post you don’t have to send postSettings at all. When its music is missing, it’s resolved in turn:

1. Your request: the backgroundMusicId or audioId you sent.
2. The attached design: the music the design was generated with.
3. Fallback: null (no audio).

The design lookup applies to designs created through the generate or import endpoints, which keep the videoSettings they were created with. A design made in the editor has none, so it falls through to no audio.

Where validation happens

• Shape checks (each *PostSettings must be an object; status, scheduledAt present and well-formed; postContent an object; selectedAccounts an array) are performed at the Embed API edge and return 422 { "status": false, "message": "..." }.
• postSettings field checks (allowed keys and the backgroundMusicId or audioId workspace/type lookup) also happen at the edge, as 422.
• All the conditional/business rules above are enforced by PostNitro and relayed back as { "success": false, "message": "...", "error": ... }. See the error reference for the full list of messages.