Skip to main content
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

​
Authentication

Authenticate with your 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
  • 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
  • Snapchat
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. Poll the job endpoint for per-platform status.
  4. Use grouped post listing and analytics endpoints for downstream reporting.
  5. 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".

​
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
  • Snapchat
Examples include Threads post type selection, TikTok direct-vs-upload mode, Pinterest board selection, and YouTube visibility. 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.
  • 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.
  • 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, Snapchat, and current runtime caveats, 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
Last modified on August 14, 2026