API reference

    Per-network options

    Per-network options are the fields a target's options object carries for one network only — a YouTube title and privacy, a TikTok privacy level, an Instagram placement, a Pinterest board, a Mastodon content warning — on top of the content and files the post shares across every network. Every field for every network is listed here; what a network does not take is reported in the dry run rather than dropped silently. How a target is named and scheduled is on posts.

    Per-network options

    Everything below goes in a target's options. The ids a few of them need come from lookups on the account, all readable with posts:read: GET /v1/oauth/accounts/{id}/boards (Pinterest), /youtube/playlists, /tiktok/creator (the privacy levels this creator may use) and /mentions?q= (Bluesky and Mastodon handles).

    Boost, on any network that takes one

    "boost": { "afterLikes": 50, "withinHours": 48, "reply": "Sign up: …", "repost": true } watches the post once it is out. When it has afterLikes likes within withinHours of publishing (48 by default, at most 168), reply is posted under it as the account and, with repost, it is reposted on Bluesky or boosted on Mastodon. Replies run on Bluesky, Mastodon, Threads, Facebook, Instagram and YouTube; elsewhere the check refuses it. Likes are read once an hour, and it runs once. Where it stands is the target's boostState; a refusal is its warning.

    UTM tags, on any network

    "utm": { "campaign": "Spring launch" } tags every link in the text, the link field, a thread and a first comment with utm_source (the network), utm_medium=social and utm_campaign (as an address reads it: spring-launch). true tags without a campaign. A link that already has a utm_ parameter stays as written, as does one on a host in skipHosts, such as your short domain. The check measures the tagged text, so a post the tags push over a limit is refused before it goes.

    YouTube

    title (up to 100; the caption's first line otherwise), description (replaces the caption), privacy (public, unlisted, private; public by default), tags (a list; 500 characters across all of them, counting commas and quotes — tags past that are left off), categoryId (YouTube's own id; 22, People & Blogs, by default and for an unknown one), madeForKids, containsSyntheticMedia (realistic altered or AI-made content), short (adds #Shorts; YouTube decides from the file whether it is a Short), defaultLanguage and defaultAudioLanguage (BCP-47), notifySubscribers: false, thumbnailMediaId (an uploaded JPEG or PNG up to 32 MB, on a verified channel), playlistId, captions and firstComment (posted as the channel once the video is public; if refused, the video stands and the target carries a warning).

    { "platform": "youtube",
      "options": {
    "title": "Weekly Mix #14", "privacy": "public",
    "tags": ["house", "dj set"], "categoryId": "10", "madeForKids": false,
    "thumbnailMediaId": "4a71…", "playlistId": "PLx0sYbCqOb8…",
    "scheduleOnYouTube": true, "firstComment": "Tracklist in the description.",
    "captions": [ { "language": "cs", "name": "", "content": "1\n00:00:01,000 --> 00:00:04,000\nAhoj…" } ]
      } }

    With scheduleOnYouTube on a public video scheduled more than 20 minutes ahead, the upload starts up to three hours before scheduledAt, private, and YouTube itself makes it public on the minute. Rescheduling or editing the caption afterwards is passed on to YouTube; the file cannot be swapped, and deleting the post deletes the waiting video. captions is a list of tracks with a language, an optional name and the file's text as content — SRT, WebVTT or SBV, up to 400 KB and five tracks. Anything YouTube would not do — a thumbnail on an unverified channel, a playlist that is gone, a track it refuses — does not fail the post and is reported in the target's warning.

    TikTok

    privacy (PUBLIC_TO_EVERYONE, MUTUAL_FOLLOW_FRIENDS, FOLLOWER_OF_CREATOR, SELF_ONLY; SELF_ONLY by default, and a level the creator may not use falls back to it), disableComment, disableDuet and disableStitch (video), yourBrand and brandedContent (branded content cannot be private), aiGenerated, coverTimestampMs (a video's cover frame), asDraft (to the creator's TikTok inbox to finish in the app).

    Pictures instead of a video make a photo post of up to 35, with photoCoverIndex for the cover. TikTok takes pictures only as JPEG or WebP up to 1080p, so each is converted and fitted on the way. Set autoAddMusic and TikTok adds a track of its own choosing — the post then shows that track rather than an original sound.

    { "platform": "tiktok",
      "options": { "privacy": "PUBLIC_TO_EVERYONE", "autoAddMusic": true, "photoCoverIndex": 0 } }
    A specific song cannot be chosen, and video cannot carry one at all. TikTok's sound library has no API behind it. A video posted through this API — or any other scheduling tool — appears under the creator's original sound.

    Instagram and Facebook

    placement: feed (default) or story — a story needs a file and carries no caption. firstComment is posted under the post once it is up; if refused, the post stands and the target carries a warning. The same option works on YouTube and LinkedIn. Instagram also takes collaborators (usernames), and on a single video trialReel (MANUAL or SS_PERFORMANCE, shown only to non-followers first; collaborators are dropped on a trial), shareToFeed: false to keep it off the grid and thumbnailMediaId for the cover. aiGenerated: true sets Instagram's AI info label (is_ai_generated) on a post, reel, story or carousel; it is set at posting and cannot be changed later. Facebook's API has no AI label, so on Facebook the check warns instead. On Facebook, asReel posts a single video of 3 to 90 seconds as a reel. Instagram takes JPEG pictures only, up to 8 MB; any other picture is converted to a JPEG when it is published, so PNG or WebP can be sent as they are. An iPhone's HEIC is made a JPEG as soon as it is uploaded.

    { "platform": "instagram",
      "options": { "trialReel": "SS_PERFORMANCE", "shareToFeed": false,
               "thumbnailMediaId": "4a71…", "firstComment": "Tracklist in bio." } }

    Posting via notification (Instagram and TikTok)

    The APIs cannot add the apps' own music, stickers or effects. Set delivery: "notify" on an Instagram or TikTok target and Preflight does not post it: at its time the person gets a push notification and an email that open a page with the caption copied and the files ready for the phone's share sheet. The target is then published with options.manual.state "waiting", and counts as one publish. TikTok's privacy is not needed, since it is chosen in the app. When it is up, POST /v1/posts/{id}/by-hand with { "action": "done", "targetId": "…", "url": "…" } marks it posted (manual.state becomes "done"); { "action": "remind" } asks again in an hour. delivery on any other network is refused.

    { "platform": "instagram", "options": { "delivery": "notify" } }

    Pinterest

    boardId picks the board; without it the pin goes to the account's default board (its first one), and is refused only when the account has no board at all. One is made with POST /v1/oauth/accounts/{id}/boards. A pin needs a picture; video is not taken. title (up to 100) defaults to the first line; the description is the rest, up to 800. The pin links to the post's linkUrl.

    Threads, Mastodon, Telegram and Discord

    Threads: topicTag (up to 50), replyControl (everyone, followers_only, accounts_you_follow, mentioned_only, parent_post_author_only) and poll, 2 to 4 answers of up to 25 characters on a post without files. aiGenerated: true sets Threads' "Made with AI" label (is_made_with_ai) on the first post. Mastodon: visibility (public, unlisted, private, direct), spoilerText for a content warning (it counts towards the limit), sensitive and language (two or three letters, such as cs); the thread's replies share the audience and warning. Telegram: silent, pin (the bot needs the right to pin), protectContent, spoiler and noLinkPreview; 1,024 characters with a file, 4,096 without. Discord: username (up to 80, without "discord" or "clyde"), avatarUrl (https), threadName (up to 100) for a forum channel and silent.

    [
      { "platform": "mastodon", "options": { "visibility": "unlisted", "spoilerText": "Spoilers", "language": "cs" } },
      { "platform": "telegram", "options": { "silent": true, "pin": true } },
      { "platform": "discord", "options": { "username": "Weekly Mix", "threadName": "Mix #14" } }
    ]

    X, LinkedIn, Bluesky and Tumblr

    X posts text only, with thread for a thread. LinkedIn posts to a personal profile: up to 20 pictures or one video (up to 30 minutes and 500 MB), or linkUrl as an article card when there is no file (with a file or a poll, the link goes at the end of the text); it takes alt text. A document (a file of kind document: PDF, PPT, PPTX, DOC or DOCX up to 100 MB and 300 pages) posts as a carousel, alone in its post, with documentTitle as its title (the file's name otherwise). poll is { "question": "…", "options": ["…", "…"], "duration": "SEVEN_DAYS" }: a question up to 140 characters, 2 to 4 answers up to 30, a duration of ONE_DAY, THREE_DAYS, SEVEN_DAYS (the default) or FOURTEEN_DAYS, one vote per person, on a post with no files. A poll cannot be edited once it is published. No other network takes a document, and no first comment goes to LinkedIn yet. Bluesky links URLs, mentions and hashtags from the text itself and takes thread; linkUrl becomes a link card (title, description and picture read from the page) when there is no file. Tumblr posts to the main blog: up to 30 pictures or one video (up to 10 minutes and 500 MB); tags is a comma-separated list, and without it hashtags on the caption's last line become the tags. All of them take caption.

    Questions: info@preflight.social. The same API as a schema: openapi.json (OpenAPI 3.1).

    Write it once. Let the rules be our problem.

    Preflight checks every post against each network's rules before it leaves, then publishes it to twelve networks. Free plan, no card.