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 click Connect and their session identifies the client; either path requires accounts:write on that client) 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 (media is required on Instagram, TikTok and YouTube; a text-only post works on X, Facebook and LinkedIn, and X needs a paid plan)

// Example: publish a text post to a connected account.
// This body suits X (paid plan), Facebook and LinkedIn. Instagram, TikTok and
// YouTube need mediaUrls, and TikTok also needs platformOptions.privacyLevel.
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)
  • privacyLevel required on all posts (use get_tiktok_creator_info to get allowed values)

YouTube:
  • Video upload (single video, mediaType: "feed")
  • Short (single square or vertical video ≤180s, mediaType: "short"; classification is not guaranteed)
  • Community publishing is unavailable through the YouTube Data API

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

Get the requesting client's own public info. The handler returns only the calling client, not every client on the account.

Create a new API client. Returns the secret once.

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

List posts. Supports cursor-based pagination. status=awaiting_account lists pristine missed content saved during an account restriction or unresolved publication. Recovery leaves this content saved until the customer explicitly chooses a new schedule.

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. A settled failed keyed create normally returns 409 with a recovery action; a settled platform-plan refusal instead returns 403 LIMIT_EXCEEDED with limit.type="platform" and details.action="upgrade_plan". Repeating its key cannot publish. For a settled platform-plan refusal with data.id, upgrade before retrying that failed post. With no existing or concurrent binding, a fresh request refused during preflight returns 403 LIMIT_EXCEEDED without data.id or details.action and creates no durable key binding; the idempotency lookup returns 404 until a binding exists. After upgrading, resend the unchanged request with the same unbound key to create and publish it. Files proven oversized before provider publication, including Facebook Reel or video Story and X GIF, image, or video uploads, return 413 MEDIA_TOO_LARGE for immediate creates; submit a new post with compliant media and a new Idempotency-Key. If a streaming source sends more bytes than its announced Content-Length, the transfer fails with a length mismatch; a Reel has not reached its publish step, while a video Story may need reconciliation after Meta starts its session. Do not automatically resend a Story whose provider outcome is uncertain. 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": "FUTURE_ISO_8601_WITHIN_30_DAYS",
  "platformOptions": {
    "mediaType": "reel",
    "aiGenerated": true
  }
}

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

// Provider acknowledged, local persistence failed (HTTP 503):
{ "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" } }

// Facebook video rejected by the local size limit (HTTP 413).
// sizeSource="reported" means the source's Content-Length; correct that header if inaccurate.
{ "success": false, "code": "MEDIA_TOO_LARGE", "details": { "retryable": false, "action": "use_smaller_media", "maxBytes": 104857600, "sizeSource": "reported", "reportedBytes": 121797838 }, "data": { "id": "..." } }

// Settled failed keyed create (HTTP 409; same key will not publish again):
{ "success": false, "code": "POST_SETTLED_FAILED_RETRY_REQUIRED", "details": { "retryable": false, "postId": "...", "action": "retry_failed_post", "retryEndpoint": "/api/v1/posts/{id}/retry" }, "data": { "id": "...", "status": "failed" } }
// The action can instead be "wait_for_publishing_limit" for Instagram's rolling
// 24-hour quota, "review_account_restriction" for an account-level restriction,
// or "repair_permissions" for a publishing-permission denial.
// Follow that remedy before calling the same failed-post retry endpoint.

// Fresh preflight platform refusal (HTTP 403; no post or durable key binding):
{
  "success": false, "code": "LIMIT_EXCEEDED",
  "error": "Twitter/X requires a paid plan. Upgrade to the Pro plan or above.",
  "limit": { "type": "platform", "current": 0, "max": 0, "tier": "free" }
}
// Upgrade, then resend the same unbound key. Lookup is 404 before a binding exists.
// Same-key replay of a settled platform-plan refusal (HTTP 403; will not publish again):
{ "success": false, "code": "LIMIT_EXCEEDED", "limit": { "type": "platform", "current": 0, "max": 0, "tier": "free" }, "details": { "retryable": false, "postId": "...", "action": "upgrade_plan" }, "data": { "id": "...", "status": "failed" } }
// The first settled response carries data:{id}; a same-key replay also carries status.
// Upgrade to a plan including the platform, then retry the same failed post.

// Settled permanent media/content rejection (HTTP 422; no post was published):
{ "success": false, "code": "POST_DEFINITIVELY_REJECTED", "details": { "retryable": false, "action": "edit_media_or_destination" }, "data": { "id": "..." } }
// An unreadable publishing credential uses action="contact_support" instead.
// If the failed-row settlement could not be saved, these typed 409/422/413
// remedies and the account refresh/reconnect codes are withheld: the response
// is 503 with data.id and no code. Inspect the post's state before retrying.
// Application failure bodies use 4xx or 503 (never 502/504), so they survive
// proxies that replace gateway-error pages.

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. outcome is the settlement state at the time of this read: published (provider post identity recorded), scheduled (also a post held as awaiting_account until its owner reschedules it; either can still publish later), not_published (settled failure with no provider marker or identity, or with an exact operator-confirmed absence attestation for its retained attempt; safe to treat as nothing published), or unresolved (not settled: in flight, awaiting reconciliation, a thread that has published, or a post returned to draft; do not settle it yourself). scheduled changes when the scheduler publishes, and a not_published post can later be retried by its owner, so re-read instead of caching an old answer. If a linked plan cannot be verified, keyed write/setup requests return 503 PLAN_LOOKUP_RETRYABLE with details.retryable:true; retain the same key and retry later without creating a replacement post. Repurpose can return a request-level 503 before work starts; post mode retains HTTP200 for per-target results; retry only failed targets as described on that endpoint. This read endpoint returns state, not the original create HTTP status; a same-key POST replay of a settled platform-plan refusal returns 403 LIMIT_EXCEEDED with details.action="upgrade_plan".

// Found:
{ "success": true, "data": { "id": "...", "status": "failed", "outcome": "unresolved", "platformPostId": "...", "platformPostUrl": "...", "recovery": { "required": true, "code": "PROVIDER_RECONCILIATION_REQUIRED", "kind": "publish_outcome" } } }
// outcome: "published" | "scheduled" | "not_published" | "unresolved"

// 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.

Retry the same failed post after checking its state and resolving the indicated account or publishing-limit problem. Media cannot be replaced on an existing post: if its stored file is gone (MEDIA_INACCESSIBLE or SCHEDULED_MEDIA_UNAVAILABLE), upload it again and create a new post. A provider-confirmed post is repaired locally without another publication; an uncertain Story remains fenced for reconciliation. A durably settled transient no-post failure returns 409 POST_SETTLED_FAILED_RETRY_REQUIRED; a permanent media/content rejection returns 422 POST_DEFINITIVELY_REJECTED; known oversized media returns 413 MEDIA_TOO_LARGE. If local failure settlement is unconfirmed, inspect this post before retrying.

// Published or locally repaired:
{ "success": true, "data": { "postId": "...", "status": "published", "platformPostId": "..." } }

// No post was published; retry this failed row after the stated remedy (HTTP 409):
{ "success": false, "code": "POST_SETTLED_FAILED_RETRY_REQUIRED", "details": { "action": "wait_for_publishing_limit", "postId": "...", "retryEndpoint": "/api/v1/posts/{id}/retry" } }
// The action may instead be "retry_failed_post", "review_account_restriction", or "repair_permissions".

// Permanent rejection (HTTP 422): action="edit_media_or_destination" or "contact_support".
// Oversized media (HTTP 413): code="MEDIA_TOO_LARGE", action="use_smaller_media".

Update a draft or scheduled post, or reschedule an awaiting_account post after its account restriction and earlier uncertain operations are resolved. Held content requires an explicit future scheduledAt at least five minutes ahead and five minutes from another recovered post; the normal 30-day window and media availability checks still apply. Send scheduledAt: null to return unattempted held or scheduled content to draft and release only its exact unused quota reservation. Active create ownership and provider-attempt guards remain; a concurrent publish claim returns 409 PUBLISH_IN_PROGRESS. Recovery never publishes missed content automatically. Free cannot assign or reschedule Twitter/X posts (403 LIMIT_EXCEEDED, limit.type="platform"); content-only edits and scheduledAt:null remain allowed.

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

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). Every item is validated against the account's platform, and one invalid item fails the whole request with 400; Instagram requires media on every item. Twitter/X publishing and scheduling require a paid plan; Free receives 403 LIMIT_EXCEEDED with limit.type="platform". 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. A durably settled immediate failure with no published item returns 409 POST_SETTLED_THREAD_NO_POST: resolve the cause, then create a new thread; unreadable credentials instead direct you to contact support. Oversized media returns 413 MEDIA_TOO_LARGE with details.action "use_smaller_media" and the byte limit; create a new thread with smaller media. A partial or uncertain thread requires reconciliation before another attempt.

{
  "accountId": "abc123",
  "items": [
    { "content": "Thread part 1...", "mediaUrls": ["https://..."] },
    { "content": "Thread part 2...", "mediaUrls": ["https://..."] }
  ],
  "scheduledAt": "FUTURE_ISO_8601_WITHIN_30_DAYS"
}

Distribute posts across optimal time slots for the next 7 days. Pro plan only. Requires a stable Idempotency-Key header (8-128 printable ASCII characters, no spaces); without it the request is rejected with 400 IDEMPOTENCY_KEY_REQUIRED before the body is read. Retrying with the same key reuses the same manifest and slot assignments instead of scheduling a second set of posts. Needs both posts:write and analytics:read, because it reads your engagement history to rank the slots. A completed operation returns pending: [] and summary.totalPending: 0; when items are still being worked on the response is a failure with code AUTO_SCHEDULE_RETRY_REQUIRED, so retry the same key rather than starting a new batch.

POST /api/v1/posts/auto-schedule
Header: Idempotency-Key: auto-schedule-week-20260420-e5f6g7h8

{
  "accountId": "abc123",
  "posts": [
    { "content": "Post 1 text" },
    { "content": "Post 2 text", "mediaUrls": ["https://..."], "platformOptions": { "aiGenerated": true } }
  ],
  "timezone": "UTC-5"
}

{ "operationId": "...", "operationStatus": "completed", "scheduled": [...], "unscheduled": [...], "pending": [], "summary": { "totalRequested": 2, "totalScheduled": 2, "totalUnscheduled": 0, "totalPending": 0 } }

List all connected social media accounts.

Get a single account. Tokens are stripped from the response. An active publishing incident exposes safe accessRecovery guidance with incidentId, account identity, remediation and recoveryUrl; ordinary token health remains separate.

Recheck an owned account connection, or consent to a new immediate verification publication. Recheck is read-only provider evidence and returns publishingVerified:false; it never clears a publishing incident or an earlier uncertain operation. Verification requires incidentId from accessRecovery, confirmNewPublication:true, an Idempotency-Key header and posts:write as well as accounts:write. It uses the normal post/media/quota pipeline and consumes two rate-limit admissions (account write, then post write), while reserving publication quota once; accountId and scheduledAt cannot be supplied inside post. An unresolved provider fence blocks verification. Exact-key replay uses the normal post idempotency contract; recover a lost response with GET /api/v1/posts/idempotency using that same header. Only matching acknowledged publication evidence closes the incident. Facebook 368/4854002 and 190/459 direct the Page owner to the Facebook mobile identity/security check, then Restore access on the same SocialCannon account before verification. An incomplete recheck returns retryable 503 ACCOUNT_CONNECTION_CHECK_UNAVAILABLE; changed recovery or tenant deletion returns a non-retryable 409.

// Read-only connection check:
{ "action": "recheck_connection" }

// New verification publication; include Idempotency-Key in the request header:
{
  "action": "verify_publishing",
  "incidentId": "11111111-1111-4111-8111-111111111111",
  "confirmNewPublication": true,
  "post": { "content": "New content I consent to publish", "mediaUrls": ["https://example.com/image.jpg"] }
}

{ "success": true, "data": { "connected": true, "publishingVerified": false, "account": { "id": "..." } } }

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. Pass accountId (and optionally postType, default "feed") so the file is checked against that destination's real per-file limit; without accountId the pipeline-wide ceiling of 140 MiB applies. Files that cannot be published are rejected — 400 MEDIA_LIMIT_EXCEEDED over the size cap, 400 UNSUPPORTED_MEDIA for a platform/type/format this pipeline cannot publish, 404 for an unknown or foreign account, 409 for a disconnected one. Upload count is unlimited on every plan; file limits and tenant ownership still apply. Uploading media does not grant publishing access: files may be prepared for a connected X account on Free, but publishing or scheduling them to X requires a paid plan.

{ "filename": "clip.mp4", "contentType": "video/mp4", "size": 12345678, "accountId": "ACCOUNT_ID", "postType": "feed" }

{ "success": true, "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,104857600", "x-goog-if-generation-match": "0", "x-goog-meta-socialcannon-client-key": "...", "x-goog-meta-socialcannon-upload-state": "quota-reserved" }, "limit": { "maxBytes": 104857600, "maxBytesDisplay": "100 MiB", "platform": "tiktok", "postType": "feed" } } }

Step 2 — upload the file bytes directly to GCS using the signed URL from step 1. This is not an open endpoint: the V4 URL carries its own write authorization, an expiry and signed headers. It must include the headers from `requiredHeaders` exactly or the signature check fails; `x-goog-content-length-range` carries the destination's limit from step 1, so GCS itself rejects a file that is too large.

Raw binary file contents

200 OK (no body)

Step 3 — finalize the upload: stamps the lifecycle retention timer (customTime) and verifies the finalized file; there is no monthly upload-count limit. Verifies the object exists in your client prefix before bookkeeping. Uploaded files are kept only while a post can still publish them: they are usually deleted within two hours after the post that uses them is published, about 12 hours after a failure is settled (a failure our support confirmed was not published keeps its file until you retry or delete the post, within the 45-day limit), and about a day after their last use if no post uses them. Upload the file again for a new post rather than reusing an old URL.

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

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

Get a content calendar view with posts, gap analysis, and summary stats for a date range (up to 7 days on Free, 90 on Pro, 365 on Agency and 365 on Enterprise).

{ "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 metrics and return current + history. Instagram Stories expire after 24 hours: a saved snapshot is returned with liveRefresh.available=false, or 400 INSTAGRAM_STORY_EXPIRED if none was collected.

{ "current": { "metrics": { "likes", "comments", "shares", "impressions", ... }, "fetchedAt" }, "history": [...], "liveRefresh?": { "available": false, "code": "INSTAGRAM_STORY_EXPIRED", "reason": "..." } }

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). Expired Instagram Stories are skipped with INSTAGRAM_STORY_EXPIRED, preserving saved snapshots; skipped posts do not count as refreshed or failed.

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

{ "refreshed": 15, "failed": 2, "skipped": 1, "results": [{ "postId", "success", "skipped?", "code?", "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 numeric tier limits. Linked users still need platform access: Free Twitter/X preview requests return 403 LIMIT_EXCEEDED before the model call; post mode retains per-target results for mixed requests. A request-level plan lookup failure returns HTTP 503 PLAN_LOOKUP_RETRYABLE with details.retryable=true before model or publishing work; retry that request later. In post mode, a per-target PLAN_LOOKUP_RETRYABLE (including thrown plan reads) carries details.retryScope="failed_target_only"; HTTP200 may include already-published successes. This endpoint has no Idempotency-Key: retry only failed targets after checking every result.

{
  "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.
If the AI adaptation itself fails: 503 { "success": false, "code": "REPURPOSE_UNAVAILABLE", "error": "...", "details": { "retryable": true } }. Nothing is drafted or posted, and the reserved repurpose quota is released (best-effort). retryable is true when retrying may help (timeouts, rate limits, provider outages) and false when it cannot until SocialCannon fixes its AI provider setup; the error text says which. If the model left out a requested platform, details.missingPlatforms names it, so you can retry without that target (when another failure occurs in the same request, that failure's answer is returned instead). If the AI provider declines to adapt your source text (a moderation or content-filter block, or a refusal, which can also be triggered by text that tries to instruct the AI): 422 { "success": false, "code": "REPURPOSE_CONTENT_REJECTED", "error": "...", "details": { "retryable": false } }; edit the text before trying again. A block in the humanizing pass, which rewrites an already adapted draft, is a retryable 503. Twitter/X, Instagram, TikTok, LinkedIn and YouTube variants over the platform's length limit (appended content included) get a best-effort shortening pass when at least 40 characters remain for the post itself; if it is skipped, fails, is blocked, or leaves the text too long, that variant's validation reports it.

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 503 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 is optional only on platforms that accept text-only posts; Instagram requires media on every variant and YouTube requires a video URL on every variant (for example an MP4); one invalid variant fails the whole request with 400. 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://example.com/variant.mp4"] },
    { "content": "You won't believe this new feature...", "mediaUrls": ["https://example.com/variant.mp4"] }
  ],
  "metric?": "engagementRate | likes | impressions | clicks",
  "minDurationHours?": 24,
  "scheduledAt?": "FUTURE_ISO_8601_WITHIN_30_DAYS",
  "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": "..." }
503 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 or Instagram Story (single media, 24h ephemeral)
• "short" — YouTube Short (single square or vertical video ≤180s)
• "community" — unsupported by the YouTube Data API; publishing is refused

Media rules:
• Stories, Reels, and Shorts accept only one media attachment
• Instagram feed supports image/video carousels up to 10 items; Facebook feed uses one media attachment
• 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 (optional, max 100 chars). If omitted, takes the first content line before its first ".", "!" or "?", trims it and limits it to 100 characters; if empty, uses the first 100 characters of the full content. Supply platformOptions.title when exact wording matters ("Version 2.0 launch" otherwise becomes "Version 2"). Shorts append #Shorts when absent and cap the result at 100 characters.
• "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" }

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

Initiate OAuth connection for a social platform. Redirects to the platform's authorization page. Accepted platform ids: twitter, facebook, instagram, linkedin, tiktok, youtube, reddit. Reddit is reachable through the API but is not offered on the public pricing page or in the guides. 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. Either way the resolved client needs the accounts:write scope, or the connect flow is refused by redirecting back with an error.

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 API clients, and read the requesting client's own details