Tools reference

This page lists every tool exposed by the Mixpost MCP server, grouped by area. For an overview of how to connect and authenticate, see the MCP Server overview.

Tools at a glance

Tool	Type	What it does
list-workspaces	Read	List accessible workspaces — call this first
get-workspace	Read	Details and counts for one workspace
list-accounts	Read	List connected social accounts
get-account	Read	Full details for one account
list-posts	Read	List and filter posts
get-post	Read	Full details for one post
create-post	Write	Create, and optionally schedule or publish, a post
update-post	Write	Change a post's content, accounts or tags
update-post-version	Write	Update a single content version of a post
delete-post-version	Destructive	Remove an account's own content version
attach-tags-to-post	Write	Add tags, keeping existing ones
detach-tags-from-post	Write	Remove tags from a post
duplicate-post	Write	Copy a post as a new draft
schedule-post	Write	Schedule for a time, or publish now
unschedule-post	Write	Clear the schedule and return the post to draft
add-post-to-queue	Write	Queue at the next available slot
delete-post	Destructive	Trash or permanently delete a post
restore-post	Write	Restore a post from the trash
list-tags	Read	List workspace tags
get-tag	Read	Details for one tag
create-tag	Write	Create a tag
update-tag	Write	Update a tag's name or colour
list-media	Read	List media library files
get-media	Read	Full metadata for one file
upload-media-by-url	Write	Add a file to the library from a URL
get-media-upload-status	Read	Check a background upload's progress
get-analytics-summary	Read	Workspace-wide analytics for a period
get-account-analytics	Read	One account's analytics, by type
get-post-analytics	Read	How a published post performed
get-best-posting-times	Read	Best times to post, and each account's next best slot

Common parameters

Two arguments appear across most tools:

Key	Format	Required	Description
workspace	string	required	UUID of the workspace to operate on. Obtain it from list-workspaces. Required by every tool except list-workspaces.
timezone	string	optional	IANA timezone (e.g. America/New_York) used to interpret input dates and format dates in the response. Defaults to your account timezone, then to UTC.

Write operations (create, update, schedule, delete, etc.) require the token owner to have the Member or Admin role in the workspace. See Roles and permissions.

---

Workspaces

list-workspaces

Read-only. List the workspaces the authenticated user can access, most recently updated first. Call this first — every other tool needs a workspace uuid.

Parameters: none.

Returns: count and a workspaces array of { uuid, name, role }.

get-workspace

Read-only. Get details about a single workspace: name, the user's role and approval rights, and the number of connected accounts, posts and members.

Key	Format	Required	Description
workspace	string	required	Workspace UUID.
timezone	string	optional	Timezone for returned datetimes.

Returns: a workspace object — { uuid, name, created_at, role, can_approve, accounts_count, posts_count, users_count }.

---

Accounts

list-accounts

Read-only. List the social media accounts connected to a workspace. Returns each account's numeric id (used with create-post), name, username, provider and authorization status.

Key	Format	Required	Description
workspace	string	required	Workspace UUID.
provider	string	optional	Filter by provider identifier, e.g. twitter, facebook_page, linkedin.
authorized_only	boolean	optional	When true, return only accounts whose authorization is still valid.

Returns: count and an accounts array of { id, name, username, provider, authorized }.

get-account

Read-only. Get full details for a single connected account by its numeric id, including profile image, external profile URL and provider-specific data (e.g. follower metrics).

Key	Format	Required	Description
workspace	string	required	Workspace UUID.
account_id	integer	required	Numeric id of the account. Obtain it from list-accounts.
timezone	string	optional	Timezone for returned datetimes.

Returns: an account object — { id, uuid, name, suffix, username, provider, provider_name, authorized, image, external_url, data, created_at }.

---

Posts

list-posts

Read-only. List posts in a workspace, most recent first, with optional filters. Returns a compact summary per post: uuid, status, schedule/publish/created times, accounts, tags, plain-text content and media count.

Key	Format	Required	Description
workspace	string	required	Workspace UUID.
status	string	optional	One of draft, scheduled, published, failed, needs_approval, trash.
account_ids	array<integer>	optional	Only posts assigned to any of these account ids.
tag_ids	array<integer>	optional	Only posts tagged with any of these tag ids.
keyword	string	optional	Only posts whose content contains this text.
scheduled_from	string	optional	Only posts scheduled at or after this UTC date/time. Format Y-m-d or Y-m-d H:i.
scheduled_to	string	optional	Only posts scheduled at or before this UTC date/time. A date-only value includes the whole day.
created_from	string	optional	Only posts created at or after this UTC date/time.
created_to	string	optional	Only posts created at or before this UTC date/time.
limit	integer	optional	Maximum number of posts to return (1–100). Defaults to 25.
timezone	string	optional	Timezone for returned datetimes.

Returns: count and a posts array of post summaries (see Post summary shape).

get-post

Read-only. Get the details of a single post by its uuid: status, schedule/publish times, author, tags, the accounts it targets (with live post URLs and any publish errors) and every content version with the text and the media ids of each item.

Key	Format	Required	Description
workspace	string	required	Workspace UUID.
uuid	string	required	UUID of the post. Obtain it from list-posts.
include	array<string>	optional	Extra parts of each content version to return (see below). Omitted by default.
timezone	string	optional	Timezone for returned datetimes.

Returns: a post object with author, tags, per-account publish info (external_url, errors) and the versions array. Each version carries synced_with: 0 or an account id when it follows that version (and holds a copy of its content), null when its content is its own.

Asking for more with include

Everything a version carries beyond its text costs real tokens, and most calls need none of it — so it is left out unless you name it. By default each content item returns body plus media as plain media ids, which is exactly what the write tools take back.

Value	Adds
media	Expands each media id into { id, name, type, url, alt_text }.
options	The per-provider options object of each version (see Versions).
content_urls	The url attached to each content item.
video_thumbs	The thumbnail chosen for each video: { media_id, thumb_id, thumb_url }.
all	All of the above. Ask for this only when you genuinely need everything.

{
  "workspace": "6059e1b3-e102-4be5-951b-82698abd9ee3",
  "uuid": "0f5b1c7a-2f4d-4d2e-9e2a-6f3f2d1c8b90",
  "include": ["media", "options"]
}

create-post

Writes data. Create a post and optionally schedule or publish it. Provide simple content for a single-version post, or versions for per-account content.

Key	Format	Required	Description
workspace	string	required	Workspace UUID.
account_ids	array<integer>	required	Numeric IDs of the connected accounts to post to (at least one). Obtain them from list-accounts.
content	string	optional	The text body, used as the default for every account. Required unless versions is given.
schedule	string	optional	draft (default), now (publish immediately), scheduled (publish at scheduled_at), or queue (next slot).
scheduled_at	string	optional	When to publish, format Y-m-d H:i (e.g. 2026-05-22 14:30). Required when schedule is scheduled.
tags	array<integer>	optional	Numeric tag IDs to attach. Obtain them from list-tags.
versions	array	optional	Per-account content versions (see Versions).
timezone	string	optional	Timezone for scheduled_at and returned datetimes.

Returns: a message, the created post summary, and the timezone used.

A post created to be published now, scheduled or queued must meet the publishing requirements of its accounts' platforms; otherwise the tool returns an error listing what to fix and creates nothing. A draft is not checked.

update-post

Writes data. Update an existing post's content (content or versions), target accounts and/or tags. Only the fields you provide change, and the schedule is left untouched — use schedule-post for timing, or unschedule-post to clear it. The post must not already be published, failed or publishing.

Each part is saved through the same endpoint the editor uses, so a post an agent updates goes through the same validation, per-provider option handling and events as one updated in the dashboard.

A scheduled post must still meet the publishing requirements of its accounts' platforms once the change is applied — the new content checked against the new accounts, when both change. Otherwise the tool returns an error listing what to fix and changes nothing; fix it in the same call, or unschedule-post first. A draft is not checked.

Key	Format	Required	Description
workspace	string	required	Workspace UUID.
uuid	string	required	UUID of the post. Obtain it from list-posts.
content	string	optional	New text body. Replaces the body of the post's original content.
account_ids	array<integer>	optional	Replace the targeted accounts with these account ids (at least one).
tags	array<integer>	optional	Replace the post's tags. Pass an empty array to remove all tags.
versions	array	optional	Versions to create or update (see Versions). Versions you leave out keep what they had — remove one with delete-post-version.
timezone	string	optional	Timezone for returned datetimes.

Returns: a message, the updated post summary, and the timezone used.

update-post-version

Writes data. Update a single content version of a post, leaving the others untouched. Target the original/default version with account_id 0, or an account id to update (or create) that account's version. To replace every version at once, use update-post.

Key	Format	Required	Description
workspace	string	required	Workspace UUID.
uuid	string	required	UUID of the post. Obtain it from list-posts.
account_id	integer	required	0 for the original/default version, or a connected account id for that account's version.
content	array	required	Ordered content items for this version (at least one); more than one publishes a thread.
options	object	optional	Per-provider post options, keyed by provider identifier (e.g. { "mastodon": { … } }).
timezone	string	optional	Timezone for returned datetimes.

Each item in content has body (string), media (array of media ids) and url (string), all optional. Leave media out to keep the media the item already has; pass an empty array to clear it. Video thumbnails are always preserved — they are not part of the tool's input.

options are validated against the target provider's rules and normalised the way the dashboard normalises them; options for an unknown provider are dropped. Leave options out to keep the ones the version already has.

On a scheduled post, the version must leave the post meeting the publishing requirements of its accounts' platforms; otherwise the tool returns an error listing what to fix and changes nothing.

A version that follows another (its synced_with in get-post is not null) stops following it once this tool writes its content.

Returns: a message, the updated post summary, and the timezone used.

delete-post-version

Destructive. Remove an account's own content version from a post, so that account falls back to the post's default content. The default version itself has no account and cannot be removed this way. The post must not already be published, failed or publishing.

Key	Format	Required	Description
workspace	string	required	Workspace UUID.
uuid	string	required	UUID of the post. Obtain it from list-posts.
account_id	integer	required	The connected account whose own version is removed. Obtain it from list-accounts.

Use get-post to see which accounts have a version of their own — each entry in versions carries the account_id it belongs to.

On a scheduled post, the default content the account falls back to must meet the publishing requirements of that account's platform; otherwise the tool returns an error listing what to fix and removes nothing.

Returns: a message, the post uuid and the account_id that was reverted. The post itself is not returned — the only version a post summary carries is the default one, which this call leaves alone.

attach-tags-to-post

Writes data. Attach one or more tags to a post, keeping any tags it already has. To replace a post's tags instead, use update-post.

Key	Format	Required	Description
workspace	string	required	Workspace UUID.
uuid	string	required	UUID of the post. Obtain it from list-posts.
tag_ids	array<integer>	required	Tag ids to attach (at least one), kept in addition to existing tags.
timezone	string	optional	Timezone for returned datetimes.

Returns: a message and the updated post summary.

detach-tags-from-post

Writes data. Remove one or more tags from a post, leaving its other tags in place.

Key	Format	Required	Description
workspace	string	required	Workspace UUID.
uuid	string	required	UUID of the post. Obtain it from list-posts.
tag_ids	array<integer>	required	Tag ids to remove (at least one).
timezone	string	optional	Timezone for returned datetimes.

Returns: a message and the updated post summary.

duplicate-post

Writes data. Duplicate an existing post. Creates a new draft copy with the same accounts, tags and content versions; the copy is never scheduled or published.

Key	Format	Required	Description
workspace	string	required	Workspace UUID.
uuid	string	required	UUID of the post to duplicate.
timezone	string	optional	Timezone for returned datetimes.

Returns: a message and the new draft post summary.

schedule-post

Writes data. Schedule an existing post for a specific date/time, or publish it immediately with post_now. The post must have at least one account, a future scheduled time, content the platform of every account can publish, and must not already be published, failed or publishing.

Key	Format	Required	Description
workspace	string	required	Workspace UUID.
uuid	string	required	UUID of the post. Obtain it from list-posts.
scheduled_at	string	optional	When to publish, format Y-m-d H:i. Required unless post_now is true or the post already has a scheduled time.
post_now	boolean	optional	When true, publish immediately instead of scheduling.
timezone	string	optional	Timezone for scheduled_at and returned datetimes.

Returns: a message and the updated post summary. If the workspace requires approval, the post becomes needs_approval; otherwise it is queued for publishing.

The post must also meet the publishing requirements of its accounts' platforms — media for an Instagram post, a board for Pinterest, a title for YouTube. Otherwise the tool returns an error listing what to fix, and the post stays as it was.

unschedule-post

Writes data. Clear a post's scheduled time and take it back to draft, so it stays put until it is scheduled again. Its accounts, tags and content are untouched. Works on a scheduled post, one waiting in the queue and one awaiting approval; a post that has already been published or failed, or one being published right now, cannot be unscheduled.

Key	Format	Required	Description
workspace	string	required	Workspace UUID.
uuid	string	required	UUID of the post. Obtain it from list-posts.

Returns: a message and the post uuid. The post itself is not returned — nothing but the schedule changed.

Use schedule-post to put it back on the calendar, or add-post-to-queue to send it to the next free slot.

add-post-to-queue

Writes data. Add an existing post to the posting queue — it is scheduled at the next available slot of the workspace's posting schedule. The post must have at least one account, content the platform of every account can publish, and must not already be published, failed or publishing.

Key	Format	Required	Description
workspace	string	required	Workspace UUID.
uuid	string	required	UUID of the post. Obtain it from list-posts.
timezone	string	optional	Timezone for returned datetimes.

Returns: a message and the updated post summary. The workspace must have posting schedule times configured.

The post must also meet the publishing requirements of its accounts' platforms; otherwise the tool returns an error listing what to fix, and the post stays as it was.

delete-post

Destructive. Delete a post. By default it is moved to the trash and can be restored; set permanent to true to delete it irreversibly. Use delete_mode to also remove the published post from the connected social platforms.

Key	Format	Required	Description
workspace	string	required	Workspace UUID.
uuid	string	required	UUID of the post. Obtain it from list-posts.
delete_mode	string	optional	app_only (default), social_only, or app_and_social.
permanent	boolean	optional	When true, permanently delete instead of moving to trash. Only applies when removing from Mixpost. Defaults to false.

Returns: a message and the deleted post's uuid.

restore-post

Writes data. Restore a post from the trash. The post is recovered as a draft. Only posts moved to the trash (not permanently deleted) can be restored. Find them with list-posts using status: "trash".

Key	Format	Required	Description
workspace	string	required	Workspace UUID.
uuid	string	required	UUID of the trashed post.
timezone	string	optional	Timezone for returned datetimes.

Returns: a message and the restored post summary.

---

Tags

list-tags

Read-only. List the tags defined in a workspace.

Key	Format	Required	Description
workspace	string	required	Workspace UUID.

Returns: count and a tags array of { id, name, hex_color }.

get-tag

Read-only. Get details for a single tag by its numeric id.

Key	Format	Required	Description
workspace	string	required	Workspace UUID.
tag_id	integer	required	Numeric id of the tag. From list-tags.

Returns: a tag object — { id, name, hex_color }.

create-tag

Writes data. Create a tag in a workspace.

Key	Format	Required	Description
workspace	string	required	Workspace UUID.
name	string	required	The tag name (max 255 characters).
hex_color	string	required	The tag colour as a hex code, e.g. #1d9bf0.

Returns: a message and the created tag.

update-tag

Writes data. Update a tag's name and/or colour. Only the fields you provide change.

Key	Format	Required	Description
workspace	string	required	Workspace UUID.
tag_id	integer	required	Numeric id of the tag. From list-tags.
name	string	optional	New tag name (max 255 characters).
hex_color	string	optional	New tag colour as a hex code, e.g. #1d9bf0.

Returns: a message and the updated tag.

---

Media

list-media

Read-only. List the media files (images, GIFs and videos) in a workspace's library, newest first. Returns each file's numeric id (which can be attached to a post version), name, type and URL.

Key	Format	Required	Description
workspace	string	required	Workspace UUID.
type	string	optional	Filter by image, gif, or video.
limit	integer	optional	Maximum number of files to return (1–100). Defaults to 50.
timezone	string	optional	Timezone for returned datetimes.

Returns: count and a media array of summaries — { id, uuid, name, type, mime_type, url, alt_text, created_at }.

get-media

Read-only. Get the full metadata for a single media file by its uuid.

Key	Format	Required	Description
workspace	string	required	Workspace UUID.
uuid	string	required	UUID of the media file. From list-media.
timezone	string	optional	Timezone for returned datetimes.

Returns: a media object — { id, uuid, name, type, mime_type, url, thumb_url, alt_text, source, … }.

upload-media-by-url

Writes data. Upload a media file to the library by downloading it from a public URL. Small files are downloaded immediately and returned; large files download in the background and appear in list-media once complete.

Key	Format	Required	Description
workspace	string	required	Workspace UUID.
url	string	required	Publicly accessible URL of the media file to download.
alt_text	string	optional	Alternative text describing the media (max 255 characters).
timezone	string	optional	Timezone for returned datetimes.

Returns: for a small file, a message and the uploaded media. For a large file, a message, status: "pending" and a download_id — poll it with get-media-upload-status.

get-media-upload-status

Read-only. Check the progress of a background media download started by upload-media-by-url.

Key	Format	Required	Description
workspace	string	required	Workspace UUID.
download_id	string	required	The download_id returned by upload-media-by-url for a large file.
timezone	string	optional	Timezone for returned datetimes.

Returns: while in progress, a status (pending, downloading, processing) and a progress percentage; on completion, status: "completed" and the uploaded media; on failure, an error message.

---

Analytics

The analytics tools report the same figures as the analytics pages of the dashboard. Every date is a UTC day — get-analytics-summary, get-account-analytics and get-post-analytics take no timezone — and every chart is a list of points: { date, value } for a time series (days as YYYY-MM-DD, months as YYYY-MM) and { label, value } for a breakdown such as ages or countries. A figure compared with the previous period comes as { value, change }, where change is the percentage difference, or null when there is nothing to compare with.

get-analytics-summary and get-account-analytics share the period arguments:

Key	Format	Required	Description
period	string	optional	One of this_week, last_week, this_month, last_month, last_3_months, this_year. Defaults to this_month. Ignored when a custom range is given.
date_from	string	optional	First day of a custom range, YYYY-MM-DD. Send it together with date_to; the range may span at most 366 days.
date_to	string	optional	Last day of a custom range, YYYY-MM-DD, on or after date_from.

Both return a period object — { start_date, end_date, previous_start_date, previous_end_date } — naming the days the figures cover and the range of the same length they are compared with.

get-analytics-summary

Read-only. The workspace at a glance, across every connected account that supports analytics: total followers, follower growth and post count against the previous period, the best growing account and the one that needs attention, a daily audience chart, a follower leaderboard, the follower distribution and posting consistency.

Key	Format	Required	Description
workspace	string	required	Workspace UUID.
period, date_from, date_to		optional	See above.

Returns: period and a summary object — { total_followers, follower_growth, total_posts, best_account, needs_attention, audience_chart, leaderboard, most_active, least_active, follower_distribution, posting_streak }. Accounts inside it use the compact { id, name, username, provider, authorized } shape.

get-account-analytics

Read-only. One account's analytics for a period. Analytics are split into types, and each provider supports its own set: overview, engagement, content, hashtags, insights, audience, reach, video, competitors, search_terms and reviews. Call it without type first — the response lists the types the account supports in tabs.

Key	Format	Required	Description
workspace	string	required	Workspace UUID.
account_id	integer	required	Numeric id of the account. Obtain it from list-accounts.
type	string	optional	The analytics type to return. Defaults to the account's default type, overview.
period, date_from, date_to		optional	See above.
page	integer	optional	Page to return for the content and reviews types. Defaults to 1.
per_page	integer	optional	Items per page for content and reviews (1–50). Defaults to 25 posts or 10 reviews.
sort_by	string	optional	Metric to sort content posts by, as named in their metrics (e.g. IMPRESSION_COUNT). Defaults to newest first.
sort_dir	string	optional	asc or desc. Defaults to desc.

Returns: { account, type, tabs, period, initial_sync, data }. data holds the analytics of the requested type; its keys depend on the provider and the type. When initial_sync.in_progress is true the account is still importing its history and the figures are incomplete. A type the account does not support is refused with the list of the supported ones.

get-post-analytics

Read-only. How a published post performed on every account it went out to: views, likes, comments and shares added up, their trend over time, the engagement rate, breakdown, reach-to-engagement funnel and peak day, plus the same figures per account with the provider's own metrics and how the post compares with that account's average post.

Key	Format	Required	Description
workspace	string	required	Workspace UUID.
uuid	string	required	UUID of the post. Obtain it from list-posts.

Returns: { post_uuid, summary, winner, accounts }. winner is the account with the highest engagement rate, or null when the post went out to fewer than two accounts. Each entry of accounts is keyed by the numeric account_id. Trends hold the daily change; a post tracked for 60 days or more is grouped by week, and one tracked for 180 days or more by month, each point dated with the first day it covers.

get-best-posting-times

Read-only. The best times to post, learned from how the past posts of the chosen accounts performed. Scores run from 0 to 100, where 50 is neutral. Unlike the other analytics tools, days and hours are in the returned timezone.

Key	Format	Required	Description
workspace	string	required	Workspace UUID.
account_ids	array<integer>	optional	Numeric ids of the accounts to consider. Defaults to every account in the workspace.
from	string	optional	Day to look for the next slots from, YYYY-MM-DD. Defaults to now; a day in the past counts as now.
include_intervals	boolean	optional	When true, also return every weekday split into 2-hour intervals with their score and confidence.
timezone	string	optional	Timezone for the returned days and hours.

Returns: { timezone, has_data, samples, best, next_slots }, plus intervals when requested.

• best — up to three { day, hour, score, samples } slots scoring highest across the accounts together, at most one per weekday; day is a weekday name such as tuesday.
• next_slots — for each account, { account_id, date, time, scheduled_at }: the next time its own best slot comes round, within 14 days and never in the past. Pass scheduled_at to schedule-post with the same timezone. An account with too little history is left out.
• intervals — keyed by weekday name, each a list of twelve { start_hour, end_hour, best_hour, score, samples, confidence } intervals.

has_data is false when none of the accounts has scored history yet.

---

Provider identifiers

The provider value on an account — and the provider filter on list-accounts — uses these identifiers:

Identifier	Platform
twitter	X (Twitter)
facebook_page	Facebook Page
instagram	Instagram (via a Facebook Page)
instagram_standalone	Instagram (standalone)
threads	Threads
linkedin	LinkedIn (profile)
linkedin_page	LinkedIn Page
tiktok	TikTok
pinterest	Pinterest
youtube	YouTube
gbp	Google Business Profile
mastodon	Mastodon
bluesky	Bluesky
pixelfed	Pixelfed

---

Versions

The create-post, update-post and update-post-version tools support per-account content versions, so a single post can have different text or media for each network. The structure mirrors the REST API's post versions:

{
  "versions": [
    {
      "account_id": 0,
      "content": [
        {
          "body": "This is the default content used for every account.",
          "media": [1],
          "url": null
        }
      ],
      "options": {
        "mastodon": { "sensitive": false }
      }
    },
    {
      "account_id": 12,
      "content": [
        { "body": "A custom version just for this account." }
      ]
    }
  ]
}

Key	Format	Required	Description
versions.*.account_id	integer	required	The account this version targets. Use 0 for the original/default version.
versions.*.content	array	required	Ordered content items. Provide more than one to publish a thread.
versions.*.content.*.body	string	optional	The text body of this content item.
versions.*.content.*.media	array<integer>	optional	Media IDs to attach. Obtain them from list-media or upload-media-by-url.
versions.*.content.*.url	string	optional	A URL associated with the content (supported by Facebook and LinkedIn).
versions.*.options	object	optional	Options available for each social service provider. Only keys matching a registered provider are kept — unknown keys are silently dropped, and rules are applied only for the provider keys you actually send. { "facebook_page": { "type": "post" // post,reel,story }, "instagram": { "type": "post" // post,reel,story }, "instagram_standalone": { "type": "post" // post,reel,story | Same options as `instagram` }, "linkedin": { "visibility": "PUBLIC" // PUBLIC,CONNECTIONS | Required when the `linkedin` object is present }, "linkedin_page": { "visibility": "PUBLIC" // PUBLIC,CONNECTIONS | Same options as `linkedin` }, "mastodon": { "sensitive": false // boolean | Marks the post's media as sensitive }, "pixelfed": { "type": "post", // post,story "sensitive": false, // boolean "duration": 10, // integer | Story duration in seconds (1-30). Only applies if type is `story` "can_reply": true, // boolean "can_react": true // boolean }, "pinterest": { "link": null, // null|string "title": "", // string "boards": { "account-1": "971672010430333260" // string | The key `account-*` is the ID of your Pinterest account } }, "youtube": { "title": null, // null|string "status": "public", // public,private,unlisted "made_for_kids": false // boolean }, "gbp": { // Google Business Profile "type": "post", // post,offer,event "button": "NONE", // NONE,BOOK,ORDER,SHOP,LEARN_MORE,SIGN_UP,CALL "button_link": "", // string | Leave empty if button is `NONE` or `CALL` "offer_has_details": false, // boolean | Only applies if type is `offer` "coupon_code": "", // string | Only applies if type is `offer` and `offer_has_details` is true "offer_link": "", // string | Only applies if type is `offer` and `offer_has_details` is true "terms": "", // string | Only applies if type is `offer` and `offer_has_details` is true "event_title": "", // string | Only applies if type is `event` or `offer` "start_date": null, // null|string | Only applies if type is `event` or `offer` "end_date": null, // null|string | Only applies if type is `event` or `offer` "event_has_time": false, // boolean | Only applies if type is `event` "start_time": "09:00", // string | Only applies if type is `event` and `event_has_time` is true "end_time": "17:00" // string | Only applies if type is `event` and `event_has_time` is true }, "tiktok": { // For every `tiktok` option, the key `account-*` is the ID of your TikTok account "privacy_level": { "account-2": "PUBLIC_TO_EVERYONE" // string | PUBLIC_TO_EVERYONE,MUTUAL_FOLLOW_FRIENDS,FOLLOWER_OF_CREATOR,SELF_ONLY }, "allow_comments": { "account-2": true // boolean }, "allow_duet": { "account-2": false // boolean }, "allow_stitch": { "account-2": false // boolean }, "is_aigc": { "account-2": false // boolean | Flags the content as AI-generated }, "auto_add_music": { "account-2": false // boolean }, "content_disclosure": { "account-2": false // boolean }, "brand_organic_toggle": { "account-2": false // boolean }, "brand_content_toggle": { "account-2": false // boolean } } } twitter, threads and bluesky are registered providers but define no options — send {} (or omit them). In responses, the options object always contains a key for every registered provider, so these appear as {} even when you didn't send them.

Every post needs a default version

The version with account_id 0 is the default content, applied to every account that does not have its own account-specific version.

• With create-post, exactly one version must have account_id 0 — the post has no content yet.
• With update-post, the versions you send are created or updated and the rest are left alone, so 0 only has to be included if the post does not already have a default version.

Updating does not wipe what you leave out

A content item you send replaces the stored one, but the keys you omit are carried over from it: leave media or url out and the item keeps them, and video thumbnails are always preserved since they are not part of the tools' input. Pass an empty media array to actually clear the media.

Removing an account's version is a separate call — delete-post-version — never something that happens because you left it out of versions.

---

Post summary shape

Most post tools return a compact summary optimised for agents (the heavy web payload is omitted to save tokens):

{
  "uuid": "6059e1b3-e102-4be5-951b-82698abd9ee3",
  "status": "scheduled",
  "scheduled_at": "2026-07-01 09:00:00",
  "published_at": null,
  "created_at": "2026-06-25 14:12:03",
  "accounts": [
    { "id": 12, "name": "Acme", "username": "acme", "provider": "twitter", "authorized": true }
  ],
  "tags": [
    { "id": 3, "name": "Launch" }
  ],
  "content": "We just shipped a big update 🚀",
  "media_count": 1
}

status is one of draft, scheduled, published, failed, needs_approval, publishing or trash. content is the plain text of the post's original version, with multiple content items joined by blank lines.