API Guide

Platforms

All connected platforms accepted by the API. Use the API value when filtering accounts (GET /accounts?platform=instagram) or as the key in platformOptions. Each platform’s guide section below documents the options the API exposes.

TikTok Options

TikTok posts support additional options via the tiktokOptions field when creating a post. By default, TikTok posts are published live. Set draft: true to send the post to your TikTok Creator Inbox for review before publishing.

{
  "content": "New book trailer!",
  "accountIds": ["tiktok_account_id"],
  "publishNow": true
}

{
  "content": "New book trailer!",
  "accountIds": ["tiktok_account_id"],
  "publishNow": true,
  "tiktokOptions": {
    "draft": true,
    "privacyLevel": "PUBLIC_TO_EVERYONE",
    "allowComment": true
  }
}

{
  "content": "Sneak peek for friends only",
  "accountIds": ["tiktok_account_id"],
  "publishNow": true,
  "tiktokOptions": {
    "privacyLevel": "MUTUAL_FOLLOW_FRIENDS",
    "allowDuet": false,
    "allowStitch": false
  }
}

Instagram Options

Instagram supports Feed posts (default), Stories, Reels, and Trial Reels (shown to non-followers first). Aspect-ratio rules differ by product: Feed accepts 0.75:1 to 1.91:1; Stories and Reels require 9:16 vertical.

{
  "content": "First chapter teaser — what do you think?",
  "accountIds": ["ig_account_id"],
  "scheduledAt": "2026-05-01T14:00:00Z",
  "mediaItems": [{ "type": "video", "url": "https://...", "width": 1080, "height": 1920 }],
  "instagramOptions": {
    "contentType": "reel",
    "coverImage": "https://media.../cover-1080x1920.png",
    "trialParams": { "graduationStrategy": "SS_PERFORMANCE" }
  }
}

{
  "content": "Behind the scenes",
  "accountIds": ["ig_account_id"],
  "mediaItems": [{ "type": "image", "url": "https://...", "width": 1080, "height": 1920 }],
  "instagramOptions": { "contentType": "story" }
}

Threads Options

Threads supports topic tags (for discovery via Meta's topic feed) and thread chains (a root post plus a sequence of replies, all from your account).

{
  "content": "Three years to write this novel. Here's what I learned. #BookThreads",
  "accountIds": ["threads_account_id"],
  "threadsOptions": { "topicTag": "Book Threads" }
}

First Thread (Thread Chains)

For multi-part threads, use platformOptions.threads.threadItems. The first item becomes the root post; subsequent items chain as replies. When threadItems is provided, the top-level contentfield is used for display/search ONLY — the first thread item is what gets published. Make the first item your strongest hook.

{
  "content": "A Threads chain about my writing process",
  "accountIds": ["threads_account_id"],
  "threadsOptions": { "topicTag": "Writing Community" },
  "platformOptions": {
    "threads": {
      "threadItems": [
        { "content": "I finished my first novel after 3 years. Here's what nobody tells you." },
        { "content": "Year 1: I wrote 200,000 words I'd later cut. Painful, but necessary." },
        { "content": "Year 3: I learned that revision is where the book actually gets written." }
      ]
    }
  }
}

YouTube Options

YouTube requires a titlefor video posts — the API returns 422 if youtubeOptions.title is missing. The top-level content becomes the video description. YouTube Shorts are auto-detected when the video is 9:16 and under 60 seconds (you can add #Shorts to the title to make routing explicit).

{
  "content": "After 3 years of writing, my first fantasy novel is here. Pre-order link in the channel description.",
  "accountIds": ["yt_account_id"],
  "scheduledAt": "2026-05-03T19:00:00Z",
  "mediaItems": [{ "type": "video", "url": "https://..." }],
  "youtubeOptions": {
    "title": "3 Years of Writing — My First Fantasy Novel #Shorts",
    "visibility": "public",
    "madeForKids": false,
    "containsSyntheticMedia": true,
    "playlistId": "PLxxxxxxxx"
  }
}

Reddit Options

Reddit requires both a subreddit and a title. The API returns 422 if either is missing. Reddit titles are the headline visible in feeds; the top-level content becomes the body text (for self posts) or the link description (for link posts).

{
  "content": "After 3 years of writing, I finally finished my fantasy novel. The hardest part was knowing when to stop revising. AMA.",
  "accountIds": ["reddit_account_id"],
  "redditOptions": {
    "subreddit": "Fantasy",
    "title": "Just published my first fantasy novel — what I wish I knew when I started",
    "forceSelf": true,
    "flairId": "abc123-def456"
  }
}

Platform Options — Raw Passthrough

For platforms or fields not covered by the typed *Options blocks above, use platformOptions.<platform>. Field names match the underlying provider's docs verbatim. Anything in here is forwarded directly to the platform without local validation, so you trade off clearer error messages for full feature access.

{
  "content": "What's your next read?",
  "accountIds": ["twitter_account_id"],
  "platformOptions": {
    "twitter": {
      "replyToTweetId": "1234567890",
      "poll": { "options": ["Fantasy", "Sci-fi", "Mystery", "Romance"], "duration_minutes": 1440 }
    }
  }
}

{
  "content": "New chapter posted!",
  "accountIds": ["discord_account_id"],
  "platformOptions": {
    "discord": {
      "channelId": "987654321",
      "forumThreadName": "Chapter 12 discussion",
      "forumAppliedTags": ["new-chapter", "fantasy"]
    }
  }
}

{
  "content": "**New post!** Check it out at https://...",
  "accountIds": ["telegram_account_id"],
  "platformOptions": {
    "telegram": {
      "parseMode": "Markdown",
      "disableWebPagePreview": false
    }
  }
}

Twitter / X

Twitter posts use the raw platformOptions.twitter block. Supported fields: replyToTweetId, replySettings (following | mentionedUsers | subscribers | verified), threadItems (multi-tweet threads), poll, and longVideo. See the raw passthrough section above for examples.

Facebook Options

LinkedIn Options

Pinterest Options

Bluesky

Bluesky uses raw platformOptions.bluesky. Supports threadItems for multi-skeet threads. Caption limit is 300 chars per skeet.

Google Business

Posts to your Google Business Profile. Use raw platformOptions.googlebusiness: topicType (STANDARD | EVENT | OFFER), callToAction, event (with start/end dates), and offer (with terms/redemption details).

Telegram

Telegram uses raw platformOptions.telegram: parseMode (HTML | Markdown | MarkdownV2), disableWebPagePreview, disableNotification, and protectContent (prevents forwarding/saving).

Snapchat

Snapchat uses raw platformOptions.snapchat: contentType (story | saved_story | spotlight). Spotlight is Snap's answer to TikTok — algorithmic feed for non-followers.

WhatsApp

WhatsApp Status posts use raw platformOptions.whatsapp. Status is the 24-hour ephemeral content visible to your contacts.

Discord

Discord uses raw platformOptions.discord: channelId (required), embeds (rich embed array), poll, crosspost (announce to following servers), forumThreadName + forumAppliedTags for forum channels, tts, plus webhook overrides (webhookUsername, webhookAvatarUrl).

Content Guides

Read the author's brand voice, prose style, copywriting principles, and social media strategy. Integrations that generate captions on the author's behalf should fetch these first so the output matches the voice the author has defined in their dashboard.

Get Guides

{
  "prose_guide": "Short punchy sentences. First-person. Never use em-dashes.",
  "brand_guide": "Cozy paranormal mystery. Coastal-town-with-secrets vibe. Always tease, never spoil.",
  "copywriting_guide": "Concrete details over adjectives. Specific character names. Questions that open loops.",
  "social_media_guide": "Instagram: 5-8 hashtags. TikTok: trending-sound hooks. LinkedIn: skip.",
  "image_style_prompt": "Dreamy golden-hour lighting, watercolor bleeds, coastal palette"
}

Any field may be nullif the author hasn't set it yet. Responses are cached for a few minutes — guides change infrequently.

AI Campaigns

Campaigns are multi-day content plans the author builds in the dashboard. The API exposes the full lifecycle so integrations can create a campaign, save an AI-generated plan, queue media generation, and schedule every post to the calendar.

List Campaigns

Returns all campaigns under the authenticated profile, newest first. Each campaign includes its id, name, objective, duration, platforms, status (draft, generating, review, scheduled, active, completed), and content mix.

Create Campaign

curl -X POST \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Spring launch — Curses and Currents",
    "objective": "Build pre-order buzz for Curses and Currents launching May 1",
    "post_count": 14,
    "platforms": ["instagram", "tiktok", "threads"],
    "content_mix": "mostly_images"
  }' \
  https://authorautomations.social/api/v1/campaigns

Save Plan

Attach a content plan to a campaign. Use when your integration generates the plan client-side (e.g. the Claude plugin has Claude write each post) and just needs to store it. Creates one campaign_post record per post.

Generate Media

Kicks off server-side media generation for every campaign post using whichever provider you've configured per task type (Magnific, fal.ai, or Google Nano Banana). Returns immediately with { "status": "started" }. Poll the GET variant to watch progress.

Returns progress: { total, completed, failed, inProgress, isRunning, posts }. Safe to poll every 5 seconds.

Schedule Campaign

Drops every campaign post into the author's per-platform queues in one pass. The queues decide when each post publishes — there is no campaign start date or per-post time. Returns per-post success / failure counts.

{
  "scheduled": 13,
  "failed": 1,
  "total": 14,
  "errors": [
    { "day": 5, "error": "All selected platforms are video-only but this post is image content." }
  ]
}

The errors[].day key is a 1-based post index (legacy field name). startDate, scheduleMode, and postTimes are accepted-but-ignored on this endpoint.

Claude Code / Cowork Plugin

Create posts and run AI campaigns directly from Claude Code or Claude Cowork. The plugin lets Claude write your captions using the full context of your conversation — it reads your brand guides, knows what you're working on, and crafts platform-specific content in your voice.

Install the Plugin

The plugin lives in its own Claude marketplace. Two commands in Claude Code or Claude Cowork:

/plugin marketplace add https://github.com/chellehoniker/claude-code-author-automations
/plugin install author-automations-social@author-automations

No git clone, no npm install, no build step. Claude Code downloads the plugin on demand.

Setup

The plugin uses our hosted MCP server, so there's no local configuration. The first time Claude calls a plugin tool, a browser window opens to /authorize on our site — click Approveand the token is stored in Claude Code's credential store.

If Claude Code asks for Client ID and Client Secret instead of opening a browser window, generate a credential pair from Settings → Cowork Connector and paste them. Same credentials work for both Cowork and Claude Code.

For the canonical step-by-step walkthrough, see /docs/connect#cli.

Quick Post

Create a single post with a slash command or natural language:

/author-automations-social:aa-post My new book is available for pre-order!

"Create an Instagram and TikTok post about my book launch"

Claude reads your content guides, writes unique captions for each platform, and schedules the post — all in one conversation.

AI Campaign

Run a full campaign from the CLI:

/author-automations-social:aa-campaign 14 posts for my spring book launch

"Create a 14-post social media campaign to promote Curses and Currents across Instagram, TikTok, and Facebook"

Claude will walk you through the full flow:

The Hybrid AI Model

Unlike typical integrations, Claude writes your captions directly — not a server-side AI. This means Claude has the full context of your conversation: what book you're working on, what chapter you just finished, what your audience cares about. Media generation (images, videos, music) happens server-side through whichever media provider you've configured per task type — Magnific, fal.ai, or Google Nano Banana — using API keys you store in Settings → AI.

Available Tools

Content Guides

For the best results, set up your content guides in the dashboard under Settings > AI Configuration:

Claude reads all four guides before writing any caption. The more detail you provide, the better the output matches your voice.