Docs

Tool reference

51 tools, and what each one does.

Every tool the MCP server registers, grouped by the scope a key needs to call it. The same names are the HTTP path segments — POST /agent/v1/<tool> — so this list is the full API surface too.

read · 25 content:write · 20 publish · 6

How they compose

Import, create, schedule

Almost every useful sequence is the same three beats. Get the raw material into the library, turn it into a finished piece of content, then put that content on a calendar. The tools chain by handing you an id: an imageId becomes a slide, a videoId becomes a post.

The middle beat is often asynchronous. Renders, imports, and AI generation return immediately with a status, and you poll get_slideshow, get_creation, or get_video until it's done. Each summary below says when that applies.

the two common chains 
# import → create → schedule
import_image_from_url  → imageId
create_slideshow       → slideshowId, "rendering"
get_slideshow          → poll until "ready"
publish_slideshow      → postIds (or review items)

# the video equivalent
get_video_upload_url   → uploadUrl, fileId
register_uploaded_video→ videoId
schedule_post          → postId + idempotencyKey

read · 25 tools

Reading the workspace

Nothing here changes state. This is the scope an agent needs to answer questions — what's in the libraries, what's queued, what's performing, and what competitors are doing.

In-app, this scope reads: List content, posts, accounts, and analytics

Tool What it does
whoami Who the key acts as, which organizations it can work in, and its scopes — plus the selected workspace's overview. Call it first to orient.
list_social_accounts Connected TikTok / Instagram / YouTube accounts with connection health: status, token expiry, and last error.
list_videos The video library, newest first. Videos with status 'completed' are publishable; 'generating' clips are still rendering.
get_video One library video in detail — status, signed URLs, duration, and generation provenance. Poll it for generate_video jobs.
list_video_groups Video groups — shuffle rotations that pre-schedule a visible queue of posts — with video/account counts and status.
get_video_group One group in detail: its videos and the per-account posting rules, next scheduled post, and current queue depth.
list_images List or hybrid-semantic-search the workspace image library. Check here before generating or re-uploading — reuse is free and instant.
list_characters Saved characters — reusable named subjects used to generate on-model images that look like the same person across scenes.
list_hooks The shared hook video library — short vertical clips meant to open a short-form video. Shared platform-wide, not per-workspace.
list_green_screens The shared green screen clip library — people cut out on green, composited over a background by create_video.
list_backgrounds The shared background image library used behind green screen memes.
list_music The platform music library — background tracks you can lay over a hook + demo video.
get_creation Render status of a create_video job. Poll until 'completed', then publish the returned resultVideoId.
list_slideshows Photo-carousel slideshows with status ('draft' or 'ready') and a signed cover thumbnail.
list_slideshow_templates Slideshow layout templates: canvas size, each text slot's exact geometry, defaults, fonts, and treatments.
get_slideshow One slideshow in full detail — per-slide render state, every text field's style overrides, and signed image URLs.
list_posts Posts across every status: review drafts, rejected, scheduled, publishing, published, failed, and canceled.
list_reviews Posts waiting for team review, with approval status, reviewer notes, target account, and planned publish time.
get_post_metrics Engagement for one published post: the latest views/likes/comments/shares snapshot plus the scraped time series.
get_account_metrics Follower and profile growth history (daily snapshots) for one connected account, or every account at once.
get_engagement_summary Engagement overview for the last N days: totals, per-platform breakdown, top posts, and a per-account breakdown.
list_inspirations Saved inspirations — external posts Post Ripple auto-analyzes into a reusable recreation recipe.
get_inspiration One inspiration in full detail, including the complete AI deconstruction: hook, shots, subjects, audio, and a recreation brief.
list_tracked_accounts Tracked external accounts this workspace polls, with status, followers, median views, and last poll time.
list_tracked_posts The 'what's working for competitors' feed — recent posts from tracked accounts, ranked by outlier score or recency.

content:write · 20 tools

Making the content

Uploads, imports, AI generation, renders, and rotation groups. This scope can't put a post on an account or wire a rotation to one — that needs publish. It isn't inert, though: adding videos to a rotation that's already wired up re-rolls which videos it will publish, and when.

In-app, this scope reads: Create and organize videos, groups, and content

Tool What it does
import_video_from_url Import a video into the library from a public URL. The download is asynchronous — poll list_videos until 'completed'.
get_video_upload_url Get a presigned upload URL for pushing a local video file into the library.
register_uploaded_video Register a video after PUTting its bytes to a presigned URL. The video becomes immediately publishable.
create_video_group Create a video group (a shuffle rotation). Uses one 'groups' credit from the plan.
add_videos_to_group Add up to 100 library videos to a group's rotation, reporting which were added and which were skipped.
get_image_upload_url Get a presigned upload URL for pushing an image into the library. JPEG at 1080×1350 strongly recommended.
register_uploaded_image Register an uploaded image into the workspace library with a title and tags, so it's findable and reusable later.
import_image_from_url Import an image from a public URL — synchronous, so the returned imageId is immediately usable in create_slideshow.
generate_character_image Generate a new AI image and save it to the library, optionally rendering a saved character on-model. Synchronous, ~10–30s.
generate_video Generate a new ~5s vertical AI clip from a prompt, character, or reference image. Asynchronous (~30–60s) — poll get_video.
save_inspiration Save an external post URL as an inspiration. Kicks off an async scrape → download → deconstruction pipeline.
track_account Start tracking an external public account so its recent posts land in the 'what's working' feed. Up to 10 per workspace.
untrack_account Stop tracking an account and delete its polled posts. Inspirations you already saved from it survive.
save_tracked_post_as_inspiration Save a tracked post into the inspirations library so it gets deconstructed and becomes recreatable.
recreate_inspiration Recreate a 'ready' inspiration as your own draft — 'person_swap', 'video', or 'slideshow'. Nothing is published.
replace_person_in_video Swap the person in any completed library video for a saved character, preserving motion, scene, and audio. Async, ~5–10 min.
update_image Update a library image's title, description, or tags — usually to make an older image easier to rediscover.
delete_image Delete a library image and its stored file. Images still in use are reported back instead, unless you force it.
create_slideshow Create a photo slideshow of 1–10 slides from library images, pre-rendered files, or template slides rendered server-side.
create_video Render a 9:16 video from library ingredients — 'text_over_video' (timed text beats over your own clip), 'hook_demo', or 'green_screen_meme'. Asynchronous — poll get_creation.

publish · 6 tools

Reaching the feed

Six tools. Two of them put content on a real account — schedule_post and publish_slideshow. Three more reschedule, swap the video on, or cancel a post that's already queued. The last, update_group_schedule, wires a rotation group to an account: an auto-publishing queue that keeps posting on its own cadence. This scope is off by default when you create a key.

In-app, this scope reads: Schedule and cancel posts to connected social accounts, and manage rotation-group schedules

Tool What it does
schedule_post Schedule a completed library video to publish on a connected account at a future time. Always pass idempotencyKey.
reschedule_post Move a still-scheduled post to a new future time. Fails once publishing has started.
swap_post_video Replace the video on a still-scheduled video post with any completed library video.
publish_slideshow Publish or schedule a ready slideshow to one or more Instagram/TikTok accounts as a native carousel or photo post.
cancel_post Cancel a still-scheduled post and refund its credit. Fails once publishing has started.
update_group_schedule Attach a social account to a rotation group or update its posting rules: posts per day, active/paused, and posting windows. The pair then auto-publishes on that cadence.

Worth knowing

Four things that bite once

Poll, don't assume

Imports, renders, and AI generation come back before the work is finished. Poll get_video, get_creation, get_slideshow, or get_inspiration until the status says it's ready. Scheduling something that isn't finished fails.

Always send an idempotency key

schedule_post and publish_slideshow take an idempotencyKey. Any unique string works, and it's the only thing that makes a retry safe on a tool that reaches a real account.

Search the library first

list_images runs hybrid semantic search over captions, tags, and prompts, so a plain description finds what's already there. Reusing an existing image costs nothing; generating a new one spends a credit.

TikTok defaults to private

A TikTok post published without tiktokSettings goes out as SELF_ONLY. Pass the settings object to make it public, or use postMode: "inbox" to drop a draft into the account's TikTok app instead.

Hand the list to your agent.

Create a scoped key and every tool above is one call away. Every paid plan includes Agent API and MCP access.

Create an API key HTTP reference