The scheduling model

How SocialClaw schedules work: one schedule document drives REST, MCP, and the CLI, applying it creates a run of posts, and each post moves through scheduled, published, action_required, failed, or canceled.

One schedule document drives REST, MCP, and the CLI. Minimal form — a timezone and a list of posts:

{
  "timezone": "UTC",
  "idempotencyKey": "launch-001",
  "posts": [
    {
      "account": "linkedin:person:123",
      "name": "Launch update",
      "description": "We just shipped the new SocialClaw workflow.",
      "publish_at": "2026-08-01T15:00:00Z",
      "media_link": "https://getsocialclaw.com/media/asset_123/dlv_123/launch.png"
    }
  ]
}

• account targets a connected account by handle — get handles from GET /v1/accounts.
• publish_at is ISO-8601; times without an offset are interpreted in the document's timezone.
• media_link is the simple single-file form; assets is the explicit form with kind and mime.
• Campaign documents use { timezone, campaigns: [...] } instead of posts — preview how they expand with POST /v1/campaigns/preview before applying.

Lifecycle: validate, apply, run. Applying a schedule creates a run; a run contains posts; each post moves through scheduled, published, action_required, failed, or canceled. action_required means the provider accepted the media but the creator must finish it in the provider app; it is not live yet. POST /v1/posts/validate checks provider rules and creates nothing; POST /v1/posts/apply preflights connected accounts and plan entitlements before creating anything; GET /v1/runs/{runId}/status shows the summary.

Draft runs. Set mode to draft to create an editable draft run instead of live scheduled posts, then publish later — optionally shifting the start time:

curl -sS https://getsocialclaw.com/v1/runs/run_123/publish \
  -H "Authorization: Bearer $SOCIALCLAW_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{ "startAt": "2026-08-01T15:00:00Z" }'

Per-post provider settings. Provider-specific behavior goes in a post's settings object. Example — TikTok inbox mode sends the media through TikTok's notification flow instead of publishing, and the creator opens the notification to finish the post in the TikTok app:

{
  "account": "tiktok:creator:123",
  "description": "Behind the scenes",
  "publish_at": "2026-08-01T18:00:00Z",
  "media_link": "https://getsocialclaw.com/media/asset_456/dlv_456/clip.mp4",
  "settings": { "tiktokPostMode": "draft" }
}

Idempotency. Always send an idempotencyKey with generated schedules. Pick a key that identifies the intent, not the attempt: launch-week-001, not a random UUID per retry. The MCP apply_schedule tool generates one automatically when the client does not supply one.