Social media API for ecommerce: how to publish through one API
A social media API publishes posts from your own software, but each platform has its own approvals and limits. Compare three routes and what a good API offers.

A social media API lets your own software create posts on social platforms without a person opening each app. For an online store the catch is that every platform has its own API, its own approvals and its own limits, so publishing to Instagram, Pinterest, TikTok and X means four separate connections. You can build each one, use a unified API that wraps them, or use a publishing API with previews and safety checks. This guide compares them.
Why does each platform need its own connection?
Each network runs its own API with its own sign-in, permissions, review process and content rules, so one integration does not carry over to the next. The work is rarely the API call itself. It is the account setup, the approvals and the upkeep around it.
For a store, a typical workflow has a product image, a caption and a list of destinations. Behind that sit four sets of requirements, covered below. They change over time, which means someone has to keep watching four sets of documentation. If you are building an agent or an internal workflow, that upkeep is the part to plan for.
What does Instagram require?
Instagram publishing needs a professional account and a two-step flow: create a media container, then publish it. Meta documents this in its content publishing guide.
The details that affect a store:
- Account type. The guide covers Instagram professional accounts. If the connected Page requires Page Publishing Authorization, publishing is blocked until that is complete.
- Permissions. The guide lists
instagram_content_publishorinstagram_business_content_publish, depending on the login route you choose. Meta's permissions reference includes an App Review submission for each, which asks for a use case and a screencast of the login and publishing flow. - Media. Media must sit on a publicly reachable server when you publish, because Meta fetches it by address. The guide says JPEG is the only supported image format.
- Containers. A container that is not published within 24 hours expires. For status checks the guide recommends polling once per minute, for no more than 5 minutes.
- Limits. The guide states 100 API-published posts in a 24-hour moving period, with carousels counting as one post. Its carousel section says 50. The page does not explain the difference, so treat the lower figure as the safe planning number.
- Scheduling. The guide mentions scheduling only once, in a recommendation that apps enforce the publishing limit themselves if they let users schedule posts for later. In practice, a tool that schedules holds the post and makes the publish call at the right time.
What do Pinterest, TikTok and X require?
Each one adds its own gate before a store's posts can appear publicly, and the gates differ in kind.
Pinterest. The documentation for creating boards and Pins lists the boards:read, boards:write, pins:read and pins:write scopes, and a Pin is saved to a board identified by a board ID. Pinterest's access tiers guide says Pins created with Trial access are visible only to their creator. Moving to Standard access needs a demo video that shows the OAuth flow and a live Pinterest integration. The same pages note that apps registered on or after September 14, 2026 may receive a 403 PINNER_DATA_ACCESS_DENIED error when requesting a board or Pin without authorization for non-business users.
TikTok. The Content Posting API guide requires a registered app with the Content Posting API product and Direct Post enabled, approval of the video.publish scope, and media that is either uploaded as a file or pulled from a verified domain or URL prefix. It states that content posted by unaudited clients is restricted to private viewing, so a new integration passes an audit before its posts can be public. The Direct Post reference documents a limit of 6 requests per minute per user access token.
X. The create a post reference uses POST /2/tweets with OAuth 2.0 user context and the tweet.write scope. Media is uploaded first, and the returned IDs are attached to the post. X's pricing page describes pay-per-usage billing from prepaid credits, with rates that can change, so check the Developer Console before you plan a budget.
What are your options besides building each connection?
You have three routes, and the right one depends on how much of the platform work you want to own.
| Route | You own | Good fit |
|---|---|---|
| Build each platform directly | App registration, review, tokens, media handling, limits, upkeep for every network | A team whose product is the integration |
| Unified API from a vendor | Your own workflow, plus the vendor's coverage and terms | Developers who need many networks behind one request shape |
| Publishing workspace with an API | Your workflow, with connections, previews and delivery records handled by the workspace | Stores and agencies that want the result without running the integrations |
Unified APIs are a category with many vendors. Compare them on facts you can check in each vendor's own documentation: which platforms and post types are covered today, whose app registration and review the connection uses, how tokens are stored, and what happens when a platform rejects a post. The platform approvals above still exist. A vendor either holds them for you or leaves them with you, so ask which.
What should a good publishing API offer?
A good publishing API separates preview from commit, makes retries safe, reports what actually happened and limits what each key can do. Those five properties matter more than the number of networks listed.
- Idempotency keys. Networks time out and agents retry. A stable key per logical post means a repeated request returns the original result instead of creating a second public post.
- Previews. A dry run that returns the normalized plan, warnings and blockers before anything is saved, so a person or an agent can review it.
- Status readback. A way to read each destination's outcome afterward. One post can succeed on Instagram and fail on Pinterest, so a single
success: truehides the part you need. - Webhooks. Signed notifications when a job changes state, so your system does not have to poll. Treat them as a nudge and read the record to confirm.
- Scoped keys. A key that can read brands and preview posts does not need permission to connect accounts or manage webhooks. If the key leaks, the damage is limited.
How does Creavily's Public API handle this?
Creavily's Public API covers the five properties above for the destinations a Brand has connected. A Workspace holds Brands, each Brand has Publishing Setups (the saved accounts and posting defaults it normally uses), and the API reads and writes within that structure. Keys carry scopes such as brands:read, channels:read, publishing:write and agent:publish, and the OAuth sign-in is available for apps that act for a user. The developer overview lists the scopes and routes, and the capability catalog at GET /v1/provider-capabilities describes what each platform supports. Live coverage varies by platform, so check the platform list on the product page before you plan around one.
The sketch below shows the safe order: read the saved destinations, preview, then read back. The values are placeholders, and the token comes from an environment variable.
# 1. Read the saved destinations for a Brand
curl -sS "https://api.creavily.com/v1/public/publishing-profiles?brandId=BRAND_ID&includeDisabledChannels=true" \
-H "Authorization: Bearer $CREAVILY_API_TOKEN"
# 2. Preview a post without saving anything
curl -sS https://api.creavily.com/v1/public/agent/publish-requests \
-H "Authorization: Bearer $CREAVILY_API_TOKEN" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: store-launch-spring-001" \
-d '{
"dryRun": true,
"plan": {
"brandId": "BRAND_ID",
"text": "Launch caption",
"mediaLibraryItemIds": ["MEDIA_ID"],
"targets": [{ "platform": "facebook_page", "channelAccountId": "CHANNEL_ACCOUNT_ID" }]
}
}'
# 3. Read a saved job and its per-destination status
curl -sS "https://api.creavily.com/v1/public/publishing/jobs/PUBLISH_JOB_ID" \
-H "Authorization: Bearer $CREAVILY_API_TOKEN"
The preview call is the agent publish request with dryRun set to true, which returns the plan and any blocking validation errors without saving or queueing anything. Setting dryRun to false on the same request saves the job, and handing it to the delivery queue is controlled by a separate enqueue flag. Reuse the same idempotency key for the same logical post and a new one for each different post.
How do webhooks, the SDK and MCP fit in?
Webhooks tell your system that something changed, the TypeScript SDK wraps the same routes in typed calls, and the MCP server lets an AI assistant use the same capabilities through a chat. All three sit on top of the Public API, so the scopes and checks are identical.
Creavily's webhook endpoints can be created and managed through the API with the webhooks:read and webhooks:write scopes, and the webhooks and SDK page describes signed updates and delivery history. The SDK's mutating methods accept an idempotency key as a request option. For assistants, the MCP server exposes read, preview and confirmed-write tools. A write needs an explicit confirmation flag and a stable idempotency key, so the assistant cannot publish by accident. The agent workflows page explains the operator side of this, and our posts on letting ChatGPT post to Instagram safely and on the AI social media manager cover it for non-developers.
What goes wrong most often, and how do you plan for it?
Most failures come from media, expired connections and uncertain outcomes, so build for those first.
- Media rejected by one network. Preview each destination separately. A file that is valid for one platform may be refused by another, and Instagram accepts only JPEG images through its publishing route.
- Expired or revoked connections. Treat a reconnect as an expected state and tell a person, instead of retrying forever.
- Timeouts after a publish call. Do not send the request again just because your client timed out. Read the job first. If the outcome is unknown, reconcile it before you retry.
- Rate limits. Respect each platform's limits and your API's limits, and back off when you receive a 429 response with a
Retry-Afterheader. - Secrets in the wrong place. Keep tokens in environment variables or a secret store, never in prompts, client code or screenshots.
Key takeaways
- Every platform has its own API, approvals and limits, so one connection per network is a large and continuing job.
- Instagram needs a professional account and a two-step publish, Pinterest limits Trial access, and TikTok restricts unaudited clients to private posts.
- You can build each connection, use a unified API, or use a publishing workspace with an API; ask any vendor which approvals it holds.
- A good publishing API offers idempotency keys, previews, per-destination status, webhooks and scoped keys.
- Never retry blindly after a timeout. Read the saved job and reconcile first.
FAQ
Is there one API that publishes to every social network?
Unified APIs exist, but each network still enforces its own account types, permissions and limits. Check which platforms and post types a vendor covers today in its own documentation.
Do I need Meta app review to publish to Instagram?
Meta's permissions reference includes an App Review submission for the publishing permissions, which asks for a use case and a screencast. If you use a tool that holds the approval, you connect your account through its sign-in instead.
Can I schedule posts with the Instagram API?
Meta's guide describes creating and publishing a container and gives no schedule field. A scheduling tool stores the post and publishes at the chosen time, and Meta advises such apps to enforce the publishing limit.
Is it safe to give an AI agent an API key?
Yes, if the key is scoped, stored as a secret and limited to preview and confirmed writes. Use a key that can only do what the agent needs, and revoke it when the job ends.
Where do I start with Creavily's API?
Create a scoped key, read your Brand and its Publishing Setups, then send a dry-run preview. The developer overview lists the routes and scopes.