Social Media API - Mallary.ai API, MCP, CLI Developer Docs

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

API Overview

Read the API overview, authentication model, platform support, and posting capabilities.

Upload Media

Start with presigned uploads if your workflow includes images or video.

Create a Post

Publish or schedule a post across one or more connected social platforms.

Track Jobs and Posts

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

https://mallary.ai

Authentication

Authenticate with your Mallary API key:

Authorization: Bearer <mallary_api_key>

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

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:

Upload media and get a public Mallary file URL.
Create a post with one or more target platforms.
If plans change before publishing starts, get the saved post and edit it.
Poll the job endpoint for per-platform status.
Use grouped post listing and analytics endpoints for downstream reporting.
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:

call the upload endpoint to get a presigned upload URL and final media URL
upload bytes to the returned URL
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

Mallary checks for new comments on supported posts.
It looks for questions about your business.
It uses your saved business details and the post to write a reply.
It posts the reply from your connected social account.
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.

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 [email protected]",
    "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

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

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

​Start here

API Overview

Upload Media

Create a Post

Track Jobs and Posts

​What the Mallary API does

​Why developers use the Mallary API

​Base URL

​Authentication

​Core API features

​Supported social media platforms

​Common Mallary API workflow

​Media upload and publishing model

​Posting and scheduling features

​AI Auto Replies

​What it does

​How it works

​How to enable it

​Connection profiles

​Platform-specific options

​Platform-specific media rules

​Analytics, job tracking, and grouped posts

​Webhooks

​Plans and feature gating

​Rate limits

​Good fit for the Mallary API