API Reference

1. Get your credentials from the dashboard Settings page (a client is auto-provisioned on signup): the client_id is always shown; the client_secret is revealed once — click "Generate API Secret" to issue a new one, which revokes the old secret 2. Get a token: POST /api/v1/auth/token with your credentials 3. Connect a social account: POST /api/v1/accounts/connect-token with the platform, then open the returned connectUrl in a browser (dashboard users just click Connect — their session authorizes the link) 4. List connected accounts: GET /api/v1/accounts (use the account id from the response) 5. Publish a post: POST /api/v1/posts with accountId, content, and optional mediaUrls

// Example: publish a text post to a connected account
POST /api/v1/posts
Authorization: Bearer YOUR_TOKEN

{
  "accountId": "your-account-id",
  "content": "Hello from SocialCannon!"
}

// Response:
{
  "success": true,
  "data": {
    "id": "post-id",
    "status": "published",
    "platformPostId": "...",
    "platformPostUrl": "https://..."
  }
}

Each platform supports different content types. Use the mediaType field in platformOptions to control how content is published.

Facebook:
  • Feed post (text, images, or video)
  • Story (single image or video, mediaType: "story")
  • Reel (single video, mediaType: "reel")

Instagram:
  • Feed post (images required, up to 10 for carousel)
  • Story (single image or video, mediaType: "story")
  • Reel (single video, mediaType: "reel")

Twitter/X:
  • Tweet (text, optional images or video)

TikTok:
  • Video post (single video required)
  • Photo carousel (multiple images, up to 35)
  • Story (single image or video, mediaType: "story")
  • privacyLevel required on all posts (use get_tiktok_creator_info to get allowed values)

YouTube:
  • Video upload (single video, mediaType: "feed")
  • Short (single vertical video ≤60s, mediaType: "short")
  • Community post (text only, mediaType: "community")

Exchange client credentials for a JWT access token (OAuth2 client_credentials flow).

{ "grant_type": "client_credentials", "client_id": "...", "client_secret": "sc_..." }

{ "success": true, "data": { "access_token": "eyJ...", "token_type": "Bearer", "expires_in": 3600, "scope": "posts:read posts:write ..." } }

Attest the active bearer token's own client ID and creation-time client name. Returns no secret, scopes, trust flag, or tenant metadata.

{ "success": true, "data": { "identityContractVersion": 1, "client_id": "...", "name": "My Client" } }

List all API clients.

Create a new API client. Returns the secret once.

{ "name": "My Client", "scopes": ["posts:read", "posts:write"] }

List posts. Supports cursor-based pagination.

Create a post. Omit scheduledAt to publish immediately. Media URLs must be publicly accessible. Maximum scheduling window: 30 days. An optional Idempotency-Key header (8-128 printable ASCII characters, no spaces) binds one canonical request to one durable post ID; exact replays never publish again and set Idempotency-Replayed: true. A different request under the same key returns 409 IDEMPOTENCY_CONFLICT. In-progress or provider-uncertain replays return 409 with the stable data.id and must be recovered, never compensated as a new post. Set platformOptions.aiGenerated: true to request the platform's native AI-content label. TikTok and YouTube support it; Instagram requests fail validation unless the deployment has explicitly enabled verified native-disclosure access — see the platformOptions reference.

{
  "accountId": "abc123",
  "content": "Hello world!",
  "mediaUrls": ["https://example.com/video.mp4"],
  "scheduledAt": "2026-04-01T10:00:00Z",
  "platformOptions": {
    "mediaType": "reel",
    "aiGenerated": true
  }
}

// Success:
{ "success": true, "data": { "id": "...", "status": "published", "platformPostId": "...", "platformPostUrl": "..." } }

// Provider acknowledged, local persistence failed (HTTP 502):
{ "success": false, "error": "...", "data": { "id": "...", "platformPostId": "...", "platformPostUrl": "...", "providerPublished": true, "reconciliationRequired": true } }

// Exact keyed replay still in progress (HTTP 409; never delete/redispatch this ID):
{ "success": false, "error": "...", "code": "IDEMPOTENCY_IN_PROGRESS", "data": { "id": "...", "status": "draft" } }

Recover the public state of a keyed POST /api/v1/posts operation. Send the original Idempotency-Key in the request header, not the URL. A 404 means no durable binding exists at that read; another same-key request can still be in preflight.

// Found:
{ "success": true, "data": { "id": "...", "status": "failed", "platformPostId": "...", "platformPostUrl": "...", "recovery": { "required": true, "code": "PROVIDER_RECONCILIATION_REQUIRED", "kind": "publish_outcome" } } }

// Not found (HTTP 404):
{ "success": false, "error": "No post was found for this Idempotency-Key", "code": "IDEMPOTENCY_NOT_FOUND" }

Get a single post by ID.

Update a draft or scheduled post.

{ "content": "Updated text", "scheduledAt": "..." }

Delete a post. Every delete now fails closed when the record contains provider-publish evidence: SocialCannon must verify any required provider deletion before removing the local record. For rollback/reconciliation, send { strictCompensation: true, platformPostId? }; the optional provider ID must exactly match persisted evidence. Unsupported or failed provider deletion returns a non-2xx response and leaves the local record available for operator reconciliation. A post with an uncertain publish attempt and no provider ID cannot be deleted until it is reconciled.

{ "strictCompensation": true, "platformPostId?": "exact provider post id" }

Create a multi-part thread (Twitter thread or Instagram carousel). Publishes immediately or schedules for later. Maximum scheduling window: 30 days. Accepts platformOptions, including aiGenerated: true. Instagram rejects that request before publishing unless verified native-disclosure access is enabled for the deployment.

{
  "accountId": "abc123",
  "items": [
    { "content": "Thread part 1..." },
    { "content": "Thread part 2...", "mediaUrls": ["https://..."] }
  ],
  "scheduledAt": "2026-04-01T10:00:00Z"
}

List all connected social media accounts.

Get a single account. Tokens are stripped from the response.

Disconnect a social account.

TikTok only. Returns the account's live posting capabilities for building a compliant post UI: allowed privacy levels (`privacyLevelOptions`), whether Comment/Duet/Stitch are disabled, the creator nickname/username, and `maxVideoPostDurationSec`.

{ "success": true, "data": { "creatorNickname": "...", "creatorUsername": "...", "creatorAvatarUrl": "...", "privacyLevelOptions": ["PUBLIC_TO_EVERYONE","SELF_ONLY"], "commentDisabled": false, "duetDisabled": false, "stitchDisabled": false, "maxVideoPostDurationSec": 600 } }

Step 1 — initialize a direct-to-GCS upload. Returns a 15-minute V4 signed PUT URL plus the final public URL. Enforces subscription quota before issuing the URL.

{ "filename": "clip.mp4", "contentType": "video/mp4", "size": 12345678 }

{ "data": { "uploadUrl": "https://storage.googleapis.com/...", "publicUrl": "https://storage.googleapis.com/...", "requiredHeaders": { "Content-Type": "video/mp4", "x-goog-acl": "public-read", "x-goog-content-length-range": "0,4294967296", "x-goog-if-generation-match": "0", "x-goog-meta-socialcannon-client-key": "...", "x-goog-meta-socialcannon-upload-state": "quota-reserved" } } }

Step 2 — upload the file bytes directly to GCS using the signed URL from step 1. Must include the headers from `requiredHeaders` exactly or the signature check fails. Supports files up to 4GB.

Raw binary file contents

200 OK (no body)

Step 3 — finalize the upload: stamps the lifecycle retention timer (customTime) and increments your `mediaUploadsThisPeriod` counter. Verifies the object exists in your client prefix before bookkeeping.

{ "publicUrl": "https://storage.googleapis.com/.../media/{clientId}/{uuid}.{ext}" }

{ "data": { "url": "...", "filename": "...", "contentType": "...", "size": 102400 } }

Get a content calendar view with posts, gap analysis, and summary stats for a date range (max 90 days).

{ "posts": [...], "summary": { "totalPosts", "postsByPlatform", "postsByDay", "gaps": [{ "date", "dayOfWeek" }] } }

Find available time slots not occupied by scheduled or published posts (max 14-day range).

{ "slots": [{ "start", "end", "available" }], "totalSlots", "availableSlots", "occupiedSlots" }

Fetch live engagement metrics from the platform, store a snapshot, and return current + history.

{ "current": { "metrics": { "likes", "comments", "shares", "impressions", ... }, "fetchedAt" }, "history": [...] }

Get aggregate analytics across all posts for a date range.

{ "totalPosts", "totalLikes", "totalComments", "totalShares", "totalImpressions", "avgEngagementRate" }

Bulk-refresh analytics for multiple posts (max 50 per request).

{ "postIds?": ["..."], "platform?": "twitter", "limit?": 20 }

{ "refreshed": 15, "failed": 2, "results": [{ "postId", "success", "error?" }] }

List tracked links with UTM parameters. Supports cursor-based pagination.

Generate a UTM-tagged URL. Optionally save it for tracking.

{ "url": "https://example.com", "platform?": "twitter", "campaign?": "launch", "content?": "cta-btn", "postId?": "...", "save?": true }

{ "originalUrl": "https://example.com", "trackedUrl": "https://example.com?utm_source=twitter&...", "linkId?": "..." }

Fetch comments and replies from the platform for a published post. Stores new engagements.

{ "engagements": [{ "type", "authorName", "content", "createdAt", ... }], "nextCursor?" }

List all stored engagements across posts. Filter by read status for an inbox view.

Mark an engagement as read.

Reply to a comment or mention directly on the social platform.

{ "content": "Thanks for the feedback!" }

{ "platformReplyId": "...", "engagementId": "...", "repliedAt": "..." }

Use AI to adapt content for multiple platforms. Two modes: "preview" returns adapted variants for review, "post" adapts and publishes in one call. Content is humanized to remove AI writing patterns. Trusted clients bypass tier limits.

{
  "sourceContent": "Your original text...",
  "targetPlatforms": ["twitter", "facebook", "tiktok"],
  "mode?": "preview",
  "tone?": "professional",
  "accountIds?": { "twitter": "acc_1", "facebook": "acc_2" },
  "mediaUrls?": { "twitter": ["https://..."] },
  "appendContent?": { "twitter": "Extra text for Twitter" },
  "appendToAll?": "Appended to all platforms"
}

preview: { "variants": [{ "platform", "content", "validation", "characterCount" }], "allValid" }
post: { "results": [{ "platform", "success": true, "postId", "postUrl?", "platformPostId?" } | { "platform", "success": false, "postId?", "platformPostId?", "providerPublished?", "reconciliationRequired?", "error" }] }
Every created post-mode result includes its SocialCannon postId, including failed sandbox dry runs. If providerPublished is true, retain platformPostId and use strict compensation or operator reconciliation.

Create an A/B test. Requires an Idempotency-Key header (8-128 printable ASCII characters, no spaces); reuse the exact key after a timeout or lost response. The test row, deterministic variant post rows, usage reservations, and active-test slot are provisioned atomically before scheduler or provider visibility. If scheduledAt is omitted, the pre-provisioned variants publish immediately through provider mutation fences; if scheduledAt is provided, all variants are scheduled atomically for that time (within 30 days). A new operation returns 201; an exact committed replay returns 200 with replayed: true; the same key with a different payload returns 409 IDEMPOTENCY_CONFLICT. Immediate uncertain outcomes retain the test in provisioning with exact post IDs and return 502 for reconciliation; an operator-confirmed absent outcome is consumed once on same-key replay before untouched variants resume. Definitive failed variants are excluded from comparison. Once all variants settle, at least two published variants activate the test; otherwise it becomes failed with terminalReason insufficient_eligible_variants and transactionally releases its active slot. Scheduled tests follow the same terminal rule. Test duration starts at the latest durable eligible-variant publish, and completion waits for analytics on every eligible variant. Per-variant mediaUrls optional. Not supported for TikTok accounts (A/B variants cannot set the privacy level TikTok requires) or platforms whose post analytics are unavailable. Set aiGenerated: true to request the native label on every variant. Instagram rejects that request before publishing unless verified native-disclosure access is enabled for the deployment.

Header: Idempotency-Key: ab-test-launch-2026-04-20

{
  "accountId": "abc123",
  "name": "CTA test",
  "variants": [
    { "content": "Check out our new feature!", "mediaUrls": ["https://..."] },
    { "content": "You won't believe this new feature..." }
  ],
  "metric?": "engagementRate | likes | impressions | clicks",
  "minDurationHours?": 24,
  "scheduledAt?": "2026-04-20T10:00:00Z",
  "aiGenerated?": true
}

201 new / 200 replay: { "success": true, "replayed?": true, "data": { "id": "...", "status": "provisioning | active | failed", "startedAt?": "...", "terminalReason?": "insufficient_eligible_variants", "variants": [{ "id", "postId", "content", "state", "platformPostId?" }], ... } }
409: { "success": false, "code": "IDEMPOTENCY_CONFLICT | SCHEDULE_EXPIRED", "error": "..." }
502 partial/reconciliation: { "success": false, "code?": "PARTIAL_FAILURE | PROVIDER_RECONCILIATION_REQUIRED | INSUFFICIENT_ELIGIBLE_VARIANTS", "error": "...", "data": { "id", "status": "provisioning | active | failed", "variants": [{ "id", "postId", "state", "platformPostId?" }] } }

List A/B tests. Filter by status.

Get test details with live per-variant analytics and current winner.

{ "variants", "variantResults": [{ "variantId", "metrics" }], "currentWinner", "confidence" }

Force-complete an active test only after at least two eligible variants are durably published and each has analytics; atomically releases its active-test slot.

Cancel an active or provisioning test and atomically release its active-test slot. Variant posts remain as regular posts.

Analyze posting history and engagement to recommend optimal days and hours for posting.

{ "suggestions": [{ "day", "hour", "engagementRate", "sampleSize" }], "timezone" }

List all supported platforms and their capabilities. Public endpoint, no auth required.

The sandbox platform is a dry-run test platform — nothing is published anywhere. Create a post with accountId: "sandbox" and a sandbox account is auto-provisioned on first use (no OAuth, no tokens). Publish returns a simulated success (fake sandbox_* post ID and URL). Sandbox posts do not consume your monthly post quota and work on every plan, so you can try the full API — create, publish, schedule, MCP tools — before connecting a real account. Sandbox usage is bounded by a lifetime allowance of 100 dry runs per account; media attachments are accepted but discarded, and auto-UTM is skipped.

The platformOptions field in POST /api/v1/posts accepts platform-specific options. Use mediaType to control how content is published.

mediaType values:
• "reel" — Facebook or Instagram Reel (single video, MP4/MOV)
• "story" — Facebook, Instagram, or TikTok Story (single media, 24h ephemeral)
• "short" — YouTube Short (single video, vertical ≤60s)
• "community" — YouTube Community tab post (text only)

Media rules:
• Stories, Reels, and Shorts accept only one media attachment
• Facebook/Instagram feed posts accept multiple images (carousel, max 10)
• TikTok photo carousel accepts up to 35 images
• TikTok video posts accept only one video
• YouTube videos/shorts accept only one video file
• All media URLs must be publicly accessible

YouTube-specific options:
• "title" — Video title (max 100 chars)
• "tags" — Comma-separated video tags
• "categoryId" — YouTube category ID (default: "10" Music)
• "privacyStatus" — "public", "unlisted", or "private"

TikTok-specific options (call GET /api/v1/accounts/:id/tiktok/creator-info first):
• "privacyLevel" — REQUIRED. One of: PUBLIC_TO_EVERYONE, MUTUAL_FOLLOW_FRIENDS, FOLLOWER_OF_CREATOR, SELF_ONLY. Choose from privacyLevelOptions returned by creator-info. Omitting this field returns 400 TIKTOK_PRIVACY_REQUIRED.
• "disableComment" — boolean (default: false). Set true to disable comments. Must be true if commentDisabled is true on creator-info.
• "disableDuet" — boolean (default: false). Video only. Set true to disable duets. Must be true if duetDisabled is true on creator-info.
• "disableStitch" — boolean (default: false). Video only. Set true to disable stitches. Must be true if stitchDisabled is true on creator-info.
• "commercialContent" — boolean. Set true if the post promotes a brand, product, or service (enables commercial content disclosure).
• "brandOrganic" — boolean. Set true if promoting your own brand ("Your Brand" disclosure). Requires commercialContent: true.
• "brandedContent" — boolean. Set true for paid/third-party partnerships. Requires commercialContent: true. Cannot be combined with privacyLevel: SELF_ONLY.

AI-generated content disclosure (cross-platform):
• "aiGenerated" — boolean (default: false). Set true when the post's media is AI-generated. SocialCannon maps it to the platform's native AI-content label:
  - Instagram: fails validation by default because native disclosure is not yet enabled for this deployment. When verified access is explicitly enabled, sends is_ai_generated on the media container (carousel parent only)
  - TikTok: is_aigc ("AI-generated" label)
  - YouTube: containsSyntheticMedia ("Altered content" disclosure)
  Ignored on platforms without a disclosure field (Facebook, X, LinkedIn).
  Also accepted by POST /api/v1/posts/thread (platformOptions), per-post in POST /api/v1/posts/auto-schedule (posts[].platformOptions), and as a test-level "aiGenerated" flag on POST /api/v1/ab-tests.

Mint a short-lived (10 min) connect token that authorizes one OAuth connect flow for your client. Required scope: accounts:write. Returns a ready-to-open connectUrl — send the user there in a browser.

{ "platform": "twitter", "redirectTo": "/dashboard/accounts" }

{ "data": { "connectUrl": "https://…/api/connect/twitter?connect_token=…", "expiresIn": 600 } }

Initiate OAuth connection for a social platform. Redirects to the platform's authorization page. Supported platforms: twitter, facebook, instagram, linkedin, tiktok, youtube. Caller must prove tenancy: either a signed-in dashboard session (the account is linked to the session's client) or a connect_token minted via POST /api/v1/accounts/connect-token. A bare client_id is not accepted.

OAuth callback handler. Exchanges authorization code for tokens and stores the connected account. Do not call directly — the platform redirects here after authorization.

Scopes control what an API client can access. Assign scopes when creating a client via POST /api/v1/auth/clients.

posts:read — List and view posts
posts:write — Create, update, schedule posts
posts:delete — Delete posts
accounts:read — List connected accounts
accounts:write — Connect/disconnect social accounts
media:upload — Upload media files
analytics:read — View analytics and timing suggestions
engagements:read — View comments and replies
engagements:write — Reply to engagements, mark as read
links:read — View tracked links
links:write — Generate UTM-tagged links
clients:manage — Create and list API clients