Skip to main content
Mallary API is the public API for multi-platform publishing, analytics, media upload, and webhooks.

Authentication

Before using the Mallary API:

  1. Sign up at 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:

Base URL

Flow Example: video post to multiple platforms

1

Get a presigned URL for your video

post-a-video.ts
2

Upload the video

post-a-video.ts
3

Create a post with the video attached

post-a-video.ts
4

Check the job status

post-a-video.ts

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
Use a new random Idempotency-Key for each approved post. After a lost reply, send the exact same request with the same key to get the original batch and job IDs. Read those jobs to check their current status. The key belongs to your Mallary account, across all profiles. Changed content, media, platforms, profile, or schedule with the same key returns 409 idempotency_key_conflict. A request still committing can return 409 post_submission_in_progress; check status, then retry the same request and key. Keys stay reserved while publishing history is kept. A new approved post needs a new key, even if its content is the same. Requests without a key do not have this retry protection.

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

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

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. Total connected social media account allowances are:
  • Starter: 5 for $15/month
  • Pro: 15 for $29/month
  • Business: 100 for $95/month
Posts are unlimited. Use any mix of supported platforms across your profiles. Existing customers keep their current terms; read the returned account limits for the authenticated workspace.

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

Saved Drafts

Saved drafts are available to all users. Save unfinished posts without a publish date or a publishing job. Read, edit, or delete them, then publish or schedule when ready. A request to save a draft does not authorize publishing.
Last modified on October 31, 2026