API Reference

1. Get your client_id and client_secret from the SocialCannon dashboard 2. Get a token: POST /api/v1/auth/token with your credentials 3. Connect a social account: redirect user to /api/connect/:platform?client_id=YOUR_ID 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).

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

{ "access_token": "eyJ...", "token_type": "bearer", "expires_in": 3600 }

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.

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

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

// Error:
{ "success": false, "error": "Publishing failed: ..." }

Get a single post by ID.

Update a draft or scheduled post.

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

Delete a post. If published, also attempts platform-side deletion.

Create a multi-part thread (Twitter thread or Instagram carousel). Publishes immediately or schedules for later. Maximum scheduling window: 30 days.

{
  "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" } } }

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", "postUrl?", "error?" }] }

Create an A/B test. Behavior matches POST /api/v1/posts: if scheduledAt is omitted, all variants publish immediately to the platform; if scheduledAt is provided, all variants are scheduled for that time (must be within 30 days). Each variant is a separate post record. Auto-completes after minDurationHours. If ANY variant fails to publish during immediate mode, the endpoint returns 502 and the partial results are marked as failed — the winning-metric comparison at completion will only consider published variants. Per-variant mediaUrls optional. Not supported for TikTok accounts (A/B variants cannot set the privacy level TikTok requires) — returns 400 with code PLATFORM_UNSUPPORTED.

{
  "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"
}

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 and determine the winner.

Cancel an active test. 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 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.

Initiate OAuth connection for a social platform. Redirects to the platform's authorization page. Supported platforms: twitter, facebook, instagram, linkedin, tiktok, youtube.

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