socialclaw

List connected social accounts in the SocialClaw workspace. Optionally filter by provider (x, facebook, instagram_business, instagram, threads, linkedin, linkedin_page, pinterest, tiktok, telegram, discord, youtube, reddit, wordpress).

{
  "type": "object",
  "properties": {
    "provider": {
      "type": "string",
      "description": "Optional provider filter."
    }
  }
}

Get publish capabilities and provider rules for connected accounts: what media is allowed, text limits, and whether publishing is currently possible. Pass accountId for one account, or provider to filter, or neither for all.

{
  "type": "object",
  "properties": {
    "accountId": {
      "type": "string",
      "description": "Optional account id."
    },
    "provider": {
      "type": "string",
      "description": "Optional provider filter."
    }
  }
}

Start connecting a new social account. For OAuth providers this returns an authorizeUrl the user must open in a browser. Telegram requires botToken and chatId; Discord requires webhookUrl.

{
  "type": "object",
  "properties": {
    "provider": {
      "type": "string",
      "description": "Provider to connect."
    },
    "botToken": {
      "type": "string",
      "description": "Telegram bot token (telegram only)."
    },
    "chatId": {
      "type": "string",
      "description": "Telegram chat target, e.g. @yourchannel (telegram only)."
    },
    "webhookUrl": {
      "type": "string",
      "description": "Discord channel webhook URL (discord only)."
    }
  },
  "required": [
    "provider"
  ]
}

Upload media (image or video) to SocialClaw hosted storage. Provide either sourceUrl (a public URL the server downloads) or contentBase64. Returns an asset id and a public URL usable as media_link in schedules.

{
  "type": "object",
  "properties": {
    "filename": {
      "type": "string",
      "description": "Filename including extension, e.g. launch.png."
    },
    "sourceUrl": {
      "type": "string",
      "description": "Public URL to download the media from."
    },
    "contentBase64": {
      "type": "string",
      "description": "Base64-encoded file content (alternative to sourceUrl)."
    }
  },
  "required": [
    "filename"
  ]
}

Validate a schedule document against provider rules, media limits, account state, and publish times WITHOUT creating any posts. Always run this before apply_schedule.

{
  "type": "object",
  "properties": {
    "schedule": {
      "type": "object",
      "description": "SocialClaw schedule document. Minimal shape: { timezone, posts: [{ account, name, description, publish_at, media_link? }] }. Campaign documents use { timezone, campaigns: [...] }. Per-post provider settings go in settings, e.g. TikTok inbox mode: settings: { tiktokPostMode: \"draft\" } sends the media to TikTok's inbox notification flow instead of publishing, and the creator finishes the post inside the TikTok app.",
      "additionalProperties": true
    }
  },
  "required": [
    "schedule"
  ]
}

Preview how a campaign schedule document expands into concrete posts and steps without creating anything.

{
  "type": "object",
  "properties": {
    "schedule": {
      "type": "object",
      "description": "SocialClaw schedule document. Minimal shape: { timezone, posts: [{ account, name, description, publish_at, media_link? }] }. Campaign documents use { timezone, campaigns: [...] }. Per-post provider settings go in settings, e.g. TikTok inbox mode: settings: { tiktokPostMode: \"draft\" } sends the media to TikTok's inbox notification flow instead of publishing, and the creator finishes the post inside the TikTok app.",
      "additionalProperties": true
    }
  },
  "required": [
    "schedule"
  ]
}

Create a publishing run from a schedule document. Posts are scheduled or published through connected accounts. Send an idempotencyKey so retries do not create duplicate runs.

{
  "type": "object",
  "properties": {
    "schedule": {
      "type": "object",
      "description": "SocialClaw schedule document. Minimal shape: { timezone, posts: [{ account, name, description, publish_at, media_link? }] }. Campaign documents use { timezone, campaigns: [...] }. Per-post provider settings go in settings, e.g. TikTok inbox mode: settings: { tiktokPostMode: \"draft\" } sends the media to TikTok's inbox notification flow instead of publishing, and the creator finishes the post inside the TikTok app.",
      "additionalProperties": true
    },
    "idempotencyKey": {
      "type": "string",
      "description": "Stable key to deduplicate retries."
    }
  },
  "required": [
    "schedule"
  ]
}

Publish a previously created draft run, optionally at a given ISO-8601 start time.

{
  "type": "object",
  "properties": {
    "runId": {
      "type": "string",
      "description": "Draft run id."
    },
    "startAt": {
      "type": "string",
      "description": "Optional ISO-8601 publish start time."
    }
  },
  "required": [
    "runId"
  ]
}

List posts in the workspace with optional filters.

{
  "type": "object",
  "properties": {
    "runId": {
      "type": "string"
    },
    "status": {
      "type": "string",
      "description": "e.g. scheduled, published, action_required, failed, canceled."
    },
    "account": {
      "type": "string",
      "description": "Account handle filter."
    },
    "provider": {
      "type": "string"
    },
    "campaignId": {
      "type": "string"
    },
    "limit": {
      "type": "number",
      "description": "Maximum posts to return. Defaults to 20 and is capped at 50."
    },
    "offset": {
      "type": "number",
      "description": "Offset for paging through results."
    }
  }
}

List media (images/videos) the user has uploaded to their SocialClaw library, newest first. Each asset includes a publicUrl usable directly as media_link in validate_schedule/apply_schedule. Use this to find a previously uploaded file (e.g. from the dashboard) to post. Optionally filter by kind (image/video), mime, or a text query over filename/id.

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Optional text match over filename, id, kind, mime, or url."
    },
    "kind": {
      "type": "string",
      "description": "Filter by media kind: image or video.",
      "enum": [
        "image",
        "video"
      ]
    },
    "mime": {
      "type": "string",
      "description": "Optional mime prefix filter, e.g. video/mp4."
    },
    "sort": {
      "type": "string",
      "description": "created_desc (default, newest first) or created_asc.",
      "enum": [
        "created_desc",
        "created_asc"
      ]
    },
    "limit": {
      "type": "number",
      "description": "Maximum assets to return. Defaults to 24, capped at 48."
    }
  }
}

Get one post including its delivery state and provider identifiers.

{
  "type": "object",
  "properties": {
    "postId": {
      "type": "string"
    }
  },
  "required": [
    "postId"
  ]
}

List publish attempts for a post, including provider errors. Use this to debug failed posts.

{
  "type": "object",
  "properties": {
    "postId": {
      "type": "string"
    }
  },
  "required": [
    "postId"
  ]
}

Retry a failed post.

{
  "type": "object",
  "properties": {
    "postId": {
      "type": "string"
    }
  },
  "required": [
    "postId"
  ]
}

Cancel a scheduled post before it publishes.

{
  "type": "object",
  "properties": {
    "postId": {
      "type": "string"
    }
  },
  "required": [
    "postId"
  ]
}

Get the status summary of a publishing run and its posts.

{
  "type": "object",
  "properties": {
    "runId": {
      "type": "string"
    }
  },
  "required": [
    "runId"
  ]
}

Get analytics snapshots for a post, an account, or a run. scope must be post, account, or run; id is the matching identifier.

{
  "type": "object",
  "properties": {
    "scope": {
      "type": "string",
      "enum": [
        "post",
        "account",
        "run"
      ]
    },
    "id": {
      "type": "string"
    },
    "window": {
      "type": "string",
      "description": "Optional analytics window, e.g. 7d."
    }
  },
  "required": [
    "scope",
    "id"
  ]
}

Fetch fresh analytics for a published post from the provider and store a new snapshot, then return it. Supported providers: Instagram, TikTok, YouTube, Reddit, X, Pinterest, Snapchat (others return an unsupported snapshot). Call this before get_analytics when you need current numbers rather than the last stored snapshot.

{
  "type": "object",
  "properties": {
    "postId": {
      "type": "string",
      "description": "The published post id to refresh."
    },
    "window": {
      "type": "string",
      "description": "Optional analytics window, e.g. 7d (default lifetime)."
    }
  },
  "required": [
    "postId"
  ]
}

List an Instagram account's recent posts (caption, permalink, timestamp, comment count) so you can find one to read or moderate comments on. account is the connected-account id or handle.

{
  "type": "object",
  "properties": {
    "account": {
      "type": "string",
      "description": "Instagram connected-account id or handle."
    },
    "limit": {
      "type": "number",
      "description": "Max media to return (default 25, capped at 100)."
    },
    "after": {
      "type": "string",
      "description": "Pagination cursor from a previous response."
    }
  },
  "required": [
    "account"
  ]
}

Read the comments (and replies) on an Instagram post. Use list_instagram_media first to get a mediaId.

{
  "type": "object",
  "properties": {
    "account": {
      "type": "string",
      "description": "Instagram connected-account id or handle."
    },
    "mediaId": {
      "type": "string",
      "description": "The IG media id from list_instagram_media."
    },
    "limit": {
      "type": "number",
      "description": "Max comments to return (default 25, capped at 100)."
    },
    "after": {
      "type": "string",
      "description": "Pagination cursor from a previous response."
    }
  },
  "required": [
    "account",
    "mediaId"
  ]
}

Reply to an Instagram comment on the user's media.

{
  "type": "object",
  "properties": {
    "account": {
      "type": "string",
      "description": "Instagram connected-account id or handle."
    },
    "commentId": {
      "type": "string"
    },
    "message": {
      "type": "string",
      "description": "The reply text."
    }
  },
  "required": [
    "account",
    "commentId",
    "message"
  ]
}

Hide or unhide an Instagram comment on the user's media. Set hidden=false to unhide.

{
  "type": "object",
  "properties": {
    "account": {
      "type": "string",
      "description": "Instagram connected-account id or handle."
    },
    "commentId": {
      "type": "string"
    },
    "hidden": {
      "type": "boolean",
      "description": "true to hide (default), false to unhide."
    }
  },
  "required": [
    "account",
    "commentId"
  ]
}

Permanently delete an Instagram comment on the user's media. Prefer hide_instagram_comment when unsure.

{
  "type": "object",
  "properties": {
    "account": {
      "type": "string",
      "description": "Instagram connected-account id or handle."
    },
    "commentId": {
      "type": "string"
    }
  },
  "required": [
    "account",
    "commentId"
  ]
}

Get analytics for one Instagram post (reach, likes, comments, saved, shares, views). Use list_instagram_media for the mediaId.

{
  "type": "object",
  "properties": {
    "account": {
      "type": "string",
      "description": "Instagram connected-account id or handle."
    },
    "mediaId": {
      "type": "string"
    },
    "mediaProductType": {
      "type": "string",
      "description": "Optional: FEED, REELS, or STORY — refines which metrics are requested."
    }
  },
  "required": [
    "account",
    "mediaId"
  ]
}

Get an Instagram account's profile stats: followers, follows, media count, bio.

{
  "type": "object",
  "properties": {
    "account": {
      "type": "string",
      "description": "Instagram connected-account id or handle."
    }
  },
  "required": [
    "account"
  ]
}

Get an Instagram account's insight trend (a daily time series, e.g. reach) over the last N days.

{
  "type": "object",
  "properties": {
    "account": {
      "type": "string",
      "description": "Instagram connected-account id or handle."
    },
    "metric": {
      "type": "string",
      "description": "Account metric, default reach (e.g. reach, profile_views, accounts_engaged)."
    },
    "days": {
      "type": "number",
      "description": "Window in days (2-30, default 14)."
    }
  },
  "required": [
    "account"
  ]
}

React to a received Instagram direct message (e.g. love).

{
  "type": "object",
  "properties": {
    "account": {
      "type": "string",
      "description": "Instagram connected-account id or handle."
    },
    "conversationId": {
      "type": "string"
    },
    "messageId": {
      "type": "string"
    },
    "recipientId": {
      "type": "string",
      "description": "The other participant's Instagram-scoped user id (IGSID)."
    },
    "reaction": {
      "type": "string",
      "description": "Reaction name, default love."
    }
  },
  "required": [
    "account",
    "conversationId",
    "messageId",
    "recipientId"
  ]
}

List recent @mentions of the workspace's Instagram accounts (captured from Instagram mention webhooks).

{
  "type": "object",
  "properties": {
    "limit": {
      "type": "number",
      "description": "Max mentions (default 30, capped at 100)."
    }
  }
}

List the Instagram direct-message conversations for an account, most recent first. Each conversation includes `counterpart` (the other person's {id, username}) — use its id as the recipientId when replying; `participants` also lists the account itself.

{
  "type": "object",
  "properties": {
    "account": {
      "type": "string",
      "description": "Instagram connected-account id or handle."
    },
    "limit": {
      "type": "number",
      "description": "Max conversations (default 25, capped at 100)."
    },
    "after": {
      "type": "string",
      "description": "Pagination cursor from a previous response."
    }
  },
  "required": [
    "account"
  ]
}

Read the messages in an Instagram direct-message conversation.

{
  "type": "object",
  "properties": {
    "account": {
      "type": "string",
      "description": "Instagram connected-account id or handle."
    },
    "conversationId": {
      "type": "string",
      "description": "Conversation id from list_instagram_conversations."
    },
    "limit": {
      "type": "number",
      "description": "Max messages (default 25, capped at 100)."
    },
    "after": {
      "type": "string",
      "description": "Pagination cursor from a previous response."
    }
  },
  "required": [
    "account",
    "conversationId"
  ]
}

Send an Instagram direct message — a text reply, or an image/video attachment via attachment_url. Only allowed within 24 hours of the recipient's last message unless a message tag (e.g. HUMAN_AGENT) is supplied.

{
  "type": "object",
  "properties": {
    "account": {
      "type": "string",
      "description": "Instagram connected-account id or handle."
    },
    "conversationId": {
      "type": "string",
      "description": "Conversation id (for routing/storage)."
    },
    "recipientId": {
      "type": "string",
      "description": "The recipient's Instagram-scoped user id (IGSID)."
    },
    "text": {
      "type": "string",
      "description": "Message body (omit when sending an attachment)."
    },
    "attachment_url": {
      "type": "string",
      "description": "Public URL of an image/video to send as an attachment."
    },
    "attachment_type": {
      "type": "string",
      "description": "Attachment type: image (default), video, or audio.",
      "enum": [
        "image",
        "video",
        "audio"
      ]
    },
    "tag": {
      "type": "string",
      "description": "Optional message tag, e.g. HUMAN_AGENT, to reply outside the 24h window."
    }
  },
  "required": [
    "account",
    "conversationId",
    "recipientId"
  ]
}

Get workspace usage counters and plan entitlement consumption.

{
  "type": "object",
  "properties": {}
}

Get workspace health, including connection state across providers. Pass provider to check one provider's connections.

{
  "type": "object",
  "properties": {
    "provider": {
      "type": "string",
      "description": "Optional provider to check connection health for."
    }
  }
}