Authentication
Before using the Mallary API:
- Sign up at https://mallary.ai
- Connect your social media accounts in the Mallary dashboard
- Get 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:twitterxfacebookinstagramlinkedinyoutubetiktokpinterestredditthreadsbluesky
Posting Features
POST /api/v1/post supports:
- one or more target platforms
- optional
profile_idfor non-default connection profiles - media attachments
comments_under_post- optional scheduling with
scheduled_at. Send an absolute timestamp such as2026-04-06T18:30:00Z - timezone-aware scheduling with
scheduled_timezone. A local2026-04-06T14:30then resolves in an IANA timezone such asAmerica/New_York - optional per-post AI auto-reply override
- per-platform
platform_options - optional
webhook_url - optional
Idempotency-Key
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:- TikTok
- YouTube
- Threads
- Bluesky
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, andcarouselpost types. Carousel posts support 2 to 20 supported media items. - YouTube requires exactly one video.
- Facebook supports
feed,story, andreelpost types. Reels use one 9:16 MP4 or MOV video that is 3 to 90 seconds long. - Instagram supports
feed,story,reel, andcarouselpost 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.
Connection Profiles
Mallary groups connections into named profiles. This supports multiple connected accounts per platform. Existing accounts use the default profile. UseGET /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:
5for $15/month - Pro:
15for $29/month - Business:
100for $95/month
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

