Shossip REST API
Everything Compose can do — list your accounts and channels, create and schedule posts, check what happened, pull stats — is also a plain HTTPS API, authenticated with an API key. This is also what the Shossip MCP server calls on your behalf.
Authentication
Every request needs an API key. Create one from Settings → API & MCP: give it a name and click Create key. The full key — it starts with sk_shossip_ — is only ever shown once, right after you create it, so copy it immediately. The list only ever shows the last 4 characters afterward. Click Revoke next to a key to disable it immediately; you can hold up to 20 live keys at a time.
Send it as a bearer token on every request:
Authorization: Bearer sk_shossip_…
Base URL:
https://shossip.com/api/v1
curl https://shossip.com/api/v1/accounts \ -H "Authorization: Bearer sk_shossip_…"
Errors and rate limits
Every error comes back as JSON, with a matching HTTP status:
{ "error": "<message>" }401— missing header: “Missing ‘Authorization: Bearer <api key>’ header”401— bad or revoked key: “Invalid or revoked API key”402— no active subscription/trial: “Subscription required”400— validation errors (see each endpoint below)404— “Not found” (wrong or inaccessible post id)409— the post has already gone out and can no longer be changed/cancelled
Each API key can make up to 300 requests per minute, of which up to 100 can create posts; over that you get HTTP 429 with a Retry-After header. Comment replies have a stricter cap of 30 per key per hour.
Endpoints
Your connected social accounts.
{
"accounts": [
{ "id": "…", "platform": "instagram", "displayName": "@yourbrand", "status": "connected" }
]
}Your brand channels — named groups of accounts. Posting to a channel posts to every account in it.
{
"channels": [
{ "id": "…", "name": "Main brand", "color": "#6533b0", "accountIds": ["…", "…"] }
]
}Create a post — and, unless it’s scheduled in the future or saved as a draft, dispatch it immediately. Requires content and at least one of channelIds / accountIds.
| Field | Type | Notes |
|---|---|---|
content | string | required — the post text/caption |
mediaUrl | string | a public image/video URL |
mediaUrls | string[] | alternative to mediaUrl. 2–10 post a carousel on Instagram (Threads too, once it’s live — coming soon for now) and a multi-photo post on Facebook (images only); with a Story flag, each item is its own Story frame. More than 10 is rejected. |
channelIds | string[] | brand-channel ids — posts to every account in them |
accountIds | string[] | individual connected-account ids |
scheduledAt | number | epoch ms; omit or a past value sends now |
draft | boolean | save without sending or scheduling |
instagramAsStory | boolean | post Instagram targets as a Story |
facebookAsStory | boolean | post Facebook Page targets as a Story. Media is required; no caption is published — the Stories API takes a media id only. |
instagramAudioId | string | attach Instagram trending audio to a Reel. Reels only, and only on an Instagram account connected via Facebook. |
instagramAudioVolume | number | 0–100, default 100 |
instagramVideoVolume | number | 0–100, default 0 (replaces the clip’s own audio) |
aiGenerated | boolean | self-disclose AI content (Instagram, YouTube, TikTok Direct Post) |
coverImageUrl | string | Reel/Short cover image URL (Instagram; ignored by TikTok) |
coverFrameMs | number | cover frame offset in ms; omit for frame 0 |
tiktok | object | TikTok Content-Posting options — presence switches TikTok targets to compliant Direct Post: privacyLevel (PUBLIC_TO_EVERYONE | MUTUAL_FOLLOW_FRIENDS | FOLLOWER_OF_CREATOR | SELF_ONLY), disableComment/disableDuet/disableStitch, commercialContent, yourBrand, brandedContent, musicConfirmed (booleans). Omit to leave TikTok as an inbox draft. |
youtubePrivacy | string | public (default) | unlisted | private |
youtubeTitle, youtubeDescription, youtubeTags, youtubeThumbnail | — | YouTube metadata; title/description default to content. A custom thumbnail needs a verified channel. |
contentOverrides | object | per-platform caption overrides, keyed by platform |
Response:
{
"id": "…",
"status": "posted",
"scheduledAt": 1735689600000,
"results": [
{ "accountId": "…", "platformPostId": "…", "url": "https://…", "error": null, "pendingContainerId": null }
]
}If some targets couldn’t take the media (e.g. an image sent to TikTok/YouTube), the response also carries droppedTargets: [{ id, platform }] — the post still goes out to everyone else.
One account per call, for anything with media. The API accepts multiple channelIds/accountIds in one request, but dispatch runs inline and each provider is polled serially — a multi-account video post costs the sum of every provider’s wait (an Instagram Reel transcode plus a TikTok delivery poll, one after the other). Shossip’s own batch tooling posts one account per call for exactly this reason, and we recommend you do too.
Your most recent posts (up to 50).
{
"posts": [
{ "id": "…", "status": "scheduled", "content": "…", "scheduledAt": 1735689600000, "accountIds": ["…"] }
]
}Status and per-account results for one post.
{
"id": "…",
"status": "posted",
"content": "…",
"scheduledAt": 1735689600000,
"results": [
{ "accountId": "…", "platformPostId": "…", "url": "https://…", "error": null, "pendingContainerId": null }
]
}Reschedule and/or re-caption a post that hasn’t gone out yet. Only works while the post is scheduled or draft — anything already posting or posted returns 409.
| Field | Type | Notes |
|---|---|---|
content | string | new caption — must be non-empty if sent |
scheduledAt | number | new send time, epoch ms — must be in the future |
At least one of the two is required. Response mirrors GET /api/v1/posts/:id (id, status, content, scheduledAt).
Cancel a post that hasn’t gone out yet (must be scheduled or draft, otherwise 409).
{ "id": "…", "cancelled": true }Live per-account metrics for a published post, fetched from each platform on demand. What’s available (likes, comments, …) varies by platform and media type — Stories and very-fresh posts may return little.
{
"id": "…",
"status": "posted",
"content": "…",
"stats": [
{ "accountId": "…", "platform": "instagram", "likes": 42, "comments": 3 }
]
}Comments on a published post, per account. Platforms whose API can’t list comments (for example TikTok) are reported with supported: false instead of an error, so the other accounts’ comments still come back.
{
"id": "…",
"status": "posted",
"accounts": [
{ "accountId": "…", "platform": "instagram", "supported": true,
"comments": [ { "id": "…", "authorName": "…", "text": "…", "createdAt": 1700000000000 } ] },
{ "accountId": "…", "platform": "tiktok", "supported": false, "comments": [],
"error": "comments not supported for tiktok" }
]
}Reply to a comment on one of your own published posts. Body: message (required, trimmed; limited to the platform’s own comment length) and accountId (which account’s copy of the post the comment is on — required when the post went out on more than one account). Capped at 30 replies per key per hour (429 beyond that).
{ "id": "…" }curl -X POST https://shossip.com/api/v1/posts \
-H "Authorization: Bearer sk_shossip_…" \
-H "Content-Type: application/json" \
-d '{
"content": "Launch day! 🚀",
"mediaUrl": "https://example.com/clip.mp4",
"accountIds": ["<account-id>"]
}'
curl https://shossip.com/api/v1/posts/<post-id> \
-H "Authorization: Bearer sk_shossip_…"