Mellow Hub API & MCP documentation

Mellow Hub

Publish one post to every network you are connected to — Instagram, TikTok, YouTube, X, LinkedIn, Threads, Bluesky, Pinterest, Facebook and Telegram — through one API call, with each network's own rules checked before anything goes out.

Base URL: https://www.mellow.world/api/hub/v1 MCP endpoint: https://www.mellow.world/mcp

The shape of the work

1. whoami — what this credential may do, which channels it can reach, and how many posts are left today. Call it first; everything else depends on the answer.
2. list_channels — the connected accounts. Each has an id beginning spc_; that is what you name in channels.
3. register_media — if the post has media. Any public https URL works and nothing is copied: the network fetches it when it publishes. For bytes you hold, ask for an upload URL and send the file straight there.
4. validate_post — free, publishes nothing, and returns every problem at once. Do this before create_post every time. It is the difference between fixing a post once and discovering the rules by breaking them publicly.
5. create_post — publishes now, or schedules for later.
6. get_post — the result per channel, with the public link.

Connecting a channel

You cannot do this. Every network makes a person sign in, Bluesky asks for a handle and an app password typed into Mellow, and a Telegram channel's owner lets Mellow's bot into the channel inside Telegram itself. connect_channel returns a URL and a sentence explaining who has to open it — pass both on and wait. When the person is done, list_channels shows the new channel.

Creative Studio and AI credits

Studio creates AI carousels and video thumbnails. The Studio tabs are Carousels, Thumbnails and Gallery; the API still uses cover for a thumbnail. Its saved projects, reference images and jobs are private to the selected profile; the login account shares one credit balance across profiles. The current catalog is available at https://www.mellow.world/api/hub/v1/pricing and https://www.mellow.world/hub/pricing.

1. Call studio_list to read designs, job status and the wallet.
2. Call studio_quote with kind carousel (and a count), outline, cover or illustration. A designed carousel costs 2 credits for its story plus 10 per slide — 32 for three. An outline costs 2; one cover or illustration costs 10. An outline creates editable text, not one generated image per slide.
3. Ask before spending unless the user has already delegated that expense. studio_generate requires ai:generate plus posts:write, a stable idempotencyKey, explicit maxCredits, and a request with kind, topic, format and style. Use the formats/styles returned by the quote. For an outline, count is 2–10. Reference asset IDs must belong to this profile.
4. Poll studio_job by jobId. Closing a tab does not cancel a saved job. Failed jobs return reserved credits once. Retry the same request with the same key after a lost response; do not create a second paid generation.
5. Read studio_project, then use studio_save with the current revision. Editing text, ordering slides and changing style is free. A stale revision is refused. If AI finishes while a user edits, the saved job result remains available without replacing newer edits.
6. studio_export renders ordered JPEGs at a saved revision, for free. Use the carousel URLs in validate_post. For a cover, attach thumbnailUrl to the VIDEO media item; keep the original video. Export never publishes.

Panorama (design: "panorama") draws one continuous 3D scene across the whole carousel and sets every word in code over it, exactly as written: put exact copy in quotation marks in the topic, and a number appears only if the topic has it. It takes kind carousel, format 4:5, 3–5 slides and no reference images, at the same price; anything else is refused with studio_panorama_unsupported. Its slides keep a label, a heading, the heading's emphasis and typed blocks (note, pills, stat, board, steps, prompt, buttons) that studio_save edits for free; the art is one picture and is not redrawn slide by slide.

Thumbnails, banners and avatars

Thumbnails are made the way YGen makes them: the person's own words go straight to the image model inside YGen's template (engine: "direct", the default), so write the idea as they said it and put the words for the picture in quotation marks — they are rendered. With a look (styleFrom) Mellow's art director writes the image prompt instead (engine: "design").

• studio_thumbnail — { topic, format, variants, faceIds?, styleFrom?, maxCredits, idempotencyKey }. 10 credits a version; variants up to 3 makes them at once for one reservation (30 for 3). The result lists every version in variants.
• studio_thumbnail_remix — a thumbnail the person likes (source: { youtube } or an imported assetId) remade with the creator in it: its composition, palette, light and type style stay; every person becomes the creator (saved faceIds) or a characterDescription; logos, watermarks and channel names go; its words become the person's own (quoted in changes) or new words of the same length and tone. 10 credits a version.
• studio_thumbnail_edit — { projectId, change }: one thing changes, the rest stays. 10 credits. referenceAssetId adds a person or object.
• studio_thumbnail_improve — { projectId }: applies the latest studio_thumbnail_review's commands to the current image, 10 credits. Review first; a review that found nothing to fix answers studio_review_nothing_to_improve.
• studio_banner — { channelName, tagline?, about?, styleFrom?, faceIds? }: a 2560×1440 YouTube channel banner with the name, the tagline and the faces inside the centre band every device shows. 15 credits.
• studio_avatar — { name?, faceId?, styleFrom?, background? }: a 800×800 square that reads inside a circle. 10 credits.
• studio_import brings a YouTube video's thumbnail, or a file put through request_upload_url, into Studio for free; studio_faces lists, adds and removes the creator's saved faces (up to 12).

Every one of them is poll-and-export: studio_job until ready, then studio_export. Banners and avatars are files to upload in YouTube Studio; Hub does not set them on the channel. A thumbnail's history lists each image it has been, oldest first: saving slides[0].imageAssetId as one of them with studio_save goes back to it, for free.

A key or app that may spend AI credits also has a daily ceiling of them, chosen when it was made (200 offered). studio_quote and studio_list say what is left today (ceiling.leftToday); a generation past it is refused with 429 daily_credit_limit, nothing reserved, and only the owner can issue a key with a higher one. insufficient_credits (402) means the shared balance is short: credits are bought by the owner in the Hub, never by an agent.

Formats: 4:5, 1:1, 9:16, 16:9. Horizontal YouTube video is supported; square or vertical videos up to three minutes may be classified as Shorts by YouTube. The connected account's restrictions and per-network validation still apply.

Existing keys do not automatically gain AI permission: POST /assistant needs ai:generate. AI writing — captions, hashtags, titles, ideas, a review and assistant replies — is included in every plan and costs no credits; it is bounded by fair use, 36 requests an hour and 40 a day for one profile (15 more a day per further profile), answered with 429 and a retry time. An account without a plan gets 402 plan_required. Legacy active subscribers keep their existing assistant access. Included credits renew monthly; purchased credits do not expire. Buy credits or change a plan only through the owner's Hub UI, never through an agent.

One caption, network-specific options

A post has one caption, one media list, and a list of channels. Where a network genuinely differs, say so in options, keyed by platform:

{
  "caption": "The same thought, everywhere.",
  "media": ["https://cdn.example.com/clip.mp4"],
  "channels": ["spc_instagram", "spc_youtube", "spc_bluesky"],
  "options": {
    "instagram": { "placement": "reels" },
    "youtube": { "title": "The same thought", "privacyStatus": "public" }
  },
  "perChannel": {
    "spc_bluesky": { "caption": "The same thought, in 300 characters." }
  }
}

options applies to every channel of that network. perChannel applies to one channel and wins over options — it is how you give Bluesky a shorter caption without shortening the post everywhere.

What you do not fit, Hub fits for each channel when it checks and sends the post, and says so in validate_post's notes (adapted_*): a caption over the limit ends at its last whole sentence that fits, closing hashtags kept; a network that takes one file gets the first; a YouTube title comes from the caption's first line; a Pinterest video gets its first frame as cover. What would have to be invented — a video for YouTube, media for Pinterest — is still an issue.

The notes also say what may go wrong on an account before the post is sent to it: its sign-in has run out (channel_needs_reconnect) or is dated to end before the post is due (channel_sign_in_ends), one of its posts is waiting for the network's limit right now (network_limit_waiting, with until), or some of its posts had to wait for that limit in the last seven days (network_limit_recent). None of them stops the post, and Hub sends again by itself what a network refuses for any of them. Tell the person the post may go out later than planned, or move it, before you publish.

And they say what a video file is against what its network takes: Hub reads an MP4's or MOV's length, frame and weight from the file's header, without downloading it, and notes media_outside_limit when one is outside a limit the network's API publishes, or media_limit_depends when it depends on the account. Hub does not change a file: give the channel one that fits.

Publishing twice is the failure to avoid

create_post requires an idempotency key, and it is not decoration. If your request times out you do not know whether it published; retrying with the same key returns the original post instead of making a second one. Use a key derived from the content or the task, not a random value per attempt. Reusing a key for *different* content is refused, because that is a bug worth seeing.

Scheduling

Give scheduledAt an ISO 8601 timestamp to publish later; omit it to publish now. Cancelling works while a post is still scheduled. Once a network has published there is no unpublishing it through any API — Mellow will say so rather than pretend.

What comes back

Each channel succeeds or fails on its own. A post to five networks where YouTube rejects the title and the other four publish comes back as partial, with the failure named on the YouTube channel and public links on the rest. Read targets, not just status.

Authority and limits

A key is a delegation with edges: the channels it may touch, whether it publishes on its own (autopilot) or only prepares a post for a person to approve (review), and how many of its posts may go out on one day. whoami reports all of them.

A post counts on the UTC day it goes out: its scheduledAt, or the moment it is created when it goes out at once. So a month of two posts a day fits a limit of two, planned in one sitting. A cancelled or failed post keeps its place on its day; a refused request costs nothing. validate_post says when a day is already full, and moving a post into a full day is refused like creating one. Everything done with the key is recorded in a journal the owner reads, and revoking a key takes effect immediately.

Channel limits apply to input checks, previews and stored posts too. Reading, retrying, moving or cancelling a stored post requires every destination in that post to be inside the grant. Restricted lists omit posts spanning other channels; the owner can still see them in Hub.

Reading further

• mellow://guide/platforms — every network's limits and required fields.
• mellow://guide/errors — what each refusal means and what to do about it.
• mellow://guide/recipes — worked examples for the common jobs.

Every network, and what it asks for

These are the rules Mellow checks before it sends anything. A post that passes validate_post has already satisfied everything on this page. Of the file itself Mellow reads a video's length, frame and weight from its header and says so in a note when one is outside a limit the network's API publishes (media_outside_limit); codecs and the network's own processing remain the network's judgement, which no API can answer in advance.

Each network below also says the video file its API takes and how often it takes a post, from the network's own pages, with the page and the day it was read. Where a network publishes no figure the line says so; none is borrowed. When a network refuses a post for its limit, Mellow Hub does this by itself: waits for the network’s limit to start over and sends it then, up to three times. The post shows until when it waits. For this account's own record, read the notes: network_limit_waiting and network_limit_recent say what its queue has met.

Instagram (instagram)

Connecting. A professional (Business or Creator) Instagram account. A personal account cannot publish through any API.

Needed to start the connection:

• connection_type — Instagram login is the direct route and the default. Facebook login is for accounts reached through a Page. One of: instagram, facebook.

Caption. Up to 2200 characters.

Media. At least 1, at most 10; image or video. Stories take exactly one item. Reels take one video.

Placement. timeline, reels, stories.

Video file. Through its API (Instagram Reels): 3 seconds to 15 minutes · up to 300 MB · 0.01:1 to 10:1 · up to 1920 pixels wide · MP4 or MOV. Read 2026-10-07 on Meta for Developers: Instagram Graph API, IG User media (reel specifications).

How often. Instagram takes 100 API-published posts from an account within a 24-hour moving period; a carousel counts as one. Read 2026-10-13 on Meta for Developers: Instagram Platform, Content Publishing.

Trial reels. trialReelType makes a reel a trial: Instagram shows it first to people who do not follow the account. manual keeps it with them until the owner shares it with their followers from the Instagram app; performance lets Instagram share it with the followers by itself if it does well within 72 hours. It applies only to one video posted as a reel (placement reels, or timeline, where a single video goes out as a reel). A story, a carousel or a picture with a trial is refused (trial_needs_reel) — a picture wherever Mellow can tell it is one — because the trial would be dropped and the post would reach the followers as an ordinary one. Instagram gives trial reels only to accounts with enough followers. Where it gives none — Hub's own bar is 200 followers, read where Hub can read the count, and otherwise Instagram's refusal is the answer — or the day's trials are used up, a trial reel is NEVER turned into an ordinary one by Hub on its own: the target fails, saying so, and nothing is posted. Only ordinaryIfTrialRefused: true (off unless set) lets it go out as an ordinary reel to the account's followers instead, and its settings then carry trialReelDeclined: true.

Finished in the app. Instagram's API publishes a file with the sound it already has: a sound from Instagram's library, or another creator's original audio (the sound of a trend), can only be chosen in the Instagram app. finishInApp: true leaves the post for the person to finish there: Hub never sends it to Instagram; at the post's time it sends them, in a message they read on their phone (a chat with Mellow where the account has one, otherwise email), the video or pictures, the caption to copy and soundUrl — the sound's page, https://www.instagram.com/reels/audio/… or a reel that uses it, which the phone opens in the Instagram app. The channel then reads publishing until the person says it is out (the button under the message, the post's link sent back, or Mellow Hub), then published. Other networks of the same post go out as usual. Hub cannot see the post in the app, so it is never marked out by itself. soundUrl without finishInApp is only noted: the reel goes out with the sound in its file.

Supports. schedule, carousel, thumbnail, collaborators, mediaTags, metrics.

TikTok (tiktok)

Connecting. A personal or creator TikTok account.

Caption. Up to 2200 characters.

Title. Optional, up to 90 characters. Used as the headline on photo posts.

Media. At least 1, at most 35; image or video. One video, or up to 35 images as a photo post. Videos and images cannot be mixed.

Video file. Through its API (TikTok): up to 3 minutes, or 10 minutes for some accounts · up to 4 GB · 360 to 4096 pixels each way · MP4, WebM or MOV. Every creator can post 3 minutes through TikTok’s API; some can post 5 or 10 minutes. Read 2026-10-07 on TikTok for Developers: Content Posting API, media transfer guide.

How often. TikTok limits the posts made to a creator account through its API in a 24-hour window. The limit varies among creators, typically around 15 a day, and is shared across every app that posts for the account. Read 2026-10-13 on TikTok for Developers: Content Sharing Guidelines.

After sending. TikTok reviews every video before anyone else can see it, usually within minutes, and does not tell Mellow when it is done, so a TikTok reads as sent rather than live and links to the profile. An account whose region is Russia cannot publish through an app: TikTok blocks the video as created in Russia, while the same account's posts from a phone abroad go out. Some accounts can change the region (Settings and privacy → Account → User information → Account region), and many registered in Russia have no such item; for those, set isDraft so the video lands in the TikTok inbox and is posted from the phone. A song baked into the file that you don't hold the rights to can get a video muted; in a draft, a sound from TikTok's library can be added instead.

Promotion. A post that promotes a product, business or service has to say so, and TikTok labels it: discloseYourBrand when it promotes your own ("Promotional content"), discloseBrandedContent when another brand pays or gifts you for it ("Paid partnership", which cannot be private). Both may be set. Sent with neither, a promotional video is flagged by TikTok itself, and its owner is asked in the app to disclose it within 24 hours or its reach in For You may be limited.

Supports. schedule, draft, carousel, metrics.

TikTok Business (tiktok_business)

Connecting. A TikTok Business account. Use it when you need business analytics; otherwise the ordinary TikTok connection is simpler.

Caption. Up to 2200 characters.

Title. Optional, up to 90 characters.

Media. At least 1, at most 35; image or video. One video, or up to 35 images as a photo post.

How often. TikTok limits the posts made to a creator account through its API in a 24-hour window. The limit varies among creators, typically around 15 a day, and is shared across every app that posts for the account. Read 2026-10-13 on TikTok for Developers: Content Sharing Guidelines.

After sending. TikTok reviews every video before anyone else can see it, usually within minutes, and does not tell Mellow when it is done, so a TikTok reads as sent rather than live and links to the profile. An account whose region is Russia cannot publish through an app: TikTok blocks the video as created in Russia, while the same account's posts from a phone abroad go out. Some accounts can change the region (Settings and privacy → Account → User information → Account region), and many registered in Russia have no such item; for those, set isDraft so the video lands in the TikTok inbox and is posted from the phone. A song baked into the file that you don't hold the rights to can get a video muted; in a draft, a sound from TikTok's library can be added instead. A Business account may use only TikTok's Commercial Music Library, so any other song is outside its rules.

Promotion. A post that promotes a product, business or service has to say so, and TikTok labels it: discloseYourBrand when it promotes your own ("Promotional content"), discloseBrandedContent when another brand pays or gifts you for it ("Paid partnership", which cannot be private). Both may be set. Sent with neither, a promotional video is flagged by TikTok itself, and its owner is asked in the app to disclose it within 24 hours or its reach in For You may be limited.

Supports. schedule, draft, carousel, thumbnail, metrics.

YouTube (youtube)

Connecting. A Google account with a YouTube channel. Uploads count against the channel's daily API quota.

Caption. Up to 5000 characters. Becomes the video description when no explicit description is given.

Title. Required, up to 100 characters. YouTube refuses an upload without a title.

Media. At least 1, at most 1; video. Exactly one video, including landscape. YouTube classifies eligible square or vertical videos up to three minutes as Shorts; there is no separate Shorts endpoint.

Video file. Through its API (YouTube Shorts): length not published · up to 256 GB. Read 2026-10-07 on YouTube Data API: Videos: insert.

How often. YouTube gives an API project 100 video uploads a day by default, shared by everybody who uploads through that project; the day starts over at midnight Pacific Time. Read 2026-10-13 on YouTube Data API: Quota calculator.

Required options. title.

Supports. schedule, thumbnail, metrics.

X (x)

Connecting. Hub posts through its provider's X app, so you need no X developer account or API credits of your own.

Needed to start the connection:

• connection_type — OAuth 2.0 is the default. OAuth 1.0a exists for apps still on the older credentials. One of: oauth2, oauth1.

Caption. Up to 280 characters. 280 is the limit for a standard account, counted the way X counts: a link is 23 however long it is, and an emoji or a Chinese, Japanese or Korean character is 2. A premium account may write far more, but Mellow cannot see the account's tier, so anything longer is reported rather than silently sent.

Media. Optional, at most 4; image or video. Up to four images, or one video. Text on its own is fine.

Video file. Through its API (X): 0.5 seconds to 20 minutes, or 125 minutes for some accounts · up to 8 GB, or 16 GB for some accounts · 1:3 to 3:1. Without Premium, X’s API takes 20 minutes; with Premium, 125 minutes. A scheduler cannot see which an account has. Read 2026-10-07 on X Developer Platform: media upload best practices.

How often. X gives an unverified account 50 original posts and 200 replies a day, split into half-hour limits. Read 2026-10-13 on X Help Center: About X limits.

Supports. schedule, carousel, poll, metrics.

LinkedIn (linkedin)

Connecting. Posts as your personal profile, or as a company page you administer.

Needed to start the connection:

• connection_type — A personal profile posts as you. A company page posts as the page and needs you to be one of its admins. One of: organization, personal.

Caption. Up to 3000 characters, and required. LinkedIn publishes nothing without commentary.

Media. Optional, at most 20; image or video. Up to twenty images, or one video.

Video file. Through its API (LinkedIn): 3 seconds to 30 minutes · up to 500 MB · at least 75 KB · MP4. Read 2026-10-07 on LinkedIn API documentation on Microsoft Learn: Videos API.

How often. LinkedIn does not publish its limits: its documentation says so, and that they are counted over 24 hours for an app and for each member, and start over at midnight UTC. Read 2026-10-13 on LinkedIn API documentation on Microsoft Learn: Rate limiting.

Supports. schedule, carousel, metrics.

Threads (threads)

Connecting. The Threads account attached to your Instagram login.

Caption. Up to 500 characters. Counted the way Threads counts: an emoji is its size in UTF-8, so 👇 is 4.

Media. Optional, at most 20; image or video. Text on its own is fine. Up to twenty items in a carousel.

Placement. timeline, reels.

Video file. Through its API (Threads): up to 5 minutes · up to 1 GB · 0.01:1 to 10:1 · up to 1920 pixels wide · MOV or MP4. Read 2026-10-07 on Meta for Developers: Threads API overview, media specifications.

How often. Threads takes 250 API-published posts from a profile within a 24-hour moving period, a carousel counting as one, and 1,000 replies. Read 2026-10-13 on Meta for Developers: Threads API overview, rate limiting.

Chains. A chain is a post and the posts that follow it in the same thread, each a reply to the one before: put them in options.threads.thread (or perChannel.<id>.thread) as a list of strings or { text, media } objects, in order. The post's own caption and media are the first of the chain; thread is what follows, up to 24 posts, each up to 500 characters (an emoji counts as its size in UTF-8) with at most one picture or video of its own. The first post must stand alone. A chain is published through the profile's own Threads sign-in through Mellow, beside the provider's channel — a person makes it once in Accounts ("Enable chains"); list_channels says chains: ready or needs_connection on each Threads channel, and a chain for a channel that is not ready is refused when the post is made (threads_chain_needs_connection), before anything goes out. A chain is one publication in the plan, goes out on Hub's own queue at the post's time (not the provider's), and is journaled. Each part is published in order; targets[].thread says how many posts the chain has and how many are on Threads. If one part fails the rest wait: the channel fails naming the part, what is out stays out, and retry_post continues from that part and never posts the first again. A chain that has begun cannot be edited, moved or cancelled. A post with no thread is an ordinary Threads post. Threads allows 250 posts and 1,000 replies per profile in 24 hours.

Supports. schedule, carousel, metrics.

Bluesky (bluesky)

Connecting. Hub connects Bluesky with your handle and an app password rather than a sign-in screen, so an agent cannot complete this step alone.

Needed to start the connection:

• handle — Your full Bluesky handle, for example name.bsky.social.
• app_password — Create one in Bluesky under Settings → App Passwords. Never your account password — an app password can be revoked on its own.

Caption. Up to 300 characters, and required. Bluesky counts graphemes, the characters as you see them: an emoji counts once, however it is built.

Media. Optional, at most 4; image or video. Up to four images, or one video.

Video file. Through its API (Bluesky): length not published · size not published. Read 2026-10-07 on Bluesky documentation: Uploading video.

How often. Bluesky counts points for an account: 5,000 an hour and 35,000 a day, three for each record created, which is at most 1,666 records an hour and 11,666 a day. Read 2026-10-13 on Bluesky documentation: Rate limits.

Supports. schedule, carousel, metrics.

Pinterest (pinterest)

Connecting. A Pinterest business account with at least one board to pin to.

Caption. Up to 500 characters. Becomes the pin description.

Title. Optional, up to 100 characters.

Media. At least 1, at most 1; image or video. One image or one video per pin. A video needs a cover: give the media item a thumbnailUrl.

Video file. Through its API (Pinterest): 4 seconds to 5 minutes · size not published · MP4, MOV or M4V. Read 2026-10-07 on Pinterest Help: Review Pin specs; Pinterest Developers: Create boards and Pins (video Pins).

How often. Pinterest publishes no number of Pins a day. For an app with Standard access it takes 100 requests a minute from a user for creating, editing or deleting boards and Pins. Read 2026-10-13 on Pinterest Developers: Rate limits.

Supports. schedule, metrics.

Facebook (facebook)

Connecting. A Facebook Page you administer. Personal timelines cannot be published to through the API.

Caption. Up to 63206 characters.

Media. Optional, at most 10; image or video. Stories take exactly one item. Reels take one video.

Placement. timeline, reels, stories.

Video file. Through its API (Facebook Reels): 3 to 90 seconds · size not published · at least 540 × 960. Read 2026-10-07 on Meta for Developers: Reels Publishing API, video specifications.

How often. Facebook’s Reels API takes 30 API-published reels within a 24-hour moving period. That page gives no figure for a Page’s other posts. Read 2026-10-13 on Meta for Developers: Reels Publishing API.

Supports. schedule, carousel, thumbnail, collaborators, mediaTags, metrics.

Telegram (telegram)

Connecting. A Telegram channel you administer. You add Mellow's bot to it with one right, to post messages; Mellow never sees your Telegram account.

Caption. Up to 4096 characters. Up to 1,024 characters sit under the media as its caption; a longer text follows the media as a message of its own. The text is read for a few marks and sent with Telegram's styles: bold, __italic__ or _italic_, ~~struck~~, ||hidden||, ` code , words, and a line that begins > as a quote. The marks are not counted in the limit, and \` before one keeps it as typed. Only Telegram reads them: the other networks of a post are sent the same text as typed, so give a styled text to the Telegram channel as its own caption.

Media. Optional, at most 10; image or video. Text on its own is fine. Up to ten items as an album. A video of up to 50 MB and a picture of up to 10 MB.

Video file. Through its API (Telegram): length not published · up to 50 MB · MP4; another format may arrive as a file. Read 2026-10-13 on Telegram Bot API: sendVideo.

How often. Telegram publishes no number of posts a day for a channel. It asks a bot to send no more than one message a second in one chat, and answers with an error to a bot that keeps going past that. Read 2026-10-13 on Telegram Bots FAQ: My bot is hitting limits.

Supports. schedule, carousel.

What a refusal means

Every error carries a code, a sentence, and retryable. Trust retryable: if it is false, the same request will fail the same way for ever, and the thing to change is the request.

A rejected post also carries issues, one per problem, each naming the channel and the field. Fix them together and try once, rather than one at a time.

An issue marked "missing": true is about something not there yet (media, text, a title, a board) rather than something wrong. A draft (draft: true) is saved with those and is asked for them when it is published or approved; anything else refuses a draft too.

Before anything is sent

Notes: what may go wrong, said before it does

validate_post and create_post return notes beside issues. A note stops nothing; it is what you tell the person, or act on, before the post goes.

After it was sent

Two failures worth naming

A partial post is not a failed post. status: "partial" means some channels published. Creating the post again duplicates those. For the channels whose target says failed, call retry_post: it sends the same post to them alone.

A channel that goes back to scheduled after sending is Hub sending it again. A network that was busy, could not process the file, or gave no reason is tried three more times within the hour; a network's limit is waited out. The target carries waiting (why, and until when). Do not send it yourself; wait for it to settle. A sign-in that ran out is different: the target reads failed with kept, and it goes out when a person signs in again within three days. retry_post cannot mend that one; say so to the person.

A timeout is not a refusal. If create_post times out, the post may exist. Retry with the same idempotency key — that is exactly what it is for — or call list_posts and look.

Worked examples

Publish a vertical video everywhere it belongs

{
  "caption": "Three minutes on why we rebuilt the editor.",
  "media": ["https://cdn.example.com/editor.mp4"],
  "channels": ["spc_ig", "spc_tiktok", "spc_youtube", "spc_threads"],
  "options": {
    "instagram": { "placement": "reels", "shareToFeed": true },
    "youtube": { "title": "Why we rebuilt the editor", "privacyStatus": "public" },
    "tiktok": { "privacyStatus": "public", "allowComment": true }
  }
}

A vertical video under three minutes becomes a Short on YouTube by itself. There is no Shorts setting to send.

One thought, different lengths

Bluesky allows 300 characters and X allows 280; LinkedIn allows 3000 and rewards using them. Write the long version once and override the short ones:

{
  "caption": "The long version, written for LinkedIn…",
  "channels": ["spc_li", "spc_bsky", "spc_x"],
  "perChannel": {
    "spc_bsky": { "caption": "The short version." },
    "spc_x": { "caption": "The short version." }
  }
}

Schedule a week

Make one create_post per slot with scheduledAt, and give each a stable idempotency key — week-32-tue-morning rather than a random value — so re-running the plan does not double-post.

Prepare something for a person to approve

Under a review key, create_post prepares the post and stops. Tell the person it is waiting; they approve it in Mellow. whoami says which mode the key is in, so check before promising to publish.

Recover from a partial failure

get_post → status "partial"
         → targets[2].status "failed", errorMessage "…"

Mellow Hub has already sent it again by itself where that helps: a busy network, a file a network could not process and a network that gave no reason get three more tries within the hour; a network's limit (429) is waited out; a post whose account's sign-in ran out is kept for three days and goes out when the person signs in again. While that is happening the channel reads scheduled with waiting (why, and until when); a kept one reads failed with kept.

For a channel that still reads failed, call retry_post with the post's id: it sends the post again to the failed channels alone. Do not create a second post for it, and do not resend the channels that published. If the message names something in the post itself, the post is out where it went and cannot be changed there: tell the person what the network said.

retry_post without an id sends again everything that failed in the last seven days. It is refused for an account whose sign-in ran out or that is no longer connected: only a person mends those, so say so plainly.