← All guides
REST API

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

GET/api/v1/accounts

Your connected social accounts.

{
  "accounts": [
    { "id": "…", "platform": "instagram", "displayName": "@yourbrand", "status": "connected" }
  ]
}
GET/api/v1/channels

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": ["…", "…"] }
  ]
}
POST/api/v1/posts

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.

FieldTypeNotes
contentstringrequired — the post text/caption
mediaUrlstringa public image/video URL
mediaUrlsstring[]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.
channelIdsstring[]brand-channel ids — posts to every account in them
accountIdsstring[]individual connected-account ids
scheduledAtnumberepoch ms; omit or a past value sends now
draftbooleansave without sending or scheduling
instagramAsStorybooleanpost Instagram targets as a Story
facebookAsStorybooleanpost Facebook Page targets as a Story. Media is required; no caption is published — the Stories API takes a media id only.
instagramAudioIdstringattach Instagram trending audio to a Reel. Reels only, and only on an Instagram account connected via Facebook.
instagramAudioVolumenumber0–100, default 100
instagramVideoVolumenumber0–100, default 0 (replaces the clip’s own audio)
aiGeneratedbooleanself-disclose AI content (Instagram, YouTube, TikTok Direct Post)
coverImageUrlstringReel/Short cover image URL (Instagram; ignored by TikTok)
coverFrameMsnumbercover frame offset in ms; omit for frame 0
tiktokobjectTikTok 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.
youtubePrivacystringpublic (default) | unlisted | private
youtubeTitle, youtubeDescription, youtubeTags, youtubeThumbnail—YouTube metadata; title/description default to content. A custom thumbnail needs a verified channel.
contentOverridesobjectper-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.

GET/api/v1/posts

Your most recent posts (up to 50).

{
  "posts": [
    { "id": "…", "status": "scheduled", "content": "…", "scheduledAt": 1735689600000, "accountIds": ["…"] }
  ]
}
GET/api/v1/posts/:id

Status and per-account results for one post.

{
  "id": "…",
  "status": "posted",
  "content": "…",
  "scheduledAt": 1735689600000,
  "results": [
    { "accountId": "…", "platformPostId": "…", "url": "https://…", "error": null, "pendingContainerId": null }
  ]
}
PATCH/api/v1/posts/:id

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.

FieldTypeNotes
contentstringnew caption — must be non-empty if sent
scheduledAtnumbernew 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).

DELETE/api/v1/posts/:id

Cancel a post that hasn’t gone out yet (must be scheduled or draft, otherwise 409).

{ "id": "…", "cancelled": true }
GET/api/v1/posts/:id/stats

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 }
  ]
}
GET/api/v1/posts/:id/comments

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" }
  ]
}
POST/api/v1/posts/:id/comments/:commentId/reply

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_…"