SociaHive Docs

Post options

Fields on the existing post create and update calls for alt text, video covers, separate edits, X long posts, X Articles, X reply settings, LinkedIn document posts, Instagram trial reels and collaborators, Facebook Page stories, YouTube video options, TikTok settings, and thread parts and first comments.

These are fields on the existing post endpoints (POST /api/v1/posts, PATCH /api/v1/posts/{id}), the create_scheduled_post and update_scheduled_post tools, and sociahive posts create|update. There is no new endpoint.

Every field is on every plan, except X Articles (Studio, Pro and Agency). X long posts also need an X Premium subscription on the account, and posting to X is on paid plans.

Alt text

alt_text on an image in media[] (up to 1,000 characters). Sent to Instagram, Facebook, LinkedIn, Threads, Pinterest, X and Bluesky; other platforms do not take it.

  • Agent: altText on each media item.
  • CLI: --alt "<text>", once per image, in order.

Video cover

On a video in media[]:

FieldMeaning
cover_urlAn image to use as the cover (an upload or a grabbed frame). Sent to YouTube, Instagram reels and Pinterest.
cover_time_msThe frame time in milliseconds. Sent to Instagram reels (when there is no cover_url) and TikTok.

Facebook, LinkedIn, X, Threads and Bluesky take no cover; the platform keeps its own.

  • Agent: coverUrl / coverTimeMs on each media item.
  • CLI: --video-cover <url|ms>, once per video, in order.

Edit one platform separately

platform_overrides.<platform>.detached: true keeps that platform's own text and media; it no longer follows edits to the shared content. Remove it to re-attach. Not offered on X Articles or reminder posts.

  • Agent: detachedPlatforms: ["twitter"].
  • CLI: --detached twitter (repeatable).

X long posts

An X account with X Basic, Premium or Premium+ may post up to 4,000 characters as one post. Each account's limit is text_limit in GET /api/v1/connected-accounts (and in list_accounts). A post longer than the account's limit is refused when it is scheduled, never at publish. If X refuses a long post, the error is X_LONG_POST_REFUSED and the account's subscription is read again.

X Articles

A long-form X Article is an X target with contentType: "article" (REST: platforms[].content_type). The post's text is the Article's body, in Markdown, and its images go in the Article. An Article must be the post's only target and cannot repeat. Set these in platforms[].metadata:

KeyValues
x_article_titleThe title, up to 100 characters.
x_article_formatmarkdown (default) or content_state (X's own JSON).
x_article_cover_urlThe https URL of one of the post's images, used as the cover.

X Articles are on the Studio, Pro and Agency plans; on other plans an Article is refused with FEATURE_DISABLED and never posted as a tweet. You can publish up to 20 Articles per calendar month (UTC), across all your X accounts. Past that, scheduling one for this month is refused with ARTICLE_MONTHLY_LIMIT, and an Article already scheduled fails with the same code without anything being posted. X also needs X Premium on the account to publish an Article.

X reply settings

x_reply_settings in platforms[].metadata on an X target limits who can reply to the post: following (accounts you follow), mentionedUsers (accounts the post mentions), subscribers or verified. Leave it out to let everyone reply. It does not apply to thread parts or to Articles.

LinkedIn document posts

Two or more images on a LinkedIn target can go out as one document (a swipeable PDF carousel) instead of an image post. Set these in platforms[].metadata (the agent's metadata on a target):

KeyValues
li_document"true"
li_document_titleThe title LinkedIn shows above the document, up to 400 characters. Without it, the first line of the text is used.

SociaHive builds the PDF from the images, in order, one page per image, when the post publishes. A post with fewer than two images, or with a video, is posted as usual.

Instagram trial reels

A reel can go out as a trial reel: Instagram shows it to people who don't follow you first, and your followers don't see it unless it is shared to them. Set this in platforms[].metadata on an Instagram target with contentType: "reels":

KeyValues
ig_trial_graduationMANUAL: you share it to your followers in the Instagram app. SS_PERFORMANCE: Instagram shares it to your followers if it does well with non-followers.
ig_share_to_feed"false" keeps a reel off your profile grid. Default: on the grid.

Instagram decides which accounts can post trial reels. If it refuses one, the target fails with TRIAL_REEL_REJECTED and nothing is posted; post it again without ig_trial_graduation to publish a normal reel. get_scheduled_post shows the setting in the target's metadata.

Instagram collaborators

ig_collaborators in platforms[].metadata on an Instagram feed post, carousel or reel invites up to 3 accounts as collaborators: their usernames, separated by commas, without @. The post shows on their profiles once they accept the invite in the Instagram app; Instagram checks the usernames only then. Stories cannot have collaborators.

Facebook Page stories

contentType: "story" on a Facebook target posts each image or video as a Page story instead of a post. A post whose targets are all stories may have no text.

YouTube video options

Platform options on a YouTube target, in platforms[].metadata (the agent's metadata on a target). All string values; leave one out for YouTube's default.

KeyValuesDefault
yt_titleThe video title, 1 to 100 characters, no < or >The first line of the text
yt_privacypublic, unlisted or privatepublic
yt_made_for_kids"true" or "false"The channel's own setting
yt_categoryA category id (below)22 (People & Blogs)
yt_upload_now"true"Off: the video uploads at the scheduled time
yt_tagsTags separated by commas, up to 500 characters in totalNone
yt_thumbnail_urlAn https image URL used as the custom thumbnail. If YouTube refuses it, the video still publishes and the post shows a warning.YouTube's own thumbnail

Categories: 1 Film & Animation, 2 Autos & Vehicles, 10 Music, 15 Pets & Animals, 17 Sports, 19 Travel & Events, 20 Gaming, 22 People & Blogs, 23 Comedy, 24 Entertainment, 25 News & Politics, 26 Howto & Style, 27 Education, 28 Science & Technology, 29 Nonprofits & Activism. An unknown value is dropped when the post is saved.

Title and description

  • Without yt_title, the first line of the text (or the YouTube override's text) is the title and the rest is the description.
  • With yt_title, the whole text is the description.
  • YouTube allows up to 100 characters in a title and 5,000 bytes in a description. Letters outside the Latin alphabet and emoji take 2 to 4 bytes each, so a description in those scripts fits fewer than 5,000 characters. YouTube does not allow < or > in either.

Upload now, publish at the scheduled time

With yt_upload_now: "true", the video is uploaded to YouTube right away as Private and goes public at the scheduled time, so you can add links in YouTube Studio first. Editing the post's title or time updates the video on YouTube; cancelling or deleting the post deletes it.

  • The post needs exactly one video, must be public, and must be scheduled at least 15 minutes ahead.
  • The YouTube account needs the youtube.force-ssl permission. Accounts connected before 2026-10-31 must reconnect YouTube; otherwise the post is refused with OPTION_UNAVAILABLE ("Reconnect @channel to enable early upload on YouTube.").
  • Until Google finishes verifying this permission, Google shows an "unverified app" screen when the channel is connected.
  • If YouTube refuses the early upload (for example the daily quota is used up), the video uploads at the scheduled time instead.

A post that breaks these rules still saves as a draft. Scheduling, publishing or approving it is refused with TEXT_TOO_LONG and a sentence for the YouTube target, for example "The YouTube title is 112 characters; the limit is 100. Shorten the first line or set a title."

Uploads that may have posted

YouTube has no way to make a retried upload safe: a second upload makes a second video. When an upload fails in a way that may have created the video (a timeout or a YouTube server error during the upload), SociaHive looks for it on the channel. If it is there, the post is marked published with that video. If not, the target fails with AMBIGUOUS_MAY_HAVE_POSTED ("May have posted. Check YouTube before you retry.") and is not retried by itself.

TikTok settings

Options on a TikTok target, in platforms[].metadata (the agent's metadata on a target). All string values. TikTok asks that viewers' comments, Duet and Stitch start off and the creator turns them on, so each one is off unless you set it to "true".

KeyValuesDefault
allow_comment"true" lets viewers commentOff
allow_duet"true" allows Duet (videos only)Off
allow_stitch"true" allows Stitch (videos only)Off
privacy_levelPUBLIC_TO_EVERYONE, MUTUAL_FOLLOW_FRIENDS, FOLLOWER_OF_CREATOR or SELF_ONLYPUBLIC_TO_EVERYONE
brand_organic_toggle"true" discloses that the post promotes your own businessOff
brand_content_toggle"true" discloses a paid partnership. Not with SELF_ONLYOff
tiktok_inbox_upload"true" sends the media to your TikTok inbox to finish in the appOff
tiktok_is_aigc"true" adds TikTok's AI-generated content label (videos)Off
{
  "platform": "tiktok",
  "metadata": { "allow_comment": "true", "allow_duet": "true", "allow_stitch": "true" }
}

Thread parts and first comment

Fields on a platform's own content: platforms[].parts and platforms[].firstComment on the agent tools, platform_overrides.<platform>.parts and platform_overrides.<platform>.first_comment on the REST API.

FieldPlatformsWhat happens
partsX, Threads, BlueskyUp to 10 replies posted in order under the post, as a thread. Each has the platform's text limit.
firstComment / first_commentInstagram, Facebook, LinkedIn, YouTubeOne comment posted under the post right after it goes live, as the account.
  • They are sent one at a time after the post is live. A failed part or comment never changes the post's status.
  • get_scheduled_post lists each one under the platform's followups, with its status: pending, sending, sent, failed (with the error), or unknown (it may have posted; it is not sent again by itself). The post page shows the same, with Retry.
  • The account needs permission to comment: on Facebook pages_manage_engagement, on YouTube youtube.force-ssl. An account connected without it is refused with OPTION_UNAVAILABLE ("Reconnect @account to enable a first comment on YouTube."). Reconnect the account to grant it.