{"id":"50bd31e9-6f07-4497-9149-92edca5994a6","entityType":"agent","slug":"clawhub-miprinia-socialcannon","name":"socialcannon","canonicalUrl":"https://www.xpersona.co/agent/clawhub-miprinia-socialcannon","canonicalPath":"/agent/clawhub-miprinia-socialcannon","generatedAt":"2026-10-10T01:43:27.536Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"editorial-content","verified":true,"confidence":"high","updatedAt":"2026-10-09T09:19:29.733Z","emptyReason":null},"description":"Publish, schedule, and manage social media posts across Twitter/X, Facebook, Instagram, LinkedIn, TikTok, and YouTube. Content calendar with gap analysis, A/B testing, engagement inbox, AI content repurposing, optimal timing suggestions, auto-scheduling, UTM tracking, and platform-native AI-content disclosure labels. Skill: socialcannon Owner: miprinia Summary: Publish, schedule, and manage social media posts across Twitter/X, Facebook, Instagram, LinkedIn, TikTok, and YouTube. Content calendar with gap analysis, A/B testing, engagement inbox, AI content repurposing, optimal timing suggestions, auto-scheduling, UTM tracking, and platform-native AI-content disclosure labels. Tags: latest:1.12.0 Version history: v1.12.0 | 2026-09-2","descriptionLabel":"Technical summary","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 3.2K downloads reported by the source. Last updated 10/9/2026.","installCommand":"clawhub skill install s172cz0evem0ty227aw7v0gby18453k4:socialcannon","sourceUrl":"https://clawhub.ai/miprinia/socialcannon","homepage":"https://clawhub.ai/miprinia/skills/socialcannon","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/miprinia/socialcannon","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/miprinia/skills/socialcannon","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":40,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"Publish, schedule, and manage social media posts across Twitter/X, Facebook, Instagram, LinkedIn, TikTok, and YouTube. Content calendar with gap analysis, A/B t"},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-09T09:19:29.733Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T09:19:29.733Z","emptyReason":null},"stars":null,"forks":null,"downloads":3176,"packageName":null,"latestVersion":"1.12.0","tractionLabel":"3.2K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T09:19:29.733Z","emptyReason":null},"lastUpdatedAt":"2026-10-09T09:19:29.733Z","lastCrawledAt":"2026-10-09T09:19:29.733Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-10T09:19:29.733Z","lastVerifiedAt":null,"highlights":[{"version":"1.12.0","createdAt":"2026-09-26T18:18:08.686Z","changelog":"- MCP tooling instructions now specify a pinned version: @socialcannon/mcp@1.0.2. - Expanded security guidance: emphasizes keeping API secrets out of config files, using environment variables and OS keychain/secret managers. - Updated agent integration examples for Hermes and Claude Desktop with stronger security practices. - Removed files: CLAUDE.md and skill-card.md for cleanup and consolidation.","fileCount":3,"zipByteSize":13889},{"version":"1.11.0","createdAt":"2026-08-18T17:59:02.375Z","changelog":"- Added support for platform-native AI-content disclosure labels. - Updated feature list in the description. - Removed the obsolete skill-card.md file.","fileCount":4,"zipByteSize":12574},{"version":"1.10.0","createdAt":"2026-07-18T08:30:50.640Z","changelog":"Version 1.10.0 - Removed the skill-card.md file. - Updated SKILL.md documentation (no visible functional or API changes). - Incremented version to 1.10.0.","fileCount":4,"zipByteSize":11931},{"version":"1.9.6","createdAt":"2026-07-11T12:01:36.991Z","changelog":"Facebook per-post analytics, engagements, and reply are gated off (Meta App Review pending) — those endpoints and Facebook A/B tests now return 400 PLATFORM_UNSUPPORTED. Publishing and scheduling are unaffected. Docs updated to match; check GET /api/v1/platforms for the authoritative per-platform capability list.","fileCount":4,"zipByteSize":12091},{"version":"1.9.5","createdAt":"2026-07-11T07:05:36.867Z","changelog":"Security-audit: reword one response-parsing doc line so the static secret-scanner stops false-flagging 'access token: ' as an exposed token (no secret was ever present; the response.data field guidance is unchanged).","fileCount":4,"zipByteSize":11675},{"version":"1.9.4","createdAt":"2026-07-11T07:00:43.303Z","changelog":"Security-audit follow-up: add a Safety section with explicit human-approval guidance for destructive/irreversible actions (publish, reply, retry, delete, disconnect, post-mode repurpose, immediate A/B); replace a JWT-shaped example placeholder that tripped a secret scanner (false positive — no secret was ever present).","fileCount":4,"zipByteSize":11737},{"version":"1.9.3","createdAt":"2026-07-11T05:45:22.087Z","changelog":"Docs fix: sign-in is Google or GitHub (was Google-only); no other content change.","fileCount":4,"zipByteSize":11326},{"version":"1.9.2","createdAt":"2026-07-10T20:00:46.415Z","changelog":"Corrected the Twitter/X rate-limit (403) example: the upgrade hint is tier-aware (Free -> Pro, Pro -> Agency, Agency/Enterprise -> sales@socialcannon.app). The previous version showed 'Upgrade to Pro for unlimited Twitter publishing', but no tier is unlimited for X and Pro users were being told to upgrade to Pro. Now matches the deployed API.","fileCount":4,"zipByteSize":11389}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s172cz0evem0ty227aw7v0gby18453k4:socialcannon","setupComplexity":"low","setupSteps":["Setup complexity is classified as HIGH. You must provision dedicated cloud infrastructure or an isolated VM. Do not run this directly on your local workstation.","Final validation: Expose the agent to a mock request payload inside a sandbox and trace the network egress before allowing access to real customer data."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-miprinia-socialcannon/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-miprinia-socialcannon/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-miprinia-socialcannon/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-miprinia-socialcannon/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-miprinia-socialcannon/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-miprinia-socialcannon/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-10T01:43:27.532Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-miprinia-socialcannon/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-miprinia-socialcannon/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-miprinia-socialcannon/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-miprinia-socialcannon/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"high","updatedAt":"2026-10-09T09:19:29.733Z","emptyReason":null},"readme":"Skill: socialcannon\n\nOwner: miprinia\n\nSummary: Publish, schedule, and manage social media posts across Twitter/X, Facebook, Instagram, LinkedIn, TikTok, and YouTube. Content calendar with gap analysis, A/B testing, engagement inbox, AI content repurposing, optimal timing suggestions, auto-scheduling, UTM tracking, and platform-native AI-content disclosure labels.\n\nTags: latest:1.12.0\n\nVersion history:\n\nv1.12.0 | 2026-09-26T18:18:08.686Z | auto\n\n- MCP tooling instructions now specify a pinned version: @socialcannon/mcp@1.0.2.\n- Expanded security guidance: emphasizes keeping API secrets out of config files, using environment variables and OS keychain/secret managers.\n- Updated agent integration examples for Hermes and Claude Desktop with stronger security practices.\n- Removed files: CLAUDE.md and skill-card.md for cleanup and consolidation.\n\nv1.11.0 | 2026-08-18T17:59:02.375Z | auto\n\n- Added support for platform-native AI-content disclosure labels.\n- Updated feature list in the description.\n- Removed the obsolete skill-card.md file.\n\nv1.10.0 | 2026-07-18T08:30:50.640Z | auto\n\nVersion 1.10.0\n\n- Removed the skill-card.md file.\n- Updated SKILL.md documentation (no visible functional or API changes).\n- Incremented version to 1.10.0.\n\nv1.9.6 | 2026-07-11T12:01:36.991Z | user\n\nFacebook per-post analytics, engagements, and reply are gated off (Meta App Review pending) — those endpoints and Facebook A/B tests now return 400 PLATFORM_UNSUPPORTED. Publishing and scheduling are unaffected. Docs updated to match; check GET /api/v1/platforms for the authoritative per-platform capability list.\n\nv1.9.5 | 2026-07-11T07:05:36.867Z | user\n\nSecurity-audit: reword one response-parsing doc line so the static secret-scanner stops false-flagging 'access token: ' as an exposed token (no secret was ever present; the response.data field guidance is unchanged).\n\nv1.9.4 | 2026-07-11T07:00:43.303Z | user\n\nSecurity-audit follow-up: add a Safety section with explicit human-approval guidance for destructive/irreversible actions (publish, reply, retry, delete, disconnect, post-mode repurpose, immediate A/B); replace a JWT-shaped example placeholder that tripped a secret scanner (false positive — no secret was ever present).\n\nv1.9.3 | 2026-07-11T05:45:22.087Z | user\n\nDocs fix: sign-in is Google or GitHub (was Google-only); no other content change.\n\nv1.9.2 | 2026-07-10T20:00:46.415Z | user\n\nCorrected the Twitter/X rate-limit (403) example: the upgrade hint is tier-aware (Free -> Pro, Pro -> Agency, Agency/Enterprise -> sales@socialcannon.app). The previous version showed 'Upgrade to Pro for unlimited Twitter publishing', but no tier is unlimited for X and Pro users were being told to upgrade to Pro. Now matches the deployed API.\n\nv1.9.1 | 2026-07-10T14:56:29.448Z | user\n\nFixed the credential setup instructions. The previous version said your Client Secret was on the dashboard Settings page, but new signups were never actually shown it — a dead-end. Now your Client Secret is revealed once, immediately after signup; if you miss it, mint a fresh one at Settings → API Keys → \"Generate API Secret\". Also corrected three docs to match the API: media uploads (images ≤25 MB are normalized to JPEG and may be resized), the content calendar (gap analysis is at response.data.summary.gaps), and timing (the optimal-slot endpoint is available on all tiers, not just Pro).\n\nv1.9.0 | 2026-07-03T16:25:36.183Z | auto\n\nVersion 1.9.0\n\n- Public signup now available; closed beta references removed from documentation.\n- Updated \"Getting Started\" instructions to reflect new onboarding process (Google sign-in, free tier included, no card required).\n- Skill card documentation file removed.\n- Minor wording and formatting improvements throughout documentation.\n\nv1.8.3 | 2026-07-02T20:21:56.882Z | auto\n\n- Version bump to 1.8.3 in SKILL.md.\n- No functional or documentation changes except updating the version number.\n\nv1.8.2 | 2026-07-02T17:32:34.174Z | user\n\nFree tier X/Twitter cap reduced from 3 to 1 post per billing period (pay-per-post cost control)\n\nv1.8.1 | 2026-07-01T18:06:10.565Z | user\n\nClarify LinkedIn is publish-only: no analytics, engagement inbox, or replies (LinkedIn Community Management API not yet approved). Updated headline and Pro-tier description.\n\nv1.8.0 | 2026-06-14T11:29:02.100Z | auto\n\n- Added instructions for using SocialCannon via MCP-compatible agents (Hermes, Claude Desktop, OpenClaw) with the @socialcannon/mcp package.\n- Provided configuration examples for Hermes Agent and Claude Desktop integration.\n- Clarified that the REST API remains fully available and MCP is an optional convenience layer.\n- Removed `skill-card.md` file.\n\nv1.7.1 | 2026-06-07T18:56:29.036Z | auto\n\n- Documentation updated: removed platform-specific and advanced post options from SKILL.md for conciseness.\n- Outdated skill-card.md file removed.\n- No API or feature changes; this release is documentation-only.\n\nv1.7.0 | 2026-06-07T06:14:42.595Z | auto\n\n- LinkedIn integration added—now supports publishing, scheduling, and managing posts for LinkedIn accounts.\n- Documentation updated to reflect LinkedIn support in all connection and API usage examples.\n- Removed internal files CLAUDE.md and skill-card.md for cleanup.\n\nv1.6.2 | 2026-06-06T06:56:01.256Z | user\n\nRemove Reddit from listed platforms and the create_post schema (not an offered platform).\n\nv1.6.1 | 2026-06-06T06:40:15.639Z | user\n\nDocs cleanup: removed internal audit/approval-status notes; the TikTok section now states only the posting fields users/agents need.\n\nv1.6.0 | 2026-06-06T06:22:02.469Z | user\n\nTikTok Direct Post support: required privacyLevel plus comment/duet/stitch and commercial/branded-content options on posts, a new get_tiktok_creator_info tool, and the GET /api/v1/accounts/{id}/tiktok/creator-info endpoint for discovering a creator's allowed privacy levels and interaction settings.\n\nv1.5.1 | 2026-05-24T08:43:10.382Z | auto\n\n- Added a closed beta notice: SocialCannon is now invite-only and requires emailing support to request access.\n- Updated the Getting Started section to reflect closed beta process for obtaining API credentials.\n- No changes to API endpoints or functionality.\n- Documentation now clarifies that public signup is not yet available.\n\nv1.5.0 | 2026-05-23T06:10:35.897Z | auto\n\n- Documentation updated to remove the \"Analytics\" section from the skill readme.\n- No changes to core functionality or API endpoints.\n- Version bumped to 1.5.0.\n\nv1.4.0 | 2026-05-23T05:52:53.352Z | auto\n\n- Documentation for the Accounts API section has been streamlined: analytics details have been removed.\n- Minor text clarifications for posts and threads documentation.\n- No API or functionality changes; this release focuses on updating documentation.\n\nv1.3.0 | 2026-05-22T18:54:17.031Z | auto\n\n- Bump version to 1.3.0.\n- No user-facing or functional changes; documentation (SKILL.md) only.\n\nv1.2.1 | 2026-05-17T17:02:07.616Z | auto\n\n- LinkedIn has been removed from the list of supported platforms.\n- The SKILL.md documentation now clarifies that LinkedIn and Reddit are planned for a future release.\n- No functional or API changes—this update mainly updates documentation to reflect current platform support.\n\nv1.2.0 | 2026-04-16T20:04:47.786Z | user\n\nClarified A/B test publish behavior: variants publish immediately when scheduledAt is omitted (mirrors POST /api/v1/posts). Documented partial-failure semantics (HTTP 502) and per-variant mediaUrls.\n\nv1.1.0 | 2026-04-14T16:55:04.462Z | user\n\nAdd TikTok + YouTube (6 platforms), getting started guide, retry endpoint, auto-schedule, optimal-slot, Stories/Reels/Shorts, support email, fix 10 API reference errors including missing grant_type\n\nv1.0.0 | 2026-04-03T09:10:14.656Z | auto\n\nInitial release of SocialCannon API skill.\n\n- Publish, schedule, and manage posts across Twitter/X, Facebook, Instagram, and LinkedIn from one API.\n- Features include content calendar with gap analysis, analytics, engagement inbox, A/B testing, AI-powered content repurposing, post timing suggestions, and UTM tracking.\n- Supports media uploads, multi-part threads/carousels, post editing/deletion, and aggregate analytics.\n- Unified inbox for managing and replying to comments on posts.\n- JWT-based authentication with access token management.\n\nArchive index:\n\nArchive v1.12.0: 3 files, 13889 bytes\n\nFiles: skill-card.md (2002b), SKILL.md (37782b), _meta.json (132b)\n\nFile v1.12.0:SKILL.md\n\n---\nname: socialcannon\ndescription: >\n Publish, schedule, and manage social media posts across Twitter/X, Facebook,\n Instagram, LinkedIn, TikTok, and YouTube. Content calendar with gap analysis,\n A/B testing, engagement inbox, AI content repurposing, optimal timing\n suggestions, auto-scheduling, UTM tracking, and platform-native AI-content\n disclosure labels.\nversion: 1.12.0\nmetadata:\n openclaw:\n requires:\n env:\n - SOCIALCANNON_CLIENT_ID\n - SOCIALCANNON_CLIENT_SECRET\n bins:\n - curl\n primaryEnv: SOCIALCANNON_CLIENT_ID\n emoji: \"\\U0001F4E3\"\n homepage: https://socialcannon.app\n---\n\n# SocialCannon\n\nSocial media publishing API. Publish to Twitter/X, Facebook, Instagram, LinkedIn, TikTok, and YouTube from one API with scheduling, analytics, A/B testing, and AI-powered features.\n\n**Base URL:** `https://socialcannon.app`\n\n## Safety: destructive & irreversible actions\n\nSeveral operations act on **live social accounts** and cannot be undone. In an agent workflow, get **explicit human approval before** any of these:\n\n- **Publish** or **immediate A/B test** (a post with no `scheduledAt`) — goes live at once.\n- **Reply to an engagement** — posts a public reply from the connected account.\n- **Retry** a post — re-attempts a real publish.\n- **Delete a post** — removes it here **and** attempts deletion on the platform.\n- **Disconnect an account** — breaks the integration; reconnecting requires the OAuth flow again.\n- **Repurpose in `post` mode** — adapts **and publishes** to the target platforms.\n\nSafer defaults for agents: prefer read-only listing and `draft`/`scheduled` posts, and use `preview`-mode repurpose before `post` mode. Keep your Client Secret in an environment variable — never paste it into a chat.\n\n## Getting Started\n\nBefore making API calls, you need credentials and at least one connected social account.\n\n### 1. Get your API credentials\n\nSign up at [socialcannon.app](https://socialcannon.app) (Google or GitHub sign-in, free tier included — no card required). **Your Client Secret is shown once, right after signup — copy it then.** If you miss it, open **Settings → API Keys** and click **Generate API Secret**. Your **Client ID** is always available on that page. Use these as `SOCIALCANNON_CLIENT_ID` and `SOCIALCANNON_CLIENT_SECRET`.\n\n### 2. Connect social accounts\n\nSocial accounts are connected via OAuth in the browser. Open the connect URL for each platform you want to use — you'll authorize SocialCannon and get redirected back:\n\n| Platform | Connect URL |\n|----------|-------------|\n| Twitter/X | `https://socialcannon.app/api/connect/twitter?client_id=YOUR_CLIENT_ID` |\n| Facebook | `https://socialcannon.app/api/connect/facebook?client_id=YOUR_CLIENT_ID` |\n| Instagram | `https://socialcannon.app/api/connect/instagram?client_id=YOUR_CLIENT_ID` |\n| LinkedIn | `https://socialcannon.app/api/connect/linkedin?client_id=YOUR_CLIENT_ID` |\n| TikTok | `https://socialcannon.app/api/connect/tiktok?client_id=YOUR_CLIENT_ID` |\n| YouTube | `https://socialcannon.app/api/connect/youtube?client_id=YOUR_CLIENT_ID` |\n\nYou can also connect accounts from the dashboard at **Settings → Accounts**. Instagram uses Facebook's OAuth flow — make sure you select the Facebook Page linked to your Instagram Business account.\n\n### 3. Get an API token and start posting\n\nOnce you have credentials and at least one connected account, authenticate and create your first post:\n\n```bash\n# Get a token\nTOKEN=$(curl -s -X POST https://socialcannon.app/api/v1/auth/token \\\n -H \"Content-Type: application/json\" \\\n -d \"{\\\"grant_type\\\": \\\"client_credentials\\\", \\\"client_id\\\": \\\"$SOCIALCANNON_CLIENT_ID\\\", \\\"client_secret\\\": \\\"$SOCIALCANNON_CLIENT_SECRET\\\"}\" \\\n | jq -r '.data.access_token')\n\n# List your connected accounts\ncurl -s https://socialcannon.app/api/v1/accounts \\\n -H \"Authorization: Bearer $TOKEN\" | jq '.data'\n\n# Publish a post (replace with an ID from the list above)\ncurl -X POST https://socialcannon.app/api/v1/posts \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"accountId\": \"\", \"content\": \"Hello from SocialCannon!\"}'\n```\n\n## Use via MCP (Hermes, Claude Desktop, OpenClaw)\n\nInstead of raw HTTP, you can expose SocialCannon's 23 tools to any MCP-compatible agent with the [`@socialcannon/mcp`](https://www.npmjs.com/package/@socialcannon/mcp) package. Use the same `SOCIALCANNON_CLIENT_ID` / `SOCIALCANNON_CLIENT_SECRET` from your dashboard.\n\nRun the exact version shown below (`@socialcannon/mcp@1.0.2`). The package runs with your credentials, so pinning means a later npm release is never picked up until you have reviewed it and changed the version yourself.\n\nKeep the Client Secret out of config files. Store it in your OS keychain or secret manager and expose it as the `SOCIALCANNON_CLIENT_SECRET` environment variable of the process that starts your agent.\n\n**Hermes Agent** — add to `~/.hermes/config.yaml`. Hermes replaces `${VAR}` references with values from its environment, so the file holds no secret:\n\n```yaml\nmcp_servers:\n socialcannon:\n command: \"npx\"\n args: [\"-y\", \"@socialcannon/mcp@1.0.2\"]\n env:\n SOCIALCANNON_CLIENT_ID: \"${SOCIALCANNON_CLIENT_ID}\"\n SOCIALCANNON_CLIENT_SECRET: \"${SOCIALCANNON_CLIENT_SECRET}\"\n```\n\n**Claude Desktop** — add an entry under `mcpServers` in `claude_desktop_config.json` with the same pinned `command`/`args`. If your MCP client can only take the secret as a literal value in its config file, make that file readable only by you (`chmod 600`), never commit or sync it, and click **Generate API Secret** under **Settings → API Keys** to replace the secret if the file is ever exposed.\n\nThe REST API documented below remains fully available; MCP is an optional convenience layer over the same endpoints.\n\n## Authentication\n\nAll requests require a JWT Bearer token. Get one by exchanging your client credentials:\n\n```bash\ncurl -X POST https://socialcannon.app/api/v1/auth/token \\\n -H \"Content-Type: application/json\" \\\n -d \"{\n \\\"grant_type\\\": \\\"client_credentials\\\",\n \\\"client_id\\\": \\\"$SOCIALCANNON_CLIENT_ID\\\",\n \\\"client_secret\\\": \\\"$SOCIALCANNON_CLIENT_SECRET\\\"\n }\"\n```\n\nResponse:\n```json\n{\n \"success\": true,\n \"data\": {\n \"access_token\": \"\",\n \"token_type\": \"Bearer\",\n \"expires_in\": 3600,\n \"scope\": \"posts:read posts:write ...\"\n }\n}\n```\n\nUse `response.data.access_token` as a Bearer token in all subsequent requests. Tokens expire after 1 hour — request a new one when you get a 401.\n\n**All requests below require this header:**\n```\nAuthorization: Bearer \nContent-Type: application/json\n```\n\n## Response Format\n\n**IMPORTANT: ALL responses are wrapped in a standard envelope.** This includes the token endpoint.\n\n- Success: `{ \"success\": true, \"data\": { ... } }`\n- Error: `{ \"success\": false, \"error\": \"message\", \"code\": \"ERROR_CODE\" }`\n\nWhen extracting data from any response, always read from `response.data`, not from the response root. For example, the access token is at `response.data.access_token` — not `response.access_token`.\n\n## Accounts\n\nAccounts represent social media profiles connected via OAuth (see Getting Started above). You need at least one connected account before you can create posts.\n\n### List connected accounts\n\n```bash\ncurl https://socialcannon.app/api/v1/accounts \\\n -H \"Authorization: Bearer $TOKEN\"\n```\n\nReturns all connected social accounts with their platform, username, and status. Use the account `id` field when creating posts. Filter by platform with `?platform=twitter`.\n\n### Get a single account\n\n```bash\ncurl https://socialcannon.app/api/v1/accounts/ \\\n -H \"Authorization: Bearer $TOKEN\"\n```\n\n### Disconnect an account\n\n```bash\ncurl -X DELETE https://socialcannon.app/api/v1/accounts/ \\\n -H \"Authorization: Bearer $TOKEN\"\n```\n\n## Posts\n\n### Create a post\n\nPublish immediately (omit `scheduledAt`) or schedule for later:\n\n```bash\ncurl -X POST https://socialcannon.app/api/v1/posts \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"accountId\": \"\",\n \"content\": \"Your post text here\",\n \"mediaUrls\": [\"https://example.com/image.jpg\"],\n \"scheduledAt\": \"2026-04-15T10:00:00Z\",\n \"platformOptions\": {\n \"autoUtm\": true\n }\n }'\n```\n\nFields:\n- `accountId` (required) — ID from the accounts list\n- `content` (required) — post text\n- `mediaUrls` (optional) — array of public image/video URLs\n- `scheduledAt` (optional) — ISO 8601 datetime, `\"optimal\"` (auto-pick best time based on engagement data, Pro), or omit for immediate publish\n- `platformOptions.autoUtm` (optional) — auto-tag URLs with UTM parameters\n- `platformOptions.aiGenerated` (optional) — set `true` when requesting the platform's native AI-content label. TikTok and YouTube support it directly. Instagram fails closed unless the SocialCannon deployment has explicitly enabled verified native-disclosure access; do not omit the flag and publish unlabeled content as a workaround. See [AI-content disclosure](#ai-content-disclosure).\n- `platformOptions.mediaType` (optional) — controls content type:\n - `\"reel\"` — Facebook/Instagram Reel (vertical 9:16 video)\n - `\"story\"` — Facebook/Instagram/TikTok Story (24h ephemeral)\n - `\"short\"` — YouTube Short (vertical video ≤60s)\n - `\"community\"` — YouTube Community post (text/image)\n- `platformOptions` **TikTok fields** — TikTok posts require `privacyLevel` and support `disableComment` / `disableDuet` / `disableStitch`, `commercialContent`, `brandOrganic`, `brandedContent`. See the [TikTok](#tiktok) section under Platform-Specific Notes.\n\n### List posts\n\n```bash\ncurl \"https://socialcannon.app/api/v1/posts?status=published&platform=twitter&limit=20\" \\\n -H \"Authorization: Bearer $TOKEN\"\n```\n\nQuery params: `status` (draft/scheduled/published/failed), `platform`, `accountId`, `limit`, `cursor`\n\n### Get a single post\n\n```bash\ncurl https://socialcannon.app/api/v1/posts/ \\\n -H \"Authorization: Bearer $TOKEN\"\n```\n\n### Update a draft or scheduled post\n\n```bash\ncurl -X PATCH https://socialcannon.app/api/v1/posts/ \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"content\": \"Updated text\",\n \"scheduledAt\": \"2026-04-16T14:00:00Z\",\n \"platformOptions\": { \"autoUtm\": true }\n }'\n```\n\nFields: `content`, `scheduledAt`, `platformOptions` — all optional.\n\n### Delete a post\n\n```bash\ncurl -X DELETE https://socialcannon.app/api/v1/posts/ \\\n -H \"Authorization: Bearer $TOKEN\"\n```\n\nIf the post is published, this also attempts to delete it from the social platform.\n\n### Retry a failed post\n\n```bash\ncurl -X POST https://socialcannon.app/api/v1/posts//retry \\\n -H \"Authorization: Bearer $TOKEN\"\n```\n\nResets the failed post and attempts to publish immediately. No body needed. If it fails again, the post returns to `failed` status with the new error.\n\n## Threads & Carousels\n\nCreate multi-part threads (Twitter reply chains or Instagram carousels):\n\n```bash\ncurl -X POST https://socialcannon.app/api/v1/posts/thread \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"accountId\": \"\",\n \"items\": [\n { \"content\": \"Thread part 1 — the hook\" },\n { \"content\": \"Thread part 2 — the detail\" },\n { \"content\": \"Thread part 3 — the CTA\", \"mediaUrls\": [\"https://...\"] }\n ],\n \"scheduledAt\": \"2026-04-15T10:00:00Z\",\n \"platformOptions\": { \"autoUtm\": true }\n }'\n```\n\nFields: `accountId` (required), `items` (required, min 2, max 25), `scheduledAt` (optional), `platformOptions` (optional — e.g. `aiGenerated: true` to request the AI-content label). Instagram requires media on each item and rejects `aiGenerated: true` before publishing unless verified native-disclosure access is enabled for the deployment.\n\n## AI-Content Disclosure\n\nWhen a post's media is AI-generated, set `platformOptions.aiGenerated: true` to request the native label. SocialCannon maps it as follows:\n\n| Platform | API field | User-facing label |\n|----------|-----------|-------------------|\n| Instagram | Default unavailable; `is_ai_generated` only after deployment capability enablement | \"AI info\" label (on carousels, parent only) |\n| TikTok | `is_aigc` | \"AI-generated\" label |\n| YouTube | `containsSyntheticMedia` | \"Altered content\" disclosure |\n\nInstagram is intentionally fail-closed by default: `aiGenerated: true` is rejected before any Meta request unless the deployment has explicitly enabled its separately verified native-disclosure capability. Never silently remove the flag to force publication; report the block instead. Facebook, X, and LinkedIn have no API disclosure field — the flag is accepted but ignored there. The request is also supported on threads (`platformOptions`), per-post in auto-schedule (`posts[].platformOptions`), and as a test-level `aiGenerated` flag on A/B tests (applies to every variant, with the same Instagram gate).\n\n## Media Upload\n\nUpload images/videos before creating posts. **Three-step direct-to-GCS flow** — bytes go straight to Google Cloud Storage via a signed URL, never through SocialCannon's server, so our API never buffers the file. Each destination still has a **per-file limit**: the smaller of what the network accepts and what our publishing pipeline can fetch. Pass the destination accountId on step 1 so an unpublishable file is rejected before any signed URL is issued; without accountId the pipeline-wide ceiling of **140 MiB** applies.\n\n| Platform | Post type | File kind | Max per file |\n|----------|-----------|-----------|--------------|\n| X (Twitter) | Feed, Threads | Images | 5 MB |\n| X (Twitter) | Feed, Threads | GIFs | 5 MB |\n| X (Twitter) | Feed, Threads | Video (MP4, MOV) | 140 MiB |\n| Instagram | Feed, Stories, Carousels | Images (JPEG only) | 8 MB |\n| Instagram | Feed, Reels, Carousels | Video (MP4, MOV) | 100 MiB |\n| Instagram | Stories | Video (MP4, MOV) | 100 MB |\n| Facebook | Feed, Stories | Images (JPEG, PNG, WebP, GIF) | 10 MB |\n| Facebook | Feed, Reels, Stories | Video | 100 MiB |\n| LinkedIn | Feed, Threads | Images (JPEG, PNG, GIF) | 20 MiB |\n| TikTok | Feed, Carousels | Photo images | 20 MB |\n| TikTok | Feed | Video | 100 MiB |\n| YouTube | Feed, Shorts | Video | 100 MiB |\n\nTikTok Story, YouTube Community posts, LinkedIn video, and all Reddit media cannot be uploaded through this flow. LinkedIn video and YouTube Community media cannot be published through SocialCannon at all. A Reddit link post can point at a file you host yourself: pass its URL in mediaUrls. Over-limit or unsupported requests fail with 400 and code \"MEDIA_LIMIT_EXCEEDED\" or \"UNSUPPORTED_MEDIA\", and cost no upload quota.\n\nX's video upload takes MP4 and MOV only: a WebM destined for an X account is refused at upload-init. WebM stays accepted for Facebook, TikTok and YouTube.\n\nX documents a 15 MB GIF allowance for its `tweet_gif` media category, which this pipeline does not use: every GIF goes up as `tweet_image`, so 5 MB is the real cap for a GIF here.\n\nAccepted types: `image/jpeg`, `image/png`, `image/gif`, `image/webp`, `video/mp4`, `video/quicktime`, `video/webm`.\n\n### Step 1 — Initialize upload\n\n```bash\ncurl -X POST https://socialcannon.app/api/v1/media/upload-init \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"filename\": \"photo.jpg\",\n \"contentType\": \"image/jpeg\",\n \"size\": 1048576,\n \"accountId\": \"\",\n \"postType\": \"feed\"\n }'\n```\n\nSend accountId — the account that will publish the media — plus optionally postType, one of feed, reel, story, short, carousel, thread (default feed), so the size and format are validated against that destination's real limit.\n\nResponse:\n```json\n{\n \"success\": true,\n \"data\": {\n \"uploadUrl\": \"https://storage.googleapis.com/...?X-Goog-Signature=...\",\n \"publicUrl\": \"https://storage.googleapis.com//media//.jpg\",\n \"requiredHeaders\": {\n \"Content-Type\": \"image/jpeg\",\n \"x-goog-acl\": \"public-read\",\n \"x-goog-content-length-range\": \"0,5000000\"\n },\n \"limit\": { \"maxBytes\": 5000000, \"maxBytesDisplay\": \"5 MB\", \"platform\": \"twitter\", \"postType\": \"feed\" }\n }\n}\n```\n\n`uploadUrl` is a V4 signed PUT URL valid for **15 minutes**. `size` must be the exact byte size of the file you're about to upload. `limit.maxBytes` echoes the cap that was applied, and `limit.platform` is `null` when no `accountId` was given.\n\n### Step 2 — PUT the file to the signed URL\n\n```bash\ncurl -X PUT \"$UPLOAD_URL\" \\\n -H \"Content-Type: image/jpeg\" \\\n -H \"x-goog-acl: public-read\" \\\n -H \"x-goog-content-length-range: 0,5000000\" \\\n --data-binary @photo.jpg\n```\n\nYou **must** send the exact headers returned in `requiredHeaders`, including the `x-goog-content-length-range` value from step 1 — it pins the size cap into the signature, so GCS itself refuses a file that is too large. Do **not** send the `Authorization` header — the signed URL carries its own auth. A successful PUT returns HTTP 200 with an empty body.\n\n### Step 3 — Finalize\n\n```bash\ncurl -X POST https://socialcannon.app/api/v1/media/upload-complete \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{ \"publicUrl\": \"https://storage.googleapis.com//media//.jpg\" }'\n```\n\nPass the `publicUrl` you got from step 1 verbatim. The server verifies the object exists, stamps `customTime` (starting the 30-day retention window), and increments your upload quota.\n\nResponse: `{ \"success\": true, \"data\": { \"url\": \"https://...\", \"filename\": \"media//.jpg\", \"contentType\": \"image/jpeg\", \"size\": 1048576 } }`\n\nUse the returned `url` in the `mediaUrls` field when creating posts. SocialCannon does not convert or resize uploads: the finalize response reports the file exactly as uploaded, and that same file is what the network receives. Upload a format and size the destination accepts — for example a JPEG for Instagram.\n\n### Quota & errors\n\n- `403` on step 1 with `code` set → your tier has hit its upload quota. Inspect `limit` in the response body.\n- `400` on step 1 with `code: \"MEDIA_LIMIT_EXCEEDED\"` → the file is larger than the destination's per-file limit; the message names the actual size, the limit and the platform. Nothing was uploaded and no quota was spent.\n- `400` on step 1 with `code: \"UNSUPPORTED_MEDIA\"` → that platform / post type / file format cannot be published through SocialCannon (for example LinkedIn video, a TikTok Story, or a PNG on Instagram). Convert the file to a format the destination accepts (Instagram images must be JPEG) or pick a supported destination.\n- `404` on step 1 → `accountId` is not one of your connected accounts. `409` → that account is disconnected; reconnect it before uploading.\n- `404` on step 3 → the PUT didn't actually land. Retry from step 2.\n- `403` on step 3 → `publicUrl` doesn't belong to your client. Use the exact URL returned by step 1, do not construct it yourself.\n\n## Content Calendar\n\n### Get calendar view\n\nSee posts grouped by date with gap analysis:\n\n```bash\ncurl \"https://socialcannon.app/api/v1/calendar?startDate=2026-04-01&endDate=2026-04-30\" \\\n -H \"Authorization: Bearer $TOKEN\"\n```\n\nReturns `posts` and `summary` (totals by status/platform/day, plus `summary.gaps` = dates with no posts). Note the gap analysis is nested at `response.data.summary.gaps`.\n\nQuery params: `startDate` (required), `endDate` (required), `accountId`, `platform`\n\n### Find available slots\n\n```bash\ncurl \"https://socialcannon.app/api/v1/calendar/slots?startDate=2026-04-01&endDate=2026-04-07&slotDurationMinutes=60\" \\\n -H \"Authorization: Bearer $TOKEN\"\n```\n\nQuery params: `startDate` (required), `endDate` (required, max 14-day range), `slotDurationMinutes` (optional, 30-1440, default 60).\n\nReturns `{ slots[], totalSlots, availableSlots, occupiedSlots }`.\n\n## Analytics\n\n### Per-post analytics\n\nFetch live engagement metrics from the platform:\n\n```bash\ncurl https://socialcannon.app/api/v1/posts//analytics \\\n -H \"Authorization: Bearer $TOKEN\"\n```\n\nReturns: likes, comments, shares, impressions, reach, clicks, engagementRate, plus historical snapshots.\n\n> **Availability:** live per-post analytics is **not available for Facebook or LinkedIn** yet — both need a platform approval (Meta App Review / LinkedIn Community Management) we don't hold, so the endpoint returns `400` with `code: \"PLATFORM_UNSUPPORTED\"`. Twitter, Instagram, TikTok, and YouTube work. Check `GET /api/v1/platforms` → `capabilities.supportsAnalytics` for the authoritative per-platform list.\n\n### Aggregate analytics\n\n```bash\ncurl \"https://socialcannon.app/api/v1/analytics/summary?startDate=2026-04-01&endDate=2026-04-30\" \\\n -H \"Authorization: Bearer $TOKEN\"\n```\n\nReturns totals across all posts for the date range.\n\n### Bulk refresh analytics\n\n```bash\ncurl -X POST https://socialcannon.app/api/v1/analytics/refresh \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{ \"platform\": \"twitter\", \"limit\": 20 }'\n```\n\nFields: `postIds` (optional, array of up to 50 post IDs to refresh), `platform` (optional, filter), `limit` (optional, default 20, max 50). If `postIds` is provided, those specific posts are refreshed; otherwise recent published posts are refreshed.\n\n## Engagements (Comment Inbox)\n\n### List engagements\n\n```bash\ncurl \"https://socialcannon.app/api/v1/engagements?isRead=false&limit=20\" \\\n -H \"Authorization: Bearer $TOKEN\"\n```\n\nQuery params: `postId`, `isRead` (true/false), `limit`, `cursor`\n\n### Fetch engagements for a post\n\n```bash\ncurl \"https://socialcannon.app/api/v1/posts//engagements?cursor=\" \\\n -H \"Authorization: Bearer $TOKEN\"\n```\n\nFetches fresh comments from the platform and stores them. Supports `cursor` for pagination.\n\n> **Availability:** **not available for Facebook or LinkedIn** yet (same platform-approval gate as analytics) — returns `400` with `code: \"PLATFORM_UNSUPPORTED\"`. Replying to an engagement is likewise gated for those two. See `capabilities.supportsEngagements` / `supportsReply` in `GET /api/v1/platforms`.\n\n### Mark as read\n\n```bash\ncurl -X PATCH https://socialcannon.app/api/v1/engagements/ \\\n -H \"Authorization: Bearer $TOKEN\"\n```\n\nMarks the engagement as read. No request body needed — the endpoint auto-marks on PATCH.\n\n### Reply to an engagement\n\n```bash\ncurl -X POST https://socialcannon.app/api/v1/engagements//reply \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{ \"content\": \"Thanks for the feedback!\" }'\n```\n\nPosts the reply directly on the social platform.\n\n## AI Content Repurposing\n\nAdapt content for multiple platforms using AI. Two modes available:\n\n### Preview mode (default) — adapt and return variants for review:\n\n```bash\ncurl -X POST https://socialcannon.app/api/v1/posts/repurpose \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"sourceContent\": \"Your long-form content here...\",\n \"targetPlatforms\": [\"twitter\", \"facebook\", \"tiktok\"],\n \"mode\": \"preview\",\n \"tone\": \"professional\"\n }'\n```\n\nReturns `{ \"variants\": [{ \"platform\", \"content\", \"validation\", \"characterCount\" }], \"allValid\" }`.\n\n### Post mode — adapt and publish in one call:\n\n```bash\ncurl -X POST https://socialcannon.app/api/v1/posts/repurpose \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"sourceContent\": \"Your content here...\",\n \"targetPlatforms\": [\"twitter\", \"facebook\"],\n \"mode\": \"post\",\n \"accountIds\": { \"twitter\": \"acc_123\", \"facebook\": \"acc_456\" },\n \"mediaUrls\": { \"twitter\": [\"https://example.com/video.mp4\"] },\n \"appendContent\": { \"twitter\": \"Links or extra text for Twitter only\" },\n \"appendToAll\": \"Text appended to all platforms\"\n }'\n```\n\nReturns `{ \"results\": [{ \"platform\", \"success\", \"postUrl?\", \"error?\" }] }`.\n\nAll content is humanized automatically to remove AI writing patterns. Trusted clients bypass tier limits.\n\n## A/B Testing (Pro)\n\n> **Not available for TikTok.** A/B-test variants carry only content + media, so they can't set the per-post privacy level TikTok requires. A TikTok account is rejected with `400` and `code: \"PLATFORM_UNSUPPORTED\"` — publish individual posts to TikTok instead.\n\n> **Not available for LinkedIn or Facebook.** Both are publish-only for analytics right now (LinkedIn needs Community Management approval; Facebook needs Meta App Review for `pages_read_engagement`), so a winner could never be determined. Those accounts are rejected with `400` and `code: \"PLATFORM_UNSUPPORTED\"` — publish individual posts instead.\n\n### Create a test\n\n```bash\ncurl -X POST https://socialcannon.app/api/v1/ab-tests \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"accountId\": \"\",\n \"name\": \"CTA test\",\n \"variants\": [\n { \"content\": \"Check out our new feature!\", \"mediaUrls\": [\"https://...\"] },\n { \"content\": \"You won'\\''t believe this new feature...\" }\n ],\n \"metric\": \"engagementRate\",\n \"minDurationHours\": 24,\n \"scheduledAt\": \"2026-04-20T10:00:00Z\",\n \"aiGenerated\": true\n }'\n```\n\n**Publish behavior matches `POST /api/v1/posts`:**\n- **Omit `scheduledAt`** → all variants publish **immediately** to the platform via the social adapter\n- **Provide `scheduledAt`** → all variants are **scheduled** for that time (must be within 30 days; cron publishes them hourly)\n\nEach variant is a separate post record. Auto-completes after `minDurationHours` and the winner is determined by the chosen metric. Per-variant `mediaUrls` is optional. The test-level `aiGenerated` flag (optional) requests the platform's native AI-content label for every variant; Instagram rejects the test before variant creation unless verified native-disclosure access is enabled.\n\n**Partial failure semantics:** if ANY variant fails to publish during immediate mode, the endpoint returns **HTTP 502** and the failed variants are marked with `status: 'failed'`. The A/B test record is still created, but the winner comparison at completion only considers successfully published variants. Inspect each variant's post status before relying on test results.\n\n### Get test results\n\n```bash\ncurl https://socialcannon.app/api/v1/ab-tests/ \\\n -H \"Authorization: Bearer $TOKEN\"\n```\n\nReturns per-variant metrics, current winner, and confidence score.\n\n### List tests\n\n```bash\ncurl \"https://socialcannon.app/api/v1/ab-tests?status=active\" \\\n -H \"Authorization: Bearer $TOKEN\"\n```\n\n### Force-complete a test\n\n```bash\ncurl -X POST https://socialcannon.app/api/v1/ab-tests//complete \\\n -H \"Authorization: Bearer $TOKEN\"\n```\n\n## Timing Suggestions (Pro)\n\n### Get recommended posting times\n\n```bash\ncurl \"https://socialcannon.app/api/v1/accounts//timing?timezone=UTC-5\" \\\n -H \"Authorization: Bearer $TOKEN\"\n```\n\nReturns top 5 time slots ranked by average engagement rate with confidence scores.\n\n### Find the single best available slot\n\nCombines engagement data with calendar availability. Unlike the other two timing endpoints, this one is available on **all tiers** (including Free):\n\n```bash\ncurl \"https://socialcannon.app/api/v1/timing/optimal-slot?accountId=&timezone=UTC-5\" \\\n -H \"Authorization: Bearer $TOKEN\"\n```\n\nReturns the next open slot ranked by historical performance.\n\n### Auto-schedule multiple posts\n\nDistribute posts across optimal time slots for the next 7 days:\n\n```bash\ncurl -X POST https://socialcannon.app/api/v1/posts/auto-schedule \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"accountId\": \"\",\n \"posts\": [\n { \"content\": \"Post 1 text\" },\n { \"content\": \"Post 2 text\", \"mediaUrls\": [\"https://...\"], \"platformOptions\": { \"aiGenerated\": true } },\n { \"content\": \"Post 3 text\" }\n ],\n \"timezone\": \"UTC-5\"\n }'\n```\n\nMax 20 posts per request. Each post gets a unique slot. Per-post `platformOptions` are supported (e.g. `aiGenerated` to request the AI-content label, `title`/`visibility` where applicable). An Instagram item with `aiGenerated: true` fails closed unless verified native-disclosure access is enabled. Returns `{ scheduled: [...], unscheduled: [...], summary: {...} }`.\n\n## UTM Link Tracking\n\nGenerate UTM-tagged URLs:\n\n```bash\ncurl -X POST https://socialcannon.app/api/v1/links/generate \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"url\": \"https://example.com/product\",\n \"platform\": \"twitter\",\n \"campaign\": \"spring-launch\",\n \"content\": \"hero-cta\",\n \"postId\": \"\",\n \"save\": true\n }'\n```\n\nFields: `url` (required), `platform` (optional — sets `utm_source`), `campaign` (optional — `utm_campaign`), `content` (optional — `utm_content`), `term` (optional — `utm_term`), `postId` (optional — link to a post), `save` (optional, default true — persist to tracked_links).\n\n### List tracked links\n\n```bash\ncurl \"https://socialcannon.app/api/v1/links?postId=&platform=twitter&limit=20&cursor=\" \\\n -H \"Authorization: Bearer $TOKEN\"\n```\n\nQuery params: `postId`, `platform`, `limit`, `cursor` — all optional.\n\n## Platforms\n\nList supported platforms and their capabilities (public, no auth required):\n\n```bash\ncurl https://socialcannon.app/api/v1/platforms\n```\n\n## Platform-Specific Notes\n\n### Twitter/X\n- 280 char limit. Up to 4 images. Threads via reply chains.\n\n### Facebook\n- 63,206 char limit. Supports native scheduling. Page-level tokens.\n- **Reels**: Set `platformOptions.mediaType` to `\"reel\"`. Video must be MP4/MOV, vertical (9:16). Without this, videos post as regular video posts.\n- **Stories**: Set `platformOptions.mediaType` to `\"story\"`. Supports one image or video. Ephemeral (24h).\n\n```bash\ncurl -X POST https://socialcannon.app/api/v1/posts \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"accountId\": \"\",\n \"content\": \"Check out this tutorial!\",\n \"mediaUrls\": [\"https://example.com/video.mp4\"],\n \"platformOptions\": {\n \"mediaType\": \"reel\"\n }\n }'\n```\n\n### Instagram\n- Requires media (no text-only). Max 10 carousel items. No API deletion.\n- **Stories**: Set `platformOptions.mediaType` to `\"story\"`. One image or video.\n- **Reels**: Set `platformOptions.mediaType` to `\"reel\"`. Vertical 9:16 video.\n- **AI-content label**: Native disclosure is default-off and fail-closed. `platformOptions.aiGenerated: true` is rejected before any Meta request unless the deployment has explicitly enabled verified capability access. When enabled, SocialCannon sends `is_ai_generated` (the \"AI info\" label); on carousels it is applied to the parent only. Do not publish by silently removing the requested disclosure.\n\n### TikTok\n- Requires media — no text-only posts. Supports video, photo carousel (up to 35 images), and Stories.\n- **`platformOptions.privacyLevel` is REQUIRED** on every TikTok post — there is no default. Omitting it returns `400` with code `TIKTOK_PRIVACY_REQUIRED`. Use a value from the creator-info endpoint's `privacyLevelOptions` (e.g. `PUBLIC_TO_EVERYONE`, `MUTUAL_FOLLOW_FRIENDS`, `FOLLOWER_OF_CREATOR`, `SELF_ONLY`).\n- **Interaction toggles** (optional, default = allowed): `disableComment`, `disableDuet`, `disableStitch` (booleans). Duet/Stitch apply to video only. If the creator-info endpoint reports an interaction is disabled account-side (`commentDisabled` / `duetDisabled` / `stitchDisabled`), set the matching `disable*` to `true` (the server force-disables it regardless).\n- **Commercial content disclosure** (optional): set `commercialContent: true` if the post promotes a brand, product, or service, then set `brandOrganic: true` (your own brand) and/or `brandedContent: true` (paid/third-party partnership). If `brandedContent` is true, `privacyLevel` cannot be `SELF_ONLY`.\n- **AI-generated disclosure** (optional): set `aiGenerated: true` when the media is AI-generated (`is_aigc` — TikTok shows an \"AI-generated\" label).\n- **Stories**: Set `platformOptions.mediaType` to `\"story\"`. One video. Ephemeral (24h).\n- Video publish uses an async poll model. No API deletion support.\n\n**Get a TikTok account's posting capabilities** — call this before composing a TikTok post; it returns the allowed privacy levels and which interactions are disabled:\n\n```bash\ncurl https://socialcannon.app/api/v1/accounts//tiktok/creator-info \\\n -H \"Authorization: Bearer $TOKEN\"\n```\n\nReturns `{ creatorNickname, creatorUsername, creatorAvatarUrl, privacyLevelOptions, commentDisabled, duetDisabled, stitchDisabled, maxVideoPostDurationSec }`. Choose `privacyLevel` from `privacyLevelOptions` and respect the `*Disabled` flags.\n\n**Example — publish a public TikTok video with comments on:**\n```bash\ncurl -X POST https://socialcannon.app/api/v1/posts \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"accountId\": \"\",\n \"content\": \"New track out now!\",\n \"mediaUrls\": [\"https://example.com/clip.mp4\"],\n \"platformOptions\": {\n \"privacyLevel\": \"PUBLIC_TO_EVERYONE\",\n \"disableComment\": false,\n \"disableDuet\": false,\n \"disableStitch\": false\n }\n }'\n```\n\n### YouTube\n- Supports regular videos, Shorts, and Community posts. Native scheduling support.\n- **Shorts**: Set `platformOptions.mediaType` to `\"short\"`. Vertical video ≤60s.\n- **Community posts**: Set `platformOptions.mediaType` to `\"community\"`. Text/image post to channel's Community tab.\n- Scheduled videos are uploaded as private with a `publishAt` timestamp.\n- **Altered content disclosure**: Set `platformOptions.aiGenerated: true` for realistic AI-generated media (`containsSyntheticMedia` — YouTube's \"Altered content\" disclosure).\n\n### LinkedIn\n- 3,000 char limit. Supports text-only and images (single or multi-image). Threads combine all items into one post.\n- Scheduling works via SocialCannon (LinkedIn has no native scheduling).\n- **No analytics, engagement inbox, or replies** for LinkedIn.\n\n## Rate Limits\n\n- Free tier: 30 requests/minute\n- Pro tier: 300 requests/minute\n- Agency tier: 600 requests/minute\n- Enterprise tier: 1200 requests/minute (default; negotiable)\n- Returns `429` with `Retry-After` header when exceeded\n\n## Subscription Tiers\n\nFour tiers. Twitter/X is the only platform with a per-post API cost passed through, so every tier carries an X-write quota.\n\n### Free — $0\n- 2 connected accounts\n- 10 posts per billing period\n- **1 Twitter/X post per billing period** (a taster — thread items count individually)\n- 2 scheduled posts at a time\n- 3 media uploads per billing period\n- 2-item threads, 5 tracked links\n- All 6 platforms: Twitter/X, Facebook, Instagram, LinkedIn, TikTok, YouTube\n- No analytics, no engagement replies, no A/B testing, no timing suggestions\n- 30 API requests/minute\n\n### Pro — $15/month\n- Unlimited accounts, posts, scheduling\n- **50 Twitter/X posts per billing period**\n- Analytics with history, 90-day calendar\n- 25-item threads, unlimited tracked links\n- A/B testing (5 concurrent, 4 variants)\n- Engagement replies, timing suggestions\n- 300 API requests/minute\n\n### Agency — $49/month\n- Everything in Pro\n- **250 Twitter/X posts per billing period**\n- A/B testing (20 concurrent, 6 variants)\n- 365-day calendar range\n- Priority support\n- 600 API requests/minute\n\n### Enterprise — custom contract\n- Custom Twitter/X quota, custom rate limits, SLA, dedicated support\n- Contact `sales@socialcannon.app`\n\n### Hitting a cap\n\nAny tier exceeding its `maxTwitterPostsPerPeriod` cap returns:\n```json\n{\n \"success\": false,\n \"error\": \"Twitter/X post limit reached (50/50). Upgrade to Agency for 250 Twitter/X posts per month.\",\n \"code\": \"LIMIT_EXCEEDED\",\n \"limit\": { \"type\": \"twitter_posts_per_period\", \"current\": 50, \"max\": 50, \"tier\": \"pro\" }\n}\n```\nHTTP `403`. Resets at the start of the next billing period. The upgrade hint is tier-aware — Free is pointed to Pro, Pro to Agency, and Agency/Enterprise to `sales@socialcannon.app` (no tier is \"unlimited\" for Twitter/X).\n\n## Support\n\nIf you run into issues with the API, account connections, or integration setup, contact **support@socialcannon.app**.\n\n## Tips for Agents\n\n1. Always list accounts first to get valid `accountId` values before creating posts.\n2. Use the calendar endpoint to check for gaps before suggesting new posts.\n3. For Instagram and TikTok, always include at least one media URL — text-only posts will fail.\n4. Use `autoUtm: true` in `platformOptions` to automatically tag URLs in posts.\n5. Check analytics after 24+ hours for meaningful engagement data.\n6. When repurposing content, review the returned `validation` field — if `valid` is false, adjust the content before publishing.\n7. Use `scheduledAt: \"optimal\"` to let SocialCannon pick the best posting time automatically (Pro).\n8. For batch scheduling, use the auto-schedule endpoint instead of creating posts one by one.\n9. For YouTube, set `mediaType` to `\"short\"` for Shorts or `\"community\"` for Community tab posts.\n10. For TikTok, call `GET /api/v1/accounts/{id}/tiktok/creator-info` first — it returns the allowed `privacyLevelOptions` (pass one as `platformOptions.privacyLevel`; it is required) and which of Comment/Duet/Stitch are disabled (never enable a disabled one).\n11. If the media is AI-generated, set `platformOptions.aiGenerated: true` to request the native label. TikTok and YouTube map it directly; Instagram fails closed unless verified native-disclosure access is enabled for the deployment. Report that block rather than silently removing the flag.\n\nFile v1.12.0:_meta.json\n\n{\n \"ownerId\": \"kn75vx9q7acz869fn4vdd2cwx1845nrx\",\n \"slug\": \"socialcannon\",\n \"version\": \"1.12.0\",\n \"publishedAt\": 1790446688686\n}\n\nFile v1.12.0:skill-card.md\n\n## Description:\n\nHelps agents publish, schedule, and manage social media posts across connected accounts using SocialCannon.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[miprinia](https://clawhub.ai/user/miprinia)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nSocial media managers, creators, and developers use this skill to help agents draft, schedule, publish, and review posts and engagement across connected social accounts.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: Publishing, replying, retrying, deleting, disconnecting, or repurposing in post mode can affect live accounts and may be irreversible.\n\nMitigation: Get explicit human approval before these actions; prefer drafts, scheduled posts, and previews where possible.\n\nRisk: Exposing the client secret or giving an optional MCP process account credentials can compromise connected accounts.\n\nMitigation: Keep secrets in environment variables or a keychain, not chat or configuration files; enable MCP only when its credential access is intended.\n\n## Reference(s):\n\n- [SocialCannon ClawHub release](https://clawhub.ai/miprinia/skills/socialcannon)\n- [SocialCannon homepage](https://socialcannon.app)\n- [Optional SocialCannon MCP package](https://www.npmjs.com/package/@socialcannon/mcp)\n\n## Skill Output:\n\n**Output Type(s):** [Text, Markdown, Shell commands, Configuration guidance]\n\n**Output Format:** [Markdown with API examples and shell commands]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Guidance for drafts, schedules, publishing, analytics, and engagement through connected accounts.]\n\n## Skill Version(s):\n\n1.12.0 (source: frontmatter and server release metadata)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nArchive v1.11.0: 4 files, 12574 bytes\n\nFiles: CLAUDE.md (43b), skill-card.md (2635b), SKILL.md (32475b), _meta.json (132b)\n\nFile v1.11.0:SKILL.md\n\n---\nname: socialcannon\ndescription: >\n Publish, schedule, and manage social media posts across Twitter/X, Facebook,\n Instagram, LinkedIn, TikTok, and YouTube. Content calendar with gap analysis,\n A/B testing, engagement inbox, AI content repurposing, optimal timing\n suggestions, auto-scheduling, UTM tracking, and platform-native AI-content\n disclosure labels.\nversion: 1.11.0\nmetadata:\n openclaw:\n requires:\n env:\n - SOCIALCANNON_CLIENT_ID\n - SOCIALCANNON_CLIENT_SECRET\n bins:\n - curl\n primaryEnv: SOCIALCANNON_CLIENT_ID\n emoji: \"\\U0001F4E3\"\n homepage: https://socialcannon.app\n---\n\n# SocialCannon\n\nSocial media publishing API. Publish to Twitter/X, Facebook, Instagram, LinkedIn, TikTok, and YouTube from one API with scheduling, analytics, A/B testing, and AI-powered features.\n\n**Base URL:** `https://socialcannon.app`\n\n## Safety: destructive & irreversible actions\n\nSeveral operations act on **live social accounts** and cannot be undone. In an agent workflow, get **explicit human approval before** any of these:\n\n- **Publish** or **immediate A/B test** (a post with no `scheduledAt`) — goes live at once.\n- **Reply to an engagement** — posts a public reply from the connected account.\n- **Retry** a post — re-attempts a real publish.\n- **Delete a post** — removes it here **and** attempts deletion on the platform.\n- **Disconnect an account** — breaks the integration; reconnecting requires the OAuth flow again.\n- **Repurpose in `post` mode** — adapts **and publishes** to the target platforms.\n\nSafer defaults for agents: prefer read-only listing and `draft`/`scheduled` posts, and use `preview`-mode repurpose before `post` mode. Keep your Client Secret in an environment variable — never paste it into a chat.\n\n## Getting Started\n\nBefore making API calls, you need credentials and at least one connected social account.\n\n### 1. Get your API credentials\n\nSign up at [socialcannon.app](https://socialcannon.app) (Google or GitHub sign-in, free tier included — no card required). **Your Client Secret is shown once, right after signup — copy it then.** If you miss it, open **Settings → API Keys** and click **Generate API Secret**. Your **Client ID** is always available on that page. Use these as `SOCIALCANNON_CLIENT_ID` and `SOCIALCANNON_CLIENT_SECRET`.\n\n### 2. Connect social accounts\n\nSocial accounts are connected via OAuth in the browser. Open the connect URL for each platform you want to use — you'll authorize SocialCannon and get redirected back:\n\n| Platform | Connect URL |\n|----------|-------------|\n| Twitter/X | `https://socialcannon.app/api/connect/twitter?client_id=YOUR_CLIENT_ID` |\n| Facebook | `https://socialcannon.app/api/connect/facebook?client_id=YOUR_CLIENT_ID` |\n| Instagram | `https://socialcannon.app/api/connect/instagram?client_id=YOUR_CLIENT_ID` |\n| LinkedIn | `https://socialcannon.app/api/connect/linkedin?client_id=YOUR_CLIENT_ID` |\n| TikTok | `https://socialcannon.app/api/connect/tiktok?client_id=YOUR_CLIENT_ID` |\n| YouTube | `https://socialcannon.app/api/connect/youtube?client_id=YOUR_CLIENT_ID` |\n\nYou can also connect accounts from the dashboard at **Settings → Accounts**. Instagram uses Facebook's OAuth flow — make sure you select the Facebook Page linked to your Instagram Business account.\n\n### 3. Get an API token and start posting\n\nOnce you have credentials and at least one connected account, authenticate and create your first post:\n\n```bash\n# Get a token\nTOKEN=$(curl -s -X POST https://socialcannon.app/api/v1/auth/token \\\n -H \"Content-Type: application/json\" \\\n -d \"{\\\"grant_type\\\": \\\"client_credentials\\\", \\\"client_id\\\": \\\"$SOCIALCANNON_CLIENT_ID\\\", \\\"client_secret\\\": \\\"$SOCIALCANNON_CLIENT_SECRET\\\"}\" \\\n | jq -r '.data.access_token')\n\n# List your connected accounts\ncurl -s https://socialcannon.app/api/v1/accounts \\\n -H \"Authorization: Bearer $TOKEN\" | jq '.data'\n\n# Publish a post (replace with an ID from the list above)\ncurl -X POST https://socialcannon.app/api/v1/posts \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"accountId\": \"\", \"content\": \"Hello from SocialCannon!\"}'\n```\n\n## Use via MCP (Hermes, Claude Desktop, OpenClaw)\n\nInstead of raw HTTP, you can expose SocialCannon's 23 tools to any MCP-compatible agent with the [`@socialcannon/mcp`](https://www.npmjs.com/package/@socialcannon/mcp) package. Use the same `SOCIALCANNON_CLIENT_ID` / `SOCIALCANNON_CLIENT_SECRET` from your dashboard.\n\n**Hermes Agent** — add to `~/.hermes/config.yaml`:\n\n```yaml\nmcp_servers:\n socialcannon:\n command: \"npx\"\n args: [\"-y\", \"@socialcannon/mcp\"]\n env:\n SOCIALCANNON_CLIENT_ID: \"your-client-id\"\n SOCIALCANNON_CLIENT_SECRET: \"your-client-secret\"\n```\n\n**Claude Desktop** — add an entry under `mcpServers` in `claude_desktop_config.json` with the same `command`/`args`/`env`.\n\nThe REST API documented below remains fully available; MCP is an optional convenience layer over the same endpoints.\n\n## Authentication\n\nAll requests require a JWT Bearer token. Get one by exchanging your client credentials:\n\n```bash\ncurl -X POST https://socialcannon.app/api/v1/auth/token \\\n -H \"Content-Type: application/json\" \\\n -d \"{\n \\\"grant_type\\\": \\\"client_credentials\\\",\n \\\"client_id\\\": \\\"$SOCIALCANNON_CLIENT_ID\\\",\n \\\"client_secret\\\": \\\"$SOCIALCANNON_CLIENT_SECRET\\\"\n }\"\n```\n\nResponse:\n```json\n{\n \"success\": true,\n \"data\": {\n \"access_token\": \"\",\n \"token_type\": \"Bearer\",\n \"expires_in\": 3600,\n \"scope\": \"posts:read posts:write ...\"\n }\n}\n```\n\nUse `response.data.access_token` as a Bearer token in all subsequent requests. Tokens expire after 1 hour — request a new one when you get a 401.\n\n**All requests below require this header:**\n```\nAuthorization: Bearer \nContent-Type: application/json\n```\n\n## Response Format\n\n**IMPORTANT: ALL responses are wrapped in a standard envelope.** This includes the token endpoint.\n\n- Success: `{ \"success\": true, \"data\": { ... } }`\n- Error: `{ \"success\": false, \"error\": \"message\", \"code\": \"ERROR_CODE\" }`\n\nWhen extracting data from any response, always read from `response.data`, not from the response root. For example, the access token is at `response.data.access_token` — not `response.access_token`.\n\n## Accounts\n\nAccounts represent social media profiles connected via OAuth (see Getting Started above). You need at least one connected account before you can create posts.\n\n### List connected accounts\n\n```bash\ncurl https://socialcannon.app/api/v1/accounts \\\n -H \"Authorization: Bearer $TOKEN\"\n```\n\nReturns all connected social accounts with their platform, username, and status. Use the account `id` field when creating posts. Filter by platform with `?platform=twitter`.\n\n### Get a single account\n\n```bash\ncurl https://socialcannon.app/api/v1/accounts/ \\\n -H \"Authorization: Bearer $TOKEN\"\n```\n\n### Disconnect an account\n\n```bash\ncurl -X DELETE https://socialcannon.app/api/v1/accounts/ \\\n -H \"Authorization: Bearer $TOKEN\"\n```\n\n## Posts\n\n### Create a post\n\nPublish immediately (omit `scheduledAt`) or schedule for later:\n\n```bash\ncurl -X POST https://socialcannon.app/api/v1/posts \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"accountId\": \"\",\n \"content\": \"Your post text here\",\n \"mediaUrls\": [\"https://example.com/image.jpg\"],\n \"scheduledAt\": \"2026-04-15T10:00:00Z\",\n \"platformOptions\": {\n \"autoUtm\": true\n }\n }'\n```\n\nFields:\n- `accountId` (required) — ID from the accounts list\n- `content` (required) — post text\n- `mediaUrls` (optional) — array of public image/video URLs\n- `scheduledAt` (optional) — ISO 8601 datetime, `\"optimal\"` (auto-pick best time based on engagement data, Pro), or omit for immediate publish\n- `platformOptions.autoUtm` (optional) — auto-tag URLs with UTM parameters\n- `platformOptions.aiGenerated` (optional) — set `true` when the post's media is AI-generated. Maps to the platform's native AI-content label (Instagram, TikTok, YouTube); ignored on platforms without one. See [AI-content disclosure](#ai-content-disclosure).\n- `platformOptions.mediaType` (optional) — controls content type:\n - `\"reel\"` — Facebook/Instagram Reel (vertical 9:16 video)\n - `\"story\"` — Facebook/Instagram/TikTok Story (24h ephemeral)\n - `\"short\"` — YouTube Short (vertical video ≤60s)\n - `\"community\"` — YouTube Community post (text/image)\n- `platformOptions` **TikTok fields** — TikTok posts require `privacyLevel` and support `disableComment` / `disableDuet` / `disableStitch`, `commercialContent`, `brandOrganic`, `brandedContent`. See the [TikTok](#tiktok) section under Platform-Specific Notes.\n\n### List posts\n\n```bash\ncurl \"https://socialcannon.app/api/v1/posts?status=published&platform=twitter&limit=20\" \\\n -H \"Authorization: Bearer $TOKEN\"\n```\n\nQuery params: `status` (draft/scheduled/published/failed), `platform`, `accountId`, `limit`, `cursor`\n\n### Get a single post\n\n```bash\ncurl https://socialcannon.app/api/v1/posts/ \\\n -H \"Authorization: Bearer $TOKEN\"\n```\n\n### Update a draft or scheduled post\n\n```bash\ncurl -X PATCH https://socialcannon.app/api/v1/posts/ \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"content\": \"Updated text\",\n \"scheduledAt\": \"2026-04-16T14:00:00Z\",\n \"platformOptions\": { \"autoUtm\": true }\n }'\n```\n\nFields: `content`, `scheduledAt`, `platformOptions` — all optional.\n\n### Delete a post\n\n```bash\ncurl -X DELETE https://socialcannon.app/api/v1/posts/ \\\n -H \"Authorization: Bearer $TOKEN\"\n```\n\nIf the post is published, this also attempts to delete it from the social platform.\n\n### Retry a failed post\n\n```bash\ncurl -X POST https://socialcannon.app/api/v1/posts//retry \\\n -H \"Authorization: Bearer $TOKEN\"\n```\n\nResets the failed post and attempts to publish immediately. No body needed. If it fails again, the post returns to `failed` status with the new error.\n\n## Threads & Carousels\n\nCreate multi-part threads (Twitter reply chains or Instagram carousels):\n\n```bash\ncurl -X POST https://socialcannon.app/api/v1/posts/thread \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"accountId\": \"\",\n \"items\": [\n { \"content\": \"Thread part 1 — the hook\" },\n { \"content\": \"Thread part 2 — the detail\" },\n { \"content\": \"Thread part 3 — the CTA\", \"mediaUrls\": [\"https://...\"] }\n ],\n \"scheduledAt\": \"2026-04-15T10:00:00Z\",\n \"platformOptions\": { \"autoUtm\": true }\n }'\n```\n\nFields: `accountId` (required), `items` (required, min 2, max 25), `scheduledAt` (optional), `platformOptions` (optional — e.g. `aiGenerated: true` for the AI-content label). Instagram requires media on each item.\n\n## AI-Content Disclosure\n\nWhen a post's media is AI-generated, set `platformOptions.aiGenerated: true`. SocialCannon maps it to each platform's native AI-content label:\n\n| Platform | API field | User-facing label |\n|----------|-----------|-------------------|\n| Instagram | `is_ai_generated` | \"AI info\" label (on carousels, applied to the carousel container) |\n| TikTok | `is_aigc` | \"AI-generated\" label |\n| YouTube | `containsSyntheticMedia` | \"Altered content\" disclosure |\n\nFacebook, X, and LinkedIn have no API disclosure field — the flag is accepted but ignored there. Also supported on threads (`platformOptions`), per-post in auto-schedule (`posts[].platformOptions`), and as a test-level `aiGenerated` flag on A/B tests (applies to every variant).\n\n## Media Upload\n\nUpload images/videos before creating posts. **Three-step direct-to-GCS flow** — bytes go straight to Google Cloud Storage via a signed URL, never through SocialCannon's server. This supports files up to **4GB**.\n\nAccepted types: `image/jpeg`, `image/png`, `image/gif`, `image/webp`, `video/mp4`, `video/quicktime`, `video/webm`.\n\n### Step 1 — Initialize upload\n\n```bash\ncurl -X POST https://socialcannon.app/api/v1/media/upload-init \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"filename\": \"photo.jpg\",\n \"contentType\": \"image/jpeg\",\n \"size\": 1048576\n }'\n```\n\nResponse:\n```json\n{\n \"success\": true,\n \"data\": {\n \"uploadUrl\": \"https://storage.googleapis.com/...?X-Goog-Signature=...\",\n \"publicUrl\": \"https://storage.googleapis.com//media//.jpg\",\n \"requiredHeaders\": {\n \"Content-Type\": \"image/jpeg\",\n \"x-goog-acl\": \"public-read\"\n }\n }\n}\n```\n\n`uploadUrl` is a V4 signed PUT URL valid for **15 minutes**. `size` must be the exact byte size of the file you're about to upload.\n\n### Step 2 — PUT the file to the signed URL\n\n```bash\ncurl -X PUT \"$UPLOAD_URL\" \\\n -H \"Content-Type: image/jpeg\" \\\n -H \"x-goog-acl: public-read\" \\\n --data-binary @photo.jpg\n```\n\nYou **must** send the exact headers returned in `requiredHeaders`. Do **not** send the `Authorization` header — the signed URL carries its own auth. A successful PUT returns HTTP 200 with an empty body.\n\n### Step 3 — Finalize\n\n```bash\ncurl -X POST https://socialcannon.app/api/v1/media/upload-complete \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{ \"publicUrl\": \"https://storage.googleapis.com//media//.jpg\" }'\n```\n\nPass the `publicUrl` you got from step 1 verbatim. The server verifies the object exists, stamps `customTime` (starting the 30-day retention window), and increments your upload quota.\n\nResponse: `{ \"success\": true, \"data\": { \"url\": \"https://...\", \"filename\": \"media//.jpg\", \"contentType\": \"image/jpeg\", \"size\": 1048576 } }`\n\nUse the returned `url` in the `mediaUrls` field when creating posts. Images up to 25 MB are normalized to JPEG (and may be resized) for platform compatibility, so the `contentType` and `size` in the finalize response can differ from what you uploaded — PNG/WebP transparency is not preserved. Videos and images larger than 25 MB are stored as-is.\n\n### Quota & errors\n\n- `403` on step 1 with `code` set → your tier has hit its upload quota. Inspect `limit` in the response body.\n- `404` on step 3 → the PUT didn't actually land. Retry from step 2.\n- `403` on step 3 → `publicUrl` doesn't belong to your client. Use the exact URL returned by step 1, do not construct it yourself.\n\n## Content Calendar\n\n### Get calendar view\n\nSee posts grouped by date with gap analysis:\n\n```bash\ncurl \"https://socialcannon.app/api/v1/calendar?startDate=2026-04-01&endDate=2026-04-30\" \\\n -H \"Authorization: Bearer $TOKEN\"\n```\n\nReturns `posts` and `summary` (totals by status/platform/day, plus `summary.gaps` = dates with no posts). Note the gap analysis is nested at `response.data.summary.gaps`.\n\nQuery params: `startDate` (required), `endDate` (required), `accountId`, `platform`\n\n### Find available slots\n\n```bash\ncurl \"https://socialcannon.app/api/v1/calendar/slots?startDate=2026-04-01&endDate=2026-04-07&slotDurationMinutes=60\" \\\n -H \"Authorization: Bearer $TOKEN\"\n```\n\nQuery params: `startDate` (required), `endDate` (required, max 14-day range), `slotDurationMinutes` (optional, 30-1440, default 60).\n\nReturns `{ slots[], totalSlots, availableSlots, occupiedSlots }`.\n\n## Analytics\n\n### Per-post analytics\n\nFetch live engagement metrics from the platform:\n\n```bash\ncurl https://socialcannon.app/api/v1/posts//analytics \\\n -H \"Authorization: Bearer $TOKEN\"\n```\n\nReturns: likes, comments, shares, impressions, reach, clicks, engagementRate, plus historical snapshots.\n\n> **Availability:** live per-post analytics is **not available for Facebook or LinkedIn** yet — both need a platform approval (Meta App Review / LinkedIn Community Management) we don't hold, so the endpoint returns `400` with `code: \"PLATFORM_UNSUPPORTED\"`. Twitter, Instagram, TikTok, and YouTube work. Check `GET /api/v1/platforms` → `capabilities.supportsAnalytics` for the authoritative per-platform list.\n\n### Aggregate analytics\n\n```bash\ncurl \"https://socialcannon.app/api/v1/analytics/summary?startDate=2026-04-01&endDate=2026-04-30\" \\\n -H \"Authorization: Bearer $TOKEN\"\n```\n\nReturns totals across all posts for the date range.\n\n### Bulk refresh analytics\n\n```bash\ncurl -X POST https://socialcannon.app/api/v1/analytics/refresh \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{ \"platform\": \"twitter\", \"limit\": 20 }'\n```\n\nFields: `postIds` (optional, array of up to 50 post IDs to refresh), `platform` (optional, filter), `limit` (optional, default 20, max 50). If `postIds` is provided, those specific posts are refreshed; otherwise recent published posts are refreshed.\n\n## Engagements (Comment Inbox)\n\n### List engagements\n\n```bash\ncurl \"https://socialcannon.app/api/v1/engagements?isRead=false&limit=20\" \\\n -H \"Authorization: Bearer $TOKEN\"\n```\n\nQuery params: `postId`, `isRead` (true/false), `limit`, `cursor`\n\n### Fetch engagements for a post\n\n```bash\ncurl \"https://socialcannon.app/api/v1/posts//engagements?cursor=\" \\\n -H \"Authorization: Bearer $TOKEN\"\n```\n\nFetches fresh comments from the platform and stores them. Supports `cursor` for pagination.\n\n> **Availability:** **not available for Facebook or LinkedIn** yet (same platform-approval gate as analytics) — returns `400` with `code: \"PLATFORM_UNSUPPORTED\"`. Replying to an engagement is likewise gated for those two. See `capabilities.supportsEngagements` / `supportsReply` in `GET /api/v1/platforms`.\n\n### Mark as read\n\n```bash\ncurl -X PATCH https://socialcannon.app/api/v1/engagements/ \\\n -H \"Authorization: Bearer $TOKEN\"\n```\n\nMarks the engagement as read. No request body needed — the endpoint auto-marks on PATCH.\n\n### Reply to an engagement\n\n```bash\ncurl -X POST https://socialcannon.app/api/v1/engagements//reply \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{ \"content\": \"Thanks for the feedback!\" }'\n```\n\nPosts the reply directly on the social platform.\n\n## AI Content Repurposing\n\nAdapt content for multiple platforms using AI. Two modes available:\n\n### Preview mode (default) — adapt and return variants for review:\n\n```bash\ncurl -X POST https://socialcannon.app/api/v1/posts/repurpose \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"sourceContent\": \"Your long-form content here...\",\n \"targetPlatforms\": [\"twitter\", \"facebook\", \"tiktok\"],\n \"mode\": \"preview\",\n \"tone\": \"professional\"\n }'\n```\n\nReturns `{ \"variants\": [{ \"platform\", \"content\", \"validation\", \"characterCount\" }], \"allValid\" }`.\n\n### Post mode — adapt and publish in one call:\n\n```bash\ncurl -X POST https://socialcannon.app/api/v1/posts/repurpose \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"sourceContent\": \"Your content here...\",\n \"targetPlatforms\": [\"twitter\", \"facebook\"],\n \"mode\": \"post\",\n \"accountIds\": { \"twitter\": \"acc_123\", \"facebook\": \"acc_456\" },\n \"mediaUrls\": { \"twitter\": [\"https://example.com/video.mp4\"] },\n \"appendContent\": { \"twitter\": \"Links or extra text for Twitter only\" },\n \"appendToAll\": \"Text appended to all platforms\"\n }'\n```\n\nReturns `{ \"results\": [{ \"platform\", \"success\", \"postUrl?\", \"error?\" }] }`.\n\nAll content is humanized automatically to remove AI writing patterns. Trusted clients bypass tier limits.\n\n## A/B Testing (Pro)\n\n> **Not available for TikTok.** A/B-test variants carry only content + media, so they can't set the per-post privacy level TikTok requires. A TikTok account is rejected with `400` and `code: \"PLATFORM_UNSUPPORTED\"` — publish individual posts to TikTok instead.\n\n> **Not available for LinkedIn or Facebook.** Both are publish-only for analytics right now (LinkedIn needs Community Management approval; Facebook needs Meta App Review for `pages_read_engagement`), so a winner could never be determined. Those accounts are rejected with `400` and `code: \"PLATFORM_UNSUPPORTED\"` — publish individual posts instead.\n\n### Create a test\n\n```bash\ncurl -X POST https://socialcannon.app/api/v1/ab-tests \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"accountId\": \"\",\n \"name\": \"CTA test\",\n \"variants\": [\n { \"content\": \"Check out our new feature!\", \"mediaUrls\": [\"https://...\"] },\n { \"content\": \"You won'\\''t believe this new feature...\" }\n ],\n \"metric\": \"engagementRate\",\n \"minDurationHours\": 24,\n \"scheduledAt\": \"2026-04-20T10:00:00Z\",\n \"aiGenerated\": true\n }'\n```\n\n**Publish behavior matches `POST /api/v1/posts`:**\n- **Omit `scheduledAt`** → all variants publish **immediately** to the platform via the social adapter\n- **Provide `scheduledAt`** → all variants are **scheduled** for that time (must be within 30 days; cron publishes them hourly)\n\nEach variant is a separate post record. Auto-completes after `minDurationHours` and the winner is determined by the chosen metric. Per-variant `mediaUrls` is optional. The test-level `aiGenerated` flag (optional) applies the platform's native AI-content label to every variant.\n\n**Partial failure semantics:** if ANY variant fails to publish during immediate mode, the endpoint returns **HTTP 502** and the failed variants are marked with `status: 'failed'`. The A/B test record is still created, but the winner comparison at completion only considers successfully published variants. Inspect each variant's post status before relying on test results.\n\n### Get test results\n\n```bash\ncurl https://socialcannon.app/api/v1/ab-tests/ \\\n -H \"Authorization: Bearer $TOKEN\"\n```\n\nReturns per-variant metrics, current winner, and confidence score.\n\n### List tests\n\n```bash\ncurl \"https://socialcannon.app/api/v1/ab-tests?status=active\" \\\n -H \"Authorization: Bearer $TOKEN\"\n```\n\n### Force-complete a test\n\n```bash\ncurl -X POST https://socialcannon.app/api/v1/ab-tests//complete \\\n -H \"Authorization: Bearer $TOKEN\"\n```\n\n## Timing Suggestions (Pro)\n\n### Get recommended posting times\n\n```bash\ncurl \"https://socialcannon.app/api/v1/accounts//timing?timezone=UTC-5\" \\\n -H \"Authorization: Bearer $TOKEN\"\n```\n\nReturns top 5 time slots ranked by average engagement rate with confidence scores.\n\n### Find the single best available slot\n\nCombines engagement data with calendar availability. Unlike the other two timing endpoints, this one is available on **all tiers** (including Free):\n\n```bash\ncurl \"https://socialcannon.app/api/v1/timing/optimal-slot?accountId=&timezone=UTC-5\" \\\n -H \"Authorization: Bearer $TOKEN\"\n```\n\nReturns the next open slot ranked by historical performance.\n\n### Auto-schedule multiple posts\n\nDistribute posts across optimal time slots for the next 7 days:\n\n```bash\ncurl -X POST https://socialcannon.app/api/v1/posts/auto-schedule \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"accountId\": \"\",\n \"posts\": [\n { \"content\": \"Post 1 text\" },\n { \"content\": \"Post 2 text\", \"mediaUrls\": [\"https://...\"], \"platformOptions\": { \"aiGenerated\": true } },\n { \"content\": \"Post 3 text\" }\n ],\n \"timezone\": \"UTC-5\"\n }'\n```\n\nMax 20 posts per request. Each post gets a unique slot. Per-post `platformOptions` are supported (e.g. `aiGenerated` for the AI-content label, `title`/`visibility` where applicable). Returns `{ scheduled: [...], unscheduled: [...], summary: {...} }`.\n\n## UTM Link Tracking\n\nGenerate UTM-tagged URLs:\n\n```bash\ncurl -X POST https://socialcannon.app/api/v1/links/generate \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"url\": \"https://example.com/product\",\n \"platform\": \"twitter\",\n \"campaign\": \"spring-launch\",\n \"content\": \"hero-cta\",\n \"postId\": \"\",\n \"save\": true\n }'\n```\n\nFields: `url` (required), `platform` (optional — sets `utm_source`), `campaign` (optional — `utm_campaign`), `content` (optional — `utm_content`), `term` (optional — `utm_term`), `postId` (optional — link to a post), `save` (optional, default true — persist to tracked_links).\n\n### List tracked links\n\n```bash\ncurl \"https://socialcannon.app/api/v1/links?postId=&platform=twitter&limit=20&cursor=\" \\\n -H \"Authorization: Bearer $TOKEN\"\n```\n\nQuery params: `postId`, `platform`, `limit`, `cursor` — all optional.\n\n## Platforms\n\nList supported platforms and their capabilities (public, no auth required):\n\n```bash\ncurl https://socialcannon.app/api/v1/platforms\n```\n\n## Platform-Specific Notes\n\n### Twitter/X\n- 280 char limit. Up to 4 images. Threads via reply chains.\n\n### Facebook\n- 63,206 char limit. Supports native scheduling. Page-level tokens.\n- **Reels**: Set `platformOptions.mediaType` to `\"reel\"`. Video must be MP4/MOV, vertical (9:16). Without this, videos post as regular video posts.\n- **Stories**: Set `platformOptions.mediaType` to `\"story\"`. Supports one image or video. Ephemeral (24h).\n\n```bash\ncurl -X POST https://socialcannon.app/api/v1/posts \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"accountId\": \"\",\n \"content\": \"Check out this tutorial!\",\n \"mediaUrls\": [\"https://example.com/video.mp4\"],\n \"platformOptions\": {\n \"mediaType\": \"reel\"\n }\n }'\n```\n\n### Instagram\n- Requires media (no text-only). Max 10 carousel items. No API deletion.\n- **Stories**: Set `platformOptions.mediaType` to `\"story\"`. One image or video.\n- **Reels**: Set `platformOptions.mediaType` to `\"reel\"`. Vertical 9:16 video.\n- **AI-content label**: Set `platformOptions.aiGenerated: true` to flag AI-generated media (`is_ai_generated` — the \"AI info\" label). On carousels it's applied to the carousel container.\n\n### TikTok\n- Requires media — no text-only posts. Supports video, photo carousel (up to 35 images), and Stories.\n- **`platformOptions.privacyLevel` is REQUIRED** on every TikTok post — there is no default. Omitting it returns `400` with code `TIKTOK_PRIVACY_REQUIRED`. Use a value from the creator-info endpoint's `privacyLevelOptions` (e.g. `PUBLIC_TO_EVERYONE`, `MUTUAL_FOLLOW_FRIENDS`, `FOLLOWER_OF_CREATOR`, `SELF_ONLY`).\n- **Interaction toggles** (optional, default = allowed): `disableComment`, `disableDuet`, `disableStitch` (booleans). Duet/Stitch apply to video only. If the creator-info endpoint reports an interaction is disabled account-side (`commentDisabled` / `duetDisabled` / `stitchDisabled`), set the matching `disable*` to `true` (the server force-disables it regardless).\n- **Commercial content disclosure** (optional): set `commercialContent: true` if the post promotes a brand, product, or service, then set `brandOrganic: true` (your own brand) and/or `brandedContent: true` (paid/third-party partnership). If `brandedContent` is true, `privacyLevel` cannot be `SELF_ONLY`.\n- **AI-generated disclosure** (optional): set `aiGenerated: true` when the media is AI-generated (`is_aigc` — TikTok shows an \"AI-generated\" label).\n- **Stories**: Set `platformOptions.mediaType` to `\"story\"`. One video. Ephemeral (24h).\n- Video publish uses an async poll model. No API deletion support.\n\n**Get a TikTok account's posting capabilities** — call this before composing a TikTok post; it returns the allowed privacy levels and which interactions are disabled:\n\n```bash\ncurl https://socialcannon.app/api/v1/accounts//tiktok/creator-info \\\n -H \"Authorization: Bearer $TOKEN\"\n```\n\nReturns `{ creatorNickname, creatorUsername, creatorAvatarUrl, privacyLevelOptions, commentDisabled, duetDisabled, stitchDisabled, maxVideoPostDurationSec }`. Choose `privacyLevel` from `privacyLevelOptions` and respect the `*Disabled` flags.\n\n**Example — publish a public TikTok video with comments on:**\n```bash\ncurl -X POST https://socialcannon.app/api/v1/posts \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"accountId\": \"\",\n \"content\": \"New track out now!\",\n \"mediaUrls\": [\"https://example.com/clip.mp4\"],\n \"platformOptions\": {\n \"privacyLevel\": \"PUBLIC_TO_EVERYONE\",\n \"disableComment\": false,\n \"disableDuet\": false,\n \"disableStitch\": false\n }\n }'\n```\n\n### YouTube\n- Supports regular videos, Shorts, and Community posts. Native scheduling support.\n- **Shorts**: Set `platformOptions.mediaType` to `\"short\"`. Vertical video ≤60s.\n- **Community posts**: Set `platformOptions.mediaType` to `\"community\"`. Text/image post to channel's Community tab.\n- Scheduled videos are uploaded as private with a `publishAt` timestamp.\n- **Altered content disclosure**: Set `platformOptions.aiGenerated: true` for realistic AI-generated media (`containsSyntheticMedia` — YouTube's \"Altered content\" disclosure).\n\n### LinkedIn\n- 3,000 char limit. Supports text-only and images (single or multi-image). Threads combine all items into one post.\n- Scheduling works via SocialCannon (LinkedIn has no native scheduling).\n- **No analytics, engagement inbox, or replies** for LinkedIn.\n\n## Rate Limits\n\n- Free tier: 30 requests/minute\n- Pro tier: 300 requests/minute\n- Agency tier: 600 requests/minute\n- Enterprise tier: 1200 requests/minute (default; negotiable)\n- Returns `429` with `Retry-After` header when exceeded\n\n## Subscription Tiers\n\nFour tiers. Twitter/X is the only platform with a per-post API cost passed through, so every tier carries an X-write quota.\n\n### Free — $0\n- 2 connected accounts\n- 10 posts per billing period\n- **1 Twitter/X post per billing period** (a taster — thread items count individually)\n- 2 scheduled posts at a time\n- 3 media uploads per billing period\n- 2-item threads, 5 tracked links\n- All 6 platforms: Twitter/X, Facebook, Instagram, LinkedIn, TikTok, YouTube\n- No analytics, no engagement replies, no A/B testing, no timing suggestions\n- 30 API requests/minute\n\n### Pro — $15/month\n- Unlimited accounts, posts, scheduling\n- **50 Twitter/X posts per billing period**\n- Analytics with history, 90-day calendar\n- 25-item threads, unlimited tracked links\n- A/B testing (5 concurrent, 4 variants)\n- Engagement replies, timing suggestions\n- 300 API requests/minute\n\n### Agency — $49/month\n- Everything in Pro\n- **250 Twitter/X posts per billing period**\n- A/B testing (20 concurrent, 6 variants)\n- 365-day calendar range\n- Priority support\n- 600 API requests/minute\n\n### Enterprise — custom contract\n- Custom Twitter/X quota, custom rate limits, SLA, dedicated support\n- Contact `sales@socialcannon.app`\n\n### Hitting a cap\n\nAny tier exceeding its `maxTwitterPostsPerPeriod` cap returns:\n```json\n{\n \"success\": false,\n \"error\": \"Twitter/X post limit reached (50/50). Upgrade to Agency for 250 Twitter/X posts per month.\",\n \"code\": \"LIMIT_EXCEEDED\",\n \"limit\": { \"type\": \"twitter_posts_per_period\", \"current\": 50, \"max\": 50, \"tier\": \"pro\" }\n}\n```\nHTTP `403`. Resets at the start of the next billing period. The upgrade hint is tier-aware — Free is pointed to Pro, Pro to Agency, and Agency/Enterprise to `sales@socialcannon.app` (no tier is \"unlimited\" for Twitter/X).\n\n## Support\n\nIf you run into issues with the API, account connections, or integration setup, contact **support@socialcannon.app**.\n\n## Tips for Agents\n\n1. Always list accounts first to get valid `accountId` values before creating posts.\n2. Use the calendar endpoint to check for gaps before suggesting new posts.\n3. For Instagram and TikTok, always include at least one media URL — text-only posts will fail.\n4. Use `autoUtm: true` in `platformOptions` to automatically tag URLs in posts.\n5. Check analytics after 24+ hours for meaningful engagement data.\n6. When repurposing content, review the returned `validation` field — if `valid` is false, adjust the content before publishing.\n7. Use `scheduledAt: \"optimal\"` to let SocialCannon pick the best posting time automatically (Pro).\n8. For batch scheduling, use the auto-schedule endpoint instead of creating posts one by one.\n9. For YouTube, set `mediaType` to `\"short\"` for Shorts or `\"community\"` for Community tab posts.\n10. For TikTok, call `GET /api/v1/accounts/{id}/tiktok/creator-info` first — it returns the allowed `privacyLevelOptions` (pass one as `platformOptions.privacyLevel`; it is required) and which of Comment/Duet/Stitch are disabled (never enable a disabled one).\n11. If the media is AI-generated, set `platformOptions.aiGenerated: true` so Instagram, TikTok, or YouTube show their native AI-content label.\n\nFile v1.11.0:_meta.json\n\n{\n \"ownerId\": \"kn75vx9q7acz869fn4vdd2cwx1845nrx\",\n \"slug\": \"socialcannon\",\n \"version\": \"1.11.0\",\n \"publishedAt\": 1787075942375\n}\n\nFile v1.11.0:CLAUDE.md\n\n\n\n\n\nFile v1.11.0:skill-card.md\n\n## Description:\n\nPublish, schedule, and manage social media posts across Twitter/X, Facebook, Instagram, LinkedIn, TikTok, and YouTube with a content calendar, gap analysis, A/B testing, engagement inbox, AI content repurposing, optimal timing suggestions, auto-scheduling, UTM tracking, and platform-native AI-content disclosure labels.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[miprinia](https://clawhub.ai/user/miprinia)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nExternal developers, operators, and social media teams use this skill to have an agent prepare API calls and workflow guidance for publishing, scheduling, analyzing, replying to, and repurposing social content across connected accounts.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The skill can guide agents through actions on live social accounts, including publishing, replying, deleting posts, retrying failed posts, disconnecting accounts, and repurposing content in post mode.\n\nMitigation: Require explicit human approval before any publishing, replying, deletion, retry, account disconnection, or repurpose post-mode action; prefer read-only, draft, scheduled, and preview workflows where possible.\n\nRisk: The optional MCP setup uses an unpinned npm package while handling SocialCannon client credentials.\n\nMitigation: Prefer REST examples or a pinned, reviewed MCP package version before use.\n\nRisk: SocialCannon credentials and connected social accounts grant access to public posting workflows.\n\nMitigation: Store client secrets in a protected environment variable or secret manager and install only where that level of account access is acceptable.\n\n## Reference(s):\n\n- [SocialCannon Homepage](https://socialcannon.app)\n- [SocialCannon MCP Package](https://www.npmjs.com/package/@socialcannon/mcp)\n- [ClawHub Skill Page](https://clawhub.ai/miprinia/skills/socialcannon)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, shell commands, configuration, guidance]\n\n**Output Format:** [Markdown guidance with bash, JSON, and YAML examples]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Produces agent-facing instructions and API examples; execution requires SocialCannon credentials and connected social accounts.]\n\n## Skill Version(s):\n\n1.11.0 (source: frontmatter and release evidence)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nArchive v1.10.0: 4 files, 11931 bytes\n\nFiles: CLAUDE.md (43b), skill-card.md (2661b), SKILL.md (30384b), _meta.json (132b)\n\nFile v1.10.0:SKILL.md\n\n---\nname: socialcannon\ndescription: >\n Publish, schedule, and manage social media posts across Twitter/X, Facebook,\n Instagram, LinkedIn, TikTok, and YouTube. Content calendar with gap analysis,\n A/B testing, engagement inbox, AI content repurposing, optimal timing\n suggestions, auto-scheduling, and UTM tracking.\nversion: 1.10.0\nmetadata:\n openclaw:\n requires:\n env:\n - SOCIALCANNON_CLIENT_ID\n - SOCIALCANNON_CLIENT_SECRET\n bins:\n - curl\n primaryEnv: SOCIALCANNON_CLIENT_ID\n emoji: \"\\U0001F4E3\"\n homepage: https://socialcannon.app\n---\n\n# SocialCannon\n\nSocial media publishing API. Publish to Twitter/X, Facebook, Instagram, LinkedIn, TikTok, and YouTube from one API with scheduling, analytics, A/B testing, and AI-powered features.\n\n**Base URL:** `https://socialcannon.app`\n\n## Safety: destructive & irreversible actions\n\nSeveral operations act on **live social accounts** and cannot be undone. In an agent workflow, get **explicit human approval before** any of these:\n\n- **Publish** or **immediate A/B test** (a post with no `scheduledAt`) — goes live at once.\n- **Reply to an engagement** — posts a public reply from the connected account.\n- **Retry** a post — re-attempts a real publish.\n- **Delete a post** — removes it here **and** attempts deletion on the platform.\n- **Disconnect an account** — breaks the integration; reconnecting requires the OAuth flow again.\n- **Repurpose in `post` mode** — adapts **and publishes** to the target platforms.\n\nSafer defaults for agents: prefer read-only listing and `draft`/`scheduled` posts, and use `preview`-mode repurpose before `post` mode. Keep your Client Secret in an environment variable — never paste it into a chat.\n\n## Getting Started\n\nBefore making API calls, you need credentials and at least one connected social account.\n\n### 1. Get your API credentials\n\nSign up at [socialcannon.app](https://socialcannon.app) (Google or GitHub sign-in, free tier included — no card required). **Your Client Secret is shown once, right after signup — copy it then.** If you miss it, open **Settings → API Keys** and click **Generate API Secret**. Your **Client ID** is always available on that page. Use these as `SOCIALCANNON_CLIENT_ID` and `SOCIALCANNON_CLIENT_SECRET`.\n\n### 2. Connect social accounts\n\nSocial accounts are connected via OAuth in the browser. Open the connect URL for each platform you want to use — you'll authorize SocialCannon and get redirected back:\n\n| Platform | Connect URL |\n|----------|-------------|\n| Twitter/X | `https://socialcannon.app/api/connect/twitter?client_id=YOUR_CLIENT_ID` |\n| Facebook | `https://socialcannon.app/api/connect/facebook?client_id=YOUR_CLIENT_ID` |\n| Instagram | `https://socialcannon.app/api/connect/instagram?client_id=YOUR_CLIENT_ID` |\n| LinkedIn | `https://socialcannon.app/api/connect/linkedin?client_id=YOUR_CLIENT_ID` |\n| TikTok | `https://socialcannon.app/api/connect/tiktok?client_id=YOUR_CLIENT_ID` |\n| YouTube | `https://socialcannon.app/api/connect/youtube?client_id=YOUR_CLIENT_ID` |\n\nYou can also connect accounts from the dashboard at **Settings → Accounts**. Instagram uses Facebook's OAuth flow — make sure you select the Facebook Page linked to your Instagram Business account.\n\n### 3. Get an API token and start posting\n\nOnce you have credentials and at least one connected account, authenticate and create your first post:\n\n```bash\n# Get a token\nTOKEN=$(curl -s -X POST https://socialcannon.app/api/v1/auth/token \\\n -H \"Content-Type: application/json\" \\\n -d \"{\\\"grant_type\\\": \\\"client_credentials\\\", \\\"client_id\\\": \\\"$SOCIALCANNON_CLIENT_ID\\\", \\\"client_secret\\\": \\\"$SOCIALCANNON_CLIENT_SECRET\\\"}\" \\\n | jq -r '.data.access_token')\n\n# List your connected accounts\ncurl -s https://socialcannon.app/api/v1/accounts \\\n -H \"Authorization: Bearer $TOKEN\" | jq '.data'\n\n# Publish a post (replace with an ID from the list above)\ncurl -X POST https://socialcannon.app/api/v1/posts \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"accountId\": \"\", \"content\": \"Hello from SocialCannon!\"}'\n```\n\n## Use via MCP (Hermes, Claude Desktop, OpenClaw)\n\nInstead of raw HTTP, you can expose SocialCannon's 23 tools to any MCP-compatible agent with the [`@socialcannon/mcp`](https://www.npmjs.com/package/@socialcannon/mcp) package. Use the same `SOCIALCANNON_CLIENT_ID` / `SOCIALCANNON_CLIENT_SECRET` from your dashboard.\n\n**Hermes Agent** — add to `~/.hermes/config.yaml`:\n\n```yaml\nmcp_servers:\n socialcannon:\n command: \"npx\"\n args: [\"-y\", \"@socialcannon/mcp\"]\n env:\n SOCIALCANNON_CLIENT_ID: \"your-client-id\"\n SOCIALCANNON_CLIENT_SECRET: \"your-client-secret\"\n```\n\n**Claude Desktop** — add an entry under `mcpServers` in `claude_desktop_config.json` with the same `command`/`args`/`env`.\n\nThe REST API documented below remains fully available; MCP is an optional convenience layer over the same endpoints.\n\n## Authentication\n\nAll requests require a JWT Bearer token. Get one by exchanging your client credentials:\n\n```bash\ncurl -X POST https://socialcannon.app/api/v1/auth/token \\\n -H \"Content-Type: application/json\" \\\n -d \"{\n \\\"grant_type\\\": \\\"client_credentials\\\",\n \\\"client_id\\\": \\\"$SOCIALCANNON_CLIENT_ID\\\",\n \\\"client_secret\\\": \\\"$SOCIALCANNON_CLIENT_SECRET\\\"\n }\"\n```\n\nResponse:\n```json\n{\n \"success\": true,\n \"data\": {\n \"access_token\": \"\",\n \"token_type\": \"Bearer\",\n \"expires_in\": 3600,\n \"scope\": \"posts:read posts:write ...\"\n }\n}\n```\n\nUse `response.data.access_token` as a Bearer token in all subsequent requests. Tokens expire after 1 hour — request a new one when you get a 401.\n\n**All requests below require this header:**\n```\nAuthorization: Bearer \nContent-Type: application/json\n```\n\n## Response Format\n\n**IMPORTANT: ALL responses are wrapped in a standard envelope.** This includes the token endpoint.\n\n- Success: `{ \"success\": true, \"data\": { ... } }`\n- Error: `{ \"success\": false, \"error\": \"message\", \"code\": \"ERROR_CODE\" }`\n\nWhen extracting data from any response, always read from `response.data`, not from the response root. For example, the access token is at `response.data.access_token` — not `response.access_token`.\n\n## Accounts\n\nAccounts represent social media profiles connected via OAuth (see Getting Started above). You need at least one connected account before you can create posts.\n\n### List connected accounts\n\n```bash\ncurl https://socialcannon.app/api/v1/accounts \\\n -H \"Authorization: Bearer $TOKEN\"\n```\n\nReturns all connected social accounts with their platform, username, and status. Use the account `id` field when creating posts. Filter by platform with `?platform=twitter`.\n\n### Get a single account\n\n```bash\ncurl https://socialcannon.app/api/v1/accounts/ \\\n -H \"Authorization: Bearer $TOKEN\"\n```\n\n### Disconnect an account\n\n```bash\ncurl -X DELETE https://socialcannon.app/api/v1/accounts/ \\\n -H \"Authorization: Bearer $TOKEN\"\n```\n\n## Posts\n\n### Create a post\n\nPublish immediately (omit `scheduledAt`) or schedule for later:\n\n```bash\ncurl -X POST https://socialcannon.app/api/v1/posts \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"accountId\": \"\",\n \"content\": \"Your post text here\",\n \"mediaUrls\": [\"https://example.com/image.jpg\"],\n \"scheduledAt\": \"2026-04-15T10:00:00Z\",\n \"platformOptions\": {\n \"autoUtm\": true\n }\n }'\n```\n\nFields:\n- `accountId` (required) — ID from the accounts list\n- `content` (required) — post text\n- `mediaUrls` (optional) — array of public image/video URLs\n- `scheduledAt` (optional) — ISO 8601 datetime, `\"optimal\"` (auto-pick best time based on engagement data, Pro), or omit for immediate publish\n- `platformOptions.autoUtm` (optional) — auto-tag URLs with UTM parameters\n- `platformOptions.mediaType` (optional) — controls content type:\n - `\"reel\"` — Facebook/Instagram Reel (vertical 9:16 video)\n - `\"story\"` — Facebook/Instagram/TikTok Story (24h ephemeral)\n - `\"short\"` — YouTube Short (vertical video ≤60s)\n - `\"community\"` — YouTube Community post (text/image)\n- `platformOptions` **TikTok fields** — TikTok posts require `privacyLevel` and support `disableComment` / `disableDuet` / `disableStitch`, `commercialContent`, `brandOrganic`, `brandedContent`. See the [TikTok](#tiktok) section under Platform-Specific Notes.\n\n### List posts\n\n```bash\ncurl \"https://socialcannon.app/api/v1/posts?status=published&platform=twitter&limit=20\" \\\n -H \"Authorization: Bearer $TOKEN\"\n```\n\nQuery params: `status` (draft/scheduled/published/failed), `platform`, `accountId`, `limit`, `cursor`\n\n### Get a single post\n\n```bash\ncurl https://socialcannon.app/api/v1/posts/ \\\n -H \"Authorization: Bearer $TOKEN\"\n```\n\n### Update a draft or scheduled post\n\n```bash\ncurl -X PATCH https://socialcannon.app/api/v1/posts/ \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"content\": \"Updated text\",\n \"scheduledAt\": \"2026-04-16T14:00:00Z\",\n \"platformOptions\": { \"autoUtm\": true }\n }'\n```\n\nFields: `content`, `scheduledAt`, `platformOptions` — all optional.\n\n### Delete a post\n\n```bash\ncurl -X DELETE https://socialcannon.app/api/v1/posts/ \\\n -H \"Authorization: Bearer $TOKEN\"\n```\n\nIf the post is published, this also attempts to delete it from the social platform.\n\n### Retry a failed post\n\n```bash\ncurl -X POST https://socialcannon.app/api/v1/posts//retry \\\n -H \"Authorization: Bearer $TOKEN\"\n```\n\nResets the failed post and attempts to publish immediately. No body needed. If it fails again, the post returns to `failed` status with the new error.\n\n## Threads & Carousels\n\nCreate multi-part threads (Twitter reply chains or Instagram carousels):\n\n```bash\ncurl -X POST https://socialcannon.app/api/v1/posts/thread \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"accountId\": \"\",\n \"items\": [\n { \"content\": \"Thread part 1 — the hook\" },\n { \"content\": \"Thread part 2 — the detail\" },\n { \"content\": \"Thread part 3 — the CTA\", \"mediaUrls\": [\"https://...\"] }\n ],\n \"scheduledAt\": \"2026-04-15T10:00:00Z\",\n \"platformOptions\": { \"autoUtm\": true }\n }'\n```\n\nFields: `accountId` (required), `items` (required, min 2, max 25), `scheduledAt` (optional), `platformOptions` (optional). Instagram requires media on each item.\n\n## Media Upload\n\nUpload images/videos before creating posts. **Three-step direct-to-GCS flow** — bytes go straight to Google Cloud Storage via a signed URL, never through SocialCannon's server. This supports files up to **4GB**.\n\nAccepted types: `image/jpeg`, `image/png`, `image/gif`, `image/webp`, `video/mp4`, `video/quicktime`, `video/webm`.\n\n### Step 1 — Initialize upload\n\n```bash\ncurl -X POST https://socialcannon.app/api/v1/media/upload-init \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"filename\": \"photo.jpg\",\n \"contentType\": \"image/jpeg\",\n \"size\": 1048576\n }'\n```\n\nResponse:\n```json\n{\n \"success\": true,\n \"data\": {\n \"uploadUrl\": \"https://storage.googleapis.com/...?X-Goog-Signature=...\",\n \"publicUrl\": \"https://storage.googleapis.com//media//.jpg\",\n \"requiredHeaders\": {\n \"Content-Type\": \"image/jpeg\",\n \"x-goog-acl\": \"public-read\"\n }\n }\n}\n```\n\n`uploadUrl` is a V4 signed PUT URL valid for **15 minutes**. `size` must be the exact byte size of the file you're about to upload.\n\n### Step 2 — PUT the file to the signed URL\n\n```bash\ncurl -X PUT \"$UPLOAD_URL\" \\\n -H \"Content-Type: image/jpeg\" \\\n -H \"x-goog-acl: public-read\" \\\n --data-binary @photo.jpg\n```\n\nYou **must** send the exact headers returned in `requiredHeaders`. Do **not** send the `Authorization` header — the signed URL carries its own auth. A successful PUT returns HTTP 200 with an empty body.\n\n### Step 3 — Finalize\n\n```bash\ncurl -X POST https://socialcannon.app/api/v1/media/upload-complete \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{ \"publicUrl\": \"https://storage.googleapis.com//media//.jpg\" }'\n```\n\nPass the `publicUrl` you got from step 1 verbatim. The server verifies the object exists, stamps `customTime` (starting the 30-day retention window), and increments your upload quota.\n\nResponse: `{ \"success\": true, \"data\": { \"url\": \"https://...\", \"filename\": \"media//.jpg\", \"contentType\": \"image/jpeg\", \"size\": 1048576 } }`\n\nUse the returned `url` in the `mediaUrls` field when creating posts. Images up to 25 MB are normalized to JPEG (and may be resized) for platform compatibility, so the `contentType` and `size` in the finalize response can differ from what you uploaded — PNG/WebP transparency is not preserved. Videos and images larger than 25 MB are stored as-is.\n\n### Quota & errors\n\n- `403` on step 1 with `code` set → your tier has hit its upload quota. Inspect `limit` in the response body.\n- `404` on step 3 → the PUT didn't actually land. Retry from step 2.\n- `403` on step 3 → `publicUrl` doesn't belong to your client. Use the exact URL returned by step 1, do not construct it yourself.\n\n## Content Calendar\n\n### Get calendar view\n\nSee posts grouped by date with gap analysis:\n\n```bash\ncurl \"https://socialcannon.app/api/v1/calendar?startDate=2026-04-01&endDate=2026-04-30\" \\\n -H \"Authorization: Bearer $TOKEN\"\n```\n\nReturns `posts` and `summary` (totals by status/platform/day, plus `summary.gaps` = dates with no posts). Note the gap analysis is nested at `response.data.summary.gaps`.\n\nQuery params: `startDate` (required), `endDate` (required), `accountId`, `platform`\n\n### Find available slots\n\n```bash\ncurl \"https://socialcannon.app/api/v1/calendar/slots?startDate=2026-04-01&endDate=2026-04-07&slotDurationMinutes=60\" \\\n -H \"Authorization: Bearer $TOKEN\"\n```\n\nQuery params: `startDate` (required), `endDate` (required, max 14-day range), `slotDurationMinutes` (optional, 30-1440, default 60).\n\nReturns `{ slots[], totalSlots, availableSlots, occupiedSlots }`.\n\n## Analytics\n\n### Per-post analytics\n\nFetch live engagement metrics from the platform:\n\n```bash\ncurl https://socialcannon.app/api/v1/posts//analytics \\\n -H \"Authorization: Bearer $TOKEN\"\n```\n\nReturns: likes, comments, shares, impressions, reach, clicks, engagementRate, plus historical snapshots.\n\n> **Availability:** live per-post analytics is **not available for Facebook or LinkedIn** yet — both need a platform approval (Meta App Review / LinkedIn Community Management) we don't hold, so the endpoint returns `400` with `code: \"PLATFORM_UNSUPPORTED\"`. Twitter, Instagram, TikTok, and YouTube work. Check `GET /api/v1/platforms` → `capabilities.supportsAnalytics` for the authoritative per-platform list.\n\n### Aggregate analytics\n\n```bash\ncurl \"https://socialcannon.app/api/v1/analytics/summary?startDate=2026-04-01&endDate=2026-04-30\" \\\n -H \"Authorization: Bearer $TOKEN\"\n```\n\nReturns totals across all posts for the date range.\n\n### Bulk refresh analytics\n\n```bash\ncurl -X POST https://socialcannon.app/api/v1/analytics/refresh \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{ \"platform\": \"twitter\", \"limit\": 20 }'\n```\n\nFields: `postIds` (optional, array of up to 50 post IDs to refresh), `platform` (optional, filter), `limit` (optional, default 20, max 50). If `postIds` is provided, those specific posts are refreshed; otherwise recent published posts are refreshed.\n\n## Engagements (Comment Inbox)\n\n### List engagements\n\n```bash\ncurl \"https://socialcannon.app/api/v1/engagements?isRead=false&limit=20\" \\\n -H \"Authorization: Bearer $TOKEN\"\n```\n\nQuery params: `postId`, `isRead` (true/false), `limit`, `cursor`\n\n### Fetch engagements for a post\n\n```bash\ncurl \"https://socialcannon.app/api/v1/posts//engagements?cursor=\" \\\n -H \"Authorization: Bearer $TOKEN\"\n```\n\nFetches fresh comments from the platform and stores them. Supports `cursor` for pagination.\n\n> **Availability:** **not available for Facebook or LinkedIn** yet (same platform-approval gate as analytics) — returns `400` with `code: \"PLATFORM_UNSUPPORTED\"`. Replying to an engagement is likewise gated for those two. See `capabilities.supportsEngagements` / `supportsReply` in `GET /api/v1/platforms`.\n\n### Mark as read\n\n```bash\ncurl -X PATCH https://socialcannon.app/api/v1/engagements/ \\\n -H \"Authorization: Bearer $TOKEN\"\n```\n\nMarks the engagement as read. No request body needed — the endpoint auto-marks on PATCH.\n\n### Reply to an engagement\n\n```bash\ncurl -X POST https://socialcannon.app/api/v1/engagements//reply \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{ \"content\": \"Thanks for the feedback!\" }'\n```\n\nPosts the reply directly on the social platform.\n\n## AI Content Repurposing\n\nAdapt content for multiple platforms using AI. Two modes available:\n\n### Preview mode (default) — adapt and return variants for review:\n\n```bash\ncurl -X POST https://socialcannon.app/api/v1/posts/repurpose \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"sourceContent\": \"Your long-form content here...\",\n \"targetPlatforms\": [\"twitter\", \"facebook\", \"tiktok\"],\n \"mode\": \"preview\",\n \"tone\": \"professional\"\n }'\n```\n\nReturns `{ \"variants\": [{ \"platform\", \"content\", \"validation\", \"characterCount\" }], \"allValid\" }`.\n\n### Post mode — adapt and publish in one call:\n\n```bash\ncurl -X POST https://socialcannon.app/api/v1/posts/repurpose \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"sourceContent\": \"Your content here...\",\n \"targetPlatforms\": [\"twitter\", \"facebook\"],\n \"mode\": \"post\",\n \"accountIds\": { \"twitter\": \"acc_123\", \"facebook\": \"acc_456\" },\n \"mediaUrls\": { \"twitter\": [\"https://example.com/video.mp4\"] },\n \"appendContent\": { \"twitter\": \"Links or extra text for Twitter only\" },\n \"appendToAll\": \"Text appended to all platforms\"\n }'\n```\n\nReturns `{ \"results\": [{ \"platform\", \"success\", \"postUrl?\", \"error?\" }] }`.\n\nAll content is humanized automatically to remove AI writing patterns. Trusted clients bypass tier limits.\n\n## A/B Testing (Pro)\n\n> **Not available for TikTok.** A/B-test variants carry only content + media, so they can't set the per-post privacy level TikTok requires. A TikTok account is rejected with `400` and `code: \"PLATFORM_UNSUPPORTED\"` — publish individual posts to TikTok instead.\n\n> **Not available for LinkedIn or Facebook.** Both are publish-only for analytics right now (LinkedIn needs Community Management approval; Facebook needs Meta App Review for `pages_read_engagement`), so a winner could never be determined. Those accounts are rejected with `400` and `code: \"PLATFORM_UNSUPPORTED\"` — publish individual posts instead.\n\n### Create a test\n\n```bash\ncurl -X POST https://socialcannon.app/api/v1/ab-tests \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"accountId\": \"\",\n \"name\": \"CTA test\",\n \"variants\": [\n { \"content\": \"Check out our new feature!\", \"mediaUrls\": [\"https://...\"] },\n { \"content\": \"You won'\\''t believe this new feature...\" }\n ],\n \"metric\": \"engagementRate\",\n \"minDurationHours\": 24,\n \"scheduledAt\": \"2026-04-20T10:00:00Z\"\n }'\n```\n\n**Publish behavior matches `POST /api/v1/posts`:**\n- **Omit `scheduledAt`** → all variants publish **immediately** to the platform via the social adapter\n- **Provide `scheduledAt`** → all variants are **scheduled** for that time (must be within 30 days; cron publishes them hourly)\n\nEach variant is a separate post record. Auto-completes after `minDurationHours` and the winner is determined by the chosen metric. Per-variant `mediaUrls` is optional.\n\n**Partial failure semantics:** if ANY variant fails to publish during immediate mode, the endpoint returns **HTTP 502** and the failed variants are marked with `status: 'failed'`. The A/B test record is still created, but the winner comparison at completion only considers successfully published variants. Inspect each variant's post status before relying on test results.\n\n### Get test results\n\n```bash\ncurl https://socialcannon.app/api/v1/ab-tests/ \\\n -H \"Authorization: Bearer $TOKEN\"\n```\n\nReturns per-variant metrics, current winner, and confidence score.\n\n### List tests\n\n```bash\ncurl \"https://socialcannon.app/api/v1/ab-tests?status=active\" \\\n -H \"Authorization: Bearer $TOKEN\"\n```\n\n### Force-complete a test\n\n```bash\ncurl -X POST https://socialcannon.app/api/v1/ab-tests//complete \\\n -H \"Authorization: Bearer $TOKEN\"\n```\n\n## Timing Suggestions (Pro)\n\n### Get recommended posting times\n\n```bash\ncurl \"https://socialcannon.app/api/v1/accounts//timing?timezone=UTC-5\" \\\n -H \"Authorization: Bearer $TOKEN\"\n```\n\nReturns top 5 time slots ranked by average engagement rate with confidence scores.\n\n### Find the single best available slot\n\nCombines engagement data with calendar availability. Unlike the other two timing endpoints, this one is available on **all tiers** (including Free):\n\n```bash\ncurl \"https://socialcannon.app/api/v1/timing/optimal-slot?accountId=&timezone=UTC-5\" \\\n -H \"Authorization: Bearer $TOKEN\"\n```\n\nReturns the next open slot ranked by historical performance.\n\n### Auto-schedule multiple posts\n\nDistribute posts across optimal time slots for the next 7 days:\n\n```bash\ncurl -X POST https://socialcannon.app/api/v1/posts/auto-schedule \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"accountId\": \"\",\n \"posts\": [\n { \"content\": \"Post 1 text\" },\n { \"content\": \"Post 2 text\", \"mediaUrls\": [\"https://...\"] },\n { \"content\": \"Post 3 text\" }\n ],\n \"timezone\": \"UTC-5\"\n }'\n```\n\nMax 20 posts per request. Each post gets a unique slot. Returns `{ scheduled: [...], unscheduled: [...], summary: {...} }`.\n\n## UTM Link Tracking\n\nGenerate UTM-tagged URLs:\n\n```bash\ncurl -X POST https://socialcannon.app/api/v1/links/generate \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"url\": \"https://example.com/product\",\n \"platform\": \"twitter\",\n \"campaign\": \"spring-launch\",\n \"content\": \"hero-cta\",\n \"postId\": \"\",\n \"save\": true\n }'\n```\n\nFields: `url` (required), `platform` (optional — sets `utm_source`), `campaign` (optional — `utm_campaign`), `content` (optional — `utm_content`), `term` (optional — `utm_term`), `postId` (optional — link to a post), `save` (optional, default true — persist to tracked_links).\n\n### List tracked links\n\n```bash\ncurl \"https://socialcannon.app/api/v1/links?postId=&platform=twitter&limit=20&cursor=\" \\\n -H \"Authorization: Bearer $TOKEN\"\n```\n\nQuery params: `postId`, `platform`, `limit`, `cursor` — all optional.\n\n## Platforms\n\nList supported platforms and their capabilities (public, no auth required):\n\n```bash\ncurl https://socialcannon.app/api/v1/platforms\n```\n\n## Platform-Specific Notes\n\n### Twitter/X\n- 280 char limit. Up to 4 images. Threads via reply chains.\n\n### Facebook\n- 63,206 char limit. Supports native scheduling. Page-level tokens.\n- **Reels**: Set `platformOptions.mediaType` to `\"reel\"`. Video must be MP4/MOV, vertical (9:16). Without this, videos post as regular video posts.\n- **Stories**: Set `platformOptions.mediaType` to `\"story\"`. Supports one image or video. Ephemeral (24h).\n\n```bash\ncurl -X POST https://socialcannon.app/api/v1/posts \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"accountId\": \"\",\n \"content\": \"Check out this tutorial!\",\n \"mediaUrls\": [\"https://example.com/video.mp4\"],\n \"platformOptions\": {\n \"mediaType\": \"reel\"\n }\n }'\n```\n\n### Instagram\n- Requires media (no text-only). Max 10 carousel items. No API deletion.\n- **Stories**: Set `platformOptions.mediaType` to `\"story\"`. One image or video.\n- **Reels**: Set `platformOptions.mediaType` to `\"reel\"`. Vertical 9:16 video.\n\n### TikTok\n- Requires media — no text-only posts. Supports video, photo carousel (up to 35 images), and Stories.\n- **`platformOptions.privacyLevel` is REQUIRED** on every TikTok post — there is no default. Omitting it returns `400` with code `TIKTOK_PRIVACY_REQUIRED`. Use a value from the creator-info endpoint's `privacyLevelOptions` (e.g. `PUBLIC_TO_EVERYONE`, `MUTUAL_FOLLOW_FRIENDS`, `FOLLOWER_OF_CREATOR`, `SELF_ONLY`).\n- **Interaction toggles** (optional, default = allowed): `disableComment`, `disableDuet`, `disableStitch` (booleans). Duet/Stitch apply to video only. If the creator-info endpoint reports an interaction is disabled account-side (`commentDisabled` / `duetDisabled` / `stitchDisabled`), set the matching `disable*` to `true` (the server force-disables it regardless).\n- **Commercial content disclosure** (optional): set `commercialContent: true` if the post promotes a brand, product, or service, then set `brandOrganic: true` (your own brand) and/or `brandedContent: true` (paid/third-party partnership). If `brandedContent` is true, `privacyLevel` cannot be `SELF_ONLY`.\n- **Stories**: Set `platformOptions.mediaType` to `\"story\"`. One video. Ephemeral (24h).\n- Video publish uses an async poll model. No API deletion support.\n\n**Get a TikTok account's posting capabilities** — call this before composing a TikTok post; it returns the allowed privacy levels and which interactions are disabled:\n\n```bash\ncurl https://socialcannon.app/api/v1/accounts//tiktok/creator-info \\\n -H \"Authorization: Bearer $TOKEN\"\n```\n\nReturns `{ creatorNickname, creatorUsername, creatorAvatarUrl, privacyLevelOptions, commentDisabled, duetDisabled, stitchDisabled, maxVideoPostDurationSec }`. Choose `privacyLevel` from `privacyLevelOptions` and respect the `*Disabled` flags.\n\n**Example — publish a public TikTok video with comments on:**\n```bash\ncurl -X POST https://socialcannon.app/api/v1/posts \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"accountId\": \"\",\n \"content\": \"New track out now!\",\n \"mediaUrls\": [\"https://example.com/clip.mp4\"],\n \"platformOptions\": {\n \"privacyLevel\": \"PUBLIC_TO_EVERYONE\",\n \"disableComment\": false,\n \"disableDuet\": false,\n \"disableStitch\": false\n }\n }'\n```\n\n### YouTube\n- Supports regular videos, Shorts, and Community posts. Native scheduling support.\n- **Shorts**: Set `platformOptions.mediaType` to `\"short\"`. Vertical video ≤60s.\n- **Community posts**: Set `platformOptions.mediaType` to `\"community\"`. Text/image post to channel's Community tab.\n- Scheduled videos are uploaded as private with a `publishAt` timestamp.\n\n### LinkedIn\n- 3,000 char limit. Supports text-only and images (single or multi-image). Threads combine all items into one post.\n- Scheduling works via SocialCannon (LinkedIn has no native scheduling).\n- **No analytics, engagement inbox, or replies** for LinkedIn.\n\n## Rate Limits\n\n- Free tier: 30 requests/minute\n- Pro tier: 300 requests/minute\n- Agency tier: 600 requests/minute\n- Enterprise tier: 1200 requests/minute (default; negotiable)\n- Returns `429` with `Retry-After` header when exceeded\n\n## Subscription Tiers\n\nFour tiers. Twitter/X is the only platform with a per-post API cost passed through, so every tier carries an X-write quota.\n\n### Free — $0\n- 2 connected accounts\n- 10 posts per billing period\n- **1 Twitter/X post per billing period** (a taster — thread items count individually)\n- 2 scheduled posts at a time\n- 3 media uploads per billing period\n- 2-item threads, 5 tracked links\n- All 6 platforms: Twitter/X, Facebook, Instagram, LinkedIn, TikTok, YouTube\n- No analytics, no engagement replies, no A/B testing, no timing suggestions\n- 30 API requests/minute\n\n### Pro — $15/month\n- Unlimited accounts, posts, scheduling\n- **50 Twitter/X posts per billing period**\n- Analytics with history, 90-day calendar\n- 25-item threads, unlimited tracked links\n- A/B testing (5 concurrent, 4 variants)\n- Engagement replies, timing suggestions\n- 300 API requests/minute\n\n### Agency — $49/month\n- Everything in Pro\n- **250 Twitter/X posts per billing period**\n- A/B testing (20 concurrent, 6 variants)\n- 365-day calendar range\n- Priority support\n- 600 API requests/minute\n\n### Enterprise — custom contract\n- Custom Twitter/X quota, custom rate limits, SLA, dedicated support\n- Contact `sales@socialcannon.app`\n\n### Hitting a cap\n\nAny tier exceeding its `maxTwitterPostsPerPeriod` cap returns:\n```json\n{\n \"success\": false,\n \"error\": \"Twitter/X post limit reached (50/50). Upgrade to Agency for 250 Twitter/X posts per month.\",\n \"code\": \"LIMIT_EXCEEDED\",\n \"limit\": { \"type\": \"twitter_posts_per_period\", \"current\": 50, \"max\": 50, \"tier\": \"pro\" }\n}\n```\nHTTP `403`. Resets at the start of the next billing period. The upgrade hint is tier-aware — Free is pointed to Pro, Pro to Agency, and Agency/Enterprise to `sales@socialcannon.app` (no tier is \"unlimited\" for Twitter/X).\n\n## Support\n\nIf you run into issues with the API, account connections, or integration setup, contact **support@socialcannon.app**.\n\n## Tips for Agents\n\n1. Always list accounts first to get valid `accountId` values before creating posts.\n2. Use the calendar endpoint to check for gaps before suggesting new posts.\n3. For Instagram and TikTok, always include at least one media URL — text-only posts will fail.\n4. Use `autoUtm: true` in `platformOptions` to automatically tag URLs in posts.\n5. Check analytics after 24+ hours for meaningful engagement data.\n6. When repurposing content, review the returned `validation` field — if `valid` is false, adjust the content before publishing.\n7. Use `scheduledAt: \"optimal\"` to let SocialCannon pick the best posting time automatically (Pro).\n8. For batch scheduling, use the auto-schedule endpoint instead of creating posts one by one.\n9. For YouTube, set `mediaType` to `\"short\"` for Shorts or `\"community\"` for Community tab posts.\n10. For TikTok, call `GET /api/v1/accounts/{id}/tiktok/creator-info` first — it returns the allowed `privacyLevelOptions` (pass one as `platformOptions.privacyLevel`; it is required) and which of Comment/Duet/Stitch are disabled (never enable a disabled one).\n\nFile v1.10.0:_meta.json\n\n{\n \"ownerId\": \"kn75vx9q7acz869fn4vdd2cwx1845nrx\",\n \"slug\": \"socialcannon\",\n \"version\": \"1.10.0\",\n \"publishedAt\": 1784363450640\n}\n\nFile v1.10.0:CLAUDE.md\n\n\n\n\n\nFile v1.10.0:skill-card.md\n\n## Description:
\nPublish, schedule, and manage social media posts across Twitter/X, Facebook, Instagram, LinkedIn, TikTok, and YouTube with content calendars, gap analysis, A/B testing, engagement inbox workflows, AI content repurposing, timing suggestions, auto-scheduling, and UTM tracking.
\n\nThis skill is ready for commercial/non-commercial use.
\n\n## Publisher:
\n[miprinia](https://clawhub.ai/user/miprinia)
\n\n### License/Terms of Use:
\nMIT-0
\n\n\n## Use Case:
\nDevelopers, marketers, and social media operators use this skill to guide agents through SocialCannon REST API or MCP setup for publishing, scheduling, analyzing, and managing posts across connected social accounts.
\n\n### Deployment Geography for Use:
\nGlobal
\n\n## Known Risks and Mitigations:
\nRisk: Live social account actions can publish, reply, retry, delete, disconnect, or repurpose content in ways that may be irreversible.
\nMitigation: Require explicit approval before publishing, replying, deleting, retrying posts, disconnecting accounts, or using repurpose post mode.
\nRisk: Client secret exposure could allow unauthorized API access to connected social accounts.
\nMitigation: Store SOCIALCANNON_CLIENT_SECRET only in environment configuration and do not paste it into chats or generated content.
\nRisk: Immediate A/B tests and repurpose post mode can publish content without a separate scheduling delay.
\nMitigation: Prefer draft, scheduled, and preview workflows first, and review generated variants and validation results before allowing live publication.
\n\n\n## Reference(s):
\n- [SocialCannon homepage](https://socialcannon.app)
\n- [Socialcannon ClawHub listing](https://clawhub.ai/miprinia/skills/socialcannon)
\n- [@socialcannon/mcp package](https://www.npmjs.com/package/@socialcannon/mcp)
\n\n\n## Skill Output:
\n**Output Type(s):** [text, markdown, shell commands, configuration, guidance]
\n**Output Format:** [Markdown with curl commands, JSON examples, and configuration snippets]
\n**Output Parameters:** [1D]
\n**Other Properties Related to Output:** [Requires curl and SOCIALCANNON_CLIENT_ID / SOCIALCANNON_CLIENT_SECRET environment variables; actions operate on live connected social accounts.]
\n\n## Skill Version(s):
\n1.10.0 (source: SKILL.md frontmatter and server release evidence)
\n\n## Ethical Considerations:
\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.
\n\nArchive v1.9.6: 4 files, 12091 bytes\n\nFiles: CLAUDE.md (43b), skill-card.md (2929b), SKILL.md (30478b), _meta.json (131b)\n\nFile v1.9.6:SKILL.md\n\n---\nname: socialcannon\ndescription: >\n Publish, schedule, and manage social media posts across Twitter/X, Facebook,\n Instagram, LinkedIn, TikTok, and YouTube. Content calendar with gap analysis,\n A/B testing, engagement inbox, AI content repurposing, optimal timing\n suggestions, auto-scheduling, and UTM tracking.\nversion: 1.9.6\nmetadata:\n openclaw:\n requires:\n env:\n - SOCIALCANNON_CLIENT_ID\n - SOCIALCANNON_CLIENT_SECRET\n bins:\n - curl\n primaryEnv: SOCIALCANNON_CLIENT_ID\n emoji: \"\\U0001F4E3\"\n homepage: https://socialcannon.app\n---\n\n# SocialCannon\n\nSocial media publishing API. Publish to Twitter/X, Facebook, Instagram, LinkedIn, TikTok, and YouTube from one API with scheduling, analytics, A/B testing, and AI-powered features.\n\n**Base URL:** `https://socialcannon.app`\n\n## Safety: destructive & irreversible actions\n\nSeveral operations act on **live social accounts** and cannot be undone. In an agent workflow, get **explicit human approval before** any of these:\n\n- **Publish** or **immediate A/B test** (a post with no `scheduledAt`) — goes live at once.\n- **Reply to an engagement** — posts a public reply from the connected account.\n- **Retry** a post — re-attempts a real publish.\n- **Delete a post** — removes it here **and** attempts deletion on the platform.\n- **Disconnect an account** — breaks the integration; reconnecting requires the OAuth flow again.\n- **Repurpose in `post` mode** — adapts **and publishes** to the target platforms.\n\nSafer defaults for agents: prefer read-only listing and `draft`/`scheduled` posts, and use `preview`-mode repurpose before `post` mode. Keep your Client Secret in an environment variable — never paste it into a chat.\n\n## Getting Started\n\nBefore making API calls, you need credentials and at least one connected social account.\n\n### 1. Get your API credentials\n\nSign up at [socialcannon.app](https://socialcannon.app) (Google or GitHub sign-in, free tier included — no card required). **Your Client Secret is shown once, right after signup — copy it then.** If you miss it, open **Settings → API Keys** and click **Generate API Secret**. Your **Client ID** is always available on that page. Use these as `SOCIALCANNON_CLIENT_ID` and `SOCIALCANNON_CLIENT_SECRET`.\n\n### 2. Connect social accounts\n\nSocial accounts are connected via OAuth in the browser. Open the connect URL for each platform you want to use — you'll authorize SocialCannon and get redirected back:\n\n| Platform | Connect URL |\n|----------|-------------|\n| Twitter/X | `https://socialcannon.app/api/connect/twitter?client_id=YOUR_CLIENT_ID` |\n| Facebook | `https://socialcannon.app/api/connect/facebook?client_id=YOUR_CLIENT_ID` |\n| Instagram | `https://socialcannon.app/api/connect/instagram?client_id=YOUR_CLIENT_ID` |\n| LinkedIn | `https://socialcannon.app/api/connect/linkedin?client_id=YOUR_CLIENT_ID` |\n| TikTok | `https://socialcannon.app/api/connect/tiktok?client_id=YOUR_CLIENT_ID` |\n| YouTube | `https://socialcannon.app/api/connect/youtube?client_id=YOUR_CLIENT_ID` |\n\nYou can also connect accounts from the dashboard at **Settings → Accounts**. Instagram uses Facebook's OAuth flow — make sure you select the Facebook Page linked to your Instagram Business account.\n\n### 3. Get an API token and start posting\n\nOnce you have credentials and at least one connected account, authenticate and create your first post:\n\n```bash\n# Get a token\nTOKEN=$(curl -s -X POST https://socialcannon.app/api/v1/auth/token \\\n -H \"Content-Type: application/json\" \\\n -d \"{\\\"grant_type\\\": \\\"client_credentials\\\", \\\"client_id\\\": \\\"$SOCIALCANNON_CLIENT_ID\\\", \\\"client_secret\\\": \\\"$SOCIALCANNON_CLIENT_SECRET\\\"}\" \\\n | jq -r '.data.access_token')\n\n# List your connected accounts\ncurl -s https://socialcannon.app/api/v1/accounts \\\n -H \"Authorization: Bearer $TOKEN\" | jq '.data'\n\n# Publish a post (replace with an ID from the list above)\ncurl -X POST https://socialcannon.app/api/v1/posts \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"accountId\": \"\", \"content\": \"Hello from SocialCannon!\"}'\n```\n\n## Use via MCP (Hermes, Claude Desktop, OpenClaw)\n\nInstead of raw HTTP, you can expose SocialCannon's 23 tools to any MCP-compatible agent with the [`@socialcannon/mcp`](https://www.npmjs.com/package/@socialcannon/mcp) package. Use the same `SOCIALCANNON_CLIENT_ID` / `SOCIALCANNON_CLIENT_SECRET` from your dashboard.\n\n**Hermes Agent** — add to `~/.hermes/config.yaml`:\n\n```yaml\nmcp_servers:\n socialcannon:\n command: \"npx\"\n args: [\"-y\", \"@socialcannon/mcp\"]\n env:\n SOCIALCANNON_CLIENT_ID: \"your-client-id\"\n SOCIALCANNON_CLIENT_SECRET: \"your-client-secret\"\n```\n\n**Claude Desktop** — add an entry under `mcpServers` in `claude_desktop_config.json` with the same `command`/`args`/`env`.\n\nThe REST API documented below remains fully available; MCP is an optional convenience layer over the same endpoints.\n\n## Authentication\n\nAll requests require a JWT Bearer token. Get one by exchanging your client credentials:\n\n```bash\ncurl -X POST https://socialcannon.app/api/v1/auth/token \\\n -H \"Content-Type: application/json\" \\\n -d \"{\n \\\"grant_type\\\": \\\"client_credentials\\\",\n \\\"client_id\\\": \\\"$SOCIALCANNON_CLIENT_ID\\\",\n \\\"client_secret\\\": \\\"$SOCIALCANNON_CLIENT_SECRET\\\"\n }\"\n```\n\nResponse:\n```json\n{\n \"success\": true,\n \"data\": {\n \"access_token\": \"\",\n \"token_type\": \"Bearer\",\n \"expires_in\": 3600,\n \"scope\": \"posts:read posts:write ...\"\n }\n}\n```\n\nUse `response.data.access_token` as a Bearer token in all subsequent requests. Tokens expire after 1 hour — request a new one when you get a 401.\n\n**All requests below require this header:**\n```\nAuthorization: Bearer \nContent-Type: application/json\n```\n\n## Response Format\n\n**IMPORTANT: ALL responses are wrapped in a standard envelope.** This includes the token endpoint.\n\n- Success: `{ \"success\": true, \"data\": { ... } }`\n- Error: `{ \"success\": false, \"error\": \"message\", \"code\": \"ERROR_CODE\" }`\n\nWhen extracting data from any response, always read from `response.data`, not from the response root. For example, the access token is at `response.data.access_token` — not `response.access_token`.\n\n## Accounts\n\nAccounts represent social media profiles connected via OAuth (see Getting Started above). You need at least one connected account before you can create posts.\n\n### List connected accounts\n\n```bash\ncurl https://socialcannon.app/api/v1/accounts \\\n -H \"Authorization: Bearer $TOKEN\"\n```\n\nReturns all connected social accounts with their platform, username, and status. Use the account `id` field when creating posts. Filter by platform with `?platform=twitter`.\n\n### Get a single account\n\n```bash\ncurl https://socialcannon.app/api/v1/accounts/ \\\n -H \"Authorization: Bearer $TOKEN\"\n```\n\n### Disconnect an account\n\n```bash\ncurl -X DELETE https://socialcannon.app/api/v1/accounts/ \\\n -H \"Authorization: Bearer $TOKEN\"\n```\n\n## Posts\n\n### Create a post\n\nPublish immediately (omit `scheduledAt`) or schedule for later:\n\n```bash\ncurl -X POST https://socialcannon.app/api/v1/posts \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"accountId\": \"\",\n \"content\": \"Your post text here\",\n \"mediaUrls\": [\"https://example.com/image.jpg\"],\n \"scheduledAt\": \"2026-04-15T10:00:00Z\",\n \"platformOptions\": {\n \"autoUtm\": true\n }\n }'\n```\n\nFields:\n- `accountId` (required) — ID from the accounts list\n- `content` (required) — post text\n- `mediaUrls` (optional) — array of public image/video URLs\n- `scheduledAt` (optional) — ISO 8601 datetime, `\"optimal\"` (auto-pick best time based on engagement data, Pro), or omit for immediate publish\n- `platformOptions.autoUtm` (optional) — auto-tag URLs with UTM parameters\n- `platformOptions.mediaType` (optional) — controls content type:\n - `\"reel\"` — Facebook/Instagram Reel (vertical 9:16 video)\n - `\"story\"` — Facebook/Instagram/TikTok Story (24h ephemeral)\n - `\"short\"` — YouTube Short (vertical video ≤60s)\n - `\"community\"` — YouTube Community post (text/image)\n- `platformOptions` **TikTok fields** — TikTok posts require `privacyLevel` and support `disableComment` / `disableDuet` / `disableStitch`, `commercialContent`, `brandOrganic`, `brandedContent`. See the [TikTok](#tiktok) section under Platform-Specific Notes.\n\n### List posts\n\n```bash\ncurl \"https://socialcannon.app/api/v1/posts?status=published&platform=twitter&limit=20\" \\\n -H \"Authorization: Bearer $TOKEN\"\n```\n\nQuery params: `status` (draft/scheduled/published/failed), `platform`, `accountId`, `limit`, `cursor`\n\n### Get a single post\n\n```bash\ncurl https://socialcannon.app/api/v1/posts/ \\\n -H \"Authorization: Bearer $TOKEN\"\n```\n\n### Update a draft or scheduled post\n\n```bash\ncurl -X PATCH https://socialcannon.app/api/v1/posts/ \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"content\": \"Updated text\",\n \"scheduledAt\": \"2026-04-16T14:00:00Z\",\n \"platformOptions\": { \"autoUtm\": true }\n }'\n```\n\nFields: `content`, `scheduledAt`, `platformOptions` — all optional.\n\n### Delete a post\n\n```bash\ncurl -X DELETE https://socialcannon.app/api/v1/posts/ \\\n -H \"Authorization: Bearer $TOKEN\"\n```\n\nIf the post is published, this also attempts to delete it from the social platform.\n\n### Retry a failed post\n\n```bash\ncurl -X POST https://socialcannon.app/api/v1/posts//retry \\\n -H \"Authorization: Bearer $TOKEN\"\n```\n\nResets the failed post and attempts to publish immediately. No body needed. If it fails again, the post returns to `failed` status with the new error.\n\n## Threads & Carousels\n\nCreate multi-part threads (Twitter reply chains or Instagram carousels):\n\n```bash\ncurl -X POST https://socialcannon.app/api/v1/posts/thread \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"accountId\": \"\",\n \"items\": [\n { \"content\": \"Thread part 1 — the hook\" },\n { \"content\": \"Thread part 2 — the detail\" },\n { \"content\": \"Thread part 3 — the CTA\", \"mediaUrls\": [\"https://...\"] }\n ],\n \"scheduledAt\": \"2026-04-15T10:00:00Z\",\n \"platformOptions\": { \"autoUtm\": true }\n }'\n```\n\nFields: `accountId` (required), `items` (required, min 2, max 25), `scheduledAt` (optional), `platformOptions` (optional). Instagram requires media on each item.\n\n## Media Upload\n\nUpload images/videos before creating posts. **Three-step direct-to-GCS flow** — bytes go straight to Google Cloud Storage via a signed URL, never through SocialCannon's server. This supports files up to **4GB**.\n\nAccepted types: `image/jpeg`, `image/png`, `image/gif`, `image/webp`, `video/mp4`, `video/quicktime`, `video/webm`.\n\n### Step 1 — Initialize upload\n\n```bash\ncurl -X POST https://socialcannon.app/api/v1/media/upload-init \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"filename\": \"photo.jpg\",\n \"contentType\": \"image/jpeg\",\n \"size\": 1048576\n }'\n```\n\nResponse:\n```json\n{\n \"success\": true,\n \"data\": {\n \"uploadUrl\": \"https://storage.googleapis.com/...?X-Goog-Signature=...\",\n \"publicUrl\": \"https://storage.googleapis.com//media//.jpg\",\n \"requiredHeaders\": {\n \"Content-Type\": \"image/jpeg\",\n \"x-goog-acl\": \"public-read\"\n }\n }\n}\n```\n\n`uploadUrl` is a V4 signed PUT URL valid for **15 minutes**. `size` must be the exact byte size of the file you're about to upload.\n\n### Step 2 — PUT the file to the signed URL\n\n```bash\ncurl -X PUT \"$UPLOAD_URL\" \\\n -H \"Content-Type: image/jpeg\" \\\n -H \"x-goog-acl: public-read\" \\\n --data-binary @photo.jpg\n```\n\nYou **must** send the exact headers returned in `requiredHeaders`. Do **not** send the `Authorization` header — the signed URL carries its own auth. A successful PUT returns HTTP 200 with an empty body.\n\n### Step 3 — Finalize\n\n```bash\ncurl -X POST https://socialcannon.app/api/v1/media/upload-complete \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{ \"publicUrl\": \"https://storage.googleapis.com//media//.jpg\" }'\n```\n\nPass the `publicUrl` you got from step 1 verbatim. The server verifies the object exists, stamps `customTime` (starting the 30-day retention window), and increments your upload quota.\n\nResponse: `{ \"success\": true, \"data\": { \"url\": \"https://...\", \"filename\": \"media//.jpg\", \"contentType\": \"image/jpeg\", \"size\": 1048576 } }`\n\nUse the returned `url` in the `mediaUrls` field when creating posts. Images up to 25 MB are normalized to JPEG (and may be resized) for platform compatibility, so the `contentType` and `size` in the finalize response can differ from what you uploaded — PNG/WebP transparency is not preserved. Videos and images larger than 25 MB are stored as-is.\n\n### Quota & errors\n\n- `403` on step 1 with `code` set → your tier has hit its upload quota. Inspect `limit` in the response body.\n- `404` on step 3 → the PUT didn't actually land. Retry from step 2.\n- `403` on step 3 → `publicUrl` doesn't belong to your client. Use the exact URL returned by step 1, do not construct it yourself.\n\n## Content Calendar\n\n### Get calendar view\n\nSee posts grouped by date with gap analysis:\n\n```bash\ncurl \"https://socialcannon.app/api/v1/calendar?startDate=2026-04-01&endDate=2026-04-30\" \\\n -H \"Authorization: Bearer $TOKEN\"\n```\n\nReturns `posts` and `summary` (totals by status/platform/day, plus `summary.gaps` = dates with no posts). Note the gap analysis is nested at `response.data.summary.gaps`.\n\nQuery params: `startDate` (required), `endDate` (required), `accountId`, `platform`\n\n### Find available slots\n\n```bash\ncurl \"https://socialcannon.app/api/v1/calendar/slots?startDate=2026-04-01&endDate=2026-04-07&slotDurationMinutes=60\" \\\n -H \"Authorization: Bearer $TOKEN\"\n```\n\nQuery params: `startDate` (required), `endDate` (required, max 14-day range), `slotDurationMinutes` (optional, 30-1440, default 60).\n\nReturns `{ slots[], totalSlots, availableSlots, occupiedSlots }`.\n\n## Analytics\n\n### Per-post analytics\n\nFetch live engagement metrics from the platform:\n\n```bash\ncurl https://socialcannon.app/api/v1/posts//analytics \\\n -H \"Authorization: Bearer $TOKEN\"\n```\n\nReturns: likes, comments, shares, impressions, reach, clicks, engagementRate, plus historical snapshots.\n\n> **Availability:** live per-post analytics is **not available for Facebook or LinkedIn** yet — both need a platform approval (Meta App Review / LinkedIn Community Management) we don't hold, so the endpoint returns `400` with `code: \"PLATFORM_UNSUPPORTED\"`. Twitter, Instagram, TikTok, and YouTube work. Check `GET /api/v1/platforms` → `capabilities.supportsAnalytics` for the authoritative per-platform list.\n\n### Aggregate analytics\n\n```bash\ncurl \"https://socialcannon.app/api/v1/analytics/summary?startDate=2026-04-01&endDate=2026-04-30\" \\\n -H \"Authorization: Bearer $TOKEN\"\n```\n\nReturns totals across all posts for the date range.\n\n### Bulk refresh analytics\n\n```bash\ncurl -X POST https://socialcannon.app/api/v1/analytics/refresh \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{ \"platform\": \"twitter\", \"limit\": 20 }'\n```\n\nFields: `postIds` (optional, array of up to 50 post IDs to refresh), `platform` (optional, filter), `limit` (optional, default 20, max 50). If `postIds` is provided, those specific posts are refreshed; otherwise recent published posts are refreshed.\n\n## Engagements (Comment Inbox)\n\n### List engagements\n\n```bash\ncurl \"https://socialcannon.app/api/v1/engagements?isRead=false&limit=20\" \\\n -H \"Authorization: Bearer $TOKEN\"\n```\n\nQuery params: `postId`, `isRead` (true/false), `limit`, `cursor`\n\n### Fetch engagements for a post\n\n```bash\ncurl \"https://socialcannon.app/api/v1/posts//engagements?cursor=\" \\\n -H \"Authorization: Bearer $TOKEN\"\n```\n\nFetches fresh comments from the platform and stores them. Supports `cursor` for pagination.\n\n> **Availability:** **not available for Facebook or LinkedIn** yet (same platform-approval gate as analytics) — returns `400` with `code: \"PLATFORM_UNSUPPORTED\"`. Replying to an engagement is likewise gated for those two. See `capabilities.supportsEngagements` / `supportsReply` in `GET /api/v1/platforms`.\n\n### Mark as read\n\n```bash\ncurl -X PATCH https://socialcannon.app/api/v1/engagements/ \\\n -H \"Authorization: Bearer $TOKEN\"\n```\n\nMarks the engagement as read. No request body needed — the endpoint auto-marks on PATCH.\n\n### Reply to an engagement\n\n```bash\ncurl -X POST https://socialcannon.app/api/v1/engagements//reply \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{ \"content\": \"Thanks for the feedback!\" }'\n```\n\nPosts the reply directly on the social platform.\n\n## AI Content Repurposing\n\nAdapt content for multiple platforms using AI. Two modes available:\n\n### Preview mode (default) — adapt and return variants for review:\n\n```bash\ncurl -X POST https://socialcannon.app/api/v1/posts/repurpose \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"sourceContent\": \"Your long-form content here...\",\n \"targetPlatforms\": [\"twitter\", \"facebook\", \"tiktok\"],\n \"mode\": \"preview\",\n \"tone\": \"professional\"\n }'\n```\n\nReturns `{ \"variants\": [{ \"platform\", \"content\", \"validation\", \"characterCount\" }], \"allValid\" }`.\n\n### Post mode — adapt and publish in one call:\n\n```bash\ncurl -X POST https://socialcannon.app/api/v1/posts/repurpose \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"sourceContent\": \"Your content here...\",\n \"targetPlatforms\": [\"twitter\", \"facebook\"],\n \"mode\": \"post\",\n \"accountIds\": { \"twitter\": \"acc_123\", \"facebook\": \"acc_456\" },\n \"mediaUrls\": { \"twitter\": [\"https://example.com/video.mp4\"] },\n \"appendContent\": { \"twitter\": \"Links or extra text for Twitter only\" },\n \"appendToAll\": \"Text appended to all platforms\"\n }'\n```\n\nReturns `{ \"results\": [{ \"platform\", \"success\", \"postUrl?\", \"error?\" }] }`.\n\nAll content is humanized automatically to remove AI writing patterns. Trusted clients bypass tier limits.\n\n## A/B Testing (Pro)\n\n> **Not available for TikTok.** A/B-test variants carry only content + media, so they can't set the per-post privacy level TikTok requires. A TikTok account is rejected with `400` and `code: \"PLATFORM_UNSUPPORTED\"` — publish individual posts to TikTok instead.\n\n> **Not available for LinkedIn or Facebook.** Both are publish-only for analytics right now (LinkedIn needs Community Management approval; Facebook needs Meta App Review for `pages_read_engagement`), so a winner could never be determined. Those accounts are rejected with `400` and `code: \"PLATFORM_UNSUPPORTED\"` — publish individual posts instead.\n\n### Create a test\n\n```bash\ncurl -X POST https://socialcannon.app/api/v1/ab-tests \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"accountId\": \"\",\n \"name\": \"CTA test\",\n \"variants\": [\n { \"content\": \"Check out our new feature!\", \"mediaUrls\": [\"https://...\"] },\n { \"content\": \"You won'\\''t believe this new feature...\" }\n ],\n \"metric\": \"engagementRate\",\n \"minDurationHours\": 24,\n \"scheduledAt\": \"2026-04-20T10:00:00Z\"\n }'\n```\n\n**Publish behavior matches `POST /api/v1/posts`:**\n- **Omit `scheduledAt`** → all variants publish **immediately** to the platform via the social adapter\n- **Provide `scheduledAt`** → all variants are **scheduled** for that time (must be within 30 days; cron publishes them hourly)\n\nEach variant is a separate post record. Auto-completes after `minDurationHours` and the winner is determined by the chosen metric. Per-variant `mediaUrls` is optional.\n\n**Partial failure semantics:** if ANY variant fails to publish during immediate mode, the endpoint returns **HTTP 502** and the failed variants are marked with `status: 'failed'`. The A/B test record is still created, but the winner comparison at completion only considers successfully published variants. Inspect each variant's post status before relying on test results.\n\n### Get test results\n\n```bash\ncurl https://socialcannon.app/api/v1/ab-tests/ \\\n -H \"Authorization: Bearer $TOKEN\"\n```\n\nReturns per-variant metrics, current winner, and confidence score.\n\n### List tests\n\n```bash\ncurl \"https://socialcannon.app/api/v1/ab-tests?status=active\" \\\n -H \"Authorization: Bearer $TOKEN\"\n```\n\n### Force-complete a test\n\n```bash\ncurl -X POST https://socialcannon.app/api/v1/ab-tests//complete \\\n -H \"Authorization: Bearer $TOKEN\"\n```\n\n## Timing Suggestions (Pro)\n\n### Get recommended posting times\n\n```bash\ncurl \"https://socialcannon.app/api/v1/accounts//timing?timezone=UTC-5\" \\\n -H \"Authorization: Bearer $TOKEN\"\n```\n\nReturns top 5 time slots ranked by average engagement rate with confidence scores.\n\n### Find the single best available slot\n\nCombines engagement data with calendar availability. Unlike the other two timing endpoints, this one is available on **all tiers** (including Free):\n\n```bash\ncurl \"https://socialcannon.app/api/v1/timing/optimal-slot?accountId=&timezone=UTC-5\" \\\n -H \"Authorization: Bearer $TOKEN\"\n```\n\nReturns the next open slot ranked by historical performance.\n\n### Auto-schedule multiple posts\n\nDistribute posts across optimal time slots for the next 7 days:\n\n```bash\ncurl -X POST https://socialcannon.app/api/v1/posts/auto-schedule \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"accountId\": \"\",\n \"posts\": [\n { \"content\": \"Post 1 text\" },\n { \"content\": \"Post 2 text\", \"mediaUrls\": [\"https://...\"] },\n { \"content\": \"Post 3 text\" }\n ],\n \"timezone\": \"UTC-5\"\n }'\n```\n\nMax 20 posts per request. Each post gets a unique slot. Returns `{ scheduled: [...], unscheduled: [...], summary: {...} }`.\n\n## UTM Link Tracking\n\nGenerate UTM-tagged URLs:\n\n```bash\ncurl -X POST https://socialcannon.app/api/v1/links/generate \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"url\": \"https://example.com/product\",\n \"platform\": \"twitter\",\n \"campaign\": \"spring-launch\",\n \"content\": \"hero-cta\",\n \"postId\": \"\",\n \"save\": true\n }'\n```\n\nFields: `url` (required), `platform` (optional — sets `utm_source`), `campaign` (optional — `utm_campaign`), `content` (optional — `utm_content`), `term` (optional — `utm_term`), `postId` (optional — link to a post), `save` (optional, default true — persist to tracked_links).\n\n### List tracked links\n\n```bash\ncurl \"https://socialcannon.app/api/v1/links?postId=&platform=twitter&limit=20&cursor=\" \\\n -H \"Authorization: Bearer $TOKEN\"\n```\n\nQuery params: `postId`, `platform`, `limit`, `cursor` — all optional.\n\n## Platforms\n\nList supported platforms and their capabilities (public, no auth required):\n\n```bash\ncurl https://socialcannon.app/api/v1/platforms\n```\n\n## Platform-Specific Notes\n\n### Twitter/X\n- 280 char limit. Up to 4 images. Threads via reply chains.\n\n### Facebook\n- 63,206 char limit. Supports native scheduling. Page-level tokens.\n- **Reels**: Set `platformOptions.mediaType` to `\"reel\"`. Video must be MP4/MOV, vertical (9:16). Without this, videos post as regular video posts.\n- **Stories**: Set `platformOptions.mediaType` to `\"story\"`. Supports one image or video. Ephemeral (24h).\n\n```bash\ncurl -X POST https://socialcannon.app/api/v1/posts \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"accountId\": \"\",\n \"content\": \"Check out this tutorial!\",\n \"mediaUrls\": [\"https://example.com/video.mp4\"],\n \"platformOptions\": {\n \"mediaType\": \"reel\"\n }\n }'\n```\n\n### Instagram\n- Requires media (no text-only). Max 10 carousel items. No API deletion.\n- **Stories**: Set `platformOptions.mediaType` to `\"story\"`. One image or video.\n- **Reels**: Set `platformOptions.mediaType` to `\"reel\"`. Vertical 9:16 video.\n\n### TikTok\n- Requires media — no text-only posts. Supports video, photo carousel (up to 35 images), and Stories.\n- **`platformOptions.privacyLevel` is REQUIRED** on every TikTok post — there is no default. Omitting it returns `400` with code `TIKTOK_PRIVACY_REQUIRED`. Use a value from the creator-info endpoint's `privacyLevelOptions` (e.g. `PUBLIC_TO_EVERYONE`, `MUTUAL_FOLLOW_FRIENDS`, `FOLLOWER_OF_CREATOR`, `SELF_ONLY`).\n- **Interaction toggles** (optional, default = allowed): `disableComment`, `disableDuet`, `disableStitch` (booleans). Duet/Stitch apply to video only. If the creator-info endpoint reports an interaction is disabled account-side (`commentDisabled` / `duetDisabled` / `stitchDisabled`), set the matching `disable*` to `true` (the server force-disables it regardless).\n- **Commercial content disclosure** (optional): set `commercialContent: true` if the post promotes a brand, product, or service, then set `brandOrganic: true` (your own brand) and/or `brandedContent: true` (paid/third-party partnership). If `brandedContent` is true, `privacyLevel` cannot be `SELF_ONLY`.\n- **Stories**: Set `platformOptions.mediaType` to `\"story\"`. One video. Ephemeral (24h).\n- Video publish uses an async poll model. No API deletion support.\n\n**Get a TikTok account's posting capabilities** — call this before composing a TikTok post; it returns the allowed privacy levels and which interactions are disabled:\n\n```bash\ncurl https://socialcannon.app/api/v1/accounts//tiktok/creator-info \\\n -H \"Authorization: Bearer $TOKEN\"\n```\n\nReturns `{ creatorNickname, creatorUsername, creatorAvatarUrl, privacyLevelOptions, commentDisabled, duetDisabled, stitchDisabled, maxVideoPostDurationSec }`. Choose `privacyLevel` from `privacyLevelOptions` and respect the `*Disabled` flags.\n\n**Example — publish a public TikTok video with comments on:**\n```bash\ncurl -X POST https://socialcannon.app/api/v1/posts \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"accountId\": \"\",\n \"content\": \"New track out now!\",\n \"mediaUrls\": [\"https://example.com/clip.mp4\"],\n \"platformOptions\": {\n \"privacyLevel\": \"PUBLIC_TO_EVERYONE\",\n \"disableComment\": false,\n \"disableDuet\": false,\n \"disableStitch\": false\n }\n }'\n```\n\n### YouTube\n- Supports regular videos, Shorts, and Community posts. Native scheduling support.\n- **Shorts**: Set `platformOptions.mediaType` to `\"short\"`. Vertical video ≤60s.\n- **Community posts**: Set `platformOptions.mediaType` to `\"community\"`. Text/image post to channel's Community tab.\n- Scheduled videos are uploaded as private with a `publishAt` timestamp.\n\n### LinkedIn\n- 3,000 char limit. Supports text-only and images (single or multi-image). Threads combine all items into one post.\n- Scheduling works via SocialCannon (LinkedIn has no native scheduling).\n- **No analytics, engagement inbox, or replies** for LinkedIn.\n\n## Rate Limits\n\n- Free tier: 30 requests/minute\n- Pro tier: 300 requests/minute\n- Agency tier: 600 requests/minute\n- Enterprise tier: 1200 requests/minute (default; negotiable)\n- Returns `429` with `Retry-After` header when exceeded\n\n## Subscription Tiers\n\nFour tiers. Twitter/X is the only platform with a per-post API cost passed through, so every tier carries an X-write quota.\n\n### Free — $0\n- 2 connected accounts\n- 10 posts per billing period\n- **1 Twitter/X post per billing period** (a taster — thread items count individually)\n- 2 scheduled posts at a time\n- 3 media uploads per billing period\n- 2-item threads, 5 tracked links\n- Twitter/X, Facebook only — Instagram, LinkedIn, TikTok, YouTube are Pro+\n- No analytics, no engagement replies, no A/B testing, no timing suggestions\n- 30 API requests/minute\n\n### Pro — $15/month\n- Unlimited accounts, posts, scheduling on free platforms\n- **50 Twitter/X posts per billing period**\n- All 6 platforms: Twitter/X, Facebook, Instagram, LinkedIn, TikTok, YouTube\n- Analytics with history, 90-day calendar\n- 25-item threads, unlimited tracked links\n- A/B testing (5 concurrent, 4 variants)\n- Engagement replies, timing suggestions\n- 300 API requests/minute\n\n### Agency — $49/month\n- Everything in Pro\n- **250 Twitter/X posts per billing period**\n- A/B testing (20 concurrent, 6 variants)\n- 365-day calendar range\n- Priority support\n- 600 API requests/minute\n\n### Enterprise — custom contract\n- Custom Twitter/X quota, custom rate limits, SLA, dedicated support\n- Contact `sales@socialcannon.app`\n\n### Hitting a cap\n\nAny tier exceeding its `maxTwitterPostsPerPeriod` cap returns:\n```json\n{\n \"success\": false,\n \"error\": \"Twitter/X post limit reached (50/50). Upgrade to Agency for 250 Twitter/X posts per month.\",\n \"code\": \"LIMIT_EXCEEDED\",\n \"limit\": { \"type\": \"twitter_posts_per_period\", \"current\": 50, \"max\": 50, \"tier\": \"pro\" }\n}\n```\nHTTP `403`. Resets at the start of the next billing period. The upgrade hint is tier-aware — Free is pointed to Pro, Pro to Agency, and Agency/Enterprise to `sales@socialcannon.app` (no tier is \"unlimited\" for Twitter/X).\n\n## Support\n\nIf you run into issues with the API, account connections, or integration setup, contact **support@socialcannon.app**.\n\n## Tips for Agents\n\n1. Always list accounts first to get valid `accountId` values before creating posts.\n2. Use the calendar endpoint to check for gaps before suggesting new posts.\n3. For Instagram and TikTok, always include at least one media URL — text-only posts will fail.\n4. Use `autoUtm: true` in `platformOptions` to automatically tag URLs in posts.\n5. Check analytics after 24+ hours for meaningful engagement data.\n6. When repurposing content, review the returned `validation` field — if `valid` is false, adjust the content before publishing.\n7. Use `scheduledAt: \"optimal\"` to let SocialCannon pick the best posting time automatically (Pro).\n8. For batch scheduling, use the auto-schedule endpoint instead of creating posts one by one.\n9. For YouTube, set `mediaType` to `\"short\"` for Shorts or `\"community\"` for Community tab posts.\n10. For TikTok, call `GET /api/v1/accounts/{id}/tiktok/creator-info` first — it returns the allowed `privacyLevelOptions` (pass one as `platformOptions.privacyLevel`; it is required) and which of Comment/Duet/Stitch are disabled (never enable a disabled one).\n\nFile v1.9.6:_meta.json\n\n{\n \"ownerId\": \"kn75vx9q7acz869fn4vdd2cwx1845nrx\",\n \"slug\": \"socialcannon\",\n \"version\": \"1.9.6\",\n \"publishedAt\": 1783771296991\n}\n\nFile v1.9.6:CLAUDE.md\n\n\n\n\n\nFile v1.9.6:skill-card.md\n\n## Description:
\nSocialcannon helps agents publish, schedule, analyze, and manage social media posts across Twitter/X, Facebook, Instagram, LinkedIn, TikTok, and YouTube.
\n\nThis skill is ready for commercial/non-commercial use.
\n\n## Publisher:
\n[miprinia](https://clawhub.ai/user/miprinia)
\n\n### License/Terms of Use:
\nMIT-0
\n\n\n## Use Case:
\nDevelopers and social media operators use this skill to let an agent prepare API calls, configuration snippets, and operational guidance for SocialCannon publishing, scheduling, analytics, engagement, A/B testing, content repurposing, and UTM tracking workflows.
\n\n### Deployment Geography for Use:
\nGlobal
\n\n## Known Risks and Mitigations:
\nRisk: The skill can guide live publishing, replies, deletes, retries, disconnects, and post-mode repurposing against real social media accounts.
\nMitigation: Require explicit human approval before any live publish, reply, delete, retry, disconnect, immediate A/B test, or post-mode repurpose action.
\nRisk: Client credentials and bearer tokens can expose SocialCannon account access.
\nMitigation: Store SOCIALCANNON_CLIENT_ID and SOCIALCANNON_CLIENT_SECRET in environment variables, keep secrets out of chat transcripts, and refresh short-lived bearer tokens as needed.
\nRisk: An agent may publish to the wrong connected account, platform, or content format.
\nMitigation: List accounts first, verify the target account and content before execution, and prefer draft, scheduled, or preview workflows by defa\n\nArchive v1.9.5: 4 files, 11675 bytes\n\nFiles: CLAUDE.md (43b), skill-card.md (2565b), SKILL.md (29658b), _meta.json (131b)\n\nArchive v1.9.4: 4 files, 11737 bytes\n\nFiles: CLAUDE.md (43b), skill-card.md (2825b), SKILL.md (29657b), _meta.json (131b)\n\nArchive v1.9.3: 4 files, 11326 bytes\n\nFiles: CLAUDE.md (43b), skill-card.md (2660b), SKILL.md (28740b), _meta.json (131b)\n\nArchive v1.9.2: 4 files, 11389 bytes\n\nFiles: CLAUDE.md (43b), skill-card.md (2742b), SKILL.md (28730b), _meta.json (131b)\n\nArchive v1.9.1: 3 files, 11146 bytes\n\nFiles: skill-card.md (2628b), SKILL.md (28562b), _meta.json (131b)\n\nArchive v1.9.0: 4 files, 11094 bytes\n\nFiles: CLAUDE.md (43b), skill-card.md (2735b), SKILL.md (28105b), _meta.json (131b)","readmeExcerpt":"Skill: socialcannon Owner: miprinia Summary: Publish, schedule, and manage social media posts across Twitter/X, Facebook, Instagram, LinkedIn, TikTok, and YouTube. Content calendar with gap analysis, A/B testing, engagement inbox, AI content repurposing, optimal timing suggestions, auto-scheduling, UTM tracking, and platform-native AI-content disclosure labels. Tags: latest:1.12.0 Version history: v1.12.0 | 2026-09-2","codeSnippets":[],"executableExamples":[{"language":"bash","snippet":"curl -s https://socialcannon.app/api/v1/accounts \\\n -H \"Authorization: Bearer $TOKEN\" | jq '.data'"},{"language":"bash","snippet":"curl -X POST https://socialcannon.app/api/v1/posts \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"accountId\": \"\", \"content\": \"Hello from SocialCannon!\"}'"},{"language":"bash","snippet":"# Get a token\nTOKEN=$(curl -s -X POST https://socialcannon.app/api/v1/auth/token \\\n -H \"Content-Type: application/json\" \\\n -d \"{\\\"grant_type\\\": \\\"client_credentials\\\", \\\"client_id\\\": \\\"$SOCIALCANNON_CLIENT_ID\\\", \\\"client_secret\\\": \\\"$SOCIALCANNON_CLIENT_SECRET\\\"}\" \\\n | jq -r '.data.access_token')\n\n# List your connected accounts\ncurl -s https://socialcannon.app/api/v1/accounts \\\n -H \"Authorization: Bearer $TOKEN\" | jq '.data'\n\n# Publish a post (replace with an ID from the list above)\ncurl -X POST https://socialcannon.app/api/v1/posts \\\n -H \"Authorization: Bearer $TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"accountId\": \"\", \"content\": \"Hello from SocialCannon!\"}'"},{"language":"yaml","snippet":"mcp_servers:\n socialcannon:\n command: \"npx\"\n args: [\"-y\", \"@socialcannon/mcp@1.0.2\"]\n env:\n SOCIALCANNON_CLIENT_ID: \"${SOCIALCANNON_CLIENT_ID}\"\n SOCIALCANNON_CLIENT_SECRET: \"${SOCIALCANNON_CLIENT_SECRET}\""},{"language":"bash","snippet":"curl -X POST https://socialcannon.app/api/v1/auth/token \\\n -H \"Content-Type: application/json\" \\\n -d \"{\n \\\"grant_type\\\": \\\"client_credentials\\\",\n \\\"client_id\\\": \\\"$SOCIALCANNON_CLIENT_ID\\\",\n \\\"client_secret\\\": \\\"$SOCIALCANNON_CLIENT_SECRET\\\""},{"language":"bash","snippet":"curl -X POST https://socialcannon.app/api/v1/auth/token \\\n -H \"Content-Type: application/json\" \\\n -d \"{\n \\\"grant_type\\\": \\\"client_credentials\\\",\n \\\"client_id\\\": \\\"$SOCIALCANNON_CLIENT_ID\\\",\n \\\"client_secret\\\": \\\"$SOCIALCANNON_CLIENT_SECRET\\\"\n }\""}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: socialcannon\ndescription: >\n Publish, schedule, and manage social media posts across Twitter/X, Facebook,\n Instagram, LinkedIn, TikTok, and YouTube. Content calendar with gap analysis,\n A/B testing, engagement inbox, AI content repurposing, optimal timing\n suggestions, auto-scheduling, UTM tracking, and platform-native AI-content\n disclosure labels.\nversion: 1.12.0\nmetadata:\n openclaw:\n requires:\n env:\n - SOCIALCANNON_CLIENT_ID\n - SOCIALCANNON_CLIENT_SECRET\n bins:\n - curl\n primaryEnv: SOCIALCANNON_CLIENT_ID\n emoji: \"\\U0001F4E3\"\n homepage: https://socialcannon.app\n---\n\n# SocialCannon\n\nSocial media publishing API. Publish to Twitter/X, Facebook, Instagram, LinkedIn, TikTok, and YouTube from one API with scheduling, analytics, A/B testing, and AI-powered features.\n\n**Base URL:** `https://socialcannon.app`\n\n## Safety: destructive & irreversible actions\n\nSeveral operations act on **live social accounts** and cannot be undone. In an agent workflow, get **explicit human approval before** any of these:\n\n- **Publish** or **immediate A/B test** (a post with no `scheduledAt`) — goes live at once.\n- **Reply to an engagement** — posts a public reply from the connected account.\n- **Retry** a post — re-attempts a real publish.\n- **Delete a post** — removes it here **and** attempts deletion on the platform.\n- **Disconnect an account** — breaks the integration; reconnecting requires the OAuth flow again.\n- **Repurpose in `post` mode** — adapts **and publishes** to the target platforms.\n\nSafer defaults for agents: prefer read-only listing and `draft`/`scheduled` posts, and use `preview`-mode repurpose before `post` mode. Keep your Client Secret in an environment variable — never paste it into a chat.\n\n## Getting Started\n\nBefore making API calls, you need credentials and at least one connected social account.\n\n### 1. Get your API credentials\n\nSign up at [socialcannon.app](https://socialcannon.app) (Google or GitHub sign-in, free tier included — no card required). **Your Client Secret is shown once, right after signup — copy it then.** If you miss it, open **Settings → API Keys** and click **Generate API Secret**. Your **Client ID** is always available on that page. Use these as `SOCIALCANNON_CLIENT_ID` and `SOCIALCANNON_CLIENT_SECRET`.\n\n### 2. Connect social accounts\n\nSocial accounts are connected via OAuth in the browser. Open the connect URL for each platform you want to use — you'll authorize SocialCannon and get redirected back:\n\n| Platform | Connect URL |\n|----------|-------------|\n| Twitter/X | `https://socialcannon.app/api/connect/twitter?client_id=YOUR_CLIENT_ID` |\n| Facebook | `https://socialcannon.app/api/connect/facebook?client_id=YOUR_CLIENT_ID` |\n| Instagram | `https://socialcannon.app/api/connect/instagram?client_id=YOUR_CLIENT_ID` |\n| LinkedIn | `https://socialcannon.app/api/connect/linkedin?client_id=YOUR_CLIENT_ID` |\n| TikTok | `https://socialcannon.app/api/connect/tiktok?client_id=YOUR_CLI"},{"path":"_meta.json","content":"{\n \"ownerId\": \"kn75vx9q7acz869fn4vdd2cwx1845nrx\",\n \"slug\": \"socialcannon\",\n \"version\": \"1.12.0\",\n \"publishedAt\": 1790446688686\n}"},{"path":"skill-card.md","content":"## Description:\n\nHelps agents publish, schedule, and manage social media posts across connected accounts using SocialCannon.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[miprinia](https://clawhub.ai/user/miprinia)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nSocial media managers, creators, and developers use this skill to help agents draft, schedule, publish, and review posts and engagement across connected social accounts.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: Publishing, replying, retrying, deleting, disconnecting, or repurposing in post mode can affect live accounts and may be irreversible.\n\nMitigation: Get explicit human approval before these actions; prefer drafts, scheduled posts, and previews where possible.\n\nRisk: Exposing the client secret or giving an optional MCP process account credentials can compromise connected accounts.\n\nMitigation: Keep secrets in environment variables or a keychain, not chat or configuration files; enable MCP only when its credential access is intended.\n\n## Reference(s):\n\n- [SocialCannon ClawHub release](https://clawhub.ai/miprinia/skills/socialcannon)\n- [SocialCannon homepage](https://socialcannon.app)\n- [Optional SocialCannon MCP package](https://www.npmjs.com/package/@socialcannon/mcp)\n\n## Skill Output:\n\n**Output Type(s):** [Text, Markdown, Shell commands, Configuration guidance]\n\n**Output Format:** [Markdown with API examples and shell commands]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Guidance for drafts, schedules, publishing, analytics, and engagement through connected accounts.]\n\n## Skill Version(s):\n\n1.12.0 (source: frontmatter and server release metadata)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment."}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":"Publish, schedule, and manage social media posts across Twitter/X, Facebook, Instagram, LinkedIn, TikTok, and YouTube. Content calendar with gap analysis, A/B testing, engagement inbox, AI content repurposing, optimal timing suggestions, auto-scheduling, UTM tracking, and platform-native AI-content disclosure labels. Skill: socialcannon Owner: miprinia Summary: Publish, schedule, and manage social media posts across Twitter/X, Facebook, Instagram, LinkedIn, TikTok, and YouTube. Content calendar with gap analysis, A/B testing, engagement inbox, AI content repurposing, optimal timing suggestions, auto-scheduling, UTM tracking, and platform-native AI-content disclosure labels. Tags: latest:1.12.0 Version history: v1.12.0 | 2026-09-2","editorialQuality":{"score":100,"threshold":65,"status":"ready","wordCount":1317,"uniquenessScore":49,"reasons":[]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-09T09:19:29.733Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-09T09:19:29.733Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-10T01:43:27.536Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}