# Get Analytics Source: https://docs.mallary.ai/api-reference/endpoint/analytics GET /api/v1/analytics Get the latest post metrics and audience counts for one Mallary profile. Use `profile_id` to read analytics for a non-default connection profile. Omit it to read analytics for the default profile. The response has two lists: * `data.analytics` has the latest metrics for recent posts. Use `post_id` to limit this list to one post. * `data.audience` has the latest saved follower or subscriber count for each connected account in the profile. It uses the same fields and statuses as [Get Audience Counts](/api-reference/endpoint/audience). The `post_id` filter does not change this list. Mallary updates supported audience counts once every 24 hours. TikTok follower counts become available after a connection grants `user.info.stats` and Mallary saves its first count. Existing connections without that permission return `permission_required` for their audience count. They keep working as before. For LinkedIn Page posts, Mallary shows LinkedIn impressions as views. LinkedIn likes and comments use the same fields as your other platforms, so your results stay easy to compare. If an older LinkedIn connection needs the analytics permission, the response uses `status: "reconnect_required"` and says `Reconnect to get analytics`. Reconnect LinkedIn once from the Platforms page. Mallary will then start collecting those post results. # Attach a TikTok Post URL Source: https://docs.mallary.ai/api-reference/endpoint/attach-tiktok-post-url POST /api/v1/jobs/{id}/tiktok/post-url Save the final TikTok post URL after a manual TikTok upload is complete. Use this endpoint only when a TikTok publishing job asks the creator to finish the upload in TikTok. Send the job ID from `POST /api/v1/post` and the final public TikTok video or photo URL. Mallary saves the TikTok post ID and URL, marks the job complete, and queues an analytics refresh. Accepted URLs include: * `https://www.tiktok.com/@handle/video/1234567890` * `https://www.tiktok.com/@handle/photo/1234567890` The endpoint returns an error if the job is not a TikTok job or does not need a final URL. # Get Audience Counts Source: https://docs.mallary.ai/api-reference/endpoint/audience GET /api/v1/audience Get the latest follower or subscriber count for every connected account in one Mallary profile. Mallary updates supported audience counts once every 24 hours. Use `profile_id` for a non-default profile. Omit it to use the default profile. The response includes every connected account. `count` is the latest saved number when Mallary can collect it. * YouTube returns `subscribers`. * Facebook Pages, Instagram, Threads, TikTok, X, Pinterest, and Bluesky return `followers`. Facebook may return `page_likes` when that is the only count the Page gives Mallary. * TikTok follower counts become available after a connection grants `user.info.stats` and Mallary saves its first count. Existing connections without that permission return `permission_required` for their audience count. They keep working as before. * LinkedIn returns `permission_required` until Mallary adds the permission it needs. * Other platforms may return `unsupported` when they do not provide an account audience count. Mallary does not add the counts together. The same person may follow more than one account. [Get Analytics](/api-reference/endpoint/analytics) returns the same list in `data.audience`, alongside post metrics. # List Comments Source: https://docs.mallary.ai/api-reference/endpoint/comments GET /api/v1/comments List the comments on a post that you published with Mallary. Available on all plans. Use `post_id` with the Mallary job/post ID returned by the posts API. If that ID belongs to a grouped multi-platform post and you omit `platform`, Mallary reads every supported platform job in the group. It then returns a combined comment list. The response uses `platform: "multiple"`, and each comment includes its concrete `platform` and `post_id`. For platforms that Mallary cannot read, `platform_errors` can include the read failures. If you want one platform from a grouped post, pass `platform`. Mallary then routes the request to the matching sibling job in that group. When the platform returns them, Mallary includes own/initial comments. When Mallary identifies the author as the connected account, these comments have `is_own: true` and `can_reply: false`. For a LinkedIn Page post, Mallary reads comments for the Page you selected when you connected LinkedIn. A comment can include the person's name and LinkedIn ID when LinkedIn sends them. LinkedIn may ask you to reconnect once so Mallary can read Page comments. # Reply to Comment Source: https://docs.mallary.ai/api-reference/endpoint/comments-reply POST /api/v1/comments/reply Reply to a specific comment on a post that you published using Mallary. Available on all plans. Mallary posts the exact `message` you send. Your AI agent or script must write the reply. For a LinkedIn Page post, Mallary sends the reply as the Page you selected. LinkedIn may ask you to reconnect once so Mallary can reply as that Page. # Create Post Source: https://docs.mallary.ai/api-reference/endpoint/create POST /api/v1/post Create or schedule a post across one or more connected platforms. ## Connection Profiles Use `profile_id` to publish from a non-default connection profile. Omit it to use the default profile. Connection profiles let one Mallary user connect multiple accounts on the same platform. Plan caps per platform are: Free 1, Starter 4, Pro 10, Business 50. ## Scheduling * If you already know the exact UTC or offset time, use `scheduled_at` with an absolute timestamp like `2026-04-06T18:30:00Z`. * To resolve the post in a specific timezone, use a local `scheduled_at` like `2026-04-06T14:30` plus `scheduled_timezone` with an IANA timezone like `America/New_York`. * Mallary stores the resolved publish time in UTC and returns the original `scheduled_timezone` on grouped post reads. ## Publish Results Post creation is asynchronous. The create response returns one Mallary job ID per platform immediately, with `platform_post_id` and `platform_post_url` set to `null` until that platform finishes publishing. After completion, use `GET /api/v1/jobs/{id}` or `GET /api/v1/posts`. These return the platform post ID and the public post URL that the platform exposes. ## Video Thumbnails Attach a custom thumbnail or cover to a video media item with `thumbnail_url`. ```json theme={null} { "message": "Launch walkthrough", "platforms": ["youtube", "facebook", "instagram", "tiktok"], "media": [ { "url": "https://files.mallary.ai/uploads/launch-video.mp4", "type": "video/mp4", "thumbnail_url": "https://files.mallary.ai/uploads/launch-cover.jpg" } ] } ``` `thumbnail_url` must be a Mallary-hosted image URL, usually created with `POST /api/v1/upload`. Mallary skips a thumbnail that is unsupported for the platform, wrong for the post type, or rejected by the provider. It then continues to publish the post where possible. To use a different cover for each platform, put `thumbnail_url` inside that platform's options. For example, use `platform_options.youtube.thumbnail_url` for YouTube and `platform_options.instagram.thumbnail_url` for Instagram. Mallary adds each cover only to that platform's video. Current thumbnail behavior: * YouTube regular videos: supported. Use a `jpg`, `jpeg`, or `png` image up to 50 MB. Use 16:9 and at least 640px wide. * YouTube Shorts: YouTube may accept and store the image but show a video frame instead. Mallary warns you because the YouTube API cannot confirm the cover viewers will see. Use YouTube Studio to add a custom image, or use the YouTube app to choose a frame. * Facebook feed videos: supported. Mallary accepts `jpg`, `jpeg`, or `png` thumbnail images up to 10 MB and retries without the thumbnail if Meta rejects it. * Instagram videos/Reels: supported with a Mallary-hosted `cover_url`. Use a cover image that matches the video placement, such as 9:16 for Reels/stories. If Meta rejects a cover variant, Mallary falls back to video creation without the cover. * TikTok video posts: TikTok currently exposes frame-based cover selection through `video_cover_timestamp_ms`, not arbitrary image thumbnails. If `thumbnail_url` is supplied, Mallary does not send `video_cover_timestamp_ms` and lets TikTok use its default cover behavior. * TikTok photo posts: `thumbnail_url` can choose the photo cover only when it exactly matches one of the image URLs in `media[]`. Mallary then uses that image index as `photo_cover_index`. Mallary does not upload it as an extra photo. ## Platform-Specific Media Rules Mallary validates media before it queues a platform job. The public API and the current publishers enforce these media rules. For a simple guide to each setting, see [Platform Posting Options](/api-reference/platform-options). ### Facebook * Feed posts can be text-only, link-only, up to 10 images, or 1 video. * Facebook does not allow mixing images and video in the same post. * Feed images accept `jpg`, `jpeg`, `png`, `gif`, and `webp`. Feed video accepts `mp4` and `mov`. * Facebook stories support 1 image or 1 video. * Facebook Reels use 1 MP4 or MOV video. The video must be 9:16, at least 540 by 960 pixels, and 3 to 90 seconds long. * Choose `feed`, `story`, or `reel` with `platform_options.facebook.post_type`. * `platform_options.facebook.message` sets a Facebook-specific message. Omit it to use the top-level `message`. ### Instagram * Instagram requires media. * The validator currently defines: feed = 1 image or 1 video, story = 1 image or 1 video, reel = 1 video, carousel = 2 to 10 mixed image/video items. * The publisher uses the matching Instagram container flow for `feed`, `story`, `reel`, and `carousel` when selected through `platform_options.instagram.post_type`. * `platform_options.instagram.message` sets an Instagram-specific caption. Omit it to use the top-level `message`. * For a Reel, `platform_options.instagram.shareToFeed` defaults to `true`. Set it to `false` to keep the Reel in the Reels tab and off the profile feed. * To publish a Trial Reel, add `platform_options.instagram.trialParams.graduationStrategy`. Use `MANUAL` to choose later in Instagram, or `SS_PERFORMANCE` to let Instagram share it with followers if it performs well. Do not add `shareToFeed` to a Trial Reel request. * Set `platform_options.instagram.isPaidPartnership` to `true` to show the Paid partnership label on a feed post, Reel, or carousel. * Add up to two sponsor usernames or numeric user IDs with `platform_options.instagram.brandedContentSponsors`. Sponsors turn on the Paid partnership label too. * Paid partnership options do not work with Stories. They require an Instagram account connected through Facebook Login. * Instagram's publishing API does not support story captions or follow-up comments. Include story text in the media itself. * Instagram image uploads use `jpg`, `jpeg`, or `png`. Video uploads use `mp4` or `mov`. * Instagram Reels and single feed videos must be 3 seconds to 15 minutes long and no larger than 300 MB. Single feed videos publish as Reels shared to the feed. ### LinkedIn * LinkedIn supports text-only posts, one image or GIF, or one MP4 video. * Videos can be up to 1 GB (1,073,741,824 bytes) and 3 seconds to 30 minutes long. Do not mix images and video. * Upload media to Mallary first. Use the returned `files.mallary.ai` URL or `storageKey`. * Mallary uploads the video to LinkedIn and waits for processing before it publishes the post. * LinkedIn image attachments accept `jpg`, `jpeg`, `png`, or `gif`. * `platform_options.linkedin.message` sets a LinkedIn-specific message. Omit it to use the top-level `message`. ### Threads * Threads supports four posting shapes: `text`, `image`, `video`, and `carousel`. * Text posts are text-only and cannot include media. * Image posts support exactly 1 image in `jpg`, `jpeg`, `png`, or `webp`. * Video posts support exactly 1 video in `mp4` or `mov`. * Carousel posts support 2 to 20 supported media items total. * `platform_options.threads.post_type` can be `text`, `image`, `video`, or `carousel`. * If you omit `platform_options.threads.post_type`, Mallary chooses from the payload: no media = `text`, one image = `image`, one video = `video`, multiple supported media items = `carousel`. * `platform_options.threads.message` sets a Threads-specific message. Omit it to use the top-level `message`. * Threads currently supports `comments_under_post`. ### YouTube * YouTube requires exactly one video. * `regular` video supports one video up to 12 hours and up to 256 GB. * `shorts` supports one video up to 3 minutes. Use vertical video. * YouTube posting does not support images. * `platform_options.youtube.message` sets a YouTube-specific description/default-title source. Omit it to use the top-level `message`. * `platform_options.youtube.title` sets the YouTube title and takes precedence over the first line of the effective message. * `platform_options.youtube.tags` adds video tags. Each tag can use up to 100 characters, and YouTube allows 500 characters across the full tag list after counting separators. * `platform_options.youtube.containsSyntheticMedia` accepts `true` or `false`. Set it to `true` when the video contains realistic AI-generated or altered content that could look real. YouTube may show a disclosure label. * `platform_options.youtube.playlist_id` adds the new video to an existing playlist owned by the connected YouTube channel. Mallary checks the playlist before upload. ### TikTok * TikTok video posts support one video file in `mp4`, `mov`, or `webm`. * TikTok photo posts support up to 35 images in `jpg`, `jpeg`, or `webp`. * `platform_options.tiktok.post_type` can be `video` or `photo`. * `platform_options.tiktok.post_mode` can be `DIRECT_POST` or `MEDIA_UPLOAD`. * TikTok defaults to `DIRECT_POST`, which publishes the post through Mallary. * Use `MEDIA_UPLOAD` only when you want Mallary to send the upload to the TikTok inbox. The job stays `action_required` until you finish the post in TikTok and attach its final TikTok URL. * For TikTok video posts, `platform_options.tiktok.source` can be `FILE_UPLOAD` or `PULL_FROM_URL`. * For TikTok photo posts, TikTok only allows `PULL_FROM_URL`. * For TikTok `PULL_FROM_URL`, Mallary only accepts media already hosted on the Mallary CDN (`https://files.mallary.ai/...`). * `platform_options.tiktok.message` sets a TikTok-specific caption/title fallback. Omit it to use the top-level `message`. * `platform_options.tiktok.title` sets the TikTok title and takes precedence over the effective message where TikTok accepts a title. * `platform_options.tiktok.description` sets the TikTok photo description. * Direct-post TikTok options include `privacy_level`, `disable_comment`, `disable_duet`, `disable_stitch`, `video_cover_timestamp_ms`, `auto_add_music`, `brand_content_toggle`, `brand_organic_toggle`, `is_aigc`, and `photo_cover_index` where applicable. * TikTok posts do not currently support `comments_under_post`. ### Pinterest * Pinterest requires exactly one image or GIF, or exactly one video. * Pinterest does not allow mixing image and video in the same Pin. * Image Pins accept one `jpg`, `jpeg`, `png`, `webp`, or `gif` file up to 32 MB. * Video Pins accept one `mp4` or `mov` file, 4 seconds to 15 minutes, up to 2 GB. * A Pinterest board is required. Send `boardId`, or use the board saved with the Pinterest connection. * `platform_options.pinterest.message` sets a Pinterest-specific description/default title source. Omit it to use the top-level `message`. Pinterest allows 800 characters in a description. Mallary shortens longer descriptions to fit. ### Reddit * `text` and `link` posts do not upload media through the Mallary API. * `image` posts require one image or GIF up to 20 MB. * The current public API path does not support Reddit video upload. To point at externally hosted video, use a link post. * `subreddit` or `subredditName` is required in platform options. * `platform_options.reddit.message` sets a Reddit-specific title/text source. Omit it to use the top-level `message`. ### Bluesky * Bluesky supports a text-only post, up to four images, or one video. * Images can be `jpg`, `jpeg`, `png`, or `webp`, up to 2 MB each. * Video must be one `mp4` file, up to 300 MB. Bluesky may apply a daily video limit to an account. * A Bluesky post can have up to 300 characters. * `platform_options.bluesky.message` sets a Bluesky-specific message. Omit it to use the top-level `message`. * `platform_options.bluesky.languages` adds up to three language codes. `langs` is also accepted. * Add `alt_text` to a media item to describe an image or video for people who use screen readers. * Bluesky supports up to three `comments_under_post` replies. ### X * X allows up to 4 images, or 1 video, or 1 GIF. * X does not allow mixing images and video in the same post. * GIFs cannot be combined with other attachments. * X images accept `jpg`, `jpeg`, `png`, `webp`, and `gif`. Video accepts `mp4` or `mov`. * X video limits depend on the connected X account. Standard accounts can use videos up to 20 minutes and 8 GB. Eligible Premium or verified accounts can use videos up to 125 minutes and 16 GB. Mallary checks the connected account before accepting a video above the standard limits. * Mallary's current upload endpoint accepts files up to 5 GB. This upload limit still applies even when X allows a larger file for the connected account. * `platform_options.x.message` or `platform_options.twitter.message` sets an X-specific message. Omit it to use the top-level `message`. # Delete Pending Post Source: https://docs.mallary.ai/api-reference/endpoint/delete DELETE /api/v1/posts/{id} Delete a grouped post before publishing has started. # Disconnect Platform Source: https://docs.mallary.ai/api-reference/endpoint/disconnect POST /api/v1/disconnect Disconnect one of the authenticated user's linked platforms. Use `profile_id` to disconnect a platform from a non-default connection profile. Omit it to disconnect from the default profile. # Get Job Source: https://docs.mallary.ai/api-reference/endpoint/get GET /api/v1/jobs/{id} Retrieve job status, result payload, and user warnings. When the platform returns or exposes them, completed publishing jobs include normalized `platform_post_id` and `platform_post_url` fields. The raw provider result remains available in `data.job.result`. # Get Post for Editing Source: https://docs.mallary.ai/api-reference/endpoint/get-scheduled-post GET /api/v1/posts/{id} Read a grouped post, its current revision, and whether it can still be edited. Use a Mallary job ID from the post. If the post has several platforms, any job ID from that group works. The response includes `data.revision` and `data.editable`. Read both before you [edit the scheduled post](/api-reference/endpoint/update-scheduled-post). It also shows the saved profile, platforms, media, and schedule. If you send `profile_id` in the query, use the post's **current** profile ID. This query does not move the post to another profile. ```bash theme={null} curl 'https://mallary.ai/api/v1/posts/12345' \ -H "Authorization: Bearer $MALLARY_API_KEY" ``` # List Connected Platforms Source: https://docs.mallary.ai/api-reference/endpoint/platforms GET /api/v1/platforms List Mallary-supported platforms and see which ones are connected for the authenticated account. Use `profile_id` to read a non-default connection profile. The response also includes the profile list, default profile id, and the plan's per-platform account cap. Each platform row includes `post_types` and `post_type_selection`. For example, Facebook and Instagram include `story`. An empty `post_types` list with `post_type_selection: "automatic"` means Mallary chooses the format from the content and media. # List Posts Source: https://docs.mallary.ai/api-reference/endpoint/posts GET /api/v1/posts List grouped multi-platform posts with per-platform results, retries, warnings, and capabilities. Use `profile_id` to list grouped posts for a non-default connection profile. Omit it to list the default profile. Each post includes per-platform `results`. When the platform returns or exposes those values, completed platform results include `platform_post_id` and `platform_post_url`. To change a scheduled post, [get its current revision](/api-reference/endpoint/get-scheduled-post), then [edit the post](/api-reference/endpoint/update-scheduled-post). # List Connection Profiles Source: https://docs.mallary.ai/api-reference/endpoint/profiles GET /api/v1/profiles List connection profiles, connected platforms per profile, and plan account limits. Connection profiles group your social media accounts. Create one profile for each of your businesses. Then connect the social media accounts of that business inside its profile. If you do not send a `profile_id`, Mallary uses your default profile. Each profile has a random public ID, such as `AbC123xYz90`. Use that ID as `profile_id` in API, MCP, and CLI requests. Omit `profile_id` on publishing and reporting endpoints to use the default profile. Send `profile_id` when you want to target a non-default profile. # Create Connection Profile Source: https://docs.mallary.ai/api-reference/endpoint/profiles-create POST /api/v1/profiles Create a named profile for grouping connected social accounts. New profiles are non-default. Existing users keep their current connections on the default profile. # Rename Connection Profile Source: https://docs.mallary.ai/api-reference/endpoint/profiles-rename POST /api/v1/profiles/{id} Rename one of the authenticated user's connection profiles. # Profile Settings Source: https://docs.mallary.ai/api-reference/endpoint/settings GET /api/v1/settings Read or update brand and AI auto-reply settings for a connection profile. Settings are profile-scoped. Omit `profile_id` to read the default profile, or pass `profile_id` to read settings for another profile. # Update Profile Settings Source: https://docs.mallary.ai/api-reference/endpoint/settings-update POST /api/v1/settings Update brand and AI auto-reply settings for a connection profile. AI auto-replies require a Pro or Business plan and a complete profile-specific brand context. # Edit Scheduled Post Source: https://docs.mallary.ai/api-reference/endpoint/update-scheduled-post PATCH /api/v1/posts/{id} Change a scheduled post before any platform starts publishing it. First, [get the post](/api-reference/endpoint/get-scheduled-post). Check that `data.editable` is `true`, and copy `data.revision`. Then send that number as `expected_revision` with at least one field to change. Fields you leave out stay the same. You can change the text, media, first comments, publish time and time zone, auto-reply setting, platform options, and destinations. One edit changes the whole post group. The scheduled time must still be in the future, and no platform in the group may have started publishing. ## Change the text ```bash theme={null} curl -X PATCH 'https://mallary.ai/api/v1/posts/12345' \ -H "Authorization: Bearer $MALLARY_API_KEY" \ -H 'Content-Type: application/json' \ -d '{"expected_revision":1,"message":"Updated launch reminder"}' ``` Replace `1` with the revision from the GET response. A successful edit returns the updated post and its new revision. ## Change the profile or platforms Send `destinations` with **both** the target profile's public `profile_id` and the **complete final** platform list. Every platform in the group uses that one profile. A platform left out of the list is removed from the scheduled post. ```json theme={null} { "expected_revision": 1, "destinations": { "profile_id": "AbC123xYz90", "platforms": ["instagram", "linkedin"] } } ``` Use [List Connection Profiles](/api-reference/endpoint/profiles) to find profile IDs and the platforms connected to each profile. If you send `profile_id` in the URL query, it identifies the post's **current** profile. Put the new profile in `destinations.profile_id`. If you change only the platforms, send the current profile ID in `destinations.profile_id`. When you move to another profile, Mallary clears saved account choices from the old profile, such as a LinkedIn author or Pinterest board. Send new `platform_options` if you need those choices. When sent, `media`, `comments_under_post`, and `platform_options` replace their saved values. Send an empty array to clear media or first comments, or an empty object to clear platform options. If the API returns `409`, get the post again before making another edit. The post may have changed or started publishing. # Upload File Source: https://docs.mallary.ai/api-reference/endpoint/upload POST /api/v1/upload Create a presigned upload URL and the final public media URL for a file. Use this upload endpoint for your post media and custom video thumbnail images. Send the file's MIME type in `type` when you know it. For an MP4 video, use: ```json theme={null} { "filename": "launch.mp4", "type": "video/mp4" } ``` If you omit `type`, Mallary uses the filename extension to choose a supported MIME type. Files with unknown extensions need an explicit supported `type`. Upload the file bytes to the returned `uploadUrl` with HTTP PUT. Use the returned `headers`, including `Content-Type`, without changing them. Wait for the upload to finish before passing `mediaUrl` to `POST /api/v1/post`. # Create Webhook Source: https://docs.mallary.ai/api-reference/endpoint/webhooks-create POST /api/v1/webhooks Create a webhook for post and auto-reply lifecycle events. ## Delivery body Mallary sends a JSON body like this: ```json theme={null} { "event": "post.published", "event_id": "7dd724b3-e237-4b1f-9d3c-28f1932eb195", "data": { "batch_id": "batch_example", "platform": "facebook", "status": "completed" }, "sent_at": "2026-08-08T12:00:00.000Z", "signed_payload": "{\"event\":\"post.published\",\"event_id\":\"7dd724b3-e237-4b1f-9d3c-28f1932eb195\",\"data\":{\"batch_id\":\"batch_example\",\"platform\":\"facebook\",\"status\":\"completed\"},\"sent_at\":\"2026-08-08T12:00:00.000Z\"}" } ``` If you set a webhook secret, Mallary sends `X-Mallary-Payload-Signature` as `sha256=`. It is the HMAC-SHA256 signature of the exact `signed_payload` string. Verify it before parsing or using the event. # Delete Webhook Source: https://docs.mallary.ai/api-reference/endpoint/webhooks-delete DELETE /api/v1/webhooks/{id} Delete an existing webhook. # List Webhooks Source: https://docs.mallary.ai/api-reference/endpoint/webhooks-list GET /api/v1/webhooks List the configured webhooks for the authenticated user. # API Overview Source: https://docs.mallary.ai/api-reference/introduction Mallary API supports uploads, multi-platform publishing, comments, post analytics, audience counts, connected platforms, webhooks, and platform disconnects. Mallary API is the public API for multi-platform publishing, analytics, media upload, and webhooks. ## Authentication
  1. Sign up at [https://mallary.ai](https://mallary.ai)
  2. Connect your social media accounts in the Mallary dashboard
  3. Get your Mallary API key
 Authenticate every request with your Mallary API key: ```http theme={null} Authorization: Bearer ``` ## Base URL ```text theme={null} https://mallary.ai ``` ## Flow Example: video post to multiple platforms ```typescript post-a-video.ts theme={null} const uploadMetaRes = await fetch("https://mallary.ai/api/v1/upload", { method: "POST", headers: { Authorization: `Bearer ${API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ filename: file.name, // launch.mp4 type: "video/mp4", }), }); const uploadMeta = await uploadMetaRes.json(); // Example output: // { // uploadUrl: "https://...", // mediaUrl: "https://files.mallary.ai/uploads/launch.mp4", // headers: { "Content-Type": "video/mp4" } // } ``` ```typescript post-a-video.ts theme={null} await fetch(uploadMeta.uploadUrl, { method: "PUT", headers: uploadMeta.headers ?? {}, body: file, }); // Example output: HTTP 200/204 from uploadMeta.uploadUrl. ``` ```typescript post-a-video.ts theme={null} const postRes = await fetch("https://mallary.ai/api/v1/post", { method: "POST", headers: { Authorization: `Bearer ${API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ message: "Check out our new product!", platforms: ["tiktok", "youtube", "facebook", "instagram"], media: [{ url: uploadMeta.mediaUrl }], comments_under_post: ["Find out more at https://example.com today"], auto_reply_enabled: true, }), }); const post = await postRes.json(); const jobId = post.jobs[0].jobId; // Example output: // { // status: "queued", // batch_id: "a1b2c3d4", // jobs: [{ platform: "facebook", jobId: "123", platform_post_id: null, platform_post_url: null }] // } ``` ```typescript post-a-video.ts theme={null} const jobRes = await fetch(`https://mallary.ai/api/v1/jobs/${jobId}`, { headers: { Authorization: `Bearer ${API_KEY}` }, }); const { data } = await jobRes.json(); console.log(data.job); // Example output: // { // id: "123", // platform: "facebook", // status: "completed", // platform_post_id: "1234567890", // platform_post_url: "https://www.facebook.com/..." // } ``` ## Core API Features The current OpenAPI spec documents: * presigned media uploads * post creation and scheduling * job status retrieval * grouped post listing * scheduled-post details and edits before publishing starts * comment listing and supplied replies * deletion of queued or scheduled posts * analytics snapshots * follower and subscriber counts for connected accounts * connected platform listing * connection profile management * profile-scoped brand and AI auto-reply settings * platform disconnects * webhook listing, creation, and deletion ## Supported Platforms The current public platform enum includes: * `twitter` * `x` * `facebook` * `instagram` * `linkedin` * `youtube` * `tiktok` * `pinterest` * `reddit` * `threads` * `bluesky` ## Posting Features `POST /api/v1/post` supports: * one or more target platforms * optional `profile_id` for non-default connection profiles * media attachments * `comments_under_post` * optional scheduling with `scheduled_at`. Send an absolute timestamp such as `2026-04-06T18:30:00Z` * timezone-aware scheduling with `scheduled_timezone`. A local `2026-04-06T14:30` then resolves in an IANA timezone such as `America/New_York` * optional per-post AI auto-reply override * per-platform `platform_options` * optional `webhook_url` * optional `Idempotency-Key` ## Platform Options The OpenAPI spec currently documents platform-specific payload areas for: * Facebook * Instagram * TikTok * YouTube * Pinterest * Reddit * Threads * Bluesky When you need the exact supported `platform_options` shape, field names, and examples, use the canonical reference here: [Platform options reference](/api-reference/endpoint/create#body-platform-options) ## Platform-Specific Media Rules Mallary enforces platform-specific media rules before it queues jobs. Examples: * Threads supports `text`, `image`, `video`, and `carousel` post types. Carousel posts support 2 to 20 supported media items. * YouTube requires exactly one video. * Facebook supports `feed`, `story`, and `reel` post types. Reels use one 9:16 MP4 or MOV video that is 3 to 90 seconds long. * Instagram supports `feed`, `story`, `reel`, and `carousel` post types. Stories use one image/video, Reels use one video, and carousels support 2 to 10 mixed media items. * Pinterest requires exactly one image or GIF, or exactly one video, and also requires `boardId`. * Reddit image posts require one image or GIF. The current public API path does not support Reddit video upload. * TikTok supports one video for video posts, or up to 35 images for photo posts. * X allows up to 4 images or 1 video or 1 GIF. For the full per-platform matrix and current runtime caveats, see: [Platform-specific media rules](/api-reference/endpoint/create#platform-specific-media-rules) ## Connection Profiles Mallary groups connections into named profiles. This supports multiple connected accounts per platform. Existing accounts use the default profile. Use `GET /api/v1/profiles` to list each profile's random public ID, such as `AbC123xYz90`. Pass `profile_id` to publish, list posts, read post analytics or audience counts, list connected platforms, update settings, or disconnect a platform for a non-default profile. Per-platform account caps by plan are: * Free: `1` * Starter: `4` * Pro: `10` * Business: `50` ## Rate Limits Rate limits are enforced per user, per minute, by plan: * plan `1`: `75 req/min` * plan `2`: `150 req/min` * plan `3`: `750 req/min` * plan `4`: `1500 req/min` ## Plan-Gated Features Some endpoints and features are plan-gated. Examples called out in the spec include: * posting limits * analytics availability * AI auto-reply availability # Platform Posting Options Source: https://docs.mallary.ai/api-reference/platform-options See which post types and settings Mallary supports for each social platform. Use this page to make each post fit the social platform you choose. Most settings go inside `platform_options`. To use one cover on every platform, add `thumbnail_url` to the video in `media`. To use a different cover for each platform, add `thumbnail_url` to that platform's options. `comments_under_post` goes in the main post request. See [Create Post](/api-reference/endpoint/create) for the full request. ## Facebook Facebook supports feed posts, Stories, and Reels. ### Facebook post type Set `platform_options.facebook.post_type` to `feed`, `story`, or `reel`. * A feed post can have text, a link, up to 10 images, or one video. * A Story can have one image or one video. * A Reel needs one 9:16 MP4 or MOV video. It must be 3 to 90 seconds long and at least 540 by 960 pixels. ### Facebook message Use `platform_options.facebook.message` to write text just for Facebook. If you leave it out, Mallary uses the main post message. ### Facebook custom video thumbnail Add `thumbnail_url` to a Facebook feed video in `media`, or use `platform_options.facebook.thumbnail_url` for a Facebook-only cover. Use a JPG or PNG file stored by Mallary. The thumbnail can be up to 10 MB. Facebook chooses the cover for Reels. ### Facebook first comments Use `comments_under_post` to add up to three comments under a feed post or Reel. Facebook Stories do not use first comments. ## Instagram Instagram supports feed posts, Stories, Reels, and carousels. ### Instagram post type Set `platform_options.instagram.post_type` to `feed`, `story`, `reel`, or `carousel`. * A feed post has one image or one video. * A Story has one image or one video. * A Reel has one video. * A carousel has 2 to 10 images and videos. ### Instagram caption Use `platform_options.instagram.message` to write a caption just for Instagram. If you leave it out, Mallary uses the main post message. Story text must be part of the image or video. ### Instagram Reel profile feed Use `platform_options.instagram.shareToFeed` with a Reel. Leave it out or set it to `true` to show the Reel in both your profile feed and Reels tab. Set it to `false` to show the Reel only in the Reels tab. This option only works when `post_type` is `reel`. ### Instagram Trial Reels Add `platform_options.instagram.trialParams` to publish a Trial Reel. Instagram shows a Trial Reel to people who do not follow you first. This option only works when `post_type` is `reel`. Do not add `shareToFeed` to the same request. ```json theme={null} { "platform_options": { "instagram": { "post_type": "reel", "trialParams": { "graduationStrategy": "SS_PERFORMANCE" } } } } ``` ### Instagram Trial Reel graduation Choose how the Trial Reel can become a regular Reel: * Use `MANUAL` when you want to make that choice later in the Instagram app. * Use `SS_PERFORMANCE` when you want Instagram to share it with followers if it performs well. ### Instagram paid partnership label Set `platform_options.instagram.isPaidPartnership` to `true` to show Instagram's **Paid partnership** label. You can use it with a feed post, Reel, or carousel. It does not work with Stories. This feature needs an Instagram account connected through Facebook Login. If the account uses Instagram Login, Mallary stops the post before it is queued and tells you to reconnect. ### Instagram branded content sponsors Use `platform_options.instagram.brandedContentSponsors` to tag up to two sponsors. Each item can be an Instagram username, with or without `@`, or a numeric Instagram user ID. Adding a sponsor also turns on the Paid partnership label. Mallary looks up each username when it publishes the post. The sponsor must be a public Business or Creator account. If Instagram cannot find the account, Mallary returns an error that names the sponsor. If the brand has already approved the partnership, Instagram can show **Paid partnership with @brand** right away. If not, Instagram shows the plain label and sends the brand an approval request. ```json theme={null} { "platform_options": { "instagram": { "post_type": "reel", "isPaidPartnership": true, "brandedContentSponsors": ["@brandone", "17841400000000000"] } } } ``` ### Instagram custom video cover Add `thumbnail_url` to a feed video or Reel in `media`, or use `platform_options.instagram.thumbnail_url` for an Instagram-only cover. Use an image stored by Mallary. A tall cover works best for a Reel. ### Instagram first comments Use `comments_under_post` to add up to three comments under a feed post, Reel, or carousel. Stories do not use first comments. ## LinkedIn LinkedIn supports text posts, one image or GIF, or one MP4 video. Videos can be up to 1 GB (1,073,741,824 bytes) and 3 seconds to 30 minutes long. Do not mix images and video. Upload the video to Mallary, then add its URL to `media`. No LinkedIn video option is needed. The dashboard, REST API, MCP, and CLI use the same publishing flow. ### LinkedIn message Use `platform_options.linkedin.message` to write text just for LinkedIn. If you leave it out, Mallary uses the main post message. ### LinkedIn choose who posts Use `platform_options.linkedin.author_urn` to choose a person or company page. You can also save this choice when you connect LinkedIn in Mallary. ## Threads Threads supports text, image, video, and carousel posts. ### Threads post type Set `platform_options.threads.post_type` to `text`, `image`, `video`, or `carousel`. You can also leave it out and let Mallary choose from your media. ### Threads message Use `platform_options.threads.message` to write text just for Threads. If you leave it out, Mallary uses the main post message. ### Threads first replies Use `comments_under_post` to add up to three replies under your new Threads post. ## YouTube YouTube supports Shorts and long-form videos. ### YouTube video type Set `platform_options.youtube.post_type` to `shorts` or `regular`. You can also leave it out and let Mallary choose from the video shape and length. ### YouTube title and description Use `platform_options.youtube.title` for the video title. Use `platform_options.youtube.message` for the description. If you leave the title out, Mallary uses the first line of the message. ### YouTube tags Use `platform_options.youtube.tags` to add words that describe the video. Send the tags as a list of text values. ```json theme={null} { "platform_options": { "youtube": { "tags": ["social media automation", "creator tips", "Mallary"] } } } ``` Each tag can use up to 100 characters. All tags together can use up to 500 characters. YouTube counts the commas between tags. It also counts two extra quote marks around a tag that has spaces. Mallary removes exact duplicate tags and checks these limits before posting. ### YouTube visibility Set `platform_options.youtube.visibility` to `public`, `unlisted`, or `private`. The default is `public`. ### YouTube custom thumbnail Add `thumbnail_url` to a YouTube video in `media`, or use `platform_options.youtube.thumbnail_url` for a YouTube-only cover. Use a JPG or PNG file stored by Mallary. The image can be up to 50 MB. For a regular video, use a 16:9 image. YouTube can show it as the custom thumbnail. For a Short, YouTube may accept and store the image but still show a frame from the video. Mallary returns a warning because the YouTube API cannot tell us which cover viewers will see. Use YouTube Studio to add a custom image, or use the YouTube app to choose a frame. ### YouTube playlist Set `platform_options.youtube.playlist_id` to add the new video to an existing playlist. The playlist must belong to the connected YouTube channel. Mallary checks the playlist before it uploads the video. ```json theme={null} { "platform_options": { "youtube": { "playlist_id": "PL1234567890" } } } ``` Mallary can add to an existing playlist. It does not create a new playlist from a name. ### YouTube category and audience Use `platform_options.youtube.categoryId` to choose a YouTube category. Use `platform_options.youtube.madeForKids` to say if the video is made for kids. ### YouTube AI content disclosure Set `platform_options.youtube.containsSyntheticMedia` to `true` when a video contains realistic AI-generated or altered content that could look real. This includes making a real person appear to say or do something they did not, changing a real event or place, or creating a realistic scene that did not happen. YouTube may show a disclosure label on the video. ```json theme={null} { "platform_options": { "youtube": { "containsSyntheticMedia": true } } } ``` This setting is optional and applies only to the YouTube video in that post. Mallary does not turn it on just because you use an AI assistant. ### YouTube first comments Use `comments_under_post` to add up to three comments when YouTube allows comments on the video. ## TikTok TikTok supports videos and photo carousels. ### TikTok post type Set `platform_options.tiktok.post_type` to `video` or `photo`. You can also leave it out and let Mallary choose from your media. ### TikTok how it publishes TikTok uses `DIRECT_POST` by default, so Mallary publishes the post for you. Set `platform_options.tiktok.post_mode` to `MEDIA_UPLOAD` only when you want to send the post to your TikTok inbox and finish it in the TikTok app. An inbox upload stays `action_required` until you add the final TikTok post URL. ### TikTok upload source For videos, set `platform_options.tiktok.source` to `FILE_UPLOAD` or `PULL_FROM_URL`. A pulled file must already be stored by Mallary. Photo posts use `PULL_FROM_URL`. ### TikTok caption and details Use these fields for TikTok text: * `platform_options.tiktok.message` sets the TikTok caption. * `platform_options.tiktok.title` sets the TikTok title. * `platform_options.tiktok.description` sets the photo post description. ### TikTok privacy and sharing Use `platform_options.tiktok.privacy_level` to choose who can see a direct post. Use `disable_comment`, `disable_duet`, and `disable_stitch` to control how people can use the post. ### TikTok cover Use `platform_options.tiktok.video_cover_timestamp_ms` to pick a frame from a video. Use `platform_options.tiktok.photo_cover_index` to pick the cover photo in a carousel. ### TikTok music Set `platform_options.tiktok.auto_add_music` to `true` to let TikTok add music to a direct photo post. To pick a trending sound, use `MEDIA_UPLOAD` and choose the sound in the TikTok app. ### TikTok content labels Use `brand_content_toggle`, `brand_organic_toggle`, and `is_aigc` when the post needs a brand, business, or AI-made label. ## Pinterest Pinterest supports image Pins and video Pins. ### Pinterest pin type Set `platform_options.pinterest.post_type` to `image` or `video`. You can also leave it out and let Mallary choose from your media. ### Pinterest board Use `platform_options.pinterest.boardId` to choose the board that gets the Pin. If you leave it out, Mallary can use the board saved with the connection. ### Pinterest title and description Use `platform_options.pinterest.title` for the Pin title. Use `platform_options.pinterest.message` for the description. Pinterest allows 800 characters in a description. Mallary shortens longer descriptions to fit, so the Pin can still publish. ### Pinterest destination link Use `platform_options.pinterest.link` to send people to a web page when they click the Pin. ### Pinterest alt text Use `platform_options.pinterest.alt_text` to add a short image description for people who use screen readers. ## Reddit Reddit supports text, link, and image posts. ### Reddit subreddit Use `platform_options.reddit.subreddit` or `subredditName` to choose the community that gets the post. ### Reddit post type Set `platform_options.reddit.post_type` to `text`, `link`, or `image`. You can also leave it out and let Mallary choose from your media. ### Reddit text Use `platform_options.reddit.message` to write text just for Reddit. Mallary uses this text for the Reddit title and post text where needed. ## Bluesky Bluesky supports text, image, and video posts. ### Bluesky message Use `platform_options.bluesky.message` to write a message just for Bluesky. A Bluesky post can have up to 300 characters. ### Bluesky post languages Use `platform_options.bluesky.languages` to add up to three language codes, such as `en` or `es`. You can also use `langs`. ### Bluesky image alt text Add `alt_text` to each image in `media`. This tells people who use screen readers what the image shows. ### Bluesky first replies Use `comments_under_post` to add up to three replies under your new Bluesky post. ## X X supports text, image, video, and GIF posts. ### X message Use `platform_options.x.message` to write text just for X. `platform_options.twitter.message` also works for older requests. ### X media type Add up to four images, one video, or one GIF to `media`. Mallary picks the post type from the media. Do not mix images and video. X video limits depend on the connected X account. Standard accounts can use videos up to 20 minutes and 8 GB. Eligible Premium or verified accounts can use videos up to 125 minutes and 16 GB. Mallary checks the account when a video is above the standard limits. Mallary's current upload endpoint accepts files up to 5 GB. ### X first replies Use `comments_under_post` to add up to three replies under your new X post. # Authentication Source: https://docs.mallary.ai/cli-reference/authentication Authenticate Mallary CLI with browser-based OAuth or an API key. OAuth is the default for interactive use, including OpenClaw, Hermes, and other AI agent harnesses.
  1. Sign up at [https://mallary.ai](https://mallary.ai)
  2. Connect your social media accounts in the Mallary dashboard
  3. Sign in to the CLI with OAuth
 ## Sign in with OAuth ```bash theme={null} mallary auth login ``` The CLI shows a Mallary sign-in URL and a one-time code. Open the URL, sign in to Mallary, review the requested access, and approve it. OpenClaw, Hermes, and other agents do not need to receive your password, API key, access token, or refresh token. One OAuth login gives the CLI all Mallary capabilities: view data, publish posts, reply to comments, and manage settings and connections. Users do not choose OAuth scopes, and no scope flags are needed. Nothing is posted or changed during login. After setup, a clear request to publish, schedule, upload media for a requested post, or send a supplied reply is enough authorization to do it. The agent should not ask the user to approve the same action again. If a needed detail is missing or unclear, the agent should ask one short question. For destructive or account-access changes, it should confirm the target and effect only when the request did not already make them clear. ## Check or remove OAuth access ```bash theme={null} mallary auth status mallary auth logout ``` `auth status` reports whether OAuth or `MALLARY_API_KEY` is active without printing credentials. OAuth access tokens refresh automatically. `auth logout` revokes and removes the stored OAuth connection. By default, OAuth credentials are stored outside the current project in the operating system's per-user application configuration directory. On macOS and Linux, the credentials file is restricted to the current user. ## API key alternative API-key authentication remains available for CI and other environments where OAuth is not practical: ```bash theme={null} export MALLARY_API_KEY="your_mallary_api_key" ``` When this variable is set, it takes precedence over stored OAuth credentials. Keep it in a masked secret store. Never commit it, paste it into an agent prompt, or print it in logs. # Automation Source: https://docs.mallary.ai/cli-reference/automation Use Mallary CLI in scripts, CI, and automated toolchains. ## JSON Output Human-readable output is the default. Use `--json` for scripting: ```bash theme={null} mallary posts list --json ``` Output rules: * direct API wrapper commands emit the API response body * convenience flows like `upload` emit CLI-specific JSON * when local file uploads happen before submission, `posts create` emits CLI-specific JSON ## Exit Codes * `0`: success * `1`: local CLI, config, or input failure * `2`: remote API or upload failure ## Shell Automation Example ```bash theme={null} #!/usr/bin/env bash set -euo pipefail export MALLARY_API_KEY="${MALLARY_API_KEY:?missing}" UPLOAD_JSON="$(mallary upload ./hero.png --json)" MEDIA_URL="$(printf '%s' "$UPLOAD_JSON" | node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>console.log(JSON.parse(s).uploads[0].media_url))')" mallary posts create \ --message "Deployed via CI" \ --platform facebook \ --platform linkedin \ --media "$MEDIA_URL" \ --json ``` ## GitHub Actions Example ```yaml theme={null} - name: Install Mallary CLI run: npm install -g @mallary/cli - name: Publish post env: MALLARY_API_KEY: ${{ secrets.MALLARY_API_KEY }} run: | mallary posts create \ --message "Release shipped." \ --platform facebook \ --platform linkedin ``` ## AI Agent Notes If you are using the CLI in an automated agent workflow: * prefer `--json` * prefer `mallary posts create --file payload.json` for complex payloads # Commands Source: https://docs.mallary.ai/cli-reference/commands The main Mallary CLI commands for authentication, health, uploads, posts, comments, jobs, analytics, audience counts, webhooks, settings, and platforms. ## Authentication ```bash theme={null} mallary auth login mallary auth status mallary auth logout ``` One OAuth login gives the CLI access to view data, publish posts, reply to comments, and manage settings and connections. Users do not choose scopes or sign in again for another capability. Login itself does not post or change anything. A clear later request to publish, schedule, edit a scheduled post, upload media for a requested post, or send a supplied reply is enough authorization; do not ask for a second confirmation. ## Health ```bash theme={null} mallary health mallary health --json ``` ## Upload ```bash theme={null} mallary upload ./image.png mallary upload ./image.png ./video.mp4 --json ``` This command: 1. calls Mallary to create a presigned upload URL 2. uploads the local bytes for you 3. returns the final Mallary media URL Use the returned URL as `media[].url` for media, or as `media[].thumbnail_url` for video thumbnails in file-mode post payloads. ## Posts ```bash theme={null} mallary posts list mallary posts list --profile-id AbC123xYz90 mallary posts list --page 2 --per-page 25 --json mallary posts get 123 --profile-id AbC123xYz90 --json mallary posts edit 123 --message "Updated text" --scheduled-at 2026-10-15T15:00:00Z mallary posts edit 123 --target-profile-id NewProfile123 --platform instagram --platform linkedin mallary posts delete 123 ``` After publishing, grouped post results include the per-platform post IDs and public post URLs that the provider makes available. ## Comments ```bash theme={null} mallary comments list --post-id 123 mallary comments list --post-id 123 --platform instagram --limit 50 --json mallary comments reply --post-id 123 --comment-id "1789..." --message "Thanks for checking this out." ``` Comments commands are available on all plans. They list comments from Mallary-published posts and post the exact reply text you provide. ## Jobs ```bash theme={null} mallary jobs get 123 mallary jobs get 123 --json ``` Completed jobs include `platform_post_id` and `platform_post_url` in JSON mode, and print `Post ID` / `Post URL` in normal output when available. ## Analytics ```bash theme={null} mallary analytics list mallary analytics list --profile-id AbC123xYz90 mallary analytics list --post-id 123 ``` ## Audience Get the latest follower or subscriber count for every connected account in a profile: ```bash theme={null} mallary audience list mallary audience list --profile-id AbC123xYz90 mallary audience list --json ``` Mallary updates supported counts once every 24 hours. TikTok returns followers when the connection includes audience stats access. LinkedIn shows `permission_required` until Mallary adds the permission it needs. ## Profiles ```bash theme={null} mallary profiles list mallary profiles list --json ``` ## Webhooks List: ```bash theme={null} mallary webhooks list ``` Create: ```bash theme={null} mallary webhooks create \ --url https://example.com/mallary \ --event post.published \ --event post.failed ``` Delete: ```bash theme={null} mallary webhooks delete 12 ``` ## Settings ```bash theme={null} mallary settings get mallary settings get --profile-id AbC123xYz90 mallary settings update --file ./settings.partial.json mallary settings update --file ./settings.partial.json --profile-id AbC123xYz90 ``` ## Platforms ```bash theme={null} mallary platforms list mallary platforms list --profile-id AbC123xYz90 mallary platforms disconnect facebook mallary platforms disconnect facebook --profile-id AbC123xYz90 ``` `platforms list` includes each destination's selectable `post_types`. Platforms whose format is chosen from the content and media report automatic selection. # Comments Source: https://docs.mallary.ai/cli-reference/comments List comments on your posts, and post replies to comments, all from the Mallary CLI. ## List comments ```bash theme={null} mallary comments list --post-id 123 mallary comments list --post-id 123 --platform instagram --limit 50 --json ``` Use the Mallary job/post ID from `mallary posts list` or `mallary jobs get`. ## Reply to a comment ```bash theme={null} mallary comments reply \ --post-id 123 \ --comment-id "1789..." \ --message "Thanks for checking this out." ``` Mallary posts the exact `--message` text. If an AI agent uses the CLI, the agent must write the reply in the user's voice first. Then the agent runs this command. Supported platforms are Facebook, Instagram, Threads, LinkedIn, X, YouTube, and Bluesky. # Install Source: https://docs.mallary.ai/cli-reference/install Install, update, and remove the Mallary CLI. View the package on NPM: [https://www.npmjs.com/package/@mallary/cli](https://www.npmjs.com/package/@mallary/cli) ## npm ```bash theme={null} npm install -g @mallary/cli ``` ## npx ```bash theme={null} npx @mallary/cli --help ``` ## Update ```bash theme={null} npm install -g @mallary/cli@latest ``` ## Uninstall ```bash theme={null} npm uninstall -g @mallary/cli ``` # CLI Overview Source: https://docs.mallary.ai/cli-reference/introduction Mallary CLI is the official command-line interface for the Mallary platform. Mallary CLI is the official command-line interface for [mallary.ai](https://mallary.ai). It gives developers, operators, scripts, CI jobs, and AI agents fast access to the public Mallary platform. The same platform powers the Mallary dashboard, REST API, and MCP server. ## What You Can Do With the CLI you can: * upload local media files to Mallary * create and schedule posts * edit scheduled posts before publishing starts * read jobs and grouped posts * list comments and post supplied replies on published posts * read post analytics and connected-account audience counts * manage webhooks * manage brand settings * list connected platforms * disconnect platforms ## API Model Mallary CLI is a direct client for the public Mallary API. It does not bypass plan limits, feature gates, or platform rules. For interactive use and AI agent harnesses, the CLI supports browser-based OAuth. One login gives access to view data, publish posts, reply to comments, and manage settings and connections. Users do not choose OAuth scopes. API-key authentication remains available as an optional override for CI and other non-interactive environments. # Posts Source: https://docs.mallary.ai/cli-reference/posts Create, inspect, and edit Mallary posts, with media and platform options. ## Flag Mode ```bash theme={null} mallary posts create \ --message "Hello from Mallary CLI" \ --platform facebook \ --platform linkedin \ --profile-id AbC123xYz90 \ --media ./launch-video.mp4 \ --thumbnail ./launch-cover.jpg \ --comment "Follow-up comment 1" \ --comment "Follow-up comment 2" \ --auto-reply-enabled \ --scheduled-at 2026-03-30T15:00:00Z ``` Schedule a local wall-clock time in a specific timezone: ```bash theme={null} mallary posts create \ --message "Timezone-aware launch" \ --platform threads \ --scheduled-at 2026-04-06T09:30 \ --scheduled-timezone America/Los_Angeles ``` Choose one post type for every compatible destination in flag mode: ```bash theme={null} mallary posts create \ --message "A new Story" \ --platform facebook \ --platform instagram \ --post-type story \ --media ./story.mp4 ``` Mallary checks the type before it uploads media or sends the post. If one selected platform cannot use that type, the command stops and lists that platform's supported types. Use file mode when different platforms need different types. ## File Mode ```bash theme={null} mallary posts create --file ./post.json ``` Example: ```json theme={null} { "message": "Launch update", "profile_id": "AbC123xYz90", "platforms": ["youtube", "facebook"], "media": [{ "url": "./launch.mp4", "thumbnail_url": "./launch-cover.jpg" }], "platform_options": { "youtube": { "message": "YouTube description for the launch video", "title": "Launch update", "tags": ["product launch", "creator tools"] }, "facebook": { "message": "Facebook caption for this launch" } } } ``` Omit `--profile-id` or `profile_id` to use your default Mallary profile. Run `mallary profiles list` to find the random public ID for each profile. `posts create` returns Mallary job IDs immediately. Once each job finishes publishing, `mallary jobs get ` and `mallary posts list --json` include `platform_post_id` and `platform_post_url` when the platform returns or exposes them. ## Edit a Scheduled Post Read the saved post and its revision: ```bash theme={null} mallary posts get 123 --profile-id AbC123xYz90 --json ``` Change its text or time: ```bash theme={null} mallary posts edit 123 --message "Updated launch text" --scheduled-at 2026-10-15T15:00:00Z ``` Move the whole post group to another connection profile and replace its platform list: ```bash theme={null} mallary posts edit 123 --target-profile-id NewProfile123 --platform instagram --platform linkedin ``` Each `--platform` names part of the **complete final destination list**. If you change only the profile, Mallary keeps the current platforms. If you change only the platforms, it keeps the current profile. Use `--profile-id` when reading a post in a non-default current profile. The CLI checks that the target profile has ready connections, and the API stops the edit if any destination has started publishing. For automation, use `--expected-revision ` with the revision from `posts get --json`. A stale revision stops the edit. `--media` and `--comment` replace the complete saved lists. Use `--file` for platform options, multiple fields, or an empty list to clear media or comments: ```json theme={null} { "expected_revision": 2, "destinations": { "profile_id": "NewProfile123", "platforms": ["instagram", "linkedin"] }, "media": [{ "url": "./new-photo.jpg" }], "platform_options": { "instagram": { "post_type": "feed" }, "linkedin": { "message": "Updated LinkedIn caption" } } } ``` Run `mallary posts edit 123 --file ./post-changes.json`. When `destinations` is present, include both fields and the complete final platform list. Omit it to keep current destinations. `platform_options` replaces the complete saved options map when present. The CLI uploads local replacement media before the edit request; if the post changes during upload, the API returns a conflict and leaves the post unchanged. ## File Mode Rules * `--file` is mutually exclusive with payload-building flags * `--post-type` works in flag mode when every selected destination should use the same supported type * use `platform_options` in file mode when destinations need different post types * Mallary uploads local `media[].url` file paths to the Mallary CDN first * Mallary uploads local `media[].thumbnail_url` file paths to the Mallary CDN first * existing remote media URLs must already point to `https://files.mallary.ai/...` * Mallary rejects external remote media URLs * Mallary passes platform-specific payloads through to the API * use `platform_options..message` for a platform-specific message or caption ## Video Thumbnails In flag mode, use `--thumbnail` with exactly one `--media` item: ```bash theme={null} mallary posts create \ --message "Launch walkthrough" \ --platform youtube \ --media ./launch.mp4 \ --thumbnail ./launch-cover.jpg ``` In file mode, put `thumbnail_url` on the media item. Mallary uploads local thumbnail paths automatically. Existing remote thumbnail URLs must already point to `https://files.mallary.ai/...`. To add a YouTube video to an existing playlist, set `platform_options.youtube.playlist_id` in file mode. The playlist must belong to the connected channel. To add YouTube video tags, set `platform_options.youtube.tags` to a list of text values in file mode. Each tag can use up to 100 characters. The full list can use up to 500 characters after YouTube counts separators. To disclose realistic AI-generated or altered content, set `platform_options.youtube.containsSyntheticMedia` to `true` in file mode. YouTube may show a disclosure label on the video. Current thumbnail support: * YouTube regular videos: use a `jpg`, `jpeg`, or `png` thumbnail up to 50 MB. Use 16:9. * YouTube Shorts: YouTube may store the image but show a video frame instead. Mallary returns a warning because the YouTube API cannot confirm the cover viewers will see. * Facebook feed videos: supported with `jpg`, `jpeg`, or `png` up to 10 MB. * Instagram videos/Reels: supported with a Mallary-hosted cover URL. Use an image that matches the video placement. * TikTok video posts: Mallary does not send arbitrary thumbnail images to TikTok. If you supply `thumbnail_url`, Mallary skips its `video_cover_timestamp_ms` behavior, and TikTok uses its default cover. * TikTok photo posts: `thumbnail_url` selects the cover only when it exactly matches one of the image URLs in the same `media[]` array. ## Scheduling Rules * use `--scheduled-at 2026-04-06T18:30:00Z` when you already know the absolute publish timestamp * use `--scheduled-at 2026-04-06T14:30 --scheduled-timezone America/New_York` when you want a local wall-clock time in a specific timezone * in file mode, send `scheduled_at` and optional `scheduled_timezone` * `scheduled_timezone` must be an IANA timezone such as `America/New_York` ## Supported Platform-Specific Payload Areas Mallary CLI README currently documents platform-specific payload examples for: * Facebook * Instagram * LinkedIn * YouTube * TikTok * Pinterest * Reddit * Threads * Bluesky * X For the exact `platform_options` fields currently supported by the posting API, see: [Platform options reference](/api-reference/endpoint/create#body-platform-options) Every publishing platform accepts `platform_options..message` as an optional platform-specific message. Leave it blank or omit it to use the top-level `message`. ## Threads Notes * `platform_options.threads.post_type` can be `text`, `image`, `video`, or `carousel`. * If you omit `platform_options.threads.post_type`, Mallary chooses from the media payload: no media = `text`, one image = `image`, one video = `video`, multiple supported media items = `carousel`. * Threads media constraints are: `text` = no media, `image` = 1 image, `video` = 1 video, `carousel` = 2 to 20 media items. * Threads-supported media formats are `jpg`, `jpeg`, `png`, `webp`, `mp4`, and `mov`. ## Platform-Specific Media Rules Mallary CLI uses the same platform media validation as the Mallary API. Important current rules: * Threads supports text-only posts, one image, one video, or a 2 to 20 item carousel. * YouTube requires exactly one video. * Facebook supports `feed`, `story`, and `reel` through `platform_options.facebook.post_type`. Reels use one 9:16 MP4 or MOV video that is 3 to 90 seconds long. * Instagram supports `feed`, `story`, `reel`, and `carousel` through `platform_options.instagram.post_type`. Stories use one image or video, Reels use one video, and carousels use 2 to 10 mixed items. For a Reel, use `shareToFeed` for profile feed placement. Add `trialParams.graduationStrategy` in file mode to publish a Trial Reel. With a Facebook Login connection, file mode also supports `isPaidPartnership` and up to two `brandedContentSponsors` on feed posts, Reels, and carousels. * LinkedIn supports text-only posts, one image or GIF, or one MP4 video. Videos can be up to 1 GB (1,073,741,824 bytes) and 3 seconds to 30 minutes long. Do not mix images and video. * TikTok video posts require one video, and TikTok photo posts support up to 35 JPEG/WebP images. * TikTok defaults to `DIRECT_POST`, which publishes through Mallary. Set `platform_options.tiktok.post_mode = MEDIA_UPLOAD` only when you want to finish the post in the TikTok app. Inbox uploads stay `action_required` until you add the final TikTok post URL. * Pinterest requires exactly one image or GIF, or exactly one video, plus `boardId`. Mallary shortens Pin descriptions longer than 800 characters so they can publish. * Reddit image posts require one image or GIF. The current public API path does not support Reddit video upload. * X allows up to 4 images, or 1 video, or 1 GIF. * Bluesky supports text-only posts, up to four JPG, PNG, or WEBP images, or one MP4 video. Add `alt_text` to a media item when it needs an accessible description. For the full per-platform matrix and current runtime caveats, see: [Platform-specific media rules](/api-reference/endpoint/create#platform-specific-media-rules) ## Comments Under Post * use repeatable `--comment` flags in flag mode * in file mode, send `comments_under_post` as an array * the current limit is 3 items * TikTok does not currently support `comments_under_post` Example: ```json theme={null} { "message": "New launch today", "platforms": ["facebook"], "media": [{ "url": "./launch.png" }], "comments_under_post": [ { "content": "What do you think?" }, { "content": "Questions? Ask below." } ] } ``` ## AI Auto Reply * available on Pro and Business plans only * you can enable it account-wide with `mallary settings update` * you can enable it per post with `--auto-reply-enabled` * it depends on saved account settings, not just the current payload To enable it, you must set these fields: * `business_name` * `website_url` * `business_description` * `services` * `contact_info` # Quickstart Source: https://docs.mallary.ai/cli-reference/quickstart Sign in once with OAuth, check your Mallary account, and get ready to publish. ## Sign In ```bash theme={null} mallary auth login mallary auth status ``` Open the Mallary URL shown by the CLI and enter the one-time code. One OAuth login gives access to view data, publish posts, reply to comments, and manage settings and connections. Users do not choose scopes. The setup checks below do not post or change anything. Later, a clear request to publish, schedule, upload media for a requested post, or send a supplied reply is enough authorization; the agent should not ask for a second confirmation. ## Health Check ```bash theme={null} mallary health ``` ## Upload Local Media ```bash theme={null} mallary upload ./launch.mp4 ``` ## Create a Post ```bash theme={null} mallary posts create \ --message "Check out my new product video!" \ --platform facebook \ --platform instagram \ --post-type story \ --profile-id AbC123xYz90 \ --media ./launch.mp4 \ --thumbnail ./launch-cover.jpg ``` ## List Posts ```bash theme={null} mallary posts list ``` ## Read a Job ```bash theme={null} mallary jobs get 123 ``` After publishing, job output includes `platform_post_id` and `platform_post_url` when the platform returns or exposes them. ## List Connected Platforms ```bash theme={null} mallary platforms list ``` This read-only command also returns each platform's selectable `post_types`, such as `story` for Facebook and Instagram. ## List Your Profiles within Mallary Profiles group your social media accounts. Create one profile for each of your businesses. Then connect the social media accounts of that business inside its profile. If you do not send a `profile_id`, Mallary uses your default profile. Each profile has a random public ID, such as AbC123xYz90. Use that ID as `profile_id` in API, MCP, and CLI requests. Omit `profile_id` on publishing and reporting endpoints to use the default profile. Send `profile_id` when you want to target a non-default profile. ```bash theme={null} mallary profiles list ``` # Settings Source: https://docs.mallary.ai/cli-reference/settings Read and update brand and auto-reply settings from the CLI. ## Get Current Settings ```bash theme={null} mallary settings get mallary settings get --profile-id AbC123xYz90 ``` ## Update Settings ```bash theme={null} mallary settings update --file ./settings.partial.json mallary settings update --file ./settings.partial.json --profile-id AbC123xYz90 ``` Example partial payload: ```json theme={null} { "auto_reply_enabled": true, "brand_profile": "Mallary helps brands schedule, publish, and manage social media content with AI-assisted workflows.", "business_name": "My Business", "business_description": "Local HVAC company", "website_url": "https://example.com", "services": "HVAC installation, repair, and maintenance", "features": "Same-day service, financing, weekend appointments", "contact_info": "Call (555) 555-5555 or email hello@example.com", "pricing": "Free estimates. Maintenance plans start at $29/month.", "faq": "Q: Do you offer emergency service? A: Yes, 24/7." } ``` ## Accepted Fields * `auto_reply_enabled` * `brand_profile` * `business_name` * `business_description` * `website_url` * `services` * `features` * `contact_info` * `pricing` * `faq` ## Notes * `mallary settings update --file ...` accepts partial updates * settings are profile-scoped. Omit `--profile-id` to use the default profile * use `mallary profiles list` to find profile IDs * only plans that include AI auto reply can turn on `auto_reply_enabled` * enabling `auto_reply_enabled` also requires: `business_name`, `website_url`, `business_description`, `services`, and `contact_info` # Agent Skill Source: https://docs.mallary.ai/home/agent-skill Give AI agents deep knowledge of Mallary's social media scheduling APIs across 10 platforms. ## Install ```bash theme={null} npx skills add mallarylabs/mallary-agent ``` Or download SKILL.md to upload to Claude or any AI tool manually. ## What's included The skill teaches your AI agent how to use the Mallary API. It covers endpoint selection, parameter usage, pagination, uploads, and platform-specific rules. These rules cover all 10 supported platforms, including TikTok, Instagram, YouTube, LinkedIn, Twitter/X, Reddit, and Facebook. The skill also teaches agents to preserve the format you ask for. If you ask for a Story, Reel, Short, carousel, photo, or video, the agent checks the destination's supported post types and does not silently replace it with a feed post. | When you say | What the skill does | | - | - | | "post this video to all my accounts" | Sends the video and the publishing intent to the Mallary CLI. The CLI handles the upload, the queue, platform-specific posting, retries, status, and reporting. | | "Schedule these 2 video posts for tomorrow at 9am and 3pm." | Resolves "tomorrow at 9am and 3pm" into exact timestamps. Uploads the two videos to the Mallary CDN. Creates two scheduled jobs through the Mallary API or MCP. A Mallary worker publishes them later, and tracks status, retries, and failures. | | "How did yesterday's post do?" | Resolves "yesterday" to the correct date range. Authenticates through the Mallary API or MCP. Finds the posts from that day. Reads the available performance data, such as views, likes, comments, shares, clicks, and platform-specific metrics. | | "How many followers do my accounts have?" | Reads the latest saved follower or subscriber count for every connected account in the selected Mallary profile. | | "Reply to everyone who commented on my launch post." | Calls the Mallary comment-list endpoint or tool for the published post. Writes each reply in the user's voice. Sends the exact reply text through the comment-reply endpoint or tool. | ## Authentication For OpenClaw, Hermes, and other CLI-backed agent harnesses, install the Mallary CLI and start browser-based OAuth: ```bash theme={null} npm install -g @mallary/cli mallary auth login mallary auth status ``` The CLI shows a Mallary sign-in URL and one-time code. The agent should show those to you and wait while you approve access in your browser. Do not paste your password, API key, access token, or refresh token into the agent. One OAuth login gives the agent access to view data, publish posts, reply to comments, and manage settings and connections. You do not choose OAuth scopes or sign in again for another capability. Login itself does not post or change anything. After setup, a clear request to publish, schedule, upload media for a requested post, or send a supplied reply is enough authorization. The agent should ask only when a needed detail is missing or unclear, and it should not ask you to approve the same action again.
  1. Sign up at [https://mallary.ai](https://mallary.ai)
  2. Connect your social media accounts in the Mallary dashboard
  3. Run mallary auth login and approve Mallary access
 `MALLARY_API_KEY` remains available as an optional fallback for CI or another environment where OAuth is not practical. Keep it in a masked secret store and never paste it into an agent prompt. When set, it takes precedence over stored OAuth. ## Skill vs MCP The MCP server gives your AI agent direct API access. It can call Mallary endpoints on your behalf. The skill teaches the agent best practices for those APIs: which endpoint to pick, how to upload files, and the platform-specific rules. Use the skill and the MCP server together, or use each one alone. ## Comment engagement Agents can use Mallary for post-publication engagement without browser automation: 1. Find the Mallary `post_id`/job ID from the post list or job lookup. 2. Call `GET /api/v1/comments` or MCP `mallary_list_comments`. 3. Write the reply in the user's voice. 4. Call `POST /api/v1/comments/reply` or MCP `mallary_reply_to_comment` with the exact reply text. Comment listing and supplied replies are available on all plans for Facebook, Instagram, Threads, LinkedIn, X, YouTube, and Bluesky. ## Links * GitHub Repository * MCP Integration — for direct API access from your agent # Social Media API Source: https://docs.mallary.ai/home/api Mallary API is a social media API for developers. Use it to publish, reply, read post analytics and audience counts, list connected platforms, manage webhooks, and disconnect platforms across 10 social sites. Mallary API is a social media API for many platforms from one integration. Use it to upload media, create posts, schedule content, and track job status. It also lists comments, posts supplied replies, reads analytics, lists connected platforms, and manages webhooks. Mallary is the API layer behind the Mallary product. It is a social media posting API, a scheduling API, and a multi-platform publishing API. Use it in your app, your backend, an automation workflow, or an AI agent. ## Start here Read the API overview, authentication model, platform support, and posting capabilities. Start with presigned uploads if your workflow includes images or video. Publish or schedule a post across one or more connected social platforms. Check job progress, grouped posts, analytics, retries, and final publish results. ## What the Mallary API does With the Mallary API you can: * upload local or generated media for publishing * create posts across multiple social platforms in one request * schedule posts for future publishing * track per-platform job status, publish results, and platform post IDs/URLs * list grouped posts and retries * list comments and post supplied replies on published posts * read analytics snapshots for published content * read follower and subscriber counts for connected accounts * list which supported platforms are currently connected for the authenticated account * manage connection profiles for multiple accounts on the same platform * read and update profile-scoped brand and AI auto-reply settings * create, list, and delete webhooks * disconnect a platform from the authenticated account ## Why developers use the Mallary API The Mallary API serves teams that want one integration. It removes the separate posting logic for every platform. It is useful for: * SaaS products that need built-in social publishing * internal tools for marketing and operations teams * automation pipelines * AI agents that need to publish or read social content * scripts and server-side workflows that need reliable API-based posting ## Base URL ```text theme={null} https://mallary.ai ``` ## Authentication Authenticate with your Mallary API key: ```http theme={null} Authorization: Bearer ``` ## Core API features The current public API supports: * presigned media uploads through `POST /api/v1/upload` * post creation and scheduling through `POST /api/v1/post` * job status lookup through `GET /api/v1/jobs/{id}` * grouped post listing through `GET /api/v1/posts` * scheduled post details through `GET /api/v1/posts/{id}` * scheduled post edits through `PATCH /api/v1/posts/{id}` * comment listing through `GET /api/v1/comments` * supplied comment replies through `POST /api/v1/comments/reply` * deletion of queued or scheduled posts through `DELETE /api/v1/posts/{id}` * analytics snapshots through `GET /api/v1/analytics` * current account audience counts through `GET /api/v1/audience` * connected platform listing through `GET /api/v1/platforms` * connection profile management through `GET /api/v1/profiles` and `POST /api/v1/profiles` * profile-scoped brand and auto-reply settings through `GET /api/v1/settings` and `POST /api/v1/settings` * platform disconnect through `POST /api/v1/disconnect` * webhook listing, creation, and deletion through `/api/v1/webhooks` ## Supported social media platforms Mallary currently publishes through a single API to: * X * Facebook * Instagram * LinkedIn * YouTube * TikTok * Pinterest * Reddit * Threads * Bluesky The OpenAPI enum also includes both `x` and `twitter` identifiers for compatibility with older data. ## Common Mallary API workflow Most integrations follow this path: 1. Upload media and get a public Mallary file URL. 2. Create a post with one or more target platforms. 3. If plans change before publishing starts, [get the saved post](/api-reference/endpoint/get-scheduled-post) and [edit it](/api-reference/endpoint/update-scheduled-post). 4. Poll the job endpoint for per-platform status. 5. Use grouped post listing and analytics endpoints for downstream reporting. 6. Optionally subscribe to webhooks instead of polling everything yourself. ## Media upload and publishing model Mallary stores media on Cloudflare R2 and serves it from the Mallary files domain. The normal flow is: 1. call the upload endpoint to get a presigned upload URL and final media URL 2. upload bytes to the returned URL 3. pass the returned public `mediaUrl` into the post request Use the same upload flow for custom video thumbnails. Pass the returned thumbnail `mediaUrl` as `media[].thumbnail_url` when creating the post. This flow keeps posting requests simple and gives downstream platforms a stable hosted media URL. ## Posting and scheduling features `POST /api/v1/post` supports more than basic single-platform publishing. The request can include: * one or more target platforms * optional `profile_id` for publishing from a non-default connection profile * media attachments * optional video thumbnail or cover URLs with `media[].thumbnail_url` * follow-up comments with `comments_under_post` on supported platform/format combinations * scheduled publishing with `scheduled_at` * timezone-aware wall-clock scheduling with `scheduled_timezone` * per-post AI auto-reply override with `auto_reply_enabled` * per-platform configuration in `platform_options` * optional completion callback with `webhook_url` * optional `Idempotency-Key` header Mallary enqueues one job per platform and returns job IDs plus a `batch_id` so you can track multi-platform work as one logical post. For scheduling, you can either send an absolute timestamp like `2026-04-06T18:30:00Z`, or send a local `scheduled_at` like `2026-04-06T14:30` together with `scheduled_timezone: "America/New_York"`. ## AI Auto Replies ### What it does AI Auto Replies can answer useful questions on posts you publish through Mallary. Mallary uses the business details saved for that profile and the post itself to write a short reply. It skips comments that are not questions or are not about your business. AI Auto Replies work with Facebook, Instagram, Threads, LinkedIn, X, YouTube, and Bluesky. They are available on Pro and Business plans. ### How it works 1. Mallary checks for new comments on supported posts. 2. It looks for questions about your business. 3. It uses your saved business details and the post to write a reply. 4. It posts the reply from your connected social account. 5. It skips comments that it should not answer. ### How to enable it First, save these details for the Mallary profile you want to use: * business name * website URL * business description * services * contact information Then send `POST /api/v1/settings` with `auto_reply_enabled` set to `true`. Add `profile_id` when you want to update a profile that is not your default profile. ```bash theme={null} curl --request POST \ --url https://mallary.ai/api/v1/settings \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "profile_id": "AbC123xYz90", "business_name": "Acme Labs", "website_url": "https://example.com", "business_description": "We make simple tools for small teams.", "services": "Project planning and team support", "contact_info": "Email help@example.com", "auto_reply_enabled": true }' ``` Leave out `profile_id` to use your default Mallary profile. After you turn it on, new posts use AI Auto Replies by default. You can set `auto_reply_enabled` to `true` or `false` in one `POST /api/v1/post` request when you want that post to use a different setting. **Important:** Turning this on lets Mallary publish future replies. Only enable it after the social account owner says yes. ## Connection profiles Connection profiles group your social media accounts. Create one profile for each of your businesses. Then connect the social media accounts of that business inside its profile. If you do not send a `profile_id`, Mallary uses your default profile. Call `GET /api/v1/profiles` to list each profile's random public ID. Profile IDs are short letter/number strings like `AbC123xYz90`, not sequential database IDs. Use `profile_id` when you want to: * publish from a non-default profile * list posts for a specific profile * read analytics for a specific profile * read audience counts for a specific profile * list connected platforms for a specific profile * update brand and AI auto-reply settings for a specific profile * disconnect a platform from a specific profile Profile caps per platform are Free: 1, Starter: 4, Pro: 10, and Business: 50. ## Platform-specific options The current OpenAPI specification documents platform-specific payload areas for: * Facebook * Instagram * Threads * TikTok * YouTube * Pinterest * Reddit * Bluesky Examples include Threads post type selection, TikTok direct-vs-upload mode, Pinterest board selection, and YouTube visibility, video tags, or AI-content disclosure. For the exact `platform_options` structure and currently documented fields by platform, see: [Platform options reference](/api-reference/endpoint/create#body-platform-options) ## Platform-specific media rules Mallary applies platform-specific media validation before it queues a post. Important examples: * Threads supports text-only posts, one image, one video, or a 2 to 20 item carousel using JPG/JPEG/PNG/WEBP/MP4/MOV media. * YouTube requires exactly one video. * Facebook supports `feed`, `story`, and `reel` post types. Reels use one 9:16 MP4 or MOV video that is 3 to 90 seconds long. * Instagram supports `feed`, `story`, `reel`, and `carousel` through `platform_options.instagram.post_type`. Stories use one image or video, Reels use one video, and carousels use 2 to 10 mixed items. For Reels, use `shareToFeed` to choose profile feed placement. Add `trialParams.graduationStrategy` to publish a Trial Reel. For Facebook Login connections, use `isPaidPartnership` and `brandedContentSponsors` on feed posts, Reels, and carousels. * TikTok video posts require one video, and TikTok photo posts support up to 35 JPEG/WebP images. * Pinterest requires exactly one image or GIF, or exactly one video. * X allows up to 4 images, or 1 video, or 1 GIF. For the full matrix, including LinkedIn, Reddit, Bluesky, and current runtime notes, see: [Platform-specific media rules](/api-reference/endpoint/create#platform-specific-media-rules) ## Analytics, job tracking, and grouped posts The Mallary API is not just for submission. You can also use it to: * read job state while a post is queued, delayed, processing, completed, failed, or cancelled * read per-platform post results * list grouped posts with retry information * read analytics snapshots for recent content or one specific post These endpoints support a real publishing workflow, not a fire-and-forget endpoint. ## Webhooks Mallary webhooks let your integration react to publishing lifecycle events without constant polling. The current documented webhook events include: * `post.scheduled` * `post.published` * `post.failed` * `post.partial` * `auto_reply.posted` * `*` to receive all supported events Each delivery includes `event`, `event_id`, `data`, and `sent_at`. If you set a webhook secret, Mallary sends `X-Mallary-Signature` for the full request body. It also sends `X-Mallary-Payload-Signature` for the exact JSON string in `signed_payload`. Verify a signature before you trust or process the event. ## Plans and feature gating Some features are gated by plan. Current platform behavior and product rules include: * Free plans do not have scheduling * Free plans do not have analytics access * Free plans do not have AI auto replies * Free plans do not have MCP access * Free plans do not have CLI access * Starter plans include scheduling, analytics, MCP, and CLI * Pro and Business plans include AI auto replies in addition to scheduling and analytics If the authenticated account does not have access to a capability, the API returns a plan-related error. ## Rate limits Rate limits are enforced per user, per minute, based on subscription plan: * plan `1`: `75` requests per minute * plan `2`: `150` requests per minute * plan `3`: `750` requests per minute * plan `4`: `1500` requests per minute ## Good fit for the Mallary API Mallary API is a strong fit if you want: * one social media API instead of many platform integrations * direct REST access instead of a CLI * a publishing backend for your product * reliable job status and grouped result tracking * analytics and webhook support in the same platform # Mallary for ChatGPT Source: https://docs.mallary.ai/home/chatgpt Add the Mallary plugin to ChatGPT with OAuth. Then publish posts, use images, reply to comments, and review results. Mallary connects your social publishing workflow to ChatGPT. You can work with your connected social accounts without sharing an API key. Mallary is available as a published ChatGPT plugin. Open Mallary in ChatGPT and install the plugin. ## Start in Three Steps 1. Click **Add to ChatGPT** above, then click **Install plugin**. 2. Sign in to Mallary and allow the connection. 3. Start a ChatGPT request with `@Mallary` and say what you want to do. ## What You Can Do * see connected social accounts * create or schedule social posts * use images you make or choose in ChatGPT * use a different message for each platform * check publishing status and open published posts * read comments and post approved replies * review post analytics * review follower and subscriber counts ## How Sign-In Works The Mallary plugin uses OAuth. ChatGPT opens Mallary in your browser and asks you to approve access. Mallary never gives the plugin your password, social account tokens, API keys, or payment details. You can review or revoke access from your Mallary account at any time. ## Your Requests Control What Happens Mallary only posts, uploads, or replies when you ask for that result. These actions are real. A post can go live on your social accounts. Check the profile, platforms, message, image, and time before you ask ChatGPT to post. ## Make an Image and Post It You can ask ChatGPT to make an image and post it with Mallary. You can also choose an image in ChatGPT. ChatGPT sends Mallary a short-lived link to the image you approved. Mallary checks the image, copies it to `https://files.mallary.ai`, and uses that Mallary link in your post. Mallary accepts JPEG, PNG, WebP, and GIF images up to 25 MB through this flow. This image tool is only for social post images. Do not use it for private customer files, health records, ID records, card details, passwords, API keys, or access tokens. ## ChatGPT Plugin and Codex The ChatGPT plugin is the quick way to use Mallary in ChatGPT. Codex uses a different setup through Mallary MCP, the CLI, or the Mallary skill. See the Codex setup steps. Mallary MCP endpoint: ```text theme={null} https://mallary.ai/mcp/openai ``` See how OAuth permissions and account revocation work. ## Post a Video The current ChatGPT plugin does not accept a video attachment directly. You can use a Mallary video URL instead. Keep your approved captions in ChatGPT. Open [Mallary Compose](https://mallary.ai/compose), upload an MP4 or MOV video in Attachments, and select **Copy video URL**. Return to the same ChatGPT chat, paste the Mallary URL, and ask Mallary to use it with your approved captions and schedule. Check the accounts, date, time zone, and platform choices before ChatGPT schedules the posts. Anyone with the URL can view the video. A client that can read your video file and send HTTP PUT requests can also use [standard MCP's video upload flow](/mcp-reference/tools#upload-a-video-with-standard-mcp). Each social platform has its own video rules. LinkedIn requires MP4. Reddit does not support video uploads through Mallary. Mallary checks your selected destinations before posting and reports any problems. # Mallary for Claude Source: https://docs.mallary.ai/home/claude Add Mallary to Claude with OAuth. Then ask Claude to post, reply, use media, and show your results. Use Mallary inside Claude to work with your social media. You can use the accounts in your Mallary profiles. You do not need to copy an API key. Mallary is in the official Claude Connector Directory. Open Mallary in Claude and add the connector. ## Start in Three Steps 1. Click **Add to Claude** above. 2. Sign in to Mallary and allow the connection. 3. [Grant Claude network access to upload files to Mallary's CDN](/home/claude#photos-and-videos) 4. Ask Claude to use Mallary for your social media work. ## What You Can Do * see your Mallary profiles and social accounts * create or schedule posts * edit a scheduled post's words, media, time, platforms, or connection profile before it starts posting * write a different message for each platform * check if a post went live * read comments and send replies * see likes, views, shares, and other results * see follower and subscriber counts for your connected accounts * work with your Mallary settings and webhooks ## How Sign-In Works Claude sends you to Mallary to sign in with OAuth. You approve the connection on the Mallary page. Claude does not see your Mallary password, API keys, social account tokens, or payment details. ## Before You Post Adding the connector does not post anything. Claude uses Mallary when you ask it to. Before you ask Claude to post, check the profile, social sites, words, media, and time. ## Edit a Scheduled Post Ask Claude to find the scheduled post and show its saved words, time, profile, and accounts. Then say exactly what you want to change. One Mallary connection profile applies to the whole post. You can move it to another profile and change the platform list in the same edit. Claude will use `mallary_get_post` to read the saved post, then `mallary_update_scheduled_post` to save your changes. If you change the profile or platforms, Claude must send the target profile ID and every platform that should get the post. Check the account names before you approve. Mallary stops the edit if posting has started or the post changed since Claude read it. ## Photos and Videos If you upload photos and videos in the Claude user interface, and ask Claude to post them on your social media platforms, then you must grant Claude network access to upload files to Mallary's CDN. Simply add `*.r2.cloudflarestorage.com` to your Additional allowed domains as shown below, then start a new chat session with Claude: Claude additional allowed domains interface ## Claude Connector and Claude Code The Claude connector is the quick way to use Mallary in Claude. The Claude Code plugin is a different setup. If you use Claude Code, connect Mallary only once. This keeps the same Mallary tools from showing up twice. ## Privacy and Support * [Privacy policy](https://mallary.ai/privacy) * [Terms of service](https://mallary.ai/tos) * [Email support](mailto:support@mallary.ai) Learn how Mallary sign-in works and how to turn off access. # Social Media CLI Source: https://docs.mallary.ai/home/cli Mallary CLI is a social media command line tool for developers, operators, CI pipelines, and AI agents. Use it to publish, inspect jobs, read post analytics and audience counts, manage webhooks, and work with connected platforms. Mallary CLI is a social media command line interface for the Mallary publishing platform. It serves developers, operators, automation scripts, CI jobs, and AI agents. If you want a social media CLI, Mallary gives you a direct command-line client for the public Mallary platform. Use it to upload media, create posts, schedule content, and read job status. You can also read post analytics and audience counts, list connected platforms, manage webhooks, and update brand settings. ## Start here Start with what the CLI covers, who it is for, and how it maps to the Mallary platform. Install, update, or remove the Mallary CLI with npm or npx. Run your first health check, upload, post creation, and job lookup commands. Use the CLI in scripts, CI pipelines, and AI-driven automation flows. ## What the Mallary CLI does With the CLI you can: * upload local media files * create and schedule posts * list comments and post supplied replies on published posts * read publishing jobs, including platform post IDs and URLs when available * list grouped posts * read post analytics and follower or subscriber counts * create, list, and delete webhooks * update settings for brand and auto-reply behavior * list connected platforms * disconnect platforms ## Who the Mallary CLI is for Mallary CLI is useful for: * developers who want quick local testing * operators who prefer shell workflows over dashboards * CI pipelines that need social publishing steps * scripts that automate content workflows * AI agents that need a stable command interface ## How Mallary CLI works Mallary CLI is a direct client for the public Mallary API. It does not bypass: * plan limits * feature gates * platform rules The CLI is a convenient interface over the same underlying Mallary system used by the dashboard, REST API, and MCP server. ## Authentication For interactive use, sign in with browser-based OAuth: ```bash theme={null} mallary auth login mallary auth status ``` One OAuth login gives access to view data, publish posts, reply to comments, and manage settings and connections. Users do not choose OAuth scopes. The CLI stores credentials outside your project by default and refreshes access automatically. `MALLARY_API_KEY` remains available as an optional environment override for CI or other non-interactive environments. ## Installation Install globally: ```bash theme={null} npm install -g @mallary/cli ``` Run without a global install: ```bash theme={null} npx @mallary/cli --help ``` ## Common commands Examples: ```bash theme={null} mallary health mallary upload ./launch.mp4 mallary posts create --message "Hello from Mallary" --platform facebook mallary posts create --message "A new Story" --platform facebook --platform instagram --post-type story --media ./story.mp4 mallary posts create --message "Hello from another profile" --platform facebook --profile-id AbC123xYz90 mallary posts list mallary posts get 123 --json mallary posts edit 123 --message "Updated text" --target-profile-id AbC123xYz90 mallary comments list --post-id 123 mallary comments reply --post-id 123 --comment-id "1789..." --message "Thanks for checking this out." mallary jobs get 123 mallary analytics list mallary audience list mallary profiles list mallary webhooks list mallary settings get mallary platforms list mallary platforms disconnect facebook ``` ## Media handling Mallary CLI handles media uploads for local and scripted workflows. Current behavior is: * Mallary uploads local files automatically * Mallary rejects external remote media URLs * Mallary accepts existing `https://files.mallary.ai/...` URLs Many downstream social platforms expect trusted hosted media URLs. ## Posting and scheduling Mallary CLI supports both simple and advanced post creation flows. You can: * create posts from flags * create posts from JSON payload files * schedule posts * schedule local wall-clock times with `--scheduled-timezone` * attach media * add follow-up comments on supported platform/format combinations * enable per-post AI auto reply * use platform-specific payloads in file mode * choose one shared format in flag mode with `--post-type` The CLI can test the same post payloads that you plan to send from automation or backend systems. For scheduling, you can either send an absolute timestamp with `--scheduled-at 2026-04-06T18:30:00Z`, or pair a local `--scheduled-at 2026-04-06T14:30` with `--scheduled-timezone America/New_York`. ## Supported platform-specific payload areas The current CLI README documents platform-specific payload examples for: * Facebook * Instagram * Threads * LinkedIn * YouTube * TikTok * Pinterest * Reddit * Bluesky * X For the exact supported `platform_options` structure and field names by platform, use the API reference here: [Platform options reference](/api-reference/endpoint/create#body-platform-options) Mallary CLI also inherits the same per-platform media rules as the API. For read-only format discovery, `mallary platforms list` returns the exact selectable `post_types` for each destination. If every selected platform should use the same type, pass `--post-type`. Use file mode when different destinations need different types. Examples: * Threads supports `platform_options.threads.post_type` with `text`, `image`, `video`, or `carousel`. * YouTube requires exactly one video. * YouTube file mode supports tags, playlist placement, and realistic AI-content disclosure through `platform_options.youtube`. * Facebook supports `platform_options.facebook.post_type` with `feed`, `story`, or `reel`. Reels use one 9:16 MP4 or MOV video that is 3 to 90 seconds long. * Instagram supports `platform_options.instagram.post_type` with `feed`, `story`, `reel`, or `carousel`. For a Reel, `shareToFeed` controls profile feed placement. Add `trialParams.graduationStrategy` in file mode to publish a Trial Reel. With a Facebook Login connection, file mode also supports `isPaidPartnership` and up to two `brandedContentSponsors` on feed posts, Reels, and carousels. * TikTok video posts require one video, and TikTok photo posts support up to 35 JPEG/WebP images. * TikTok defaults to `DIRECT_POST`, which publishes through Mallary. Set `platform_options.tiktok.post_mode = MEDIA_UPLOAD` only when you want to finish the post in the TikTok app. Inbox uploads stay `action_required` until you add the final TikTok post URL. * Pinterest requires exactly one image or GIF, or exactly one video. Mallary shortens Pin descriptions longer than 800 characters so they can publish. * X allows up to 4 images, or 1 video, or 1 GIF. For the full matrix, see: [Platform-specific media rules](/api-reference/endpoint/create#platform-specific-media-rules) ## JSON output and automation Mallary CLI supports `--json` output for scripting and automated workflows. This output format is a good fit for: * shell scripts * GitHub Actions * CI jobs * agent toolchains * local testing before integrating with the raw API ## Plans and access CLI access is available on paid plans only: * Starter * Pro * Business Current product rules are: * Free plans do not have CLI access * analytics access follows plan capabilities * use `mallary profiles list` to find the random public profile ID for non-default profiles * use `--profile-id` for non-default profiles when posting, listing posts, reading post analytics, audience counts, or settings, listing platforms, or disconnecting a platform * AI auto-reply features follow plan capabilities ## Good fit for the Mallary CLI Mallary CLI is a strong fit if you want: * the fastest way to test Mallary without building an API client * shell-first social media automation * a CI-friendly publishing interface * a command surface for AI agents or local scripts * easy local-media-to-post workflows # Mallary for Cursor Source: https://docs.mallary.ai/home/cursor Use Mallary in Cursor to plan posts, publish after approval, reply to comments, and check social media results. Mallary brings your social media workflow into Cursor. The plugin connects to your Mallary account with OAuth, so you do not need to paste an API key into Cursor. The Mallary plugin is ready for Cursor Marketplace review. Until Cursor approves the listing, you can install it from source for testing. ## What You Can Do * see your Mallary profiles and connected social accounts * create or schedule social posts * use a different message for each platform * check publishing jobs and open published posts * read comments and post approved replies * review post analytics * manage profiles, settings, platforms, and webhooks ## Install from Source Cursor needs a real directory copy. Do not use a symlink. ```bash theme={null} git clone https://github.com/mallarylabs/cursor-plugin.git mkdir -p ~/.cursor/plugins/local rsync -a --delete --exclude='.git' cursor-plugin/ ~/.cursor/plugins/local/mallary/ ``` Reload Cursor with `Cmd-Shift-P`, then choose `Developer: Reload Window`. Open `Cursor Settings` → `Plugins` and confirm Mallary appears. Then open `Cursor Settings` → `Tools & MCPs` and confirm `mallary` is listed. ## Sign In The first Mallary request opens Mallary in your browser. Sign in and approve the requested access. Cursor can then use Mallary without seeing your password, API keys, social account tokens, or payment details. Try this safe prompt: ```text theme={null} Ask Mallary to show my profiles and connected social accounts. Do not post or change anything. ``` You can also use the plugin command: ```text theme={null} /mallary Show my latest posts and their status. ``` ## Switching from an Older Setup If Mallary appears twice in Cursor, remove the older Mallary entry from `~/.cursor/mcp.json` or disable the older Claude plugin copy. Keep only one Mallary MCP connection enabled so Cursor does not show duplicate tools. ## Install from the Marketplace After Cursor approves the listing, install Mallary from Cursor chat: ```text theme={null} /add-plugin mallary ``` ## Safe Actions The plugin reads the current state first. Before it publishes, replies, deletes, disconnects an account, changes settings, or manages a webhook, it shows the exact action and asks for confirmation. Do not approve an action until the profile, platforms, message, schedule, destination, and other details are correct. ## Media in Version 1 Version 1 supports media that is already hosted at `https://files.mallary.ai`. Creating an upload URL does not upload a local file. Upload local media through Mallary or the Mallary CLI first, then use the approved Mallary media URL. ## Privacy and Support * [Privacy policy](https://mallary.ai/privacy) * [Terms of service](https://mallary.ai/tos) * [Cursor plugin source](https://github.com/mallarylabs/cursor-plugin) * [Email support](mailto:support@mallary.ai) See how OAuth permissions and account revocation work. # Social Media Automation for Make Source: https://docs.mallary.ai/home/make Use the official Mallary app for Make to create social posts, call the full Mallary API, and start workflows from publishing events. Mallary for Make has three simple modules. You can publish content, use any Mallary API feature, and start a workflow when Mallary sends an event. The official Mallary app has been submitted to Make and is under review for Marketplace publication. ## The three modules ### Create a Post Publish now or schedule a post on one or more connected social platforms. You can: * add your message, * choose the platforms, * choose a Mallary profile, * upload one image or video from an earlier Make step, * use more files that are already hosted at `files.mallary.ai`, * set a date and time, * add comments under the post, and * add options for each platform. ### Make an API Call Use any supported Mallary API route with your saved Mallary connection. This gives you access to profiles, connected platforms, posts, jobs, comments, replies, analytics, audience counts, settings, webhooks, and new API features. ### Watch Mallary Events Start a Make workflow when Mallary schedules, publishes, partly publishes, or fails a post. ## Connect your Mallary account 1. Open the Mallary dashboard. 2. Create a separate API key for Make. 3. Add a Mallary module to your Make scenario. 4. Click **Add** next to the Mallary connection field. 5. Paste your API key into the private connection form. 6. Save the connection. 7. Use **Make an API Call** with `GET /api/v1/profiles` to test it. Keep your API key private. Store it only in the Make connection. Do not put it in module fields, logs, notes, or screenshots. ## Publish a post Use **Create a Post**. Add: 1. Your message. 2. One or more platforms. 3. A profile ID if you do not want to use your default profile. 4. An image or video if you need one. 5. A date and time if you want to schedule the post. 6. Platform options if a platform needs its own message, title, privacy choice, board, subreddit, or other setting. This module can publish to real social accounts. Check the profile, platforms, text, media, and time before the scenario runs. The first response includes a Mallary job for each platform. Use **Make an API Call** to check a job or list posts after publishing finishes. ## Upload a file while posting Turn on **Upload one file** inside **Create a Post**. Map the file name and file data from an earlier Make step, then choose its content type. Mallary creates a short-lived upload URL, sends the file to Mallary storage, and adds the new `https://files.mallary.ai/...` URL to your post. This sends the selected file to Mallary storage. Do not map private, regulated, or secret files unless you mean to publish them. ## Use the full Mallary API Use **Make an API Call** for any feature that is not shown inside **Create a Post**. * Choose `GET`, `POST`, `PUT`, `PATCH`, or `DELETE`. * Enter a relative path such as `/api/v1/profiles`. * Add query values in the **Query string** field. * Add write data in the **JSON body** field. * Do not enter a full URL. * Do not add the Mallary authorization header. The saved connection adds it for you. Useful examples: * `GET /api/v1/profiles` * `GET /api/v1/platforms` * `GET /api/v1/posts` * `GET /api/v1/audience` * `GET /api/v1/comments` See the [API overview](/api-reference/introduction) for all routes and request fields. A custom API call can publish, reply, upload, change settings, disconnect accounts, or delete pending posts. Check the method, path, profile, and body before you run a write request. ## Watch Mallary events Use **Watch Mallary Events** to start a scenario when Mallary sends one of these events: * `post.scheduled` * `post.published` * `post.failed` * `post.partial` * `auto_reply.posted` When you enable the trigger, Make registers its webhook URL with Mallary. Mallary signs each delivery, and the trigger checks the signature before it returns the event. ## Source and support * Source: [github.com/mallarylabs/make-app-mallary](https://github.com/mallarylabs/make-app-mallary) * Mallary API: [API overview](/api-reference/introduction) * Website: [mallary.ai/integrations/make](https://mallary.ai/integrations/make) The source keeps the older focused modules hidden so existing Make scenarios can still use them. New scenarios show only the three modules listed on this page. # Social Media MCP Server Source: https://docs.mallary.ai/home/mcp Mallary MCP is a remote social media MCP server for AI agents and assistants. Use it to publish, reply, read post analytics and audience counts, manage profiles and settings, list connected platforms, and manage webhooks through Model Context Protocol. Mallary MCP is a remote social media MCP server for AI assistants, agent workflows, and developer tools that speak Model Context Protocol. Mallary MCP gives you a structured tool layer over the Mallary platform. Your AI agent can post to social media, upload media, and reply to comments. It can also read analytics and publishing jobs, manage profiles, settings, and webhooks, and list connected platforms. You do not need to build a custom REST client first. ## Start here Start with the transport model, endpoint shape, and base MCP behavior. Learn how to connect with OAuth or a Mallary API key. See the current Mallary MCP tool names for posting, uploads, comments, analytics, profiles, settings, connected platform listing, and webhooks. Review preflight, idempotency forwarding, API parity, and error handling details. ## Add to Cursor 1. Open Cursor Settings 2. Go to Tools & MCP 3. Click + Add new MCP server 4. Paste the following configuration: ```json theme={null} { "mcpServers": { "mallary": { "url": "https://mallary.ai/mcp" } } } ``` 5. Save the configuration. 6. Return to Tools & MCP. 7. When Cursor prompts you, click Connect. 8. Enter your Mallary API key in the browser to complete the OAuth flow. ## Add to Claude Code The official Mallary Claude Code plugin is under review for publication in the Claude Code plugin directory. While review is pending, you can install it directly from Mallary's GitHub marketplace. Mallary also provides an official Claude Code plugin that bundles this MCP server with Mallary-specific workflow instructions: ```bash theme={null} claude plugin marketplace add mallarylabs/claude-code-plugins claude plugin install mallary@mallary claude plugin enable mallary@mallary ``` Claude Code asks for your Mallary API key when you enable the plugin. To connect only the MCP server without the plugin: 1. For Claude Code, run: ```bash theme={null} claude mcp add --transport http mallary https://mallary.ai/mcp ``` 2. Run `/mcp`. 3. Select Authenticate for Mallary to complete the OAuth flow. ## Add to Claude Mallary is in the Claude Connector Directory. You do not need to add a custom server or paste in an API key. Open Mallary in Claude and add the connector. 1. Click **Add to Claude** above. 2. Sign in to Mallary and allow the connection. 3. [Grant Claude network access to upload files to Mallary's CDN](/home/claude#photos-and-videos) 4. Ask Claude to use Mallary for your social media work. See what Claude can do with Mallary. ## Add to ChatGPT Mallary is available as a ChatGPT plugin. You do not need to add a custom server or paste in an API key. Open Mallary in ChatGPT and install the plugin. 1. Click **Add to ChatGPT** above, then click **Install plugin**. 2. Sign in to Mallary and allow the connection. 3. Start a ChatGPT request with `@Mallary` and say what you want to do. See what ChatGPT can do with Mallary. ## Add to Codex ```bash theme={null} codex mcp add mallary --url https://mallary.ai/mcp ``` Run Codex with `codex`. Codex then prompts you to authenticate with OAuth. ## Add to VSCode Open the Command Palette (`CMD+Shift+P`) → `MCP: Add Server` and enter: ``` https://mallary.ai/mcp ``` or, add the following to your VSCode dedicated MCP configuration file `mcp.json`: ```json mcp.json theme={null} { "servers": { "mallary": { "url": "https://mallary.ai/mcp" } } } ``` ## Add to OpenCode Add to your `opencode.jsonc`: ```json opencode.jsonc theme={null} { "$schema": "https://opencode.ai/config.json", "mcp": { "mallary": { "type": "remote", "url": "https://mallary.ai/mcp", "oauth": {} } } } ``` Then authenticate: ```bash theme={null} opencode mcp auth mallary ``` ## What Mallary MCP does Mallary MCP exposes the same public publishing surface as the Mallary API through MCP tools. With Mallary MCP you can: * create upload URLs * create and schedule social media posts * read job status * list grouped posts * list comments and post supplied replies on published posts * delete pending posts * read analytics * list connected platforms across Mallary's supported platform set * list profile IDs with `mallary_list_profiles` * create and rename connection profiles * target non-default connection profiles with `profile_id` * read and update profile settings * manage webhooks * disconnect platforms ## Why teams use Mallary MCP Mallary MCP is useful when you want to connect social publishing directly into: * AI assistants * autonomous agent workflows * IDE agents * internal AI tooling * LLM-based operator workflows A model does not need to compose raw HTTP requests for every task. Instead, you give it a tool surface with clearer actions and safer inputs. ## Base URL ```text theme={null} https://mallary.ai ``` ## Endpoint Mallary serves MCP at: ```text theme={null} /mcp ``` Supported methods: * `POST /mcp` * `GET /mcp` * `DELETE /mcp` ## Authentication OAuth-ready clients should use Mallary's browser sign-in flow. Existing scripts and manual clients can still authenticate with a Mallary API key: ```http theme={null} Authorization: Bearer ``` Identity is resolved from the API key owner. ## MCP transport and behavior Mallary exposes a remote MCP server over Streamable HTTP for public API parity. That means: * MCP tools route through the existing `/api/v1/*` handlers * posting logic is not duplicated in a separate MCP-only implementation * Mallary can return tool responses as event-stream payloads * `mallary_create_post` runs preflight first by default ## Mallary MCP tools The current enabled tools are: * `mallary_create_upload_url` * `mallary_create_post` * `mallary_get_job` * `mallary_attach_tiktok_post_url` * `mallary_list_posts` * `mallary_list_comments` * `mallary_reply_to_comment` * `mallary_delete_post` * `mallary_get_analytics` * `mallary_get_audience` * `mallary_list_profiles` * `mallary_create_profile` * `mallary_rename_profile` * `mallary_list_platforms` * `mallary_disconnect_platform` * `mallary_get_settings` * `mallary_update_settings` * `mallary_list_webhooks` * `mallary_create_webhook` * `mallary_delete_webhook` Use `mallary_list_profiles` to find random public profile IDs. Tools that publish, list posts, read comments, read post analytics, read audience counts, list platforms, read settings, update settings, or disconnect platforms accept `profile_id` for non-default connection profiles. Omit it to use the default profile. ## What makes Mallary MCP useful Mallary MCP is a strong fit when you want an AI workflow to: * generate content and publish it * upload images or video before publishing * read whether a post succeeded or failed * list previous posts and grouped outcomes * read analytics snapshots after publishing * read follower and subscriber counts for connected accounts * register or remove webhooks as part of automation It gives you one social media tool surface instead of separate per-platform agent integrations. ## Relationship to the Mallary API Mallary MCP is not a separate product surface with different business rules. It uses the same underlying platform as the dashboard, REST API, and CLI, which means: * plan gating still applies * platform rules still apply * account identity still comes from the same Mallary user account * job and analytics behavior stay aligned across product surfaces When an MCP tool creates posts, any platform-specific posting behavior still comes from the API request model, especially `platform_options`. The same applies to scheduling. `mallary_create_post` accepts an absolute `scheduled_at`. It also accepts a local `scheduled_at` with a `scheduled_timezone` such as `America/New_York`. For the exact supported fields and examples by platform, see: [Platform options reference](/api-reference/endpoint/create#body-platform-options) The same is true for media validation. Examples: * Threads supports text-only posts, one image, one video, or a 2 to 20 item carousel using supported JPG/JPEG/PNG/WEBP/MP4/MOV media. * YouTube requires exactly one video. * YouTube video tags use `platform_options.youtube.tags`. * YouTube AI-content disclosure uses `platform_options.youtube.containsSyntheticMedia`. * Video thumbnails use `media[].thumbnail_url` and must point to a Mallary-hosted file URL. * TikTok video posts require one video, and TikTok photo posts support up to 35 JPEG/WebP images. * Pinterest requires exactly one image or GIF, or exactly one video. For the full matrix of platform-specific media rules, see: [Platform-specific media rules](/api-reference/endpoint/create#platform-specific-media-rules) ## Plans and feature access Comment listing and comment replies are available on all Mallary plans. Most other MCP tools require a paid plan. Current product rules are: * Free: comment listing and comment replies * Starter: MCP enabled * Pro: MCP enabled * Business: MCP enabled Other related capabilities such as analytics or AI auto replies still follow the plan rules of the authenticated account. ## Error handling When the underlying API call is not successful, Mallary MCP returns structured errors. Non-2xx results include fields such as: * `http_status` * `code` * `message` * `details` when available These fields help agents and integrations decide whether to retry, ask for missing data, or report a plan or validation error. ## Good fit for Mallary MCP Mallary MCP is a strong fit if you want: * social media tools inside an AI assistant * a clean MCP tool surface instead of raw HTTP orchestration * the same posting backend used by Mallary itself * uploads, posting, analytics, and webhooks in one MCP server # Social Media n8n Community Node Source: https://docs.mallary.ai/home/n8n You can now post your social media content, manage your replies, and trigger workflows from n8n with Mallary. Social media has always been central to automation, and when you combine the reliability and developer-first experience of Mallary, with the composability of n8n, something genuinely useful emerges. You can now post, schedule, manage comments, trigger workflows from events, and much more, all from within n8n. n8n workflow interface n8n has quietly become one of the most powerful workflow automation platforms available today. Whether you are syncing CRMs, building approval pipelines, or reacting to events in real time, n8n gives developers and teams the flexibility to automate almost anything without being locked into a single vendor. ## Things you can do with n8n and Mallary * create and schedule social media posts * upload image and video files to Mallary * use platform-specific captions with `platform_options` * list grouped posts and publishing jobs * get platform post IDs and post URLs * list your comments on published posts * post comment replies using your workflow * pull analytics into reports * list profiles and your connected social platforms * manage Mallary webhooks * start workflows from Mallary webhook events ## Install Self-hosted n8n users can install it from npm: ```bash theme={null} npm install @mallary/n8n-nodes-mallary ``` or via Settings > Community nodes: The Community nodes page in n8n settings Click the "Install a community node" button: The Install a community node button in n8n Enter the npm package name "@mallary/n8n-nodes-mallary" in the box. Then click Install: The n8n community node install dialog with the Mallary package name entered Create a new workflow. Open the nodes panel with + or the Tab key. Then search for Mallary: The n8n nodes panel with Mallary in the search box ## Credentials Get your API key from the Mallary dashboard. Then add it as a Mallary API credential. Keep your API key private. It can publish posts, reply to comments, read account data, and manage webhooks. Store it only in n8n credentials. # Node Types: ## Mallary node Use the Mallary action node when a workflow must perform an action in Mallary. Common workflows include: * publish one post to many platforms * upload a video and schedule it across YouTube, TikTok, Instagram, and LinkedIn * send new comments to Slack or a CRM * draft a reply with an AI step, then post that exact reply through Mallary * build a weekly social media analytics report ## Mallary Trigger Use the Mallary Trigger node when a Mallary event must start an n8n workflow. Supported events: * `post.scheduled` * `post.published` * `post.failed` * `post.partial` * `auto_reply.posted` * `*` When you activate the workflow, the trigger registers the n8n webhook URL with Mallary. When you deactivate the workflow, the trigger removes that webhook. ## Platform options The node includes common fields for platform-specific messages. It also supports advanced `platform_options` JSON for fields such as: * Instagram post type * TikTok direct post options * YouTube title and visibility * Pinterest board ID * Reddit subreddit * platform-specific captions Explicit n8n fields override matching values in the advanced JSON field. For the full API request shape, see [Create Post](/api-reference/endpoint/create). ## Safe use * Do not use production profiles for test posts unless you want public posts. * Do not upload private or sensitive files unless Mallary must host them. * Do not print or log your Mallary API key. * Review workflows that delete posts, disconnect platforms, or update settings. * Use test accounts before turning on scheduled or automatic workflows. ## Links * npm package: [https://www.npmjs.com/package/@mallary/n8n-nodes-mallary](https://www.npmjs.com/package/@mallary/n8n-nodes-mallary) * GitHub repo: [https://github.com/mallarylabs/n8n-nodes-mallary](https://github.com/mallarylabs/n8n-nodes-mallary) If you build something cool with it, we'd love to hear about it. # Get Started Source: https://docs.mallary.ai/index Mallary.ai provides a social media scheduling tool built for developers — with API, CLI, MCP, n8n, and Make support, plus AI-powered comment replies that keep your audience engaged automatically. ## 1. Setting up Get your API key. Then start posting.
  1. Sign up at [https://mallary.ai](https://mallary.ai)
  2. Connect your social media accounts using the dashboard
  3. Get your API key
  4. Start posting using the API, MCP, CLI, or dashboard
 ## 2. Choose your integration path Mallary has several ways to connect, and all of them reach the same underlying system. Use the ChatGPT plugin or Claude connector for a simple chat. Use the API for full control, or MCP for AI agents. Use the CLI for shell scripts, n8n or Make for workflow automation, or the dashboard for no-code publishing. You can switch between them, or combine them, at any time. Add Mallary to ChatGPT with OAuth. Then ask ChatGPT to post, reply, use images, and show your results. Add Mallary to Claude with OAuth. Then ask Claude to post, reply, upload media, and show your results. Build your own integration. A REST API with endpoints for posting, scheduling, media uploads, and analytics. It works with any language or framework. Native Model Context Protocol integration. Your AI assistant can schedule posts, read analytics, and manage accounts from the chat. Give your OpenClaw agent access to social media with the Mallary.ai CLI. It can plan, write, and post content across 10 platforms from one chat message. Use the official Mallary n8n community node to post, schedule, upload media, reply to comments, read analytics, and react to Mallary webhook events. Build visual social media workflows with the official Mallary app for Make. Publish posts, upload files, work with comments, read results, and watch events. Use the Mallary dashboard to connect accounts, create posts, schedule content, and review analytics without building an integration first. # Authentication Source: https://docs.mallary.ai/mcp-reference/authentication Connect to Mallary MCP with OAuth or a Mallary API key. Mallary MCP supports OAuth 2.1 for apps and agents. Mallary API keys remain supported for scripts and existing integrations. Mallary connectors for Claude, ChatGPT, Codex, and Cursor use OAuth. They never ask the user to create, paste, or reveal a Mallary API key.
  1. Sign up at [https://mallary.ai](https://mallary.ai)
  2. Connect your social media accounts in the Mallary dashboard
  3. Approve the access requested by your app, or get a Mallary API key for a manual setup
 ## OAuth OAuth-ready clients discover Mallary's authorization server automatically from: ```text theme={null} https://mallary.ai/.well-known/oauth-protected-resource ``` ChatGPT uses its own protected resource metadata: ```text theme={null} https://mallary.ai/.well-known/oauth-protected-resource/mcp/openai ``` Mallary uses the authorization code flow with PKCE. The authorization server is: ```text theme={null} https://auth.mallary.ai ``` Mallary asks the signed-in user to approve the app connection. First-party Mallary clients request the capabilities they need in one login, so the user does not choose scopes or sign in again before posting. Mallary never gives the app the user's password or connected social account tokens. Claude can use a Client ID Metadata Document, while other clients can use Mallary's dynamic client registration endpoint. Mallary keeps both methods available. Access tokens are short lived. Refresh tokens rotate, and revoked grants stop working. Users can review and revoke OAuth access at `https://mallary.ai/oauth-connections`. ## Keep an App Connected The app that runs the MCP client must renew its OAuth access tokens. Mallary cannot renew a token stored inside another app on that app's behalf. Read the current endpoints from this discovery document. Do not guess paths such as `/authorize`. ```text theme={null} https://auth.mallary.ai/.well-known/oauth-authorization-server ``` For a public client using dynamic registration, register both grant types and use PKCE with `S256`: ```json theme={null} { "grant_types": ["authorization_code", "refresh_token"], "response_types": ["code"], "token_endpoint_auth_method": "none" } ``` Also supply the client's name and exact callback URL. Use `https://mallary.ai/mcp` as the OAuth `resource` for the standard MCP endpoint. Request only the scopes the integration needs. Uploading, publishing, scheduling, and reading results need `mallary.publish` and `mallary.read`. Mallary issues refresh tokens to public PKCE clients registered for the refresh grant, even without `offline_access`. A registration that allows only `authorization_code` will not receive this capability. A client with a shared secret must also request `offline_access` to receive a refresh token. The connector host must: 1. Keep tokens and expiry details in its secure credential store. Never put them in prompts or logs. 2. Use the returned `expires_in` value to renew shortly before expiry. 3. Allow only one refresh at a time for each connection. Other requests must wait for that refresh. 4. Send `grant_type=refresh_token` to the discovered token endpoint with the registered client authentication and resource. 5. Save the new access token, rotated refresh token, and expiry together before resuming requests. Do not reuse the old refresh token. 6. On `invalid_grant`, stop and ask the user to reconnect. Do not keep retrying a revoked or expired grant. For endpoints that issue MCP sessions, a refreshed token from the same client and grant can use the existing session. A new consent grant needs a new session. A fresh credential reference from a host's vault does not, by itself, prove that the underlying OAuth token was renewed. Before releasing a connector, test two token renewals and a new conversation without asking the user to reconnect. If the host manages OAuth internally, the host must provide this behavior; a tool description or skill cannot add it. ## OAuth Scope Reference These scopes remain part of the OAuth protocol for client compatibility. They are not choices shown by the Mallary CLI. * `mallary.read`: read posts, comments, analytics, profiles, platforms, settings, and webhooks * `mallary.publish`: upload media and create or schedule posts * `mallary.engage`: reply to comments * `mallary.manage`: change settings, profiles, webhooks, connections, and pending posts ## API Key Header For a manual API-key setup, send the key as a bearer token: ```http theme={null} Authorization: Bearer ``` ## Identity Resolution Identity is always resolved from the OAuth grant or API key owner. You do not separately pass a user ID when calling MCP tools. ## Base URL Mallary MCP is served from: ```text theme={null} https://mallary.ai ``` ## Endpoint Use the MCP server at: ```text theme={null} /mcp ``` Use this OAuth-only endpoint for ChatGPT: ```text theme={null} /mcp/openai ``` # Behavior Source: https://docs.mallary.ai/mcp-reference/behavior How Mallary MCP handles tool execution, preflight, idempotency, and errors. ## API Parity Mallary exposes a remote MCP server over Streamable HTTP for public API parity. MCP tools route through the existing `/api/v1/*` handlers. Mallary does not duplicate posting logic in a separate MCP-only layer. ## Preflight `mallary_create_post` runs preflight first by default with `run_preflight=true`. ## Idempotency If you send `idempotency_key`, Mallary forwards it as an `Idempotency-Key` header to the underlying API handler. Do not treat that header as a guarantee that a repeated request will be deduplicated. If a publishing call times out or loses its response, use `mallary_list_posts` and `mallary_get_job` to check the saved result before taking any further action. Do not automatically repeat a publishing call. ## Error Shape Mallary returns non-2xx API results as structured MCP errors with: * `http_status` * `code` * `message` * `details` when available ## Transport Note The standard `/mcp` endpoint returns one JSON result for each POST containing a JSON-RPC request. Other Mallary MCP endpoints can return an SSE stream. Clients must support both `application/json` and `text/event-stream` and include both in the `Accept` header. Keep the returned `Mcp-Session-Id` and negotiated `Mcp-Protocol-Version` for later requests. An accepted notification, including `notifications/initialized`, returns `202` with an empty body. Reuse the session for a workflow instead of initializing before every tool call. For SSE, read complete events until the response with the matching JSON-RPC ID arrives. Do not wait for a fixed-size buffer or stream closure. Close the response when finished and bound both blocked reads and total elapsed time. ## Approval Waits and Timeouts A host may pause a request for user approval before Mallary receives it. Mallary cannot remove that prompt or tell the client how long the user will take. Use the host's supported background execution and process-status tools while an approval is pending. A short execution yield is a way to return control; it must not kill the network request. Keep one process active rather than starting another copy. Check every timeout layer. A shell or task timeout must allow enough time for all sequential network requests and cleanup. For example, a 150-second process timeout will kill a client that is allowed to wait 300 seconds for one request. Keep time limits bounded and show an honest timeout message; do not label every delay as a Mallary outage. ## Recovering from Errors | Result | Client action | | - | - | | `401` / invalid token | Use the host's supported OAuth renewal path. Do not keep sending the rejected token. Reconnect if renewal is unavailable or returns `invalid_grant`. Report temporary network failures as temporary; do not force new consent for them. | | `403` / scope or session mismatch | Check the required scope and connection. A new grant must not reuse another grant's session. Do not widen access silently. | | `404` / JSON-RPC `-32004`, "Session not found" | Initialize a new MCP session. Read calls can then be resumed. Preserve the rule against automatically repeating writes. | | `429` | Respect `Retry-After` and use bounded backoff for safe reads. | | Timeout, disconnect, invalid response, or `5xx` | A write may already have succeeded. Check saved posts or jobs before taking any further action. | Keep credentials, signed upload URLs, and raw provider response bodies out of diagnostic logs. # Configuration Source: https://docs.mallary.ai/mcp-reference/configuration Environment variables used to control the Mallary MCP server. ## Environment Variables These environment variables configure Mallary MCP: * `MCP_ENABLED` * `MCP_PATH` * `MCP_MAX_BODY_BYTES` * `MCP_ALLOWED_ORIGINS` OAuth is run as a separate Node service. It uses: * `MALLARY_OAUTH_ENABLED` * `MALLARY_OAUTH_ISSUER` * `MALLARY_OAUTH_RESOURCE` * `MALLARY_OAUTH_PORT` * `MALLARY_OAUTH_STORAGE_KEY` * `MALLARY_OAUTH_INTERACTION_KEY` * `MALLARY_OAUTH_JWKS_PATH` or `MALLARY_OAUTH_JWKS_JSON` * `MALLARY_OAUTH_INTROSPECTION_CLIENT_ID` * `MALLARY_OAUTH_INTROSPECTION_CLIENT_SECRET` (optional; derived from the storage key when omitted) * `MALLARY_OAUTH_TEST_USER_IDS` (optional rollout allowlist) ## Defaults and Values * `MCP_ENABLED`: `0` or `1` * `MCP_PATH`: defaults to `/mcp` * `MCP_ALLOWED_ORIGINS`: comma-separated list of allowed origins ## Endpoint Methods Mallary MCP supports: * `POST /mcp` * `GET /mcp` * `DELETE /mcp` `GET /mcp` supports session transport. `DELETE /mcp` supports session termination. The OAuth service should bind to a private local port and be exposed only through TLS at `https://auth.mallary.ai`. # MCP Overview Source: https://docs.mallary.ai/mcp-reference/introduction Connect to the Mallary MCP server over Streamable HTTP. Mallary exposes a remote MCP server over Streamable HTTP for public API parity. ChatGPT uses a smaller OAuth-only MCP endpoint at `/mcp/openai`. It includes the tools needed to upload social images, publish posts, reply to comments, and read results. The main `/mcp` endpoint keeps the full Mallary tool set for other MCP clients. ## Base URL ```text theme={null} https://mallary.ai ``` ## MCP Endpoint Mallary serves MCP at: ```text theme={null} /mcp ``` Supported methods: * `POST /mcp` * `GET /mcp` * `DELETE /mcp` ChatGPT uses the same methods at: ```text theme={null} /mcp/openai ``` ## What You Can Do Mallary MCP gives MCP clients the same publishing surface as the public Mallary API. This surface includes: * posting and media uploads * comment listing and comment replies * analytics * connected platform listing and platform disconnects * webhook management ## Included Reference Pages Use the rest of this section for: * authentication * enabled tools * runtime behavior * server configuration # Tools Source: https://docs.mallary.ai/mcp-reference/tools The tools currently exposed by the Mallary MCP server. ## Enabled Tools (v1) Mallary MCP currently exposes these tool names: * `mallary_create_upload_url` * `mallary_create_post` * `mallary_get_job` * `mallary_attach_tiktok_post_url` * `mallary_list_posts` * `mallary_get_post` * `mallary_update_scheduled_post` * `mallary_list_comments` * `mallary_reply_to_comment` * `mallary_delete_post` * `mallary_get_analytics` * `mallary_get_audience` * `mallary_list_profiles` * `mallary_create_profile` * `mallary_rename_profile` * `mallary_list_platforms` * `mallary_disconnect_platform` * `mallary_get_settings` * `mallary_update_settings` * `mallary_list_webhooks` * `mallary_create_webhook` * `mallary_delete_webhook` ## Upload a Video with Standard MCP The standard MCP endpoint at `https://mallary.ai/mcp` exposes `mallary_create_upload_url` for images and videos. It uses the same presigned upload flow as the REST API. 1. Call `mallary_create_upload_url` with `{"filename":"launch.mp4","type":"video/mp4"}`. 2. Send the video bytes to the returned `uploadUrl` with HTTP PUT. Use the returned `headers` without changing them. 3. Wait for the upload to finish, then pass `mediaUrl` to `mallary_create_post` in `media[].url`. Your MCP client must be able to read the file and send the HTTP PUT request. The upload tool returns a URL; it does not copy a local file by itself. Mallary's current ChatGPT plugin uses a separate tool set and does not expose this flow. ## ChatGPT Tool Set The current public ChatGPT plugin connects through `/mcp/openai`. This smaller endpoint does not expose profile management, settings, webhooks, account disconnects, pending-post deletion, or scheduled-post editing. Its currently approved tool set includes: * `mallary_upload_image` * `mallary_create_post` * `mallary_get_job` * `mallary_list_posts` * `mallary_list_comments` * `mallary_reply_to_comment` * `mallary_get_analytics` * `mallary_get_audience` * `mallary_list_profiles` * `mallary_list_platforms` `mallary_upload_image` accepts one image that the user chose or made in ChatGPT. Mallary checks the file bytes, accepts JPEG, PNG, WebP, or GIF images up to 25 MB, stores the image at `files.mallary.ai`, and returns the `media_url` used by `mallary_create_post`. Do not use the ChatGPT image tool for private customer files, health records, ID records, card details, passwords, API keys, or access tokens. ## Tool Surface These tools cover: * uploads * post creation * job lookup * TikTok final URL attachment * post listing * scheduled-post detail and editing * comment listing and supplied comment replies * post deletion * post analytics and account audience retrieval * profile listing * profile creation and rename * profile settings retrieval and update * connected platform listing * platform disconnects * webhook listing * webhook creation * webhook deletion ## Connected Platforms `mallary_list_platforms` returns Mallary's supported public platform set and marks which of those platforms are currently connected for the authenticated account. The response includes: * `platforms`: every supported public platform with a `connected` boolean * `connected`: the connected subset * `disconnected`: the remaining supported platforms * `counts`: connected and supported totals * `profiles`, `profile_id`, `default_profile_id`, and `limits` for connection profile context ## Connection profiles MCP tools use the default Mallary profile unless you send `profile_id`. Use `mallary_list_profiles` to list each profile's random public ID, then pass that string as `profile_id` when targeting a non-default profile. Use `mallary_create_profile` to create a new profile and `mallary_rename_profile` to rename an existing profile. `mallary_get_audience` returns the latest follower or subscriber count for every connected account in the selected profile. Mallary updates supported counts once every 24 hours. TikTok returns followers when the connection includes audience stats access. LinkedIn reports `permission_required` until Mallary adds the permission it needs. The following tools accept `profile_id`: * `mallary_create_post` * `mallary_list_posts` * `mallary_update_scheduled_post` (inside `destinations` when moving a post group) * `mallary_list_comments` * `mallary_get_analytics` * `mallary_get_audience` * `mallary_list_platforms` * `mallary_get_settings` * `mallary_update_settings` * `mallary_disconnect_platform` ## Settings `mallary_get_settings` reads profile settings, business profile fields, auto-reply status, warnings, and plan capabilities. `mallary_update_settings` updates only the fields you send. Supported fields include `auto_reply_enabled`, `brand_profile`, `business_name`, `business_description`, `website_url`, `services`, `features`, `contact_info`, `pricing`, and `faq`. ## Comment Engagement `mallary_list_comments` and `mallary_reply_to_comment` are available on all Mallary plans. Use `mallary_list_comments` with a Mallary `post_id`/job ID to read comments on a published post. Then you or your AI agent can write a reply and pass that exact text to `mallary_reply_to_comment`. Supported platforms are Facebook, Instagram, Threads, LinkedIn, X, YouTube, and Bluesky. The MCP tool does not generate the reply. If you want auto-generated replies, use the Mallary AI auto reply feature. ## Scheduling `mallary_create_post` uses the same scheduling contract as the Mallary API: * send an absolute `scheduled_at` like `2026-04-06T18:30:00Z` * or send a local `scheduled_at` like `2026-04-06T14:30` together with `scheduled_timezone: "America/New_York"` * `scheduled_timezone` must be a valid IANA timezone ## Edit a Scheduled Post Use `mallary_get_post` with the stable numeric Mallary post ID from `mallary_list_posts`. It returns the saved content, schedule, destination accounts, `editable` status, and `revision`. Only a post group whose destinations have not started publishing can be edited. Use `mallary_update_scheduled_post` with that ID, `expected_revision`, and only the fields to change. You can edit the message, media, comments under the post, platform options, auto-reply setting, date, time, time zone, destination platforms, and connection profile. `media`, `comments_under_post`, and `platform_options` replace their saved values when supplied, so send the complete final value or leave the field out. If another edit or publishing starts first, the update returns a conflict. Read the post again before deciding what to do; do not repeat the old update automatically. One connection profile applies to the whole post group. To change its profile or platforms, send **both** `destinations.profile_id` and the complete final `destinations.platforms` list. Get the target profile ID from `mallary_list_profiles`, then check its accounts with `mallary_list_platforms`. Mallary validates every selected destination. A platform omitted from the final list is removed, so list every platform the user wants to keep. Leaving `destinations` out keeps the existing profile and platforms. ```json theme={null} { "id": 123, "expected_revision": 4, "message": "Updated launch note", "scheduled_at": "2026-10-15T14:30:00Z", "destinations": { "profile_id": "ProfileTarget1", "platforms": ["linkedin", "bluesky"] } } ``` Use an empty `media` or `comments_under_post` array to clear those fields. Use `platform_options: null` to clear all platform overrides, or `scheduled_timezone: null` to clear the saved time zone when changing to an absolute scheduled time. Mallary checks account-specific options, such as a Pinterest board, against the final destination accounts. The ChatGPT tool accepts a strict set of platform option fields. If the saved post has an option that ChatGPT cannot send back, leave `platform_options` out to keep it. Use the dashboard or API if that option itself must change. ## Publish Results `mallary_create_post` returns Mallary job IDs immediately. After each platform finishes publishing, `mallary_get_job` and `mallary_list_posts` include `platform_post_id` and `platform_post_url` when the platform returns or exposes them. ## Platform-specific options `mallary_create_post` uses the same underlying post payload as the Mallary API, including `platform_options` for platform-specific behavior. For the exact supported `platform_options` fields and examples, use the API reference here: [Platform options reference](/api-reference/endpoint/create#body-platform-options) ## Platform-specific media rules `mallary_create_post` also uses the same platform media validation rules as the Mallary API. LinkedIn accepts one MP4 video up to 1 GB (1,073,741,824 bytes), from 3 seconds to 30 minutes long. Use `mallary_create_upload_url` to upload the video to Mallary, then pass the returned media URL to `mallary_create_post` with `platforms: ["linkedin"]`. No video-specific platform option is needed. Do not mix images and video. Examples: * Threads supports `platform_options.threads.post_type` with `text`, `image`, `video`, or `carousel`. Its media shapes are text-only, one image, one video, or a 2 to 20 item carousel. * Instagram Reels support `platform_options.instagram.shareToFeed`. It defaults to `true`; set it to `false` to keep the Reel off the profile feed. * Instagram Trial Reels support `platform_options.instagram.trialParams.graduationStrategy`. Use `MANUAL` or `SS_PERFORMANCE`. Do not send `shareToFeed` with `trialParams`. * Instagram feed posts, Reels, and carousels support `platform_options.instagram.isPaidPartnership` and up to two `brandedContentSponsors`. This needs an Instagram account connected through Facebook Login. Sponsors can be usernames or numeric Instagram user IDs. * YouTube requires exactly one video. * TikTok video posts require one video, and TikTok photo posts support up to 35 JPEG/WebP images. * TikTok uses `DIRECT_POST` by default. Use `MEDIA_UPLOAD` only when you want to finish the post in TikTok. Inbox uploads stay `action_required` until you add the final TikTok post URL. * Pinterest requires exactly one image or GIF, or exactly one video, plus `boardId`. * Reddit image posts require one image or GIF. The current public API path does not support Reddit video upload. * X allows up to 4 images, or 1 video, or 1 GIF. For the full per-platform matrix and current runtime caveats, see: [Platform-specific media rules](/api-reference/endpoint/create#platform-specific-media-rules) ## Video thumbnails `mallary_create_post` accepts `thumbnail_url` on media items, using the same contract as the REST API: ```json theme={null} { "platforms": ["youtube", "facebook"], "message": "Launch walkthrough", "media": [ { "url": "https://files.mallary.ai/uploads/launch.mp4", "thumbnail_url": "https://files.mallary.ai/uploads/launch-cover.jpg" } ] } ``` The thumbnail URL must already point to `https://files.mallary.ai/...`. YouTube regular videos, Facebook feed videos, and Instagram videos/Reels can use custom thumbnails or covers. For a YouTube Short, YouTube may store the image but show a video frame instead. Mallary returns a warning when this happens. TikTok video posts use a frame from the video instead of a separate image. TikTok photo posts can use `thumbnail_url` only when it matches one of the supplied photo URLs, and that image becomes the photo cover. All media URLs used with `mallary_create_post` must point to `https://files.mallary.ai/...`. For another file, call `mallary_create_upload_url`, upload the file with the returned PUT URL, and then use the returned Mallary media URL. Mallary rejects outside media URLs because they may be private or expire before a post is published. For YouTube, set `platform_options.youtube.playlist_id` to add the new video to an existing playlist owned by the connected channel. Set `platform_options.youtube.tags` to a list of video tags. Each tag can use up to 100 characters, and the full tag list can use up to 500 characters after YouTube counts separators. Set `platform_options.youtube.containsSyntheticMedia` to `true` when the video contains realistic AI-generated or altered content that could look real.