Social Media Posting API
A social media posting API lets you publish to multiple platforms with one request instead of building and maintaining a separate integration for every network.
curl -X POST {{API_BASE_URL}}/v1/posts \
-H "x-access-key: your-api-key" \
-H "Content-Type: application/json" \
-d '{
"content": "A short example update.",
"mediaItems": [
{ "type": "image", "url": "https://example.com/launch.png" }
],
"platforms": [
{ "platform": "twitter", "accountId": "acc_tw_123" },
{ "platform": "instagram", "accountId": "acc_ig_456" },
{ "platform": "facebook", "accountId": "acc_fb_789" },
{ "platform": "tiktok", "accountId": "acc_tt_012" }
],
"publishNow": true
}'curl -X POST {{API_BASE_URL}}/v1/posts \
-H "x-access-key: your-api-key" \
-H "Content-Type: application/json" \
This guide covers the exact create-post contract, the field map for content, media, scheduling, and platform-specific options, and how to handle per-platform results when some destinations succeed and others fail.
What a social media posting API does
Think of this kind of API as a single doorway to many social accounts. Your software hands over one normalized payload, and the service translates it for each connected destination, returning a separate outcome per network. That design suits products where people should post from inside the app, or tools that generate copy and need it delivered consistently. The compromise is reliance on the middle layer for formatting, media checks, authorization, and error handling, so confirm native-feature coverage for each destination before adopting it.
Add social media to your product in three steps
Getting started follows a simple sequence. You first obtain a key and present it through the x-access-key header. Next, each social account is linked once via hosted authorization, sparing your codebase from creating developer applications or managing token refresh for every network. Then you issue a create-post call specifying the text, optional media, and a platforms entry for each destination and accountId. Because the link persists, the same accounts can later support publishing, scheduling, analytics, comments, and messaging without repeating setup.
Exact endpoint contract
Calls go to POST {{API_BASE_URL}}/v1/posts, authenticated with the x-access-key header and carrying a JSON payload under Content-Type application/json. In the curl example, content holds the shared text, mediaItems holds objects with type and url, platforms holds objects with platform and accountId, and publishNow signals immediate delivery. For server-side Node.js work, the JavaScript fetch example follows the same shape, with the key read from an environment variable instead of being embedded in source.
Field map for content, media, scheduling, and platform-specific data
Build your client around the field map. Use content for the common message, mediaItems for the common media list, and platforms for destinations, where each item pairs platform with accountId. Inside each platforms[] item, place options for that network in platformSpecificData, such as Twitter polls, YouTube tags, TikTok privacy settings, or Pinterest board targeting. Scheduling uses scheduledFor together with an IANA timezone to pin down local time. Before sending, verify that each platforms entry includes both platform and accountId, each mediaItems entry has a reachable url, scheduledFor lies in the future for a planned post, and platformSpecificData contains only options valid for that destination.
Structured response and per-platform status
A successful call returns postId for the unified post, status for the overall state, and a platforms array with one object per destination containing platform, success, and platformPostUrl. Inspect those per-destination objects rather than trusting the top-level status alone, since a request spanning several networks may only partly succeed. A sound client keeps postId for later lookup, saves each platformPostUrl for reporting and links, and handles failed destinations individually so only those are retried.
Media, scheduling, and partial-failure handling
Supported media includes images, videos, carousels, and destination-native formats such as Reels, Shorts, and Stories, checked and adapted for each network before delivery. Limits differ by destination and account, so media accepted in one place may be refused in another. If a destination fails, the ones that succeeded stay published, the failed entry reports its own platform-specific error for retry, and failed posts do not consume credits. Retry only the failed platforms entries and preserve successful platformPostUrl values, because resending everything would duplicate posts where delivery already worked.
Integration paths: REST, SDKs, no-code, and AI agents
Pick the path that fits your team. REST is the primary route and uses the contract described here. Typed SDKs for Node.js and Python wrap that same contract for teams preferring generated clients. No-code automation tools that support HTTP requests or webhooks, such as Make, Zapier, and n8n, can call the endpoint without a custom backend. AI agents can publish through REST tool calling, hosted MCP, or agent skills. Regardless of path, keep the same discipline: validate media and scheduling fields first, examine every platforms entry in the response, and retry only destinations that failed.
Choosing one unified API versus separate native APIs
A unified posting API makes sense when you publish to several platforms from one codebase, want authorization and token handling centralized, and can reach needed native features through platformSpecificData. Separate native APIs make sense when a destination-specific behavior is unavailable through the unified layer, or when you need direct control over that platform's developer application and rate limits. Either choice can start from the contract here: one POST to /v1/posts, a clear field map, and per-platform results you can act on.
| Field | Location | Purpose |
|---|---|---|
| content | Request body | Shared post text |
| mediaItems | Request body | Array of media objects with type and url |
| platforms | Request body | Array of destination targets |
| platform | platforms entry | Destination platform name |
| accountId | platforms entry | Connected account to publish from |
| publishNow | Request body | Publish immediately when true |
| scheduledFor | Request body | Scheduled publish time, used with an IANA timezone |
| platformSpecificData | Each platforms[] entry | Options for that destination only; alongside its platform/accountId and optional content override |
| postId | Response | Unified post identifier |
| status | Response | Overall post status |
| success | platforms entry | Per-platform success state |
| platformPostUrl | platforms entry | Published post URL for that destination |
Requiredness and types are not fully specified in the captured source; this map records observed field names and roles only.
| Scenario | What to check | Action |
|---|---|---|
| All destinations succeed | Every platforms entry has success true and a platformPostUrl | Store postId and each platformPostUrl |
| Some destinations fail | Failed entries carry a platform-specific error; successful entries remain published | Retry only the failed platforms entries; failed posts do not consume credits |
| Media rejected by one destination | The failing entry's error names the platform constraint | Adjust or replace the mediaItems entry for that destination and retry it |
| Scheduled post needs changing | scheduledFor and timezone were supplied on the original request | Use the scheduling workflow to view, modify, or cancel before delivery |
Partial-failure and credit semantics are retained only as captured in the source FAQ text.
| Criterion | Unified posting API | Separate native platform APIs |
|---|---|---|
| Number of destinations | Better when you publish to many platforms from one codebase | Better when you support only one or two networks |
| Authorization | Hosted flow centralizes OAuth and token lifecycle | You manage each platform's developer application and tokens |
| Native features | Reached through platformSpecificData where exposed | Full direct access to each platform's native surface |
| Failure handling | One response with per-platform success and platformPostUrl | Separate responses and error formats per platform |
| Maintenance | One contract to maintain as platforms change | Each integration maintained independently |
Decision criteria are editorial guidance, not a claim about any specific provider's implementation.
Frequently asked questions
What is a social media posting API?
It is a programmatic interface that sends content to linked social accounts on a schedule or immediately. A product can therefore offer in-app publishing, and a content generator can distribute its output across several networks through a single normalized endpoint.
Which social media platforms can I publish to?
Destinations named for this workflow are Twitter/X, Instagram, YouTube, Facebook, TikTok, Threads, Pinterest, LinkedIn, Bluesky, and Google Business Profile. Whether a given account can publish, and which media it accepts, depends on that network and account.
Can I publish to multiple platforms in one request?
Yes. Put one entry per destination in the platforms array, each pairing a platform name with an accountId. The reply then contains a separate outcome for each entry, including its success flag and platformPostUrl, so you can see exactly which destinations worked.
Do I need to create developer applications for every platform?
Under a hosted authorization setup, the provider runs the underlying platform integrations and keeps tokens refreshed. The account owner still grants permission on the social network itself, but your own application does not need its own developer application for each network.
Which media formats can I publish?
Images, video, GIFs, carousels, and network-specific formats like Reels, Shorts, and Stories are the formats described for this workflow. Limits vary by destination and account, so check the target network's rules before sending media.
Can I schedule posts?
Supply scheduledFor along with an IANA timezone in the publishing request. Before the post goes out, the scheduling workflow lets you inspect, change, or cancel it.
What happens when one platform fails?
Results can be mixed: destinations that worked stay live, and each unsuccessful one reports its own error so it can be tried again on its own. A post that fails does not use credits.
Can I use this API without writing code?
Yes. Tools that can issue HTTP requests or handle webhooks, including Make, Zapier, and n8n, can invoke the endpoint directly without a bespoke backend.
Can an AI agent publish through this API?
An agent can call the endpoint through REST tool calling, a hosted MCP server, or agent skills where those paths are offered. It still needs a valid API key and linked accounts for every destination it posts to.
{
"postId": "post_abc123",
"status": "published",
"platforms": [
{
"platform": "twitter",
"success": true,
"platformPostUrl": "https://x.com/user/status/123"
},
{
"platform": "instagram",
"success": true,
"platformPostUrl": "https://instagram.com/p/abc"
},
{
"platform": "facebook",
"success": true,
"platformPostUrl": "https://facebook.com/post/456"
},
{
"platform": "tiktok",
"success": true,
"platformPostUrl": "https://tiktok.com/@user/video/789"
}
]
}