Overview
What PostMantis is, who it is for, and the core concepts behind the public API.
PostMantis gives you one API for agentic social workflows. Connect social accounts once in the dashboard, then publish and track delivery results centrally across Instagram, TikTok, LinkedIn, YouTube, X, Facebook, Threads, and Pinterest.
The API is the runtime surface. The dashboard handles setup and administration.
What to remember
Connect accounts once. Operate through one API. Keep publishing and delivery visibility in one place.
What PostMantis handles
Provider authentication
Connect accounts once in the dashboard. PostMantis manages OAuth tokens and refreshes them automatically — your code never touches provider credentials.
Format requirements
Each provider has different requirements for media, text limits, and post structure. PostMantis translates your request into what each provider expects.
Delivery and retries
PostMantis manages delivery jobs, handles rate limits, and surfaces per-delivery results so you know exactly what succeeded and what failed.
Partial failure visibility
One post can succeed on some providers and fail on others. Outcomes are reported per delivery — nothing is hidden behind a single status.
Who PostMantis is for
SaaS products
Embed social publishing into your product without building provider integrations yourself. Your users connect their accounts; your product posts on their behalf.
Automation pipelines
Add a reliable publish step to any workflow — scheduled jobs, event-driven systems, content pipelines, or backend workers.
Agencies
Manage multiple client accounts with clean separation. Each client's profiles and API keys are isolated.
AI agents and MCP servers
Give agents a single stable contract for drafting, scheduling, publishing, and inspecting social content across all providers.
Dashboard vs API
Both use the same post model. The difference is where setup happens and where runtime work happens.
Connect profiles
Connect social accounts and reconnect expired access.
Create posts manually
Draft, schedule, and publish posts directly from the dashboard UI.
Create API keys
Create and scope keys for automations and agents.
Admin and billing
Settings, billing, and operational visibility.
List profiles
Discover which connected profiles the API key is allowed to use.
Create and publish posts
Draft, schedule, publish, cancel, and inspect posts programmatically.
Uploads and delivery visibility
Handle private file uploads and inspect asynchronous delivery outcomes later.
How it works
You handle the content — PostMantis handles the delivery
You submit one request with your post body, selected profiles, and any media. PostMantis expands that into per-delivery jobs, processes media, applies provider requirements, and reports results back through the same post resource.
- Connect your social accounts in the dashboard.
- PostMantis stores and manages provider authentication — your API key never touches OAuth directly.
- Submit a post with
profilesset to your desired destinations. - PostMantis processes media, initiates delivery, and tracks per-delivery outcomes.
- Read results back from the post.
API key scope model
Keys can be restricted along three dimensions — only the allowed subset of profiles, providers, and actions is exposed to that key.
Key scope is immutable. If the allowed subset changes, revoke the old key and create a new one.
Permission scope
Read-only or write-capable.
Provider scope
Restrict to specific providers such as X, LinkedIn, or YouTube.
Profile scope
Restrict to specific connected profiles.
Posts are visible only when every delivery on the post is inside the key scope.
Core concepts
Profile
One connected publishable destination. Profiles are connected in the dashboard and selected in API requests by ID.
Post
The top-level publishing resource. Carries the body, media, selected profiles, scheduling, and provider-specific options.
Delivery
One delivery unit created by pairing a post with a selected profile. Delivery outcomes live at this level.
Media
Provided by remote URL, upload session, or direct multipart upload, then ingested into PostMantis-owned storage.
Naming guide
profiles— where the post should goprovider_options— provider-specific options for destinations you already selecteddeliveries— one delivery path inside a post (post × profile)- delivery results — what actually happened on each delivery