Schedule Instagram photos, carousels, Reels and Stories from your backend or your AI agent. Upload the media, send one POST /v1/posts, and get a signed webhook when it is live.
Base URL https://api.so-me.studio/v1 · Auth X-API-Key · socialMedia: INSTAGRAM
Send one of these values as postType. Every post needs text, and photos or videos are attached by fileId from your media library.
IMAGE
A single photo in the feed.
CAROUSEL
2 to 10 photos in one swipeable post. MULTIPLE_IMAGES is accepted as well.
REEL
One video, published as a Reel.
VIDEO
One video, which Instagram also publishes as a Reel. Its size rules are looser than those of REEL.
STORY
One photo or video as a Story. Instagram shows no caption on Stories.
Upload the media, then create the post. Leave out scheduledAt to publish right away.
POST /v1/media/presign-upload adds the file to your media library and returns a fileId and a presigned uploadUrl.
curl -X POST https://api.so-me.studio/v1/media/presign-upload \
-H "X-API-Key: $SOME_API_KEY" \
-H "Content-Type: application/json" \
-d '{"files":[{"filename":"launch-reel.mp4","mimetype":"video/mp4","size":48211904}]}'
# → [{ "fileId": "…", "uploadUrl": "https://…", "fileSrc": "…", "s3Key": "…" }]PUT the bytes to uploadUrl with exactly the Content-Type you declared. The URL is valid for one hour.
curl -X PUT "$UPLOAD_URL" \
-H "Content-Type: video/mp4" \
--upload-file ./launch-reel.mp4POST /v1/posts with the fileId. The response is the post with status SCHEDULED, and it publishes at scheduledAt through a queue that retries on failure.
curl -X POST https://api.so-me.studio/v1/posts \
-H "X-API-Key: $SOME_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"socialMedia": "INSTAGRAM",
"postType": "REEL",
"text": "Behind the scenes of launch week",
"fileIds": ["<fileId>"],
"scheduledAt": "2026-11-03T15:00:00Z",
"firstComment": "#launchweek #buildinpublic"
}'accountId is optional when the workspace has one Instagram account. Otherwise pass an id from GET /v1/accounts.
Files attached with fileIds are checked against the Instagram limits below before anything is queued. A file that breaks a rule returns 400 with a report per file.
The fields that change how a post is published on Instagram.
| Field | What it does |
|---|---|
| firstComment | A comment posted under the post right after it goes live, up to 2,200 characters. Good for hashtags or a link. |
| metaData.taggedPeople | An array of public Instagram usernames to tag on photos, carousel photos and Reels. Tagging is best effort: a wrong username never blocks the post. |
| accountId | The Instagram account to post from, as listed by GET /v1/accounts. Optional when the workspace has only one. |
Social media studio checks each file against these limits before it publishes. They are our configured limits, not a promise from Instagram: GET /v1/media/rules returns the live table, and POST /v1/media/validate checks a file without posting it.
Post type IMAGE
Post type CAROUSEL
Post type REEL
Post type VIDEO
Post type STORY
Publishing is asynchronous. Subscribe to post.published and post.failed, or poll GET /v1/posts/:id until postStatus is POSTED or FAILED.
curl -X POST https://api.so-me.studio/v1/webhooks/subscriptions \
-H "X-API-Key: $SOME_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com/hooks/social",
"categories": ["post"],
"events": ["post.published", "post.failed"]
}'
# The response includes the secret that signs every delivery.POST /hooks/social
X-Webhook-Event: post.published
X-Webhook-Signature: <hex HMAC-SHA256 of the raw body>
{
"event": "post.published",
"category": "post",
"timestamp": "2026-11-03T15:00:07.412Z",
"data": { "postId": "…", "platform": "INSTAGRAM" }
}Every delivery is signed with HMAC-SHA256 in X-Webhook-Signature. post.failed fires after the last retry; fix the cause and call POST /v1/posts/:id/retry. A first comment reports on its own with post.first_comment_posted or post.first_comment_failed.
The same API key drives an MCP server with 200+ tools and a CLI, so an agent can post to Instagram without hand-written HTTP calls.
Add the server to Claude, Cursor or any MCP client with your API key. OAuth works too. For Instagram, the agent calls these tools with the same fields as the REST request:
{
"mcpServers": {
"so-me-studio": {
"url": "https://api.so-me.studio/mcp",
"headers": { "X-API-Key": "sk_live_…" }
}
}
}Install it with npm i -g @social-media-scheduler/cli. It uploads local files for you and prints JSON, so a script or a CI job can schedule a Instagram post in one command.
so-me posts:create --platform INSTAGRAM --post-type REEL \
-m ./launch-reel.mp4 \
-c "Behind the scenes of launch week" \
-s 2026-11-03T15:00:00Z \
--first-comment "#launchweek #buildinpublic"API, CLI and MCP access is included on every paid plan: Lite, Creator, Standard, Advanced and Lifetime. See plans and limits
An Instagram professional account, Business or Creator. Instagram does not let apps publish to personal accounts. You connect the account once in the Social media studio dashboard.
No. Instagram needs a photo or video on every post, so a text-only Instagram post fails. Attach media with fileIds, and the media check runs before the post is queued.
Yes. Send postType STORY with one photo or video and a scheduledAt time. The API still requires text, but Instagram does not display captions on Stories.
No. You connect the Instagram account once in the Social media studio dashboard through the Instagram sign-in. Its tokens are stored encrypted and refreshed on our side, and your code only sends your Social media studio API key in the X-API-Key header.
No. It returns as soon as the post is queued. Publishing runs in a worker that retries on failure, so listen for post.published and post.failed, or poll GET /v1/posts/:id.
The REST API, the CLI and the MCP server are included on every paid plan: Lite, Creator, Standard, Advanced and Lifetime. Lite, Creator, Standard and Advanced start with a 7-day trial (card required), and Lifetime is a one-time payment.
Stop juggling tabs, draft, customize, and publish to 20 platforms from a single calendar.