# AutomateSocials

An agent that runs social media accounts: it writes the posts, makes the pictures, keeps the calendar and publishes. Everything on this page can be said in the chat, called from your own agent over MCP, or called over HTTP.

## How to reach it

### In the chat

Type the sentence. The agent picks the tools, shows what it is about to do, and asks before anything is published or any credit is spent.

### From Claude Code or Cursor, over MCP

Make an API key under Settings → API & MCP, then add the server with the key in the x-api-key header. Every tool on this page is there, with the same names. Cursor and other MCP clients take the same URL and header in their MCP settings.

```bash
claude mcp add --transport http automate-socials https://new.automatesocials.net/mcp --header "x-api-key: sk_live_..."
```

### Inside claude.ai and Claude Desktop

Their custom connectors take a URL and nothing else, so the key goes at the end of the URL. Customize → Connectors → Add custom connector, paste the URL, Add. Then just talk: "schedule three posts about the autumn offer for next week". The URL is a credential: keep it as you would the key, and revoke the key if it leaks.

```bash
https://new.automatesocials.net/mcp/sk_live_...
```

### Inside ChatGPT

Plus, Pro, Business and Enterprise plans. Settings → Apps & Connectors → Advanced settings → turn on Developer mode. Then Apps & Connectors → Create: a name, the URL, Authentication "Token", and paste the key. ChatGPT picks the tools itself and confirms before anything is written.

```bash
URL: https://new.automatesocials.net/mcp
Authentication: Token → sk_live_...
```

### Over REST

Every tool is also an HTTP endpoint, and publishing, scheduling and reading back have plain paths of their own. The full machine-readable list is at /api/v2/openapi.json.

```bash
curl -X POST https://new.automatesocials.net/api/v2/tools/save_draft \
  -H "x-api-key: sk_live_..." -H "content-type: application/json" \
  -d '{"text":"Hello","platforms":["facebook"]}'
```

## Rules that apply to all of it

- Nothing is published without a human yes. The exceptions are a workflow and a campaign you have turned on - turning them on is that yes, and pausing takes it back.
- A campaign’s posts are written in the background a couple of days before each one goes out and land under Scheduled, where you can still read, change or cancel them.
- Every project is separate: its accounts, its posts, its knowledge and its voice. Credits belong to you and are shared across your projects.
- Prices are quoted in credits before anything runs, and you are charged what the provider actually billed, not the estimate.

## Writing posts

The agent writes a post and saves it as a draft in the same breath, one text per network rather than one text truncated. Drafts live under Posts, where they can be edited, scheduled or thrown away.

Things to say:

- "Write a post about our new opening hours for Facebook and LinkedIn"
- "Write five posts about office plants, one a day next week, and save them as drafts"
- "Rewrite draft #4 so it opens with the number, not the question"
- "Translate draft #2 into English and keep the picture"
- "Read post #7 back to me in full"

### `save_draft` — Save a draft

Saves a post you have written so it appears under Drafts and can be published or scheduled later. Use it whenever you write a post the user has not asked you to publish yet, instead of leaving it in the conversation: a draft in the chat is lost, a saved one is not. Always name the platforms it is for, and attach any picture you made for it. To change something that already exists, use edit_post rather than saving a second copy. Nothing is published by this.

Access: write

- `text` (string, required) — The post body.
- `postId` (string) — Revise this draft instead of saving a new one.
- `title` (string) — Internal title, never published.
- `platforms` (array, required) — Which platforms this draft is for, e.g. ["x", "linkedin"]. Required: a draft that does not say where it is going cannot be shown beside the account it belongs to, and nobody can tell what it was written for.
- `mediaIds` (array) — Media ids, e.g. from generate_image.
- `thread` (array) — Continuations for X or Threads.
- `variants` (object) — Per-platform wording, keyed by platform.

### `edit_post` — Edit a post

Changes a post that already exists: its words, its pictures, the platforms it is for, or any combination. Pass only what changes; everything else stays. This is how you rewrite a draft or swap its image - do not write a second copy. Read it with get_post first when you are changing the words, since you cannot rewrite what you have not read. Works on drafts and on posts that are scheduled but have not gone out; a published post cannot be edited here.

Access: write

- `postId` (string, required) — The post, by id or by the number shown to the user (#2).
- `text` (string) — New words. Leave out to keep what is there.
- `mediaIds` (array) — Replaces the pictures or video. Pass an empty list to take the media off entirely.
- `platforms` (array) — Which platforms it is for, if that is changing.
- `title` (string) — Internal title, never published.

### `get_post` — Read a post

The full text of one post, with its pictures, its per-platform wording and its state. Call it before changing or rewriting a post: list_posts only shows the first line of each, and working from that means working from a fragment.

Access: read

- `postId` (string, required) — The post, by id or by the number shown to the user (#2).

### `list_posts` — Posts

Lists posts in this workspace, newest first, with the first line of each. Use it before writing to check what has already been said. The text here is shortened: to work on a post, read it with get_post first.

Access: read

- `status` (string) — draft, scheduled, published or failed.
- `limit` (number) — How many to return, at most 50.

### `delete_post` — Delete a post

Deletes a draft, or cancels one that has not gone out yet. A post that is already published cannot be deleted here: it exists on the platform, and removing our record would not remove it.

Access: destructive (asks a human first in the chat)

- `postId` (string, required) — The post, by id or by the number shown to the user.

## Pictures and video

Images and video are generated through fal and cost credits, so the price is shown before anything runs and you approve it. The project’s own image and video style is wrapped around every prompt, including the ones an agent sends over MCP.

Things to say:

- "Make a picture for draft #3, something calm with a lot of white space"
- "What would a 10 second video at 1080p cost?"
- "Make a 5 second video from the picture on draft #3"
- "Make it with Nano Banana Pro instead"
- "Which image models can I use and what do they cost?"

### `generate_image` — Generate an image

Makes a picture from a description and stores it, ready to attach to a post. Call it as soon as you know what the picture should be: the user is asked to confirm the spend before it runs, with the price, so you do not need to ask them first. Describe the subject and the setting in the prompt; the model cannot see the brand kit, so put anything from it that matters into the words. If the project has set an image prompt, it is wrapped around what you write and sets the look, so you do not need to repeat the house style.

Access: destructive (asks a human first in the chat)

- `prompt` (string, required) — What the picture should show, in detail.
- `model` (string) — A model from list_image_models. Defaults to the workspace one.
- `count` (number) — How many to make, up to 4. Defaults to 1.
- `aspectRatio` (string) — e.g. 1:1, 4:5 for Instagram, 16:9 for a link preview.
- `forPlatform` (string) — Where this picture is going: facebook, instagram, x, linkedin or tiktok. Give it and the shape is chosen to suit that feed, which saves the user a cropped post.
- `resolution` (string) — 1K, 2K or 4K. Larger costs more at some models.
- `imageUrl` (string) — An existing picture to edit or work from, rather than starting blank.
- `ignoreProjectStyle` (boolean) — Generate exactly this prompt, without the project's image template. Only when the user asks for something outside their usual look.

### `estimate_image_cost` — What an image would cost

Says what generating would cost in credits, without generating. Use it when the user asks what something would cost. You do not need it before generating: the confirmation prompt already states the price.

Access: read

- `model` (string) — A model from list_image_models. Defaults to the workspace one.
- `count` (number) — How many images. Defaults to 1.
- `resolution` (string) — 1K, 2K or 4K. Larger costs more at some models.

### `list_image_models` — Image models

The image models available, what each costs in credits, and which one this workspace uses by default. Call it when the user asks what you can make images with, or before generating if they might care about the price.

Access: read

### `generate_video` — Generate a video

Makes a short video with its own audio and stores it, ready to attach to a post. Say what it will cost first; video is the most expensive thing here and is charged by the second. Pass imageId to animate a picture the project already has - a product photo or one you generated - and it becomes the first frame. Structure the prompt with [VISUAL], [SPEECH], [SOUNDS] and [TEXT] sections; English is the language the model is validated in.

Access: destructive (asks a human first in the chat)

- `prompt` (string, required) — What happens, what is said, what is heard. E.g. "[VISUAL] a hand lifts the jar... [SPEECH] Three plants, one minute. [SOUNDS] quiet kitchen".
- `seconds` (number) — How long. Shorter is cheaper and usually better.
- `resolution` (string) — Defaults to 720p, which is right for a phone screen. Higher costs several times more; list_video_models has the rates.
- `aspectRatio` (string) — 16:9, 9:16 for reels and TikTok, 1:1, 4:3, 3:4, or auto to let the model choose.
- `imageId` (string) — A picture in this project to animate; it becomes the first frame.
- `imageUrl` (string) — A public picture to animate, if it is not one of ours.
- `audioUrl` (string) — Narration or music to build the visuals around.
- `negativePrompt` (string) — What to keep out of it.
- `model` (string) — A model from list_video_models.
- `ignoreProjectStyle` (boolean) — Make exactly this prompt, without the project's video template. Only when the user asks for something outside their usual look.

### `estimate_video_cost` — What a video would cost

Says what a video of a given length and resolution would cost in credits, without making one. Use it whenever the user has not agreed to a price, since video is the most expensive thing here.

Access: read

- `seconds` (number) — How long, in seconds.
- `resolution` (string) — Defaults to 720p. What each model offers, and at what price, is in list_video_models.
- `model` (string) — A model from list_video_models.

### `list_video_models` — Video models

The video models available, what each costs per second at each resolution, and how long a clip can be. Call it when the user asks whether you can make video.

Access: read

## Publishing and the calendar

Publishing is the one thing that cannot be undone, so it always asks first. A post can go now, at a time you name, or into the next free opening in your weekly calendar.

Things to say:

- "Publish draft #2 to Facebook now"
- "Schedule draft #5 for tomorrow at 9:00"
- "Put draft #6 in the next free slot"
- "Move the post scheduled for Thursday to Friday morning"
- "We post Monday, Wednesday and Friday at 9 — set that up"
- "What is scheduled this week?"

### `create_post` — Publish or schedule a post

Publishes a post, or schedules one to be published. This is not how a draft is saved: use save_draft for that, which needs no confirmation. Publishes immediately by default; pass scheduledTime for a specific moment, or useNextFreeSlot to take the next opening in the calendar. Use variants to word the same post differently per platform. To publish something you saved with save_draft, pass its postId and the draft becomes the post rather than a second copy of it.

Access: destructive (asks a human first in the chat)

- `text` (string) — The post body. Per-platform limits apply; see variants to differ by platform. Leave it out when publishing an existing draft by postId: the draft already has its words.
- `postId` (string) — A draft to publish, by its id or by the number shown to the user (#1). Its text, pictures and per-platform wording are used unless you pass your own.
- `destinations` (array) — Where to publish. Leave it out when publishing a draft by postId: it goes to the connected account for each platform the draft was written for.
- `mediaIds` (array) — Media ids from an upload tool.
- `thread` (array) — Continuations, posted as replies to the first one. X and Threads only; other platforms ignore them.
- `variants` (object) — Per-platform overrides, keyed by platform name.
- `scheduledTime` (string) — ISO 8601 instant to publish at.
- `useNextFreeSlot` (boolean) — Take the next free opening in the calendar.
- `title` (string) — Internal title, never published.

### `get_post_status` — Post status

Returns where a post stands on each platform, including the public link once it is live. Instagram and TikTok process uploads in the background, so a post can be accepted and not yet visible.

Access: read

- `postId` (string, required) — Post id, or a submission id returned by create_post.

### `list_schedules` — Scheduled posts

Lists posts waiting to go out, soonest first.

Access: read

- `limit` (number) — How many to return, at most 50.

### `update_schedule` — Move a scheduled post

Changes when a post goes out, or takes it off the calendar and leaves it as a draft. Pass scheduledTime for a specific moment or useNextFreeSlot to take the next opening. A post that has already gone out cannot be moved.

Access: write

- `submissionId` (string, required) — The scheduled post: a submission id from list_schedules, a post id, or the number shown to the user (#4).
- `scheduledTime` (string) — ISO 8601 instant to publish at instead.
- `useNextFreeSlot` (boolean) — Take the next free opening in the calendar.
- `unschedule` (boolean) — Take it off the calendar and leave it as a draft, without cancelling it.

### `delete_schedule` — Cancel a scheduled post

Cancels a post that has not gone out yet. A post that is already published cannot be cancelled: the platform has it and we do not.

Access: destructive (asks a human first in the chat)

- `submissionId` (string, required) — The scheduled post: a submission id, a post id, or the number shown to the user (#4).

### `list_slots` — Publishing calendar

Lists the recurring weekly openings this workspace publishes in, and which of the coming ones are already taken. Read this before scheduling, so posts land in the rhythm the user already chose.

Access: read

- `days` (number) — How far ahead to show occupancy, default 14.

### `create_slots` — Add publishing slots

Adds recurring weekly openings to the calendar. Times are in the workspace timezone. Adding more slots than there is content for produces gaps, so ask how often the user actually wants to post.

Access: write

- `slots` (array, required)

### `delete_slot` — Remove a publishing slot

Removes one recurring opening. Posts already scheduled into it keep their time.

Access: write

- `slotId` (string, required)

### `next_available_slot` — Next opening

Returns the next free opening in the calendar, without taking it. Use it to tell the user when a post would go out before scheduling it.

Access: read

- `accountId` (string) — Only consider slots that publish to this account.

## Campaigns

A campaign is what a month of posts says together: it is planned as one line per post - the day, what kind of post it is, its theme and its angle - and the posts themselves are written a couple of days before each one goes out, so each has seen the ones before it. Ask for one and the agent will interview you first.

Things to say:

- "Let’s make a campaign"
- "Plan 12 posts for the spring range, weekdays at 9, with a picture each"
- "Show me the plan for Spring"
- "Add a picture to every post of Spring"
- "Add one more post to Spring about the delivery times"
- "Write the next two posts of Spring now so I can see them"
- "Pause Spring"
- "Cancel Spring and everything of it that has not gone out"

### `plan_campaign` — Plan a campaign

Plans a run of posts around one goal: what each post is for, its theme and its angle, spread over the days the project posts on. It writes nothing and publishes nothing - the plan is one line per post, to be read and changed before anything is written. Use this when the user wants a month of content, a launch, or anything with more than a couple of posts behind one idea.

Access: write

- `name` (string, required) — What to call it.
- `goal` (string, required) — What the campaign is for, in the user's words.
- `posts` (number, required) — How many posts, up to 60.
- `platforms` (array) — Which platforms. Defaults to every connected account.
- `daysOfWeek` (array) — Days to post on, 0 is Sunday. Defaults to every day.
- `timeOfDay` (string) — HH:MM in the project timezone. Defaults to 09:00.
- `startsOn` (string) — ISO date for the first post. Defaults to tomorrow.
- `themes` (array) — Subjects it should cover.
- `audience` (string) — Who it is for, if not the usual audience.
- `offer` (string) — What is being promoted, if anything.
- `sources` (array) — Pages the campaign is based on - articles, a product page, a blog. They are read here and kept in the knowledge base, and every post of the campaign is then written from what they say. Pass them whenever the user says the campaign is about their own content; you do not need to read anything first.
- `withImages` (boolean) — Generate a picture for each post. This costs credits.
- `useSlots` (boolean) — Publish into the project's own calendar slots instead of at a fixed hour, taking the next free one on or after each planned day. Prefer this when the project has slots.
- `leadDays` (number) — How many days before a post goes out it is written. Default 2.
- `notes` (string) — Anything else the planner should know.

### `update_campaign` — Change a campaign

Changes how a campaign runs: whether its posts get a generated picture, whether it uses the calendar slots, how many days ahead it writes, or its name. Pass only what changes. Pictures apply to the posts not yet written and cost a credit each at the cheapest model - say the number before turning them on.

Access: write

- `id` (string, required) — The campaign, by id or by name.
- `withImages` (boolean) — Generate a picture for each post still to be written. This costs credits.
- `useSlots` (boolean) — Publish into the project's calendar slots.
- `leadDays` (number) — How many days before a post goes out it is written.
- `name` (string)

### `edit_campaign_plan` — Change a campaign plan

Adds posts to a campaign plan, removes planned ones, or rewrites their theme and angle. This is how you add "one more post about X" without planning the campaign again. Posts already written keep their words - use edit_post for those - and removing one that is already written is refused.

Access: write

- `id` (string, required) — The campaign, by id or by name.
- `add` (array) — Posts to add to the plan.
- `remove` (array) — Day numbers to drop, as get_campaign shows them.
- `update` (array) — Changes to planned posts.

### `list_campaigns` — Campaigns

The campaigns in this project, what each is for, and how far through it is.

Access: read

### `get_campaign` — Read a campaign

One campaign in full: every planned post with its date, kind (educational, promotional, engagement, proof, behind_the_scenes, news), theme and angle, and which of them have been written. Read it before changing anything about the campaign.

Access: read

- `id` (string, required) — The campaign, by id or by name.

### `start_campaign` — Start a campaign

Turns a campaign on. Its posts are written a couple of days before each one goes out and land in the calendar as scheduled, where they can still be read, edited or cancelled. Posts with pictures spend credits as they are written. Tell the user how many posts and roughly how many credits before calling this.

Access: destructive (asks a human first in the chat)

- `id` (string, required) — The campaign, by id or by name.

### `write_campaign_posts` — Write the next campaign posts now

Writes the next few posts of a campaign immediately instead of waiting for their lead time, and schedules them at their planned dates. Use it to show the user what the plan actually produces.

Access: destructive (asks a human first in the chat)

- `id` (string, required) — The campaign, by id or by name.
- `count` (number) — How many to write now. Default 2.

### `pause_campaign` — Pause a campaign

Stops a campaign writing any more posts. Posts already written keep their place in the calendar; cancel them individually if they should not go out.

Access: write

- `id` (string, required) — The campaign, by id or by name.

### `cancel_campaign_posts` — Cancel a campaign and its scheduled posts

Pauses a campaign and cancels every post of it that has not gone out yet. Posts already published are untouched: they exist on the platform.

Access: destructive (asks a human first in the chat)

- `id` (string, required) — The campaign, by id or by name.

### `delete_campaign` — Delete a campaign

Removes a campaign and its plan. Posts it already produced are kept - they are posts like any other, and some may be published.

Access: destructive (asks a human first in the chat)

- `id` (string, required) — The campaign, by id or by name.

## Workflows

Work that repeats on its own: read a source, write a post, make a picture, publish it. A workflow is created paused and does nothing until you turn it on; turning it on is what you agree to, because from then on it publishes without asking.

Things to say:

- "Every weekday at 8, read our blog and save a post as a draft"
- "Run that workflow now so I can see what it makes"
- "Add a picture step to the morning workflow"
- "Pause the morning workflow"
- "How did last night’s run go?"

### `create_workflow` — Create a workflow

Sets up work that repeats on its own: read a source, write a post, make a picture, publish it. Steps run in the order given. It is created paused and does nothing until start_workflow turns it on, so making one is safe. Use it when the user asks for something to happen daily, weekly or at a set time.

Access: write

- `name` (string, required) — What it is for, in a few words.
- `steps` (array, required) — The steps, in order.
- `trigger` (string) — recurring (default), once, or manual for run-on-demand only.
- `daysOfWeek` (array) — recurring: 0 is Sunday. [1,2,3,4,5] is weekdays.
- `timeOfDay` (string) — recurring: HH:MM in the project timezone.
- `runAt` (string) — once: an ISO time.
- `context` (object) — Shared settings every step can read.

### `list_workflows` — Workflows

The workflows in this project, what they do, when they next run, and how the last run went. Call it when the user asks what is running on its own.

Access: read

### `get_workflow` — Read a workflow

One workflow in full: every step with its settings, its schedule, and how the last runs went. Read it before changing anything, since update_workflow replaces the steps you pass and you cannot keep what you have not seen.

Access: read

- `id` (string, required) — The workflow, by id or by its name.

### `update_workflow` — Change a workflow

Changes a workflow that already exists: its steps, its name, or when it runs. Pass only what changes. Call get_workflow first when you are changing the steps, since the list you pass replaces the ones that are there. Its run history is kept.

Access: write

- `id` (string, required) — The workflow, by id or by its name.
- `name` (string)
- `steps` (array) — The complete new list of steps, in order.
- `daysOfWeek` (array) — 0 is Sunday.
- `timeOfDay` (string) — HH:MM in the project timezone.
- `runAt` (string) — For a one-off: an ISO time.
- `context` (object)

### `start_workflow` — Start a workflow

Turns a workflow on. From then on it runs to its schedule and publishes without asking again, so make sure the user has seen what it does. Use stop_workflow to pause it.

Access: destructive (asks a human first in the chat)

- `id` (string, required) — The workflow, by id or by its name as list_workflows shows it.

### `stop_workflow` — Pause a workflow

Pauses a workflow so it stops running on its own. Nothing is deleted and it can be started again.

Access: write

- `id` (string, required) — The workflow, by id or by its name as list_workflows shows it.

### `run_workflow` — Run a workflow now

Runs a workflow immediately, whatever its schedule says, and reports what each step did. Use it to show the user what their workflow actually produces before leaving it to run on its own.

Access: destructive (asks a human first in the chat)

- `id` (string, required) — The workflow, by id or by its name as list_workflows shows it.

### `delete_workflow` — Delete a workflow

Removes a workflow and its run history. Posts it already published are untouched.

Access: destructive (asks a human first in the chat)

- `id` (string, required) — The workflow, by id or by its name as list_workflows shows it.

## Connected accounts

Facebook, Instagram, X, TikTok and LinkedIn. One connection per network per project; pages and organisations hang under it. Instagram is reached through the Facebook page it is linked to: connect Facebook, then pick the Instagram business account. A connection that has expired says so rather than failing at publish time.

Things to say:

- "Connect our Facebook page"
- "Which accounts are connected?"
- "Which Facebook pages can I post to?"
- "Connect our Instagram"
- "Disconnect LinkedIn"

### `list_accounts` — Connected accounts

Lists the social accounts connected to this workspace, with their platform, handle and whether they are currently usable. Call this before writing or scheduling, so you only offer platforms that are actually connected.

Access: read

- `platform` (string) — Limit to one platform: facebook, instagram, x, linkedin or tiktok.

### `list_subaccounts` — Pages and organizations

Lists the pages, organizations or boards an account can publish to. Facebook posts go to a page and LinkedIn can post as a company, so this is where the id for those comes from.

Access: read

- `accountId` (string, required) — The connected account to list destinations for.

### `connect_account` — Connect an account

Produces a link the user opens to connect a social account. Authorization happens on the platform, so give them the link and wait; the account appears in list_accounts once they have finished. Use this when an account they want is missing, or when one is marked as needing a reconnect.

Access: write

- `platform` (string, required) — facebook, instagram, x, linkedin or tiktok.

### `list_instagram_accounts` — Instagram accounts

Lists the Instagram business accounts linked to the connected Facebook pages, the ones this project can post to. Facebook must be connected first. Follow with connect_instagram.

Access: read

### `connect_instagram` — Connect Instagram

Connects an Instagram business account found by list_instagram_accounts. With only one available, instagramId can be left out. Replaces a different Instagram account already on this project, as every connection does.

Access: write

- `instagramId` (string) — instagramId or @username from list_instagram_accounts.

### `disconnect_account` — Disconnect an account

Removes a connected account and cancels anything still scheduled to it. Say how many posts that is before asking the user to confirm.

Access: destructive (asks a human first in the chat)

- `accountId` (string, required) — Account id from list_accounts.

### `get_user` — Account info

Returns the signed-in user, the active workspace, the plan and the credit balance. Call this first to confirm which workspace you are acting on.

Access: read

## Knowledge base

What the project knows about itself: pages, documents, notes. The agent searches it while writing, so a post can cite a real number or a real customer instead of inventing one.

Things to say:

- "Add https://our-site.com/about to the knowledge base"
- "Remember this: our delivery takes 2 to 4 working days"
- "What does the knowledge base say about pricing?"
- "What is in the knowledge base?"

### `add_knowledge` — Store something in the knowledge base

Stores text the workspace will want again: product details, positioning, a policy, notes from a call. Use it when the user tells you something factual worth keeping, rather than only using it in this conversation. Give it a title so it can be recognised later.

Access: write

- `title` (string) — A short name, e.g. "Pricing, 2026".
- `content` (string, required) — The text to store.
- `sourceUrl` (string) — Where it came from, if anywhere.

### `add_knowledge_from_url` — Read a page into the knowledge base

Fetches a web page or a PDF at a URL and stores its text so it can be searched later. Use it for the workspace's own site, a product page, a press release. It reads the page as it is served, so a page that needs a sign-in will not work.

Access: write

- `url` (string, required) — The address to read.
- `title` (string) — A name for it. Defaults to the page title.

### `add_knowledge_from_file` — Read a file into the knowledge base

Reads an already uploaded PDF, image or text file and stores what it says so it can be searched. Give it a media id from an upload.

Access: write

- `mediaId` (string, required) — Media id from an upload tool.
- `title` (string) — A name for it. Defaults to the file name.

### `search_knowledge` — Search the knowledge base

Searches what this workspace has stored: notes, pages, documents, product details. Use it before writing anything factual about them, rather than guessing or asking. It searches by meaning, so ask in whatever words the user used. Returns nothing when the workspace has stored nothing, which is worth saying rather than working around.

Access: read

- `query` (string, required) — What you need to know, in plain words.
- `limit` (number) — How many passages to return, up to 20. Defaults to 5.

### `list_knowledge` — Knowledge base

Lists what this workspace has stored, with whether each item is searchable yet. Use it when the user asks what you know about them, or when a search came back empty and you want to say why.

Access: read

### `delete_knowledge` — Delete from the knowledge base

Removes a stored item and everything derived from it. Name what you are about to delete first.

Access: destructive (asks a human first in the chat)

- `itemId` (string, required) — Item id from list_knowledge or search_knowledge.

## YouTube, TikTok, audio and research

Turns a video, a voice recording or a question into text to write from. A YouTube or TikTok video gives its spoken transcript; TikTok reads its own captions when it has them and pays for speech-to-text only when it does not. An audio file is transcribed. A question is answered from a live web search. Article pages, PDFs and pasted text are free and go through add_knowledge_from_url and add_knowledge instead; these four cost credits, quoted first, and are stored in the knowledge base by default.

Things to say:

- "Read this YouTube video and write three posts from it: <url>"
- "Get the transcript of this TikTok: <url>"
- "Transcribe this voice memo: <url>"
- "Research what people are saying about AI video generation this year"

### `estimate_source_cost` — What reading this source would cost

Says what youtube, tiktok, audio or research would cost in credits, without reading anything. Article, PDF and plain text pages are free: use add_knowledge_from_url or add_knowledge for those instead.

Access: read

- `sourceType` (string, required) — youtube, tiktok, audio or research.

### `read_source` — Read a source

Turns a YouTube video, a TikTok, an audio file, or a research question into text to write from. sourceType youtube or tiktok take a video url and read its spoken transcript (English captions for YouTube; TikTok's own captions when it has them, speech-to-text otherwise). sourceType audio takes a url to a recording and transcribes it. sourceType research takes a question and answers it from a live web search. Each costs credits; quote it first with estimate_source_cost. The text is stored in the knowledge base unless saveToKnowledge is false, and is also returned here so it can be used straight away.

Access: destructive (asks a human first in the chat)

- `sourceType` (string, required) — youtube, tiktok, audio or research.
- `value` (string, required) — A video or audio URL for youtube, tiktok and audio; the question itself for research.
- `saveToKnowledge` (boolean) — Store the result in the knowledge base. Defaults to true.
- `title` (string) — A name for it, if stored. Defaults to the source’s own title.

## The project’s voice and rules

The profile is per project: what you do, who for, the words never to use, the standing rules for everything written, and the template wrapped around every generated picture. Filled in once, applied everywhere - including by an agent over MCP that has never seen the settings screen.

Things to say:

- "Read our website and fill in the profile"
- "Always end posts with a question, never name a competitor"
- "Our voice is warm and practical; never say “solution”"
- "Set the image style to flat vector illustration, muted colours"
- "Take the voice from our last posts"
- "Delete this project"

### `get_brand_kit` — Brand kit

The workspace's voice, audience, rules and example posts. You are already given this in your instructions, so call it only when the user asks what is set or you are about to change something.

Access: read

### `update_brand_kit` — Update the brand kit

Records what the workspace sounds like. Pass only the fields you are changing; anything you leave out is kept. Example posts matter most: ask for two or three things they actually published, since those define the voice better than adjectives do. Use this whenever the user tells you something about their voice, audience or rules, rather than remembering it for one conversation.

Access: write

- `name` (string) — The brand or business name.
- `website` (string)
- `oneLiner` (string) — What they do, in one sentence.
- `description` (string) — A paragraph of background.
- `audience` (array) — Who the posts are for, e.g. "office managers".
- `voice` (array) — Adjectives for the voice, e.g. "warm", "practical".
- `toneDo` (array) — Things to do, e.g. "name the plant".
- `toneDont` (array) — Things to avoid, e.g. "use stock phrases".
- `bannedWords` (array) — Words never to use.
- `ctas` (array) — Calls to action they use.
- `keywords` (array) — What this project is about, in the words people would search for.
- `contentInstructions` (string) — Standing rules for everything written for this project, e.g. "always end with a question". These are applied to every draft, so put a rule here rather than repeating it each time. Pass an empty string to clear them.
- `defaultImagePrompt` (string) — A template wrapped around every image prompt, where {{DESCRIPTION}} is replaced by what the picture should show. This is how a project keeps one look. Pass an empty string to clear it.
- `defaultVideoPrompt` (string) — The same, for video, where {{DESCRIPTION}} is what the clip should show. Left empty, videos use the image template, since a project usually has one look. Pass an empty string to clear it.
- `languagePrimary` (string) — Two-letter code for the language posts are usually written in.
- `hashtagSets` (object) — Named sets of hashtags, e.g. {"core": ["#plants", "#office"]}.
- `examplePosts` (array) — Posts they wrote themselves. These define the voice; add rather than invent.
- `replaceExamplePosts` (boolean) — Replace the stored examples instead of adding to them.

### `analyze_website` — Read the website

Reads the project's website and fills in what it does, who it is for, its keywords and its voice. Use it when the brand kit is empty and you know the address, instead of interviewing the user about things their own site already says. It fills only empty fields unless you say otherwise.

Access: write

- `url` (string) — The website. Defaults to the one already on the profile.
- `overwrite` (boolean) — Replace fields that are already filled in. Ask the user before doing this.

### `learn_voice_from_published` — Learn the voice from published posts

Fills the brand kit's example posts from what this workspace has already published. Use it when the brand kit has no examples and there is a publishing history, instead of asking the user to paste posts they have already sent.

Access: write

- `platform` (string) — Take examples from one platform only.
- `limit` (number) — How many to take, up to 10. Defaults to 5.

### `set_default_image_model` — Choose the image model

Sets which model this workspace generates with unless told otherwise. Use it when the user says they want a particular one from now on.

Access: write

- `model` (string, required) — A model from list_image_models.

### `delete_project` — Delete this project

Permanently deletes the current project and everything in it: posts, scheduled posts, connected accounts, knowledge, workflows, campaigns and its API keys. Credits are not affected. Only the owner can do it, it cannot be the only project, and confirmName must be the project name exactly as the user typed it. Before calling, tell the user what will be lost and have them type the name. It cannot be undone.

Access: destructive (asks a human first in the chat)

- `confirmName` (string, required) — The project name, typed by the user to confirm.

## Reading other people’s feeds

Scraping runs through Apify and is charged per post read, so it says what it will cost first. Use it for what is working elsewhere, not to copy it.

Things to say:

- "Read the last 10 posts from @competitor on Instagram"
- "What are they posting about lately?"
- "Write our own version of their best performing post"

### `scrape_posts` — Read a feed

Reads recent posts from a public profile on Instagram, Facebook, LinkedIn, TikTok or X, and keeps them so patterns across weeks can be seen. Use it to look at a competitor before writing, or as the first step of a workflow. It costs credits per post read, so say what it will cost first.

Access: destructive (asks a human first in the chat)

- `platform` (string, required) — instagram, facebook, linkedin, tiktok or x.
- `target` (string, required) — A handle, a profile URL, or a search term where the network allows one.
- `limit` (number) — How many posts to read, up to 100. Defaults to 10.

### `estimate_scrape_cost` — What reading a feed would cost

Says what reading someone’s posts would cost in credits, without reading anything.

Access: read

- `platform` (string, required) — instagram, facebook, linkedin, tiktok or x.
- `limit` (number) — How many posts. Defaults to 10.

### `list_scrapers` — What can be scraped

The networks this server can read posts from, and what each costs per result. Call it when the user asks whether you can look at a competitor.

Access: read

## Files

Upload a picture or a video from your machine, or hand over a URL and it is copied into our storage - platforms fetch media from us, so a link that expires would break a post scheduled for next week.

Things to say:

- "Use this picture for draft #3"
- "Add https://example.com/photo.jpg to the post"

### `upload_media_from_url` — Import media

Downloads a publicly reachable file into storage and returns a stable URL to use in posts. Use this for images or video that already live on the web.

Access: write

- `url` (string, required) — Publicly reachable URL of the file.
- `altText` (string) — Accessibility description.

### `create_presigned_upload_url` — Prepare upload

Returns a presigned URL for uploading a local file directly to storage. PUT the file bytes to uploadUrl with the same Content-Type, then use mediaId or publicUrl when creating a post.

Access: write

- `filename` (string, required) — Original file name, used for the extension.
- `contentType` (string, required) — MIME type, for example image/jpeg or video/mp4.

### `get_media` — Media details

Returns the stored details of one media asset, including whether its bytes have arrived.

Access: read

- `mediaId` (string, required) — Id returned when the media was created.

## How posts did

Every published post is measured an hour, a day and a week after it goes out, then once a day for a month: views, reach, likes, comments, shares and saves, as each network reports them. Ask which post worked, over any period, on one network or all; each network a post went to is ranked on its own, and every reading is kept so you can see whether it is still growing. Reading the numbers costs nothing.

Things to say:

- "Which post did best this month?"
- "What worked on LinkedIn in the last two weeks?"
- "How is #7 doing?"
- "Rank last month by engagement"
- "Read #9 again now and tell me if it is still growing"

### `list_top_posts` — Top posts

Ranks published posts by how they did: views, likes, comments, shares, reach, saves, or engagement (likes + comments + shares + saves). Each network a post went to is ranked on its own. Numbers are the ones already collected (an hour, a day and a week after publishing, then daily for a month); nothing is fetched from the networks. Use it for "which post worked", "what did best on LinkedIn this month", or before planning what to write next.

Access: read

- `sortBy` (string) — One of views, likes, comments, shares, reach, saves, engagement. Defaults to views.
- `platform` (string) — facebook, instagram, x, linkedin or tiktok. Leave out for all.
- `since` (string) — ISO date or time; posts published on or after it. Defaults to 30 days ago.
- `until` (string) — ISO date or time; posts published on or before it.
- `limit` (number) — How many, 1 to 50. Defaults to 10.

### `get_post_analytics` — How a post did

The numbers for one published post on every network it went to: the latest reading and every earlier one, so you can say whether it is still growing. Pass refresh: true to read the networks again now (at most every ten minutes); leave it off to use what was already collected.

Access: read

- `postId` (string, required) — The post, by id or by the number the user sees (#7).
- `refresh` (boolean) — Read the networks again now. Defaults to false.

## Credits

Writing and scheduling are free, and so is publishing to Facebook, Instagram, LinkedIn and TikTok. X charges for every post, so a post to X is 1 credit, or 8 when it contains a link (a bare domain counts), for each post in a thread; it is taken when the post goes out and not at all if X refuses it. Generated pictures, video and scraping cost credits, and the price is always shown before you agree to it.

Things to say:

- "How many credits do I have left?"
- "What has been using my credits?"
- "Buy the 500 credit pack."

### `get_credits` — Credit balance

Returns the credit balance for the workspace. Credits pay for generated images, video, transcription and scraping; writing, publishing and scheduling are free on paid plans.

Access: read

### `buy_credits` — Buy credits

Returns a Stripe checkout link for a credit pack. Nothing is charged until the user opens the link and pays; the credits are added to their account as soon as Stripe confirms the payment. Packs: starter (50 credits, $4.99), growth (200, $14.99), power (500, $29.99), power_plus (1000, $49.99). Credits never expire. Give the user the link; never claim the credits were added.

Access: write

- `packageId` (any, required) — starter, growth, power or power_plus.

## Plumbing

Not things to ask for - they are here because a machine reading this page should know the whole surface. `noop` and `echo` are for checking a connection works; `publish` is the low-level publish that create_post is built on.

### `noop` — Connectivity check

Verifies the connection end to end. Returns the caller identity, the channel it arrived on, and the server time. It is for someone checking that an API key or an MCP setup works, and it does nothing else: never call it as a step in doing what the user asked.

Access: read

- `echo` (string) — Text echoed back unchanged.

### `check_projects` — Check the projects are separate

Counts what each of your projects holds and checks that nothing crosses between them: posts, accounts, pages, campaigns, workflows, knowledge and media. Run it after adding a project, or whenever something looks like it belongs somewhere else.

Access: read