contentstudio
/contentstudio
ContentStudio is a tool to schedule social-media posts, manage the social inbox, and pull performance analytics across Facebook, LinkedIn, Twitter/X, Instagram, YouTube, TikTok, Pinterest, Threads, Tumblr, Bluesky, and Google Business Profile. Use when the user wants to list/create/delete/approve posts, find the best time to post, generate or edit images with AI, read and reply to DMs, comments and reviews, manage media, audit workspaces, accounts, campaigns, labels, categories, or team-members, or pull analytics reports (top posts, engagement, impressions, follower growth, AI insights, etc.)
- Author
- contentstudioio ↗
- Repository
- contentstudio-agent ↗
- Licence
- MIT
- Last repository change
- 13.10.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 31
No signals detected. Repository changed on 13.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
ContentStudio is a tool to schedule social-media posts, manage the social inbox, and pull performance analytics across Facebook, LinkedIn, Twitter/X, Instagram, YouTube, TikTok, Pinterest, Threads, Tumblr, Bluesky, and Google Business Profile. Use when the user wants to list/create/delete/approve posts, find the best time to post, generate or edit images with AI, read and reply to DMs, comments and reviews, manage media, audit workspaces, accounts, campaigns, labels, categories, or team-members, or pull analytics reports (top posts, engagement, impressions, follower growth, AI insights, etc.)
Original author description
ContentStudio is a tool to schedule social-media posts, manage the social inbox, and pull performance analytics across Facebook, LinkedIn, Twitter/X, Instagram, YouTube, TikTok, Pinterest, Threads, Tumblr, Bluesky, and Google Business Profile. Use when the user wants to list/create/delete/approve posts, find the best time to post, generate or edit images with AI, read and reply to DMs, comments and reviews, manage media, audit workspaces, accounts, campaigns, labels, categories, or team-members, or pull analytics reports (top posts, engagement, impressions, follower growth, AI insights, etc.)
How it works
- Hosted MCP server (Cursor, Grok Bot, Grok Build plugins)
- Install ContentStudio CLI if it doesn't exist
- ⚠️ Authentication Required
- Invocation rules for agents
- Pagination — be proactive, don't silently truncate
- Command Reference
- Examples
- Error handling
- When NOT to use this skill
SKILL.md preview
---
name: contentstudio
description: ContentStudio is a tool to schedule social-media posts, manage the social inbox, and pull performance analytics across Facebook, LinkedIn, Twitter/X, Instagram, YouTube, TikTok, Pinterest, Threads, Tumblr, Bluesky, and Google Business Profile. Use when the user wants to list/create/delete/approve posts, find the best time to post, generate or edit images with AI, read and reply to DMs, comments and reviews, manage media, audit workspaces, accounts, campaigns, labels, categories, or team-members, or pull analytics reports (top posts, engagement, impressions, follower growth, AI insights, etc.) on their ContentStudio account.
version: 1.5.0
homepage: https://api.contentstudio.io/guide
metadata: {"openclaw":{"emoji":"📅","requires":{"bins":["contentstudio"],"env":["CONTENTSTUDIO_API_KEY"]}}}
---
## Hosted MCP server (Cursor, Grok Bot, Grok Build plugins)
When this skill is installed as a plugin, it also connects the hosted ContentStudio MCP server at `https://mcp.contentstudio.io/mcp`. The user signs in with their ContentStudio account through OAuth on first use. No API key is needed.
If ContentStudio MCP tools are available (for example `fetch_workspaces`, `fetch_posts`, `create_post`), use them first. Use the CLI below only when the MCP tools are not connected, or for a task the MCP tools don't cover. Before any tool that publishes, deletes, or approves a post, show the user what will happen and wait for them to confirm.
## Install ContentStudio CLI if it doesn't exist
```bash
npm install -g contentstudio-cli
# or
pnpm install -g contentstudio-cli
```
npm release: https://www.npmjs.com/package/contentstudio-cli
contentstudio-agent github: https://github.com/contentstudioio/contentstudio-agent
contentstudio API docs: https://api.contentstudio.io/api-docs
official website: https://contentstudio.io
---
| Property | Value |
|----------|-------|
| **name** | contentstudio |
| **description** | Social-media automation CLI for scheduling posts and managing media/accounts via the ContentStudio public API |
| **allowed-tools** | Bash(contentstudio:*) |
---
## ⚠️ Authentication Required
**You MUST authenticate before running any contentstudio CLI command.** All commands will fail without a valid API key.
Before doing anything else, check auth status:
```bash
contentstudio auth:status
```
If `has_api_key` is `false`, authenticate one of two ways. The user can generate a key from **ContentStudio Dashboard → Settings → API Keys**.
1. **API key (interactive)** — stores the key in the CLI config file:
```bash
contentstudio auth:login --api-key cs_...
```
2. **Environment variable (headless / agent runtimes)** — the CLI reads `CONTENTSTUDIO_API_KEY` from the environment and it takes precedence over the config file:
```bash
export CONTENTSTUDIO_API_KEY=cs_...
```
> **Headless deployment note (OpenClaw, CI, daemons):** a shell `export` does **not** persist to a service process. Set `CONTENTSTUDIO_API_KEY` in the agent's actual environment — e.g. systemd `Environment=` (`systemctl edit`), an `EnvironmentFile=`, or Docker `-e` / compose `environment:` — then restart the service. Runtimes that gate on declared requirements (e.g. OpenClaw's `requires.env`) will stay blocked until this variable is present in the process environment.
Then verify a workspace is selected:
```bash
contentstudio --json workspaces:current
```
If `active_workspace_id` is `null`, list workspaces and ask the user to pick one:
```bash
contentstudio --json workspaces:list
contentstudio workspaces:use <workspace_id>
```
---
## Invocation rules for agents
- **Always pass `--json` before the subcommand** for stable, parseable output.
- **Envelope shape**:
- Success: `{"ok": true, "data": <payload>, "pagination"?: {...}}`
- Error: `{"ok": false, "error": {"type": "<ErrorType>", "message": "...", "http_status": <int>, "hint": "..."}}`
- **Exit codes** are non-zero on error. Check both `returncode` and `ok`.
- **Parse stdout only** — human messages go to stderr.
- **Before any mutating action (posts/comments/media), run it with `--dry-run`** first to verify the payload is correct. `--dry-run` never touches the API.
- **"Share link" is ambiguous — ask which one.** Two unrelated features carry the name: sharing the scheduled **posts** with a client (for comment/approval) and sharing a live **analytics dashboard**. Only the first is reachable from this API, as `planner-share-links:*`; dashboard sharing is web-app-only. If the user did not say which they mean, ask before running anything — do not assume the one the CLI happens to support. Full wording in the callout under **Planner share links**.
### Confirm the target workspace before mutating actions
The CLI silently defaults to the active workspace (whatever was set by `workspaces:use`). That default is fine for **read-only** calls (`workspaces:list`, `accounts:list`, `posts:list`, `media:list`, etc.) — just use the active workspace.
But for any **mutating** action — `accounts:connect`, `accounts:add-bluesky`, `accounts:add-facebook-group`, `accounts:remove`, `posts:create`, `posts:update`, `posts:delete`, `posts:approve`, `posts:reject`, `comments:add`, `media:upload`, `workspaces:update`, `workspaces:delete`, `labels:create`, `labels:update`, `labels:delete`, `campaigns:create`, `campaigns:update`, `campaigns:delete`, `team:add`, `team:update`, `team:remove`, `categories:create`, `categories:update`, `categories:delete`, `categories:shuffle`, `category-slots:create`, `category-slots:update`, `category-slots:delete`, `approval-workflows:create`, `approval-workflows:update`, `approval-workflows:delete`, `approval-workflows:duplicate`, `approval-workflows:set-default`, `approval-workflows:remove-default`, `planner-share-links:create`, `planner-share-links:update`, `planner-share-links:delete`, `planner-share-links:send-invitations`, every `inbox:*` write (`inbox:send`, `inbox:comment-add`, `inbox:comment-delete`, `inbox:review-reply`, `inbox:update`, `inbox:tag-*`, …), and `ai-video:generate` / `ai-video:run-tool` / `ai-video:cancel-job` — you MUST confirm the workspace with the user first, even if a workspace is already active. Don't assume the active workspace is the one they want to mutate.
> **AI video generation costs credits.** `ai-video:generate` and `ai-video:run-tool` submit a real (billed) job the moment they're called without `--dry-run` — run `ai-video:estimate` first when the flags support it, show the estimate/cost to the user, and `--dry-run` the actual call before running it for real. `ai-video:cancel-job` may also charge for partial work already consumed — don't cancel a job on the user's behalf without confirming.
> **Inbox writes are customer-facing.** `inbox:send`, `inbox:comment-add`, and `inbox:review-reply` publish text to a real person on a real social platform, and there is no undo on the provider side. Always `--dry-run` first, show the exact message text to the user, and get explicit approval before sending. Never compose-and-send a reply to a customer in one step.
(`workspaces:create` is the one write that is **not** workspace-scoped — it creates a brand-new workspace and ignores the active one.)
Pattern:
1. Run `contentstudio --json workspaces:current` to see what's active.
2. Tell the user: "Your active workspace is **`<name>`** (`<id>`). Do you want to connect/post/delete in this workspace, or a different one?"
3. If they say a different one, run `workspaces:list`, let them pick, then either:
- Run `workspaces:use <id>` to switch the default, or
- Pass `--workspace <id>` on the single mutating call (preferred when it's a one-off — does not change the active workspace).
4. Only then run the mutating command.
This is mandatory even when the user's request seems to imply the active workspace ("connect a Facebook page", "create a draft post") — they may have just switched contexts in their head and forgotten which workspace is active in the CLI.
## Pagination — be proactive, don't silently truncate
**All list commands return a `pagination` block** in JSON mode when more results exist than fit on one page:
```json
{
"ok": true,
"data": [ /* current page of items */ ],
"pagination": {
"current_page": 1,
"per_page": 10,
"total": 48,
"last_page": 5,
"from": 1,
"to": 10,
"has_more": true
}
}
```
**Mandatory rule**: Whenever `pagination.has_more === true`, the user has more data than what was returned. **You MUST NOT silently treat the current page as "all results"**. Pick one of these three strategies:
1. **Ask the user** (default for ambiguous requests):
> "I retrieved 10 of your 48 workspaces. Do you want me to fetch the rest, or is the first 10 enough for what you're doing?"
2. **Auto-paginate** — if the user's request implies they want everything (e.g. "list ALL my accounts", "show every draft post", "delete all queued posts"):
- Call again with `--per-page <total>` to get everything in one round-trip:
```bash
contentstudio --json workspaces:list --per-page 48
```
- Or iterate `--page 2`, `--page 3`, … `--page <last_page>` if `total` is large (>200) and you want bounded pages.
3. **Filter, don't paginate** — if the user asked for something specific (e.g. "Facebook accounts only"), use the relevant filter flag (`--platform facebook`, `--search "..."`, `--status draft`) instead of paginating. Smaller result set = no pagination needed.
### Quick decision tree for the agent
```
Did the user say "all" / "every" / "complete list" / "every single"?
→ YES: auto-paginate using --per-page <pagination.total>
→ NO:
Did the user give a specific count? ("show me top 5", "first 20 posts")
→ YES: respect that count; use --per-page accordingly
→ NO:
pagination.has_more === true?
→ YES: ASK the user before assuming you have everything
→ NO: you have all the data; proceed
```
### Examples
**User**: "list my workspaces"
**Agent should**:
1. Run `contentstudio --json workspaces:list --per-page 50` (high default to often avoid pagination)
2. If `pagination.has_more` is still true, say: "I see 50 of N workspaces. Want me to fetch all N?"
**User**: "delete all my draft posts"
**Agent should**:
1. Run `contentstudio --json posts:list --status draft --per-page 1` to peek at `total`
2. Run `contentstudio --json posts:list --status draft --per-page <total>` to get them all
3. Iterate over `data[]` and delete each
4. Never delete just the first page and report "done"
**User**: "show me my Facebook accounts"
**Agent should**:
1. Use `--platform facebook` filter — usually returns 0 or a handful, no pagination concern
2. If `has_more` still true (>20 FB accounts), ask before auto-fetching
### Endpoints that paginate
All `*:list` commands paginate:
`workspaces:list`, `accounts:list`, `posts:list`, `comments:list`, `media:list`, `campaigns:list`, `categories:list`, `labels:list`, `team:list`, `approval-workflows:list`, `planner-share-links:list`, `ai-video:jobs`.
`category-slots:list` and `planner-share-links:activity` return everything in one shot and carry no `pagination` block — a category has a handful of slots, and activity answers its own `total`.
Non-list commands (`auth:whoami`, `posts:create`, `posts:delete`, `media:upload`, `ai-video:tools`, `ai-video:models`, `ai-video:job`, etc.) never include `pagination` in their envelope.
---
## Command Reference
All commands are invoked as `contentstudio <group>:<command>`.
### Authentication
| Command | Purpose |
|---------|---------|
| `auth:login --api-key cs_...` | Store and verify API key |
| `auth:logout` | Forget stored credentials |
| `auth:whoami` | Hit `/me` and return user info |
| `auth:status` | Show local config (key redacted) |
### Workspaces
| Command | Purpose |
|---------|---------|
| `workspaces:list` | List user's workspaces |
| `workspaces:use <id>` | Set active workspace |
| `workspaces:current` | Show active workspace |
| `workspaces:create --name <n> --logo <url> --timezone <tz> [--super-admin-id <id>] [--note <t>] [--instagram-posting-method api\|mobile] [--first-day-day <Day> --first-day-key <0-6>]` | Create a new workspace (NOT workspace-scoped) |
| `workspaces:update [<id>] [--name] [--logo] [--timezone] [--note] [--instagram-posting-method] [--first-day-day --first-day-key]` | Update a workspace (defaults to active; ≥1 field required) |
| `workspaces:delete <id>` | Delete a workspace |
| `workspaces:limits` | Plan entitlement + what is left of it (see **Check the limits before a batch** below) |
`workspaces:create` / `workspaces:update`:
- `--name` ≤35 chars, letters/spaces/digits/period only.
- `--logo` must be a URL; `--timezone` is an IANA string (e.g. `Asia/Karachi`).
- `--super-admin-id` (create only) — account owner to create under; required when you manage multiple super admins.
- First day of week is expressed as two paired flags: `--first-day-day <Sunday..Saturday>` + `--first-day-key <index>` where the key is the day's index (`Sunday=0 … Saturday=6`). Both build `first_day: {day, key}`.
- `workspaces:update` defaults to the active workspace if `<id>` is omitted and requires at least one field.
- Errors: `WORKSPACE_DELETE_FAILED` (422) on delete failure; 404 when the workspace doesn't exist.
**Check the limits before a batch.** `workspaces:limits` answers
`{ plan, limits[], usage_reset }` in one cheap call. It is **not cached** — it
is built live on every request, so it already reflects writes you just made.
Run it BEFORE any bulk operation (creating twenty posts, uploading a folder of
media, generating images) rather than discovering a ceiling halfway through and
leaving the user with a half-finished job.
- Each entry in `limits[]` is `{ key, label, used, limit, remaining, scope,
is_unlimited, is_on_plan, unit, period, resets_at, note }`.
- **`scope` decides what `used`/`remaining` actually count, and you must read
it before sizing a batch:**
- `account` — the figure is **shared across every workspace on the
account**. `social_accounts` with `remaining: 3` means three more on the
**whole account**, not three more in this workspace. Account-scoped keys:
`workspaces`, `social_accounts`, `team_members`, `listening_topics`,
`automations`, `media_storage`.
- `workspace` — this workspace only. That is the eight credit counters:
`x_posting_credits`, `listening_mentions`, `ai_text_credits`,
`ai_image_credits`, `ai_video_credits`, `video_clip_credits`,
`ai_auto_reply_credits`, `api_credits`.
- **`key` is the stable identifier — never branch on `label` or `note`.** Both
are localized: the backend resolves `label` through
`limits.labels.<key>` across 8 locales, and composes `note` at runtime from
several localized fragments, so an API key on a non-English account gets
different display text for the same entry.
- **`limit: null` is ambiguous on its own** — check the booleans instead:
`is_unlimited: true` means no ceiling; `is_on_plan: false` means the plan
does not carry the feature at all (that is a hard zero, NOT unlimited). Never
render a null `limit`/`remaining` as `0`.
- `unit` is `count` or `bytes` (`bytes` only for `media_storage`). `period` is
`monthly` or `lifetime`; `resets_at` is an ISO 8601 timestamp for `monthly`
entries and `null` for `lifetime` ones.
- The 14 keys, always all present: `workspaces`, `social_accounts`,
`team_members`, `x_posting_credits`, `listening_topics`,
`listening_mentions`, `ai_text_credits`, `ai_image_credits`,
`ai_video_credits`, `video_clip_credits`, `ai_auto_reply_credits`,
`automations`, `media_storage`, `api_credits`.
- `api_credits` is ONE pool shared by API calls and webhook deliveries —
spending it here spends it there.
- `usage_reset` (`last_reset_at` / `next_reset_at`, ISO 8601 with offset) says
when the monthly counters roll over.
- **There is no `rate_limit` and no `cache` block in the body.** The per-caller
rate ceiling is published on the `X-RateLimit-Limit` /
`X-RateLimit-Remaining` response headers instead; a `429` surfaces as a
`RateLimitError` (exit 5).
### Social accounts (read + connect)
| Command | Purpose |
|---------|---------|
| `accounts:list [--platform <p>] [--search <q>]` | List connected social accounts |
| `platforms:list` | List platforms supported for new account connections |
| `accounts:connect <platform>` | Generate a one-time OAuth URL to connect a new account |
| `accounts:connect <platform> --reconnect --account-id <id>` | Refresh an expired/invalid account |
| `accounts:add-bluesky --handle <h> --app-password <p>` | Connect a Bluesky account (no browser — uses app password) |
| `accounts:add-facebook-group --name <n> [--image <url>]` | Manually add a Facebook Group connection |
| `accounts:remove <account_id>` | Remove (disconnect) a social account. `account_id` is the account's `id` from `accounts:list`. Requires the `save_social` permission (403 otherwise). |
`--platform` values for `accounts:list` filter: `facebook`, `linkedin`, `twitter`, `instagram`, `youtube`, `tiktok`, `pinterest`, `gmb`.
`<platform>` values for `accounts:connect`: `facebook`, `facebook-profile`, `instagram`, `instagram-via-facebook`, `twitter`, `linkedin`, `pinterest`, `tiktok`, `youtube`, `threads`, `gmb`, `tumblr`.
**Account-connection flow for AI agents:**
1. Run `platforms:list` to see what's supported and which method each uses (`oauth` / `credentials` / `manual`).
2. For OAuth platforms (most), call `accounts:connect <platform>` and surface the returned URL to the user — they open it in their browser to authorize. The CLI itself never handles credentials.
3. For Bluesky, ask the user for their handle + app-password (link them to <https://bsky.app/settings/app-passwords>) and call `accounts:add-bluesky`.
4. For Facebook Groups, just call `accounts:add-facebook-group --name "..."`.
### Posts
| Command | Purpose |
|---------|---------|
| `posts:list [--status draft\|scheduled\|...] [--date-from] [--date-to]` | List posts |
| `posts:get <post_id>` | Read one post (identical payload to that post's `posts:list` row) |
| `posts:create -c "text" -i <account> -t <publish_type> [-s "YYYY-MM-DD HH:MM:SS"] [-m <image_url>]` | Create a post (shortcut mode) |
| `posts:create -c "text" -t content_category --content-category-id <cat_id>` | Create a content-category post (accounts come from the category) |
| `posts:create -c "text" -i <fb_account> -t draft --facebook-carousel '<json>'` | Create a Facebook carousel post (2–10 cards) |
| `posts:create -c "text" -i <threads_account> -t draft --threads '<json>'` | Create a Threads multi-thread (chained) post (max 10 items) |
| `posts:create -c "text" -i <twitter_account> -t draft --twitter '<json>'` | Create a Twitter/X threaded-tweet post (max 10 tweets) |
| `posts:create -c "text" -i <account> -t draft --first-comment "..." --first-comment-account <id>` | Create a post with a first comment |
| `posts:create -c "text" -i <linkedin_account> -t draft --post-type poll --linkedin-options '<json>'` | Create a LinkedIn poll post (text-only) |
| `posts:create -c "text" -i <ig_account> -t draft --post-type reel --video-url <url> --instagram-trial-reel` | Create an Instagram trial reel (shown to non-followers first) |
| `posts:create -c "common text" -i <fb_account> -i <tiktok_account> -t draft -m <img_url> --platform-overrides '<json>'` | Same post to multiple platforms with a per-platform content override |
| `posts:create -c "text" -i <account> -t scheduled -s "..." --repeat-type Week --repeat-times 4 --repeat-gap 1` | Create a post that repeats (spawns 4 independent child posts) |
| `posts:create --body /path/to/body.json` | Create a post with full JSON body |
| `posts:update <post_id> [same flags as posts:create]` | Update an existing post (same body). Rejected (422) once the post is published/processing |
| `posts:delete <post_id> [--delete-from-social]` | Delete a post |
| `posts:approve <post_id> [--comment "..."]` | Approve a pending post |
| `posts:reject <post_id> [--comment "..."]` | Reject a pending post |
`-t / --publish-type` values: `scheduled`, `draft`, `queued`, `content_category`. (`scheduled` and `draft` want `-s / --scheduled-at`.) There is no publish-now type — to send something immediately, schedule it at the next minute.
`posts:get <post_id>` returns a single post whose payload is identical to that post's row in `posts:list` — use it to re-read one post after a write instead of re-listing. A deleted post, a post in another workspace, and a malformed id all answer **404**, so a 404 is not proof the id never existed.
`posts:update <post_id>` takes the **exact same flags and body** as `posts:create` (both `--body` and shortcut mode) — it PUTs to `/workspaces/{w}/posts/{post_id}`. The backend allows the update only while the post's status is **not** `published` or `processing` (otherwise it returns 422). Use `--approval-workflow-action` (below) on update to change an already-attached workflow.
**`posts:create` / `posts:update` shortcut-mode flags:**
- `-c / --content` (required) — post text.
- `-i / --account <id>` (repeatable) — account ID(s) to post to. **Required UNLESS `--content-category-id` is given.**
- `--content-category-id <id>` — sets top-level `content_category_id`. **Required by the backend when `--publish-type content_category`.** When set, accounts are derived from the category, so `--account` is not required (and may be omitted). Use this instead of `--account` for content-category posts.
- `-s / --scheduled-at "YYYY-MM-DD HH:MM:SS"` — scheduling time. The CLI normalizes any parseable date to `YYYY-MM-DD HH:MM:SS` (the backend's required `date_format`) and sends it as a plain wall-clock string. **The API reads it in the workspace's timezone, not UTC** — so pass the local time the user wants the post to fire at, and get the zone from `workspaces:current` if you're unsure. `scheduling:best-times` already returns slots in that zone, so they can be passed straight through.
- `-m / --image-url <url>` (repeatable), `--video-url <url>`, `--media-id <id>` (repeatable) — media.
- `--post-type <type>` — e.g. `feed`, `reel`, `carousel`, `story`, `poll`. A **carousel** is auto-derived by the backend when `post_type=carousel` and 2+ images are attached. A **poll** requires `--post-type poll` **and** a text-only `--linkedin-options` poll block (no media).
- `--label <id>` (repeatable, max 20) → `labels`.
- `--campaign-id <id>` → `campaign_id`.
- **Repeat** `--repeat-type Day|Week|Month` + `--repeat-times <1-30>` + `--repeat-gap <1-99>` → `scheduling.repeat`. All three are required together (the CLI errors locally otherwise) and the CLI always sends `enabled: true` with them, which the backend requires whenever the `repeat` key is present at all.
- **Only valid with `--publish-type scheduled`.** `draft`, `queued` and `content_category` are refused, and the CLI errors locally before the call goes out.
- `--repeat-gap` must be **≥3 when `--repeat-type Day`** (the composer refuses a tighter daily repeat).
- Creates **N independent child posts**, not one recurring post — editing or deleting the parent does not touch the children. Children drop Twitter/X and YouTube accounts. Each child carries the post's approvers.
- **Repeat is never inherited on update.** A `posts:update` without the repeat flags creates no children, so a read-modify-write of a repeating post is safe: you cannot accidentally re-spawn the series by round-tripping it.
- On the **read** side (`posts:get` / `posts:list`) `scheduling.repeat` is `{is_parent, is_child, parent_id, type, times, gap}` — there is **no `enabled` key**, that one is request-only. Do not feed a read payload's repeat block straight back into an update and expect it to mean the same thing.
- `--linkedin-options '<json>'` → `linkedin_options` (**LinkedIn accounts**). Pass a JSON **object**; the CLI parses it locally (invalid JSON → `ConfigError`) and sends it verbatim.
- Shape: `{ "title"?: <string>, "poll"?: { "question": <≤140>, "options": <string[2..4], each ≤30>, "duration": "ONE_DAY" | "THREE_DAYS" | "SEVEN_DAYS" | "FOURTEEN_DAYS" } }`
- A **poll** must be paired with `--post-type poll` and text-only content (no images/video). Backend validates and 422s on violations.
- `--facebook-collaborator <user_id>` (repeatable, **max 10**) → `facebook_options.collaborators` (Facebook accounts). Merges with `--facebook-carousel` / `--facebook-background-id`.
- `--instagram-collaborator <user_id>` (repeatable, **max 3**) → `instagram_options.collaborators` (Instagram accounts). Rejected (422) together with `--instagram-trial-reel`.
- `--instagram-trial-reel` (boolean, default `false`) → `instagram_options.trial_reel.enabled`. Publishes an Instagram **trial reel** — shown to non-followers first, so it does not appear on the profile grid or in follower feeds.
- `--instagram-trial-reel-graduation SS_PERFORMANCE|MANUAL` (default `SS_PERFORMANCE`) → `instagram_options.trial_reel.graduation_strategy`. `SS_PERFORMANCE` lets Instagram auto-graduate it to followers if it performs well; `MANUAL` requires graduating it by hand in the Instagram app (Instagram has no API for that).
- Requires `--post-type reel` **exactly** (not `feed+reel`) and a video — feed/carousel/story are rejected. The CLI does not pre-validate this; the backend returns 422.
- **Rejected (422) together with `--instagram-collaborator`.** Share-to-story is silently dropped (not rejected) when combined with a trial reel.
- Not available when the workspace posts to Instagram via the mobile app (`instagram_posting_option=mobile`).
- `--platform-overrides '<json>'` → `platform_overrides` (top-level, works across any platform in the post). Pass a JSON **object** keyed by platform (`facebook`, `instagram`, `twitter`, `linkedin`, `pinterest`, `youtube`, `tiktok`, `gmb`, `tumblr`, `threads`, `bluesky`, `telegram`); the CLI parses it locally (invalid JSON → `ConfigError`) and sends it verbatim.
- Shape per platform: `{ "content": { "text"?: <string>, "post_type"?: <string>, "media"?: { "images"?: <url[] ≤10>, "video"?: <url> } } }`.
- `text` and `post_type` each merge **independently** with the common top-level `content` — an override with only `media` still inherits the common `text`/`post_type`.
- `media` is **atomic**: if an override's `content` includes a `media` key at all, that platform's media is defined ENTIRELY by the override (no per-field fallback to the common media for whichever of `images`/`video` it omits). Omitting `media` entirely inherits the common `content.media` wholesale. This exists because some platforms (e.g. TikTok) can never support mixed images+video.
- Omitting `--platform-overrides` entirely publishes the same top-level `content` to every targeted platform.
- Override images are URLs only (no `media_ids`) and follow the same validation as the top-level media (max 10 images, no mixing images+video in one override).
- **Approval — two mutually-exclusive systems (pass only one):**
- **Legacy** `--approver <user_id>` (repeatable) + `--approve-option anyone|everyone` (default `anyone`) + `--approval-notes "..."` → builds `approval: {approvers, approve_option, notes}` only when at least one approver is given. The post creator cannot be an approver. `anyone` = any single approver; `everyone` = all must approve.
- **Workflow** `--approval-workflow-id <id>` + `--approval-workflow-notes "..."` → `approval_workflow: {workflow_id, notes?}` — ATTACH a workflow (works on both create and update). Get the id from `approval-workflows:list` (its `id`).
- **Workflow (update only)** `--approval-workflow-action restart|resume|renotify_current|keep|remove` + `--approval-workflow-notes "..."` → `approval_workflow: {workflow_action, notes?}` — mutate the already-attached workflow. Only valid on `posts:update`.
- **Exactly one** of `--approval-workflow-id` / `--approval-workflow-action`, and `--approver` cannot be combined with either `--approval-workflow-*` flag. The CLI errors locally (`ConfigError`) if these rules are broken.
- `--facebook-background-id <id>` → `facebook_options.facebook_background_id` (plain-text Facebook posts only; rejected if media is attached). Get a valid id from `facebook:text-backgrounds`.
- `--facebook-carousel '<json>'` → `facebook_options.carousel` (**Facebook accounts only**). Pass a JSON **object**; the CLI parses it locally (invalid JSON → `ConfigError`) and adds `is_carousel_post: true`. It **merges** with `--facebook-background-id` (neither clobbers the other). The backend validates card counts/CTA/limits and returns a 422 if they're wrong.
- Shape: `{ "cards": [ { "image": <url, required>, "link": <url, required>, "title"?: <≤255>, "description"?: <≤1000> } ], "call_to_action"?, "end_card"?: <bool>, "end_card_url"?: <url>, "accounts"?: <string[]> }`
- **MIN 2, MAX 10 cards.** The Facebook account ID(s) still go in the top-level `-i / --account` (or in `carousel.accounts`).
- `call_to_action` is one of 33 values: `NO_BUTTON`, `ADD_TO_CART`, `APPLY_NOW`, `BET_NOW`, `BOOK_TRAVEL`, `BUY_NOW`, `BUY_TICKETS`, `CALL_NOW`, `CONTACT_US`, `DOWNLOAD`, `GET_DIRECTIONS`, `GET_OFFER`, `GET_QUOTE`, `GO_LIVE`, `INSTALL_MOBILE_APP`, `LEARN_MORE`, `LIKE_PAGE`, `LISTEN_MUSIC`, `OPEN_LINK`, `ORDER_NOW`, `PLAY_GAME`, `REGISTER_NOW`, `REQUEST_TIME`, `SAVE`, `MESSAGE_PAGE`, `WHATSAPP_MESSAGE`, `SHOP_NOW`, `SIGN_UP`, `SUBSCRIBE`, `USE_APP`, `WATCH_MORE`, `WATCH_VIDEO`.
- `--threads '<json>'` → `threads_options` (**Threads accounts only**). Pass a JSON **array** of thread items; the CLI parses it locally (invalid JSON → `ConfigError`), sets `has_multi_threads: true` and `multi_threads: <array>`. The Threads account ID goes in the top-level `-i / --account`.
- Shape: `[ { "message": <string>, "media"?: <url[] ≤10>, "media_ids"?: <string[] ≤10> } ]`
- **MAX 10 items.** Each item needs `message` OR `media`. Threads allows mixed media. Backend validates limits and returns a 422 if exceeded.
- `--twitter '<json>'` → `twitter_options` (**Twitter/X accounts only**). Pass a JSON **array** of tweet items; the CLI parses it locally (invalid JSON → `ConfigError`), sets `has_threaded_tweets: true` and `threaded_tweets: <array>`. The Twitter account ID goes in the top-level `-i / --account`. This mirrors `--threads` but for Twitter threaded tweets.
- Shape: `[ { "message": <string>, "media"?: <url[] ≤10>, "media_ids"?: <string[] ≤10> } ]`
- **MAX 10 tweets.** Each item needs `message` OR `media`. **Twitter does NOT allow mixed media in one tweet** (no images + video together) and **max 1 video per tweet**. The CLI does not validate tweet contents — the backend enforces these limits and returns a 422 if violated.
- `--first-comment "<message>"` → `first_comment` (≤2000 chars). The CLI builds `first_comment: { message, accounts? }`. The accounts are supplied with `--first-comment-account <id>` (repeatable).
- `--first-comment-account <id>` (repeatable) → `first_comment.accounts`. **The backend REQUIRES at least one account when a `--first-comment` message is given, and the accounts must be a subset of the post's main `--account` IDs.** The CLI does not hard-block client-side — if you omit `--first-comment-account`, the backend returns a 422.
(`--facebook-carousel`, `--facebook-collaborator`, `--instagram-collaborator`, `--instagram-trial-reel`, `--instagram-trial-reel-graduation`, `--linkedin-options`, `--platform-overrides`, `--threads`, and `--twitter` only apply in shortcut mode. The `--body` JSON mode already supports `facebook_options` (carousel + collaborators), `instagram_options` (`collaborators` + `trial_reel`), `linkedin_options`, `threads_options`, `twitter_options`, `first_comment`, `approval`, `approval_workflow`, and top-level `platform_overrides` natively — use it for posts that mix multiple platform option blocks.)
The `posts:list` payload now includes `linkedin_options` and `approval_workflow` per post (in addition to the existing fields) — they surface automatically in the `--json` output.
### Scheduling — best time to post
| Command | Purpose |
|---------|---------|
| `scheduling:best-times` | Ranked posting slots for the workspace, derived from the connected accounts' history |
| `scheduling:best-times --account <platform>:<account_id>` | Restrict the analysis to specific accounts (repeatable) |
| `scheduling:best-times --global-slots <n> --per-account-slots <n>` | How many recommendations to return (1–24 each) |
| `scheduling:best-times --entities '<json>'` | Full entity array, for per-account slot counts |
A **slot** is one recommended posting time: a weekday and an hour. Slots come back ranked best-first, so `--global-slots 3` means *the three best hours to post*.
- **Times are always in the workspace timezone**, echoed as `meta.timezone`. There is no timezone parameter. That is the same clock `posts:create --scheduled-at` writes against, so a slot can be scheduled as-is — do **not** convert it to UTC first.
- **Omit `--account` to analyse every connected account.** Otherwise pass `<platform>:<account_id>` where both halves come from one `accounts:list` row (its `platform` and `_id`), e.g. `--account facebook:<account_id>`. Supported platforms: `facebook`, `instagram`, `linkedin`, `twitter`, `tiktok`, `youtube`, `pinterest`, `threads`, `gmb`, `tumblr`, `bluesky`, `telegram`.
- `--entities '[{"id":"<account_id>","type":"facebook","slots":3}]'` is the escape hatch for a **different slot count per account**; it cannot be combined with `--account`.
- `--global-slots` (API default 5) sizes the pooled `global` view; `--per-account-slots` (API default 3) sizes each account's list. Both are 1–24 and are validated by the CLI before the call. Neither changes the underlying analysis or the `heatmap_matrix`, which always carries every hour that had signal.
**Response shape** (`data` in the JSON envelope):
- `meta` — `{generated_at, timezone, warnings[], missing_entities[], ai_fallback_entities[]}`.
- `global` — pooled across analysed accounts: `top_recommendations[]` (each `{rank, day, date, time, score, platform_breakdown}`, where `time` is the hour as a bare string, e.g. `"14"` = 14:00), plus `heatmap_matrix.data` (sparse `[hour, day_index, score]` triples, `day_index` 0 = Monday) and `dates_key`. **`null` when no account had usable data.**
- `individual` — the same breakdown keyed by account id, each with `platform` and `source` (`data_driven` or an AI fallback).
**A thin workspace still returns HTTP 200.** Accounts with too little history come back in `meta.missing_entities` and `global` may be `null` — that is a successful read, not an error. Tell the user which accounts were skipped rather than reporting a failure. Accounts listed in `meta.ai_fallback_entities` are estimates, not measurements — say so when you present them.
Errors: 422 for unknown accounts or a workspace with no connected accounts; 502 (`BackendError`) when the optimizer is temporarily unavailable — retry rather than reporting no data.
**Reading is safe.** `scheduling:best-times` only reads, so it needs no `--dry-run` and no workspace confirmation. Scheduling a post from a slot is a mutation, so the usual `--dry-run` + workspace-confirmation rules apply to that step.
### Comments / Internal notes
| Command | Purpose |
|---------|---------|
| `comments:list <post_id>` | List comments on a post |
| `comments:add <post_id> "message" [--note] [--mention <user_id>]` | Add public comment or internal note |
### Media library
| Command | Purpose |
|---------|---------|
| `media:list [--type images\|videos] [--sort recent\|...]` | List media assets |
| `media:upload --file <local_path>` | Upload a local file |
| `media:upload --url <external_url>` | Import from external URL |
### AI images
| Command | Purpose |
|---------|---------|
| `images:tools` | The image tools this API can invoke, with each tool's required inputs and control options |
| `images:models` | Model identifiers `images:generate` accepts |
| `images:brand` | `{configured, enabled}` — whether `--use-brand` will apply anything |
| `images:generate -p "<prompt>"` | Prompt → image, saved to the media library |
| `images:generate -p "<edit>" --image-url <url>` | Edit an existing image instead of generating from scratch |
| `images:product-image --product-image-url <url>` | Restage a product photo |
| `images:headshot --image-url <url>` | Professional headshot from a photo of a person |
| `images:face-swap --target-image-url <url> --face-image-url <url>` | Put one image's face onto another's subject |
| `images:outfit-swap --target-image-url <url> --outfit-image-url <url>` | Virtual try-on |
| `images:upscale --image-url <url>` | Raise an image's resolution |
| `images:remove-background --image-url <url>` | Cut the subject out of its background |
| `images:tool <tool_key> --body '<json>'` | Any tool, with its full control set (this is how you reach `image-to-image`'s `style`, `aspect_ratio`, `image_resolution`, `image_quality`, multiple `attachments`, `reference_image_urls`) |
**Every generation returns the same payload, and `data.media_id` is the handle you pass to `posts:create --media-id`.** That two-step is the normal way to publish an AI image — see the generate-then-publish recipe in the Examples section.
```jsonc
{ "ok": true, "data": {
"media_id": "66f1a2b3c4d5e6f708192a3b", // → posts:create --media-id
"url": "https://storage.googleapis.com/.../generated.png",
"width": 1024, "height": 1024, "mime_type": "image/png",
"model_used": "nano-banana-pro", // may differ from --model
"brand_applied": false,
"credits": { "consumed": 1, "available": 412 },
"persist_error": null } }
```
- **`media_id` is the durable handle; `url` is not.** Use `url` for a preview or as the input to the next tool. Do not store it — a `url` returned alongside a `persist_error` is a temporary provider link.
- **Check `persist_error` (or `media_id !== null`) before calling a 200 done.** The image was generated *and charged* but could not be saved: `media_storage_full` means the workspace is out of media storage (retrying costs another credit and fails again), anything else is worth one retry. Tell the user to download the `url` now.
- **Tools chain.** A media-library `url` from one call is valid input to the next (generate → upscale → remove-background). Each call is charged separately.
- **Every image URL you pass in must be publicly fetchable over http(s)** by the image service — no auth, no expired signed URL, no private bucket, no local path. Upload a local file with `media:upload --file` first and pass the returned URL. A URL the service cannot download is `ValidationError` (`IMAGE_INPUT_REJECTED`), not a service outage.
- **Generation is slow and billable.** The server's deadline is 120s; the CLI waits 150s (`--timeout <seconds>` to change it). These calls are **not retried** — the built-in 429/5xx retry is off for them, because re-running a generation can consume a second image credit. Retry deliberately, not in a loop.
- **`--model` is optional.** Omit it for the service default. Costs differ (most models 1 image credit, `gpt-image-2` 5, `gpt-image-2.5-flare` 3, `gpt-image-2.5-sunburst` 5), so read `credits.consumed` rather than assuming. `images:models` lists each model's `credits_per_image`. Every listed model, including `gpt-image-2.5-flare` and `gpt-image-2.5-sunburst`, generates and edits (`--image-url`).
- **`--background <auto|opaque|transparent>`** sets the image background (sent as `image_background`). Only `gpt-image-2.5-flare` and `gpt-image-2.5-sunburst` honor it; every other model ignores it silently. Use `--background transparent` for logos, stickers and cut-outs, and pair it with one of those two models.
- **`model_used` is not one of the `images:models` values** — it comes back provider-prefixed (`fal-ai/nano-banana-pro`, `pixelcut/background-removal`) and names the model that actually ran after any fallback. Report it; never compare it for equality with `--model`.
- **`images:tools` `controls` describe the underlying tool, not the public payload.** Take `--resolution` / `--aspect-ratio` values from there, but a control with no matching flag cannot be sent at all — `upscale` lists `model` and `upscale_factor`, and neither is in the API's tool payload. Likewise `accepts_instructions: true` on `headshot` and `face-swap` is not reachable: only `images:product-image` has `--instructions`. Sending an unsupported field is dropped in silence, so it will look like it worked.
- **`--dimensions`** is `square`, `square_hd`, `portrait_4_5` or `landscape_16_9`, text→image only. Exact pixels are the model's choice — read `width`/`height` back. Anything else is rejected by the CLI before the call.
- **Brand knowledge is a boolean, read-only.** `--use-brand` on `images:generate` only; it is resolved server-side and no brand ID or brand content is ever accepted or returned. `--use-brand` with no brand profile is `brand_applied: false`, not an error — `images:brand` tells you in advance. **The tool commands and `images:generate --image-url` always report `brand_applied: false`** — edits and tools do not apply brand knowledge.
- **`--dry-run` on every generating command** prints the endpoint and body and calls nothing. Use it to show the user the prompt before spending a credit. The three discovery commands are reads and need no `--dry-run`.
- **Rate limit: 30 requests/minute**, shared with the ContentStudio app's own AI usage on the same account. A `RateLimitError` here needs the full minute.
- Video tools (`image-to-video`, `motion-control`, `lip-sync`, `talking-avatar`) are **not** on this API; asking for one is `NotFoundError` (`TOOL_NOT_FOUND`), same as an unknown key.
- `images:tools` answering with an empty list means the catalogue is temporarily unreachable, not that the workspace has no tools. Retry rather than telling the user there are none.
- Sample workspaces are read-only: the three discovery commands work, both generating paths return 403.
### AI Video
| Command | Purpose |
|---------|---------|
| `ai-video:tools` | List enabled AI video tools (`key`, `label`, `description?`, `inputs[]`, `controls[]`) |
| `ai-video:models` | List every model `ai-video:generate` / `ai-video:estimate` can select (`key`, `provider`, `modes[]`, `supported_resolutions?`, `supported_durations?`, `supported_ratios?`, `supports_audio?`, defaults) |
| `ai-video:estimate [--duration] [--model] [--resolution] [--mode text-to-video\|image-to-video\|reference-to-video] [--audio] [--aspect-ratio] [--enhance-prompt]` | Real credit/time estimate. Nothing submitted or charged |
| `ai-video:generate --prompt "..." [--image-url \| --reference-image-url <url> (repeatable)] [--model] [--duration] [--resolution] [--aspect-ratio] [--audio] [--enhance-prompt] [--style] [--use-brand]` | Submit an async video generation job |
| `ai-video:run-tool motion-control --image-url <url> --video-url <url>` | Apply motion from a driving video to a source image |
| `ai-video:run-tool lip-sync --video-url <url> --audio-url <url>` | Sync a video's mouth movement to an audio track |
| `ai-video:run-tool talking-avatar --image-url <url> --audio-url <url>` | Animate a still image into a talking avatar from audio |
| `ai-video:jobs [--status queued\|processing\|completed\|failed\|cancelled] [--page] [--per-page]` | Paginated list of video jobs submitted through this API (never chat/internal-tool jobs) |
| `ai-video:job <job_id>` | Single job status — local snapshot if terminal, live-polled otherwise |
| `ai-video:cancel-job <job_id>` | Cancel a still-active job. May charge for partial work already consumed |
**`ai-video:generate` notes:**
- `--prompt` is required, max 1000 characters.
- Omitting both `--image-url` and `--reference-image-url` is **text-to-video**. `--image-url` switches to **image-to-video**. `--reference-image-url` (repeatable, max 8) switches to **reference-to-video**. `--image-url` and `--reference-image-url` are **mutually exclusive** — the CLI raises a `ConfigError` locally if both are set.
- `--use-brand` (default false) resolves brand assets **server-side** — there is no `--brand-id` flag; the backend does not accept one.
- Response `data`: `{ job_id, status_url (relative path to ai-video:job), status, estimated_credits, estimated_seconds? }`. Poll `ai-video:job <job_id>` (or fetch `status_url` directly) until `status` is terminal.
**`ai-video:run-tool <tool_key>` notes:**
- `tool_key` is one of the keys from `ai-video:tools` — currently `motion-control`, `lip-sync`, `talking-avatar`. The CLI validates the required input pair locally before sending (`motion-control` → image+video, `lip-sync` → video+audio, `talking-avatar` → image+audio) and raises `ConfigError` if a required flag is missing.
- No upfront estimate — the response's `estimated_credits` / `estimated_seconds` are always `null`. Run `ai-video:tools` to see each tool's declared `inputs[]` / `controls[]` if the flags above don't cover a newer tool.
**`ai-video:jobs` / `ai-video:job` / `ai-video:cancel-job` notes:**
- `ai-video:jobs` only ever returns jobs **submitted through this API** — chat/internal-tool-generated jobs never appear.
- Job `status` is one of `queued`, `processing`, `completed`, `failed`, `cancelled`. `stage` / `message` / `result` / `credits` / `brand_applied` are present depending on status.
- `ai-video:cancel-job` 409s (`ConflictError`) with `JOB_ALREADY_TERMINAL` if the job already finished, failed, or was cancelled — check `ai-video:job <job_id>` first if unsure.
**Errors specific to AI Video** (in addition to the standard table below): 403 `INSUFFICIENT_VIDEO_CREDITS` (not enough credits — surfaces as `AuthError`), 403 `STORAGE_LIMIT_EXCEEDED` (surfaces as `AuthError`), 404 `TOOL_NOT_FOUND` / `JOB_NOT_FOUND` (`NotFoundError`), 409 `JOB_ALREADY_TERMINAL` (`ConflictError`), 502 `AI_SERVICE_UNAVAILABLE` / 504 `AI_SERVICE_TIMEOUT` (`BackendError` — safe to retry after a short backoff).
### Lookup tables (read)
| Command | Purpose |
|---------|---------|
| `campaigns:list` | List campaigns (folders) |
| `categories:list` | List content categories |
| `labels:list` | List labels |
| `team:list` | List workspace team members |
| `approval-workflows:list` | List approval workflows (use an item's `id` as `--approval-workflow-id`) |
Each `approval-workflows:list` item is `{ id, name, is_default, levels: [{ level_number, title, rule, members: [{ user_id }] }] }`. Use `id` as `posts:create` / `posts:update`'s `--approval-workflow-id`.
`approval-workflows:list` needs the `manage_workflow` permission like the rest of that group — see **Approval workflows (write)** below. `categories:list` is the entry point for **Content categories (write) + posting slots**.
### Content categories (write) + posting slots
A content category is an evergreen bucket: posts dropped into it are dealt out
across the category's weekly **slots** instead of being given a time each. Use
`categories:list` to find one, then:
| Command | Purpose |
|---------|---------|
| `categories:get <category_id>` | Read one category — the response **inlines `slots[]`**, so no second call |
| `categories:create --name <n> --color <color_N> [--account <id>…] [--allowed-member <user_id>…]` | Create a category |
| `categories:update <category_id> [--name] [--color] [--account…] [--allowed-member…]` | Partial update |
| `categories:delete <category_id>` | Delete a category |
| `categories:shuffle <category_id>` | Re-deal the category's upcoming posts across its slots |
| `category-slots:list <category_id>` | List the category's weekly slots |
| `category-slots:next <category_id> [--post-id <id>]` | Resolve the next free slot |
| `category-slots:create <category_id> --day <d> --hour <h> --minute <m> --period AM\|PM` | Add one slot |
| `category-slots:update <category_id> <slot_id> [--day] [--hour] [--minute] [--period]` | Partial update of one slot |
| `category-slots:delete <category_id> <slot_id>` | Delete one slot |
- `--name` ≤100 chars; `--color` is `color_1` … `color_20` (same enum as labels/campaigns).
- `--account` (repeatable) is ONE **flat** list of social account ids mixed across platforms — not a per-platform map. `--allowed-member` (repeatable) takes team-member **user ids**; every one must be on the workspace team or the call 422s.
- Both write commands **replace** the array they are given: `categories:update --account a1` leaves the category with exactly one account.
- `--day` is lowercase (`sunday` … `saturday`). `--hour` is a **12-hour** clock, `0`–`12`, paired with `--period AM|PM`; **12 normalises to 0**, so hour 12 + `AM` is midnight and hour 12 + `PM` is noon. `--minute` is `0`–`59`. The CLI sends both as JSON **integers** — a string `"12"` slips past the backend's noon normalisation and persists an hour the scheduler cannot match.
- Slot rows carry `weekday_sorting` (Sunday = 0) — the index the scheduler orders by, so sort on that rather than re-deriving day order from the name.
- `categories:shuffle` on a category with nothing upcoming answers `{"shuffled_posts_count": 0}` with a **success** envelope. Zero is an answer, not a failure — report it as "nothing to shuffle", not as an error.
- `category-slots:next` answers `{next_slot, timezone, scheduled}`. **`next_slot: null` comes back on a 200** and means the category has no upcoming slot. `--post-id` asks what slot that specific post would take; `scheduled: true` means the answer is the post's own existing time rather than a free slot.
- Errors: `CONTENT_CATEGORY_NOT_FOUND` (404), `CONTENT_CATEGORY_ACCESS_DENIED` (403), `CONTENT_CATEGORY_IS_GLOBAL` (422 — global categories cannot be edited or deleted through the API), `CONTENT_CATEGORY_INVALID_ACCOUNT` (422), `CONTENT_CATEGORY_SHUFFLE_FAILED` (422), `CONTENT_CATEGORY_SLOT_NOT_FOUND` (404), `CONTENT_CATEGORY_SLOT_DUPLICATE` (422 — that weekday/time is already taken).
### Approval workflows (write)
| Command | Purpose |
|---------|---------|
| `approval-workflows:get <workflow_id>` | Read one workflow |
| `approval-workflows:create --name <n> --levels '<json>' [--draft]` | Create a workflow |
| `approval-workflows:update <workflow_id> [--name] [--levels '<json>'] [--draft] [--confirmed]` | Partial update |
| `approval-workflows:delete <workflow_id> [--force]` | Delete a workflow |
| `approval-workflows:duplicate <workflow_id>` | Copy it into a new workflow |
| `approval-workflows:set-default <workflow_id>` | Make it the workspace default |
| `approval-workflows:remove-default <workflow_id>` | Clear the default flag |
| `approval-workflows:cascade-job <cascade_job_id>` | Poll a background cascade |
- **Every command in this group — `approval-workflows:list` included — requires the `manage_workflow` permission.** A caller who can read posts may still get a 403 here; that is a permission answer, not a bad key, so do not send the user to `auth:login` for it.
- `--name` ≤120 chars. `--levels` is a JSON **array**: `[{"level_number":1,"title":"Editors","rule":"anyone"|"everyone","members":[{"user_id":"<id>"}]}]`. `level_number` must be unique across the payload, member ids must be unique within a level, and every member must be on the workspace team.
- `--draft` → `is_draft`. A workflow with an unstaffed level is a draft regardless of the flag, and **a draft cannot be the default** — `set-default` on one answers `CANNOT_SET_DRAFT_AS_DEFAULT` (422).
- `is_default` is **not** accepted on create/update — promote with `set-default`.
- **`--confirmed` on update re-applies the edited workflow to posts already in review.** That answers **202** with `cascade_job_id` instead of the workflow; the write landed but the re-application is still running. Poll it with `approval-workflows:cascade-job <id>` until `status` is terminal before telling the user the change took effect everywhere. Without `--confirmed` the edit only affects future posts.
- **Delete with posts in flight is refused**: 422 `REQUIRES_FORCE_DELETE`, with `context.in_flight_posts_count`. Show that count to the user and get an explicit go-ahead before re-running with `--force` — forcing deletes the workflow AND cleans those posts up (202 + `cascade_job_id`). The response also carries `was_default: true` when you just removed the workspace's default, leaving it with none until another is promoted; say so.
- Errors: `APPROVAL_WORKFLOW_NOT_FOUND` (404), `CANNOT_SET_DRAFT_AS_DEFAULT` (422), `REQUIRES_FORCE_DELETE` (422), `CASCADE_JOB_NOT_FOUND` (404).
### Planner share links
A planner share link is a public URL that shows someone outside the workspace
the scheduled **posts**, optionally letting them comment or approve.
> **STOP — two unrelated features are both called "share link".** If the user
> said "share link", "share a link", "send a link to the client" or anything
> else without naming which, **ASK before running anything**. Do not guess, and
> do not infer one from the surrounding conversation. The two create different
> records on different endpoints and are not interchangeable.
>
> Ask them, roughly:
>
> > "Two different things are called a share link in ContentStudio — which do
> > you want?
> > **(a) A planner share link** — shows the client the actual scheduled
> > **posts**, and can let them comment on them or approve/reject them.
> > **(b) An analytics share link** — shows the client a live **analytics
> > dashboard/report**: follower growth, engagement, top posts. Read-only
> > numbers, no posts."
>
> Then:
>
> - **(a) → `planner-share-links:*`** (this section). Proceed normally.
> - **(b) → tell them it is not available here.** Analytics dashboard sharing
> has no public-API endpoint — it exists only on the internal, session-authed
> API the web app uses, which an API key cannot reach. Say so plainly and
> point them at the ContentStudio web app (Analytics → the report → Share).
> **Do not run `share-links:*`** hoping it works; see the warning in
> **Analytics: reports, schedules, share links**.
>
> Answering (b) with "I can't do that from here, but here is where you can" is
> the correct outcome. Quietly building a planner link instead, because that is
> the one that works, is not — the user would be handed posts when they asked
> for numbers.
>
> Only skip the question when the user has already named the feature
> unambiguously — "planner share link", "let the client approve these posts" →
> (a); "analytics share link", "share the report/dashboard" → (b) — or when
> they are clearly continuing work on a specific link you already created in
> this conversation. Skipping the question still means answering the branch
> they named: an unambiguous (b) goes straight to "not available here", not to
> a planner link.
| Command | Purpose |
|---------|---------|
| `planner-share-links:list` | List the workspace's planner share links |
| `planner-share-links:get <link_id>` | Read one link |
| `planner-share-links:create --name <n> [--plan <post_id>…] [--note <id>…] [--scope] [--view] [--calendar-date] [--password] [--single-post] [--allow-comments] [--allow-approval-actions] [--show-notes] [--social-selections '<json>']` | Create a link |
| `planner-share-links:update <link_id> [same fields, plus --disabled / --approval-flow / --approval-email / --approval-option]` | Partial update |
| `planner-share-links:delete <link_id>` | Delete a link |
| `planner-share-links:send-invitations <link_id> --email <e>… --approval-option anyone\|everyone` | Turn approval on and email 1–10 reviewers |
| `planner-share-links:activity <link_id> [--type comment\|action]` | What clients did on the other side |
- **`<link_id>` is the RECORD id** (the resource's `id`), never the public `link_id` slug in the shareable URL. The resource returns both — passing the slug gets you a 404.
- `--name` is 3–255 chars, **letters, digits and spaces only**. Punctuation is refused, because the name is slugified straight into the public URL. "Q3 Review!" fails; "Q3 Review" works.
- **One of `--plan` / `--note` is required on EVERY create**, including calendar-window links — the product snapshots the visible posts even when the window extends past them.
- `--scope selection|future|all` (default `selection`) and `--view list|calendar|compact_list` (default `list`). **`future` and `all` are calendar-only** (they need `--view calendar`), **require `--calendar-date`**, and **cannot collect external approvals** (`--allow-approval-actions` is rejected on them). `--calendar-date` is conversely **refused** on `selection`. It is free-form, e.g. `"2026-01-01 - 2026-03-31"`.
- `--single-post` needs `--scope selection` and exactly one `--plan`.
- `--password` (≥4 chars) implies `--password-protected`; pass `--no-password-protected` to lift protection on update.
- `--plan` and `filters` are **create-only**: the update endpoint rejects the field outright rather than accepting it and quietly dropping it. To change which posts a link shows, make a new link.
- The response **never** contains `password` or `approval_tokens`. Outstanding invitations surface as the derived `outstanding_invitations_count`.
- `planner-share-links:activity` answers `{total, data[]}` newest-first, each entry `{type, post_id, name, email, comment, action, created_at}`. `--type` narrows to comments or actions; omit it for both.
- Prefer `planner-share-links:update <id> --disabled` over `:delete` when a client engagement is only pausing — disabling is reversible, deleting is not.
- Errors: `SHARE_LINK_NOT_FOUND` (404), `SHARE_LINK_TOKEN_REVOKE_FAILED` (422).
### Labels (write)
| Command | Purpose |
|---------|---------|
| `labels:create --name <n> --color <color_N>` | Create a label |
| `labels:update <label_id> [--name] [--color]` | Update a label |
| `labels:delete <label_id>` | Delete a label |
### Campaigns (write)
| Command | Purpose |
|---------|---------|
| `campaigns:create --name <n> --color <color_N>` | Create a campaign |
| `campaigns:update <campaign_id> [--name] [--color]` | Update a campaign |
| `campaigns:delete <campaign_id>` | Delete a campaign |
For labels and campaigns: `--name` ≤100 chars; `--color` is one of the enum values `color_1` … `color_20`. On update, pass `--name` and/or `--color` (each is required-if-present).
### Team members (write)
| Command | Purpose |
|---------|---------|
| `team:add --email <e> --role <r> [--membership team\|client] [--permissions '<json>']` | Invite a member |
| `team:update <member_id> --role <r> --permissions '<json>' [--membership]` | Update a member's role/permissions |
| `team:remove <member_id> [--confirmed]` | Remove a member |
- `member_id` is the **membership id** — the `member_id` field from `team:list` (not the user's `id`, a distinct field).
- `--role` (required): `admin`, `approver`, or `collaborator`.
- `--email` (required for `team:add`): a single email address.
- `--membership` (optional): `team` (internal) or `client` (external; hidden from internal notes). Default `team`.
- `--permissions` (optional for `team:add`, **required for `team:update`**): a **role-aware** JSON object passed as a string (e.g. `--permissions '{"addSocial":true}'`). Invalid JSON → local `ConfigError`; invalid role/key combinations → backend 422. `team:update` is a partial merge — only the keys you send change; a role change drops boolean keys not valid for the new role.
- **Shared booleans** (any role): `accessSharedFolder`, `allow_workflow_management`.
- **admin**: full access — only the `hasBillingAccess` boolean applies.
- **collaborator** booleans: `addBlog`, `addSocial`, `addSource`, `addTopic`, `viewTeam`, `rescheduleQueue`, `postsReview`, `changeFBGroupPublishAs`, `hasListeningAccess`.
- **approver** booleans: `approverCanEditPost`, `approverCanAddNotes`, `approverCanCreatePost` (approvers can only approve/reject otherwise).
- **Account-access arrays** (any role; mus
[…] pełny plik w paczce .zip
Versions
The database has no other skills named contentstudio.
Identical content appears in 1 other GitHub folders. We show one copy with the highest score.
Database snapshot: 13.11.2026 · package version dfa860df994f (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 90social-media-post
Create, schedule, and manage social media posts using PostFast. Use when the user wants to publish, schedule, or manage posts on Facebook, Instagram, X (Twitter), TikTok, LinkedIn, YouTube, BlueSky, Threads, Pinterest, Telegram, or Google Business Profile. - 100sendcove
Draft, schedule and publish social media posts, upload media, check engagement and best times to post, and answer inbox comments with the Sendcove MCP server (X, Instagram, TikTok, Threads, Bluesky, YouTube, Facebook Pages, LinkedIn). Use when the user asks to write, schedule,… - 90social-media-insights
Report, rank, compare, and trend social media performance across Instagram, Facebook Pages, TikTok, YouTube, LinkedIn Pages, and Google Business Profile through Windsor.ai. Use when the user asks about reach, impressions, engagement (likes, comments, shares, saves), follower… - 100postfast
Schedule and manage social media posts across TikTok, Instagram, Facebook, X (Twitter), YouTube, LinkedIn, Threads, Bluesky, Pinterest, and Telegram using the PostFast API. Use when the user wants to schedule social media posts, manage social media content, upload media for… - 100postfjord
Plan, write, schedule and publish social posts through Postfjord (Instagram, Facebook, LinkedIn, Threads, TikTok, Pinterest, X, Bluesky, Mastodon, Tumblr and blogs), read analytics and the publish log, draft and schedule emails, answer the Inbox, set up DM and email automations,… - 100schedule-posts
Schedule and publish social media posts through PostFast, with the user's approval before anything goes out. Use when someone wants to post or schedule something on X, Instagram, Facebook, TikTok, LinkedIn, YouTube, Threads, Pinterest, Bluesky, Telegram or Google Business…