MCP tool reference

This page is generated from the server's own tool listing, so it is exact for the deployed version. How to connect, how calls behave, and the workflow nuances are in the MCP server guide.

309 tools in 9 toolsets: 101 read-only, 173 change data, 35 spend credits. Connect to https://api.pamba.app/mcp for all of them, ?toolsets=<name,name> for a subset, ?readonly=true for reads only.

Toolsets

• •videos (49 tools): Projects and videos: create from a script or idea, generate, replicate a TikTok, edit drafts and scenes, schedule posts, run campaigns, and the avatar creation wizard.
• •editing (24 tools): The editor: creative concept versions, clip takes, renders, text hooks and bullets, captions, model switches, duplicates and automation re-runs.
• •avatars (39 tools): Avatars: appearance, voices, scene libraries and variations, reference frames, image editing, external TikTok tracking.
• •accounts (35 tools): TikTok, Instagram and Facebook accounts: the fleet inventory, seats and billing, profile edits, warming, health checks and incidents, and the posting queue's individual posts.
• •ideas (15 tools): The ideas library: captured videos, scripts, tracked inspiration accounts and their metrics.
• •discover (14 tools): Discover: the viral-video corpus, niche feed, trends, breakout creators, and the create page's source picker.
• •content (45 tools): Content review and knowledge: script batches, the review desk, patterns, principles, playbooks, term lists, the writer engine and the learning loop.
• •automation (32 tools): Automation strategy: campaign settings, cadences, mix targets, taxonomies, constraints, and content plans.
• •workspace (56 tools): Workspace and account: settings, members and invitations, onboarding, billing and credits, the media library, API keys, help search, and support.

Toolset videos

accept_avatar_appearance

Accept avatar appearance. Changes data. Spends no credits.

Step 2 of 4. Locks in the wizard's appearance and moves to voice selection. Next: call get_avatar_wizard(wizard_id) — free basic voices are already on it; generate_avatar_voices only if the user asked for premium clones.

Parameters:

• •wizard_id (string, required): The wizard id.

archive_project

Archive project. Changes data. Spends no credits.

Archive (hide) a video project by its id.

Parameters:

• •project_id (string, required): The project id (UUID) to archive.

assign_avatar_to_campaign

Assign avatar to campaign. Changes data. Spends no credits.

Move an avatar+account assignment into a campaign, or back to the Default campaign when campaign_id is omitted. A move is complete: the campaign becomes the assignment's only one (any extra memberships are cleared). Get assignment_id from list_campaign_assignments.

Parameters:

• •assignment_id (string, required): The assignment id (from list_campaign_assignments).
• •campaign_id (string, optional): The target campaign id; omit to move the assignment back to Default.

create_avatar

Create avatar. Spends credits: image credits — 15 per generated appearance/scene image.

Step 1 of 4 to create an avatar. Starts the avatar wizard from a natural-language appearance description and generates candidate scene images (spends image credits). Waits for the scenes, then returns a wizard_id and the scene image urls. Next: review the scenes and call accept_avatar_appearance(wizard_id).

Parameters:

• •appearance_prompt (string, required): Describe the avatar's appearance, vibe and niche.

create_campaign

Create campaign. Changes data. Spends no credits.

Create a new automation campaign (Content > Automation). It copies the Default campaign's schedule and starts disabled with no members. Next: move avatars in with assign_avatar_to_campaign, then turn it on with set_campaign_enabled.

Parameters:

• •name (string, required): The campaign name.

create_draft_project

Create draft project. Changes data. Spends no credits.

Create a new empty draft video project in the workspace.

No parameters.

create_video_project

Create video project. Changes data. Spends no credits.

Create a video project for an avatar from EITHER a spoken script (used verbatim) OR an idea_description (a fresh script is written from it — every call is its own LLM run, so fanning one idea across several avatars yields a DISTINCT script per avatar; never copy one generated script to multiple avatars yourself). The script is split into clips for the chosen video model. generate_video renders it when the user asks for generation (spends video credits). Pass an avatar_project_id from list_avatars.

Parameters:

• •script (string, optional): The spoken script, used verbatim. Provide exactly one of script or idea_description.
• •idea_description (string, optional): An idea to write the script from — each call writes a fresh, distinct script.
• •avatar_project_id (string, required): The avatar's project id (from list_avatars).
• •project_name (string, optional): Optional project name. When inventing one, use sentence case: capitalize only the first word, proper nouns, and the pronoun I.
• •video_model (string, optional): Optional: grok-imagine-1.5 | seedance | gemini-omni. Defaults to the avatar's default video model, then gemini-omni.
• •pattern_slug (string, optional): Optional content-pattern slug (from list_content_patterns) this video follows — recording it feeds the automation planner's performance data.
• •promotional (boolean, optional): Optional, default true. Pass false for a NON-promotional script from idea_description: the workspace's business context is not woven in and nothing gets promoted. Ignored with a verbatim script.

disable_campaign

Disable campaign. Changes data. Spends no credits.

Turn an automation campaign off, stopping its automatic content cycles and credit spend.

Parameters:

• •campaign_id (string, required): The campaign id (from list_campaigns).

edit_clip_videos

Edit clip videos. Spends credits: video credits at the Gemini Omni rate (~22.1/sec of each edited clip).

Edit already-generated clip videos with Gemini Omni video-to-video: describe a visual change (e.g. "make her skin look oiled, as if she just applied tanning oil") and each clip's current video is re-rendered with that change as a new take in its generation history, auto-selected when it completes (spends video credits at the Gemini Omni per-second rate — see get_credit_pricing). Works whatever model produced the current video; clips must already have a video and be 3-10s. For a LONGER clip, edit a 3-10s segment of it: pass in_point/out_point (with exactly one clip index) and the window is edited and spliced back into the take. clip_indices is an optional JSON array of 0-based clip indices; omit to edit every eligible clip (has a video and is 3-10s — ineligible clips are skipped automatically when omitted). Runs in the background — poll get_project for clip generation_status.

Parameters:

• •project_id (string, required): The project id.
• •edit_prompt (string, required): The visual change to apply, phrased as an instruction.
• •clip_indices (string, optional): Optional JSON array of 0-based clip indices, e.g. [0,1]. Omit for all clips with videos.
• •in_point (number, optional): Optional segment start in seconds. With out_point, edits only that window of ONE clip (clip_indices must name exactly one index) — the edited window is spliced back into the take. This is how clips longer than 10s get edited.
• •out_point (number, optional): Optional segment end in seconds; pair with in_point. The window must be 3-10 seconds long.

edit_draft_script

Edit draft script. Spends credits: free unless the re-split ADDS scenes — each new scene generates one frame (~18 image credits incl. its realism pass).

Rewrite a draft's whole spoken read (replication or script draft alike) — propagates like the editor's script edit: each spoken segment re-splits into clip-sized scenes at natural speech boundaries, so the scene count may change. Unchanged scenes keep their frames; on replication drafts new scenes appear frameless and their frames generate from the reference automatically (image credits per new scene), while script drafts stamp new scenes with library-scene frames instantly and free. Scenes whose words don't own their timing (sung, b-roll, off-camera voiceover) stay pinned in place between the segments — pass one segment per stretch of consecutive speech_editable scenes, in play order (get_scene_frames shows each scene's speech_editable flag and current text on replication drafts; on script drafts every non-sung, non-b-roll scene with spoken words is editable; do NOT key segments on spoken_mode).

Parameters:

• •project_id (string, required): The draft's project id.
• •segments (array, required): The spoken stretches between pinned sung/b-roll scenes, in play order — one string per stretch.

edit_scene

Edit scene. Spends credits: image + AI credits — the scene rewrites and each of its clips regenerates a frame (~18 per frame incl. its realism pass; +1 frame if the fix mints a new look).

Edit EXACTLY ONE scene of a replication draft from a plain-language instruction — what's wrong, or just what should be different (e.g. "make the background a kitchen", "she holds the product in this shot", "rewrite the line to mention SPF"): the scene's concept entry is rewritten in isolation — visuals, frame brief, script, motion — and only that scene's frames and scripts re-derive; every other scene is untouched. A background move joins another scene's existing setting when it matches or gets a dedicated fresh one; an outfit/look change mints a new appearance state of the same avatar. The scene is addressed by any of its clip ids (get_scene_frames). Spends image credits (one frame per clip of the scene; the first returns in the response, the rest generate in the background). Scene duration, ordering, adding/removing scenes, and replacing the person are refused — those go through request_draft_edits. For pure wording changes prefer edit_scene_script (free); for whole-read rewrites prefer edit_draft_script.

Parameters:

• •project_id (string, required): The replication draft's project id.
• •clip_id (string, required): Any clip id of the scene to fix.
• •instruction (string, required): What should change in this scene, in the user's own words.

edit_scene_script

Edit scene script. Changes data. Spends no credits.

Rewrite ONE spoken scene's script on a draft (replication or script draft alike), in place — the clip's duration re-derives from the words automatically and the scene keeps its frame (free until Generate; the edited clip regenerates then). Structure-pinned: text past the single-clip budget is refused with trim guidance — use edit_draft_script for rewrites that should re-split scenes. Sung and b-roll scenes are refused (their timing belongs to the music/visuals — use request_draft_edits). Scene clip_ids and current lines come from get_scene_frames on replication drafts, or the project's clips (get_project) on script drafts.

Parameters:

• •project_id (string, required): The draft's project id.
• •clip_id (string, required): The scene's clip id.
• •script (string, required): The scene's new spoken line, verbatim.

edit_video

Edit video. Changes data. Spends no credits.

Make video edits from a natural-language instruction — the PREFERRED way to edit a project's timeline. A dedicated editing agent sees the project's current editor state (every element with its timing and screen position), the creative concept (what is spoken in each clip), and the workspace media library, then reasons holistically: it updates/replaces an existing text hook instead of stacking a duplicate, places new elements in free screen bands so nothing covers anything else, times brand media to the words that reference it, and keeps inserted demo videos muted under the presenter's voice. Validated operations are applied and saved server-side; the response reports exactly what was applied, what was rejected and why, and the agent's reasoning. Pass the user's intent (plus any specifics like asset names, wording, or timing) — do NOT hand-build editor JSON for edits this can express; set_editor_state remains the raw escape hatch for full-state rewrites.

Parameters:

• •project_id (string, required): The project id.
• •instruction (string, required): The edit to make, in natural language.

enable_campaign

Enable campaign. Spends credits: an enabled campaign auto-generates content each cycle (spends credits).

Turn an automation campaign on. An enabled campaign plans, writes and generates content for its members on every cycle, which spends credits automatically until it is disabled.

Parameters:

• •campaign_id (string, required): The campaign id (from list_campaigns).

generate_avatar_voices

Generate avatar voices. Spends credits: 1500 credits per premium voice (premium_count).

Step 3 of 4, premium voices only — the wizard's free basic voices are already there on get_avatar_wizard, so call this only when the user asked for premium options. Clones premium_count (1-3) premium video-model voices at 1500 credits each, waits for them, then returns voice_options with sample urls. Next: call select_avatar_voice(wizard_id, option_id) with the chosen id.

Parameters:

• •wizard_id (string, required): The wizard id.
• •premium_count (integer, optional): How many premium video-model voices to clone (required, 1-3; 1500 credits each).

generate_clips

Generate clips. Spends credits: video credits at each clip model's rate (Grok ~15.6/sec, Gemini Omni ~22.1/sec, Seedance ~53.3/sec).

Generate the video for a project's clips with their stored model (spends video credits at the model's per-second rate — call get_credit_pricing for current per-model rates). clip_indices is an optional JSON array of 0-based clip indices (e.g. [0,2]); omit to generate all clips. Runs in the background — poll get_project for clip generation_status.

Parameters:

• •project_id (string, required): The project id.
• •clip_indices (string, optional): Optional JSON array of 0-based clip indices, e.g. [0,1]. Omit for all clips.
• •keep_raw_voice (boolean, optional): Keep the model's raw audio instead of dubbing the avatar voice. Default false.

generate_replication_draft

Generate replication draft. Spends credits: video credits for every scene clip at the replica model's per-second rate, plus the final edit pass.

Approve a reviewed replication DRAFT into the full pipeline: generates every scene's clip, runs the final editing pass, and renders the video (spends video credits for the whole replica). This is the generate path for drafts built with replicate_project draft_only=true — the project's editor stays read-only until this completes. Poll get_replication_status(project_id).

Parameters:

• •project_id (string, required): The replication draft's project id.

generate_starting_frames

Generate starting frames. Spends 60 credits: 4 images × 15 credits.

Generate avatar starting-frame images for a project's concept using image generation (spends image credits, 15 per image). The project needs a selected avatar and a creative concept. Returns the generated image urls.

Parameters:

• •project_id (string, required): The project id.
• •camera_style (string, optional): Optional: selfie | tripod | tripod_full_body | podcast. Defaults to selfie.

generate_video

Generate video. Spends credits: video credits for each not-yet-generated clip at its model's rate (Grok ~15.6/sec, Gemini Omni ~22.1/sec, Seedance ~53.3/sec).

Render a project's video with its stored video model. Picks the avatar's frame, generates each clip, and stitches the final video. Spends credits per clip; runs in the background.

Parameters:

• •project_id (string, required): The project id to generate the video for.

get_analytics_summary

Get analytics summary. Read-only.

Summarize analytics for the workspace over the last N days on one platform (tiktok, instagram or facebook): total views, a per-avatar breakdown, and the accounts behind each avatar. Optionally narrow to one avatar by name or id.

Parameters:

• •days (integer, optional): Look-back window in days (1-365). Defaults to 30.
• •platform (string, optional): tiktok | instagram | facebook. Defaults to tiktok.
• •avatar (string, optional): Optional avatar name or avatar id — narrows the summary to that avatar's accounts.

get_avatar_wizard

Get avatar wizard. Read-only.

Check an in-progress avatar wizard: current step, generated scene images, and voice options. Use to poll when create_avatar or generate_avatar_voices reported the job was still running.

Parameters:

• •wizard_id (string, required): The wizard id.

get_conversation_info

Get conversation info. Read-only.

Get this conversation's id and workspace id. Share them when the user wants to report a bug or reference this chat with support — they let the team locate the exact transcript.

No parameters.

get_credit_balance

Get credit balance. Read-only.

Get the workspace's remaining credit balance.

No parameters.

get_project

Get project. Read-only.

Get a project's full detail: name, status, creative concept (speaker/background plus each clip's index, script, prompt_config.positive_prompt_template, words_in_prompt, duration_seconds, video_model, scene_kind, lyrics, scene_label, starting frame, generated video url and generation status — words_in_prompt: true means the clip's words ride in the template's quoted phrases and script is NOT what the video says; change such words by editing the quoted phrases and passing the clip back, every field included, through set_creative_concept), whether a replication build wove in brand promotion (promotional: true/false — recorded by replication and idea→script builds — or not_applicable when no build made that decision, e.g. verbatim scripts), final_video_duration_seconds (measured length of the rendered final video, 'unknown' until probed — prefer it over summing the clips' planned duration_seconds), generated_at (when the current video finished generating; empty until every clip has a generated video), and the full editor_state JSON (main video track trims plus overlay tracks: text hooks, captions, adjustments, audio). Read this before set_creative_concept / set_editor_state / generate_clips.

Parameters:

• •project_id (string, required): The project id.

get_replication_status

Get replication status. Read-only.

Check the replication job for a project started with replicate_project: status, progress and any error.

Parameters:

• •project_id (string, required): The replica's project id (from replicate_project).

get_scene_frames

Get scene frames. Read-only.

Read a replication project's per-scene frame state: each scene's editable frame brief (the frozen-instant description its frame generates from), its live frame url, and the full frame history — the build's frame plus every re-roll, each with the brief that produced it. Use before regenerate_scene_frame when the user wants to change what a scene shows.

Parameters:

• •project_id (string, required): The replication project's id.

list_avatar_generations

List avatar generations. Read-only.

List avatar jobs. Without arguments: the workspace's avatar-creation jobs. With avatar_project_id (from list_avatars): that avatar's profile-edit jobs — redesigns, premium voice, voice options — still running or finished but not yet reviewed by the user, with each finished job's result_summary (what actually changed) or error.

Parameters:

• •avatar_project_id (string, optional): Optional avatar project id — list one avatar's unresolved profile-edit jobs instead.

list_avatars

List avatars. Read-only.

List the avatars in the user's workspace with name, status and linked TikTok usernames.

No parameters.

list_campaign_assignments

List campaign assignments. Read-only.

List the avatar+account assignments the Automation studio plans content for: avatar name, TikTok account, home campaign, status and scripts-per-day cadence. assignment_id is what assign_avatar_to_campaign takes. avatar_active is the avatar's pause switch — campaigns only plan content for assignments whose avatar is active.

No parameters.

list_campaigns

List campaigns. Read-only.

List the workspace's automation campaigns (the Content > Automation tab). A campaign is an autonomous content cycle: on its schedule it plans and writes scripts for its member avatar+account assignments, generates their videos, and queues the posts. Returns each campaign's settings, next fire time and member count. Every workspace has a Default campaign that owns unassigned members.

No parameters.

list_library_frames

List library frames. Read-only.

List the active reusable scene/starting-frame library for a project's avatar — image urls you can set as clip starting frames in set_creative_concept. Each frame carries content_labels (camera framing, presenter, attire, skin, setting, lighting) and a scene_description paragraph, so you can pick the scene that best fits a clip.

Parameters:

• •project_id (string, required): The project id.

list_projects

List projects. Read-only.

List the user's video projects with name, status, visibility and created date. Archived projects are excluded unless include_archived is true. Pass posted_only to keep only videos that actually went live.

Parameters:

• •include_archived (boolean, optional): Also include archived projects. Defaults to false.
• •posted_only (boolean, optional): Only projects whose video actually got posted. Defaults to false.

list_scheduled_posts

List scheduled posts. Read-only.

List the workspace's scheduled and posted videos in a date window (the Content > Schedule queue): per post the account username, platform, scheduled time (UTC), status (pending, in_progress, completed, failed or cancelled) and project id. Use for questions like 'what's posting today' or 'which avatars have no post yet' (match account usernames to list_avatars).

Parameters:

• •from_date (string, optional): Window start date, YYYY-MM-DD (UTC). Defaults to today.
• •to_date (string, optional): Window end date inclusive, YYYY-MM-DD (UTC). Defaults to from_date + 7 days; capped at 90 days.

list_voice_effect_noises

List voice effect noises. Read-only.

List the room-tone beds set_clip_voice_effects can put under a clip's voice: the quiet ambience (fans, vents, traffic, rain) that makes generated audio sound recorded rather than synthesized. Each bed is a blend of 3 or 5 field recordings, all at the same loudness, so swapping one changes character and not level. Returns each bed's id, label and a preview URL.

No parameters.

regenerate_look_canon

Regenerate look canon. Spends credits: image credits — typically ~18 for the accepted canon (frame + realism pass); screened attempts bill at cost.

Regenerate a replication draft's LOOK CANON — the root image (generated from the avatar reference + the concept's words) that every scene frame anchors identity, wardrobe, and place to. Use when the user wants to change WHO/WHAT the video looks like (outfit, setting, continuity, the opening shot) — per-scene re-rolls cannot move those, they inherit them from the canon. Non-blank fields replace the concept's stored values; the new canon re-anchors every later re-roll (existing frames on other scenes keep the old look until re-rolled). Spends image credits.

Parameters:

• •project_id (string, required): The replication project's id.
• •outfit (string, optional): Optional replacement for the subject's outfit/look description.
• •background (string, optional): Optional replacement for the video's default setting description.
• •continuity (array, optional): Optional replacement continuity constraints (each item one constraint).
• •canon_scene_brief (string, optional): Optional replacement frozen-instant brief for the canon (first on-camera) scene.

regenerate_scene_frame

Regenerate scene frame. Spends credits: image credits — typically ~18 for the accepted frame (generation + realism pass); screened attempts bill at cost.

Re-roll ONE scene's starting frame on a replication draft — for a broken/failed frame or when the user wants a different take of that scene. The new frame stays anchored to the draft's look canon and is screened before it ships (spends image credits). Scene clip_ids come from get_studio_overview's drafts view, get_project, or get_scene_frames (which also carries each scene's current frame brief).

Parameters:

• •project_id (string, required): The replication draft's project id.
• •clip_id (string, required): The scene's clip id.
• •guidance (string, optional): Optional plain-language change for the shot (e.g. "wider angle", "no sunglasses").
• •frame_brief (string, optional): Optional edited frozen-instant scene description: replaces the scene's frame brief and the new frame generates from it. Read the current brief via get_scene_frames.

render_project

Render project. Changes data. Spends no credits.

Render the project's final video by stitching its generated clips with the current editor_state trims. Returns the rendered video url. Run after the clips are generated.

Parameters:

• •project_id (string, required): The project id.

replicate_project

Replicate project. Spends credits: image + video credits — ~18 per frame (generation + realism pass), plus the replica model's per-second video rate (e.g. Grok ~15.6/sec).

Replicate a reference video into a new project for an avatar: analyzes the reference (a TikTok url or a workspace/content-hub video url), rebuilds its script, frames and clips around the avatar, and generates the replica in the background (spends video credits for the whole replica; bulk requests past the workspace cap wait in a queue; draft_only=true stops at a reviewable draft instead). Passing source_project_id replicates one of the workspace's own projects the same way: its rendered video runs through the exact same analysis pipeline (the project must have a finished video). Returns the new project_id; poll get_replication_status(project_id) until it completes.

Parameters:

• •avatar_project_id (string, required): The avatar's project id (from list_avatars) to star in the replica.
• •tiktok_url (string, optional): The reference TikTok video url. Pass this, source_video_url, or source_project_id.
• •source_video_url (string, optional): A workspace/content-hub video url (GCS) to replicate instead of a TikTok.
• •source_project_id (string, optional): One of this workspace's own projects to replicate (from list_projects) — its rendered video is the reference, so it must have a finished video.
• •video_model (string, optional): Optional: grok-imagine-1.5 | seedance | gemini-omni. Defaults to the avatar's default video model, then gemini-omni.
• •max_duration_seconds (integer, optional): Optional target length in seconds — shorter OR longer than the original; omit to match the original length. Capped at 160s (longer requests are clamped, and a longer reference is condensed onto it).
• •variation_instructions (string, optional): Optional free-form changes to make vs the reference (product, hook, tone, setting…).
• •promotional (boolean, optional): Optional, default true. Pass false for a NON-promotional replica: the workspace's business context is not woven in and no brand/product promotion is added.
• •draft_only (boolean, optional): Optional, default false. True builds a reviewable draft (concept, avatar frames, editor state — only the analysis/frame build is charged) and stops before clip generation; the user generates from the project when ready.
• •acknowledge_low_feasibility (boolean, optional): Optional, default false. A source the feasibility judge marked hard to replicate gets a low_feasibility_warning with the judge's reason instead of starting, and one needing brand files the library lacks gets missing_brand_assets; pass true after the user confirms they want it anyway.

request_draft_edits

Request draft edits. Spends credits: image + AI credits — the concept re-composes and every scene frame regenerates (~18 per frame incl. its realism pass).

Apply the user's broad-stroke feedback to a replication DRAFT (e.g. "make the hook about SPF", "drop the pool scene", "more energy, shorter"): the creative concept re-composes with the feedback and everything downstream — scenes, frames, overlays, music plan, the draft's timeline — rebuilds from the revised concept (spends image + AI credits; takes a few minutes). Use for concept-level changes on drafts; use edit_video for timeline edits on generated videos.

Parameters:

• •project_id (string, required): The replication draft's project id.
• •feedback (string, required): The user's requested changes, in their own words — passed to the concept composer verbatim.

reroll_preset_voices

Reroll preset voices. Changes data. Spends no credits.

Swaps the wizard's three basic voices for three different ones from the curated roster (matched to the avatar's gender and age). Instant and free — use when the user wants to hear other basic options. Pass direction "deeper" or "higher" when the user asked for a deeper or higher-pitched voice; omit it for a fresh random spread. Premium options are untouched.

Parameters:

• •wizard_id (string, required): The wizard id.
• •direction (string, optional): Optional: "deeper" or "higher" to steer past the current picks; omit for random.

retry_draft_build

Retry draft build. Spends credits: only the stages after the last completed checkpoint re-run — worst case a full frame pass (~18 per frame incl. its realism pass).

Retry a FAILED replication draft build from its last completed checkpoint — only the stage that died (and everything after it) re-runs, so finished analysis/concept/frames are never re-paid. Use when get_replication_status shows job_status FAILED on a draft-only build; transient/timeout failures usually succeed on retry, while safety/content failures are better served by request_draft_edits.

Parameters:

• •project_id (string, required): The failed replication draft's project id.

revert_scene_edit

Revert scene edit. Changes data. Spends no credits.

Undo a scene's most recent edit_scene on a replication draft — the scene's concept entry, scripts, and frames restore instantly from the edit's own snapshot, at no cost (nothing regenerates). LIFO per scene: any scene with a revertible edit can be reverted regardless of edits to other scenes, and repeating the call on one scene steps back through its earlier edits. Refused once anything else has changed that scene since the edit.

Parameters:

• •project_id (string, required): The replication draft's project id.
• •clip_id (string, required): Any clip id of the scene the last edit touched.

run_campaign_now

Run campaign now. Spends credits: spends credits for the whole campaign batch.

Fire an automation campaign immediately: plans the GAP days — tomorrow through the day before the next scheduled cycle's posting window — so it tops up the coming days without stealing the scheduled cycle's own window (which still fires on time). Days that already have plans are planned around. If the scheduled window is already imminent, it plans that window instead. Spends credits once the batch is approved. Returns the created batch id; review it in the plan grid on Content > Automation.

Parameters:

• •campaign_id (string, required): The campaign id (from list_campaigns).

schedule_post

Schedule post. Changes data. Spends no credits.

Schedule a project's video to post at a given time (ISO 8601 UTC, e.g. 2026-12-25T14:00:00Z) or on a given date (yyyy-MM-dd — auto-picks a time that day). Pass tiktok_username to post to TikTok, also_post_to_instagram to post the same video to the avatar's Instagram, or both — both platforms are scheduled as ONE unit, so if either cannot be placed (device busy, no slot left that day) NOTHING is scheduled and the request is rejected. Requires a connected posting account — UNLESS the avatar has none on a platform yet: then pass await_new_account=true (TikTok) and/or await_new_instagram_account=true to schedule ahead of a managed-account purchase; each waiting post goes out automatically once its platform's purchased account is created and linked (buy with purchase_account_seats + link_avatar_project_id — buying both platforms together prices the second account at $50/mo instead of $100/mo).

Parameters:

• •project_id (string, required): The project id.
• •tiktok_username (string, optional): The TikTok account username to post to. Omit to post to Instagram only.
• •caption (string, required): The post caption.
• •scheduled_at (string, required): When to post: ISO 8601 UTC (e.g. 2026-12-25T14:00:00Z), or a date only (yyyy-MM-dd) to auto-pick a time that day.
• •also_post_to_instagram (boolean, optional): true to post the same video to the avatar's Instagram account in the same schedule.
• •instagram_username (string, optional): Which Instagram account to post to; omit when the avatar has exactly one.
• •share_to_facebook (boolean, optional): true to force Facebook cross-posting of the Instagram Reel, false to disable it; omit for auto.
• •await_new_account (boolean, optional): true to schedule to the avatar's first TikTok account BEFORE it exists (schedule-then-buy). The post fires once a purchased account links to the avatar. Cannot be combined with tiktok_username.
• •await_new_instagram_account (boolean, optional): true to schedule to the avatar's first Instagram account BEFORE it exists (schedule-then-buy). Cannot be combined with also_post_to_instagram/instagram_username. Combinable with a TikTok leg, live or awaiting.

select_avatar_voice

Select avatar voice. Spends credits: free for basic (roster) and already-generated premium picks; a pre-retirement designed option charges 100 credits when kept.

Step 4 of 4. Selects the avatar's voice by option id (a basic voice from get_avatar_wizard, or a premium clone from generate_avatar_voices) and finishes the wizard (basic voices are free; a premium clone was already charged when generated; the first kept scene becomes the profile image). Completion also starts background pose/angle variation generation for every kept scene (charged per generated image except on the user's first avatar) — no need to call generate_scene_variations for a freshly created avatar. Returns the finished avatar to use in create_video_project.

Parameters:

• •wizard_id (string, required): The wizard id.
• •option_id (string, required): The chosen voice option id.

set_clip_voice_effects

Set clip voice effects. Changes data. Spends no credits.

Adjust the realistic voice effects baked into generated clips' audio: the acoustic environment (inside/outside/car — auto-detected from the scene at generation time), the room character for inside scenes, and the strength of the camera-distance and head-direction automation (1-5, 3 is the lab's measured setting), the room-tone bed mixed under the voice — the quiet ambience a real phone recording always has (a bed is assigned automatically at generation time; list_voice_effect_noises returns the ids) — and the clean-up amounts de_ess / de_plosive (0-100, 0 = off) that soften close-mic esses and breath thumps. environment "none" removes the environment layer, noise "none" removes the bed; enabled=false reverts a clip to its un-effected audio. Reprocesses each clip's audio in place (video frames untouched, a few seconds per clip, no credits) and returns the new video URLs. clip_indices is an optional JSON array of 0-based clip indices; omit to apply to every clip with a generated video.

Parameters:

• •project_id (string, required): The project id.
• •clip_indices (string, optional): Optional JSON array of 0-based clip indices, e.g. [0,1]. Omit for all clips with videos.
• •environment (string, optional): "inside", "outside", "car", or "none" (no environment layer). Omit to keep each clip's current environment.
• •room (string, optional): Room character for inside scenes, smallest to biggest: "small", "small_plus", "medium", "large", "hall", or "livedroom" (typical furnished room). Car always uses the car cabin; outside has no room.
• •environment_strength (integer, optional): Environment effect strength 1-5 (Subtle, Low, Mid, High, Strong), scaling the environment's EQ and reverb together: 3 is the lab's measured setting, and indoor clips start at 1 because a phone at arm's length barely picks the room up.
• •distance_strength (integer, optional): Camera-distance effect strength 0-5: 0 = off, 3 = measured default.
• •head_direction_strength (integer, optional): Head-direction effect strength 0-5: 0 = off, 3 = measured default.
• •noise (string, optional): Room-tone bed id from list_voice_effect_noises (e.g. "mix5-07"), or "none" to remove the bed. Omit to keep each clip's current bed.
• •noise_volume (integer, optional): Room-tone loudness 0-100 (20 = default). 0 mutes the bed.
• •de_ess (integer, optional): De-esser amount 0-100 (0 = off, the default): softens loud esses above 5 kHz. Too much sounds lispy.
• •de_plosive (integer, optional): De-plosive amount 0-100 (0 = off, the default): tames breath thumps below 150 Hz. High amounts thin deep voices.
• •enabled (boolean, optional): false reverts the clips to their un-effected audio; true re-enables.

set_creative_concept

Set creative concept. Changes data. Spends no credits.

Set a project's creative concept with explicit clips. clips_json is a JSON array, one object per clip: [{"script":"...","duration_seconds":8,"starting_frame_url":"<url>","video_model":"grok-imagine-1.5"}]. duration_seconds is 4-10 for Gemini Omni and 4-15 for Grok Imagine and Seedance; starting_frame_url and video_model are optional. A clip may also carry "prompt_config":{"positive_prompt_template":"..."}, its video prompt template, plus scene_kind, lyrics, scene_label and parent_clip_id. The save writes exactly what it is given, so when re-saving a replication project pass every clip back with all of its get_project fields (prompt_config, duration_seconds, video_model, scene_kind, lyrics, scene_label, and parent_clip_id, which is how its take and frame follow it) and change only what should change: edit the template's quoted phrases to change what a words_in_prompt clip says (the save aligns that clip's script to the phrases and lists it in script_aligned_clips; a script written for such a clip does not take); omitting prompt_config drops the template so generation builds the default prompt from script, and omitting scene_kind reclassifies a lip-sync or b-roll clip as yapper. generate_clips renders them when the user asks for generation (spends video credits).

Parameters:

• •project_id (string, required): The project id.
• •speaker_description (string, required): Who is speaking / on camera.
• •background_description (string, required): The setting / background.
• •clips_json (string, required): JSON array of clips (see tool description).

set_editor_state

Set editor state. Changes data. Spends no credits.

Replace a project's ENTIRE editor_state — main video track trims plus any overlay tracks (text hooks, captions, adjustments) and audio. Read editor_state_json from get_project, modify it, and pass the whole object back; anything you leave out is removed. When changing one field of an existing item, copy the item verbatim and change only that field — never rebuild items from scratch (an item keeping its id inherits its prior placement/style for fields left null, but explicit values always win). Minimal shape: {"main_video_track":[{"clip_id":"<uuid>","in_point":0.0,"out_point":5.0,"type":"video"}]}. Overlay item shapes — text: {"id","type":"text","start","duration","text","x","y","w","style"} with x/y/w normalized 0..1 (x 0.5 = horizontally centered; y is the vertical CENTER, 0 = top edge — a 'top' hook is y≈0.12-0.2, bottom ≈0.8); always set x and y on text items, null renders center-frame. style.font_size is NOT normalized: it is px on the 1080x1920 reference frame — 64.0 is the platform hook default, 24.0 the readable minimum; a fraction-scale value here renders as unreadable glyph dust. Text never auto-wraps (break lines with \n in "text") unless "text_wrap":true, which makes w an explicit box width the text wraps inside — the editor's side-handle wrap box. adjust: {"id","type":"adjust","start","duration","adjust":{"saturation","contrast","brightness","temperature","tint"}} sliders -100..100, 0 = neutral. image/video (media inserts — logos, screenshots, product shots from list_assets, or any public url): {"id","type":"image"|"video","start","duration","src","x","y","w"} — src must be a DURABLE public url (an asset's signed url expires; re-host via the project's editor-asset upload before placing); w is the width fraction (1.0 = fullscreen, ~0.6 = floating pip, ~0.4 = logo flash), aspect ratio keeps itself; video items also take "media_in" (source trim start), "speed" (0.5-2.0 playback rate; start/duration stay timeline seconds — the item consumes duration×speed source seconds) and "volume" (set 0 so an inserted demo clip never talks over the presenter). A track entry with "use_original_voice":true renders that clip with its original (pre voice-replacement) audio. A track entry or media/audio overlay item may carry "voice_effect" (one of deep|reverb|room|phone|cheap_mic|no_bass|crisp|bass_boost|podcast|full|voice_focus) plus optional "voice_strength" 0-100 (default 100) — a voice-changer/mic-polish preset applied to that clip's audio in renders; omit voice_effect (or set "original") for no effect.

Parameters:

• •project_id (string, required): The project id.
• •editor_state_json (string, required): The full editor_state JSON (see tool description).

unarchive_project

Unarchive project. Changes data. Spends no credits.

Restore an archived video project by its id, bringing it back to the visible lists.

Parameters:

• •project_id (string, required): The project id (UUID) to restore.

Toolset editing

apply_clips

Apply clips. Changes data. Spends no credits.

Re-run the finishing pipeline for an automated project WITHOUT regenerating clips: re-stitches the current clip takes and re-applies text overlays, then updates the scheduled post video. Use after select_clip_video on an automated project. Requires automation to be completed or failed; runs in the background (poll get_project).

Parameters:

• •project_id (string, required): The project id.

delete_starting_frames

Delete starting frames. Changes data. Spends no credits.

Delete starting-frame images from a project's avatar library by frame id. This removes them from the reusable library, not from clips that already generated with them.

Parameters:

• •project_id (string, required): The project id.
• •frame_ids (string, required): JSON array of frame ids (UUIDs), e.g. ["<uuid>"].

duplicate_project

Duplicate project. Changes data. Spends no credits.

Duplicate a project as a fresh starting point: copies the avatar, speaker/background concept and starting frames but NOT the script, clips, generated videos or chat. Returns the new project id — set its script with set_creative_concept next.

Parameters:

• •project_id (string, required): The project id to duplicate (from list_projects).

duplicate_project_full

Duplicate project full. Changes data. Spends no credits.

Duplicate a project as an exact independent copy: script, clips, storyboard, already-generated clip videos (shared files, nothing re-billed), editor edits and the final video all come along. Use it to branch a project — edits and new generations in the copy never touch the original. Scheduled posts, chat history and approval state do NOT carry over, and neither do in-flight generations (duplicating mid-generation copies only the settled takes; the copy's remaining clips can be generated normally). Returns the new project id.

Parameters:

• •project_id (string, required): The project id to duplicate (from list_projects).

generate_project_description

Generate project description. Read-only.

Write a post description (caption) for a project from its script and the workspace's company profile: a scroll-stopping opening line plus exactly 5 relevant hashtags, pre-validated against the posting rules (max 5 hashtags, no @, no banned tags). Returns the text WITHOUT saving it anywhere — pass it on yourself as the caption to schedule_post or update_scheduled_post.

Parameters:

• •project_id (string, required): The project id.

get_render_job

Get render job. Read-only.

Check a project's render job started with start_render: status, output video urls and any error. Omit render_job_id for the most recent job. Poll after start_render until the status is terminal.

Parameters:

• •project_id (string, required): The project id.
• •render_job_id (string, optional): Optional job id (from start_render); omit for the latest job.

get_scene_frame_sequence

Get scene frame sequence. Read-only.

Distribute a scene's starting-frame pool (the reference frame plus its variations) across N clips the same way automation does — returns one frame url per clip, ready to paste into set_creative_concept as each clip's starting_frame_url. frame_url comes from list_library_frames.

Parameters:

• •project_id (string, required): The project id.
• •frame_url (string, required): The scene's reference frame image url (from list_library_frames).
• •clip_count (integer, required): How many clips to cover (1-100).

get_text_hook_placement

Get text hook placement. Read-only.

Get the on-screen placement of a project's text hook overlay (vertical center in pixels, font size, max width; 1080x1920 reference). Requires the project to have a text hook and a stitched video. Use before reposition_text_hook. If it reports no text hook, the hook may live in the editor state's overlay tracks instead — read get_project and move it there via set_editor_state + start_render.

Parameters:

• •project_id (string, required): The project id.

list_creative_concepts

List creative concepts. Read-only.

List a project's creative-concept versions (newest first): id, created date, whether it is the selected one, speaker/background descriptions, script and clip count. Pass creative_concept_id to instead get that version's clips with their scripts, video urls and generation statuses. Use before revert_creative_concept; the SELECTED concept's clips are already in get_project.

Parameters:

• •project_id (string, required): The project id (from list_projects).
• •creative_concept_id (string, optional): Optional concept version id to fetch that version's clip statuses.

list_text_style_presets

List text style presets. Read-only.

List the platform's named text style presets (id, label, one-line look description). Text overlay items saved via set_editor_state may carry "style_preset": "<id>" — the save resolves it into the preset's exact style values. Prefer a preset over hand-building a style.

No parameters.

list_video_generations

List video generations. Read-only.

List every generated take per clip of a project's selected concept (id, status, video url, created date), or pass clip_id (from get_project) for one clip's full take history. Pick a take with select_clip_video(video_generation_id).

Parameters:

• •project_id (string, required): The project id (from list_projects).
• •clip_id (string, optional): Optional clip id (from get_project) to list only that clip's takes.

preview_script_clips

Preview script clips. Read-only.

Preview how a script splits into video clips for a video model WITHOUT saving anything: returns each clip's text and duration. Use to check pacing before set_creative_concept or create_video_project.

Parameters:

• •script (string, required): The spoken script to split.
• •video_model (string, optional): Optional: grok-imagine-1.5 | seedance | gemini-omni. Defaults to the platform default.

reposition_bullets

Reposition bullets. Changes data. Spends no credits.

Re-detect when each on-screen text step is spoken against the project's current clips and trims, returning a start time (seconds on the timeline) per step. Works with a bullet-list overlay (entries are indexed by bullet position) or, when the project has none, with the editor's materialized hook/bullet text items (entries carry item_id — the editor overlay item to re-time). Apply the times via set_editor_state: by bullet index, or by item_id when present.

Parameters:

• •project_id (string, required): The project id.

reposition_text_hook

Reposition text hook. Changes data. Spends no credits.

Move a project's text hook overlay to a new vertical position (y_center in pixels on the 1080x1920 video; read the current placement with get_text_hook_placement) and re-render the overlay onto the video. Returns the updated video url.

Parameters:

• •project_id (string, required): The project id.
• •y_center (integer, required): The new vertical center of the text hook in pixels.
• •font_size (integer, optional): Optional font size override.
• •max_width (integer, optional): Optional max text width override in pixels.

resolve_bullet_texts

Resolve bullet texts. Changes data. Spends no credits.

Get a project's bullet overlay texts, generating and saving them from the script when they were never materialized (older projects). Requires a bullet-list overlay.

Parameters:

• •project_id (string, required): The project id.

restart_automation

Restart automation. Spends credits: regenerates every clip (spends video credits at the clip model's rate, e.g. Grok ~15.6/sec).

Restart an automated project's pipeline from scratch: regenerates EVERY clip (spends video credits for the whole video), re-stitches and re-applies overlays. Use resume_automation instead when only finishing a failed run.

Parameters:

• •project_id (string, required): The project id (from list_projects).

resume_automation

Resume automation. Spends credits: spends video credits for any clips that still need generating (per-model rate, e.g. Grok ~15.6/sec).

Resume a stopped or failed automated project from where it left off — generates any clips that still need video (spends video credits), then stitches, overlays and reschedules. Fails while clips are still generating or automation is already running.

Parameters:

• •project_id (string, required): The project id (from list_projects).

revert_creative_concept

Revert creative concept. Changes data. Spends no credits.

Revert a project's selected creative concept to a prior version (from list_creative_concepts). Restores that version's script, clips and editor state. Fails while automation is running.

Parameters:

• •project_id (string, required): The project id.
• •creative_concept_id (string, required): The concept version id to revert to (from list_creative_concepts).

select_clip_video

Select clip video. Changes data. Spends no credits.

Pick which generated take a clip uses in the final video, by video_generation_id from list_video_generations. Re-render with start_render or render_project afterwards to bake the change in.

Parameters:

• •project_id (string, required): The project id.
• •clip_id (string, required): The clip id (from get_project or list_video_generations).
• •video_generation_id (string, required): The take to use (from list_video_generations).

set_edited_video

Set edited video. Changes data. Spends no credits.

Replace a project's final (edited) video with a video downloaded from a url — use when the user supplies their own finished video instead of rendering in Pamba. The url must be a publicly reachable http(s) video file. Scheduled posts for the project pick up the new video.

Parameters:

• •project_id (string, required): The project id.
• •source_url (string, required): A public http(s) url of the video file to use.

set_video_model

Set video model. Changes data. Spends no credits.

Change the video model content will generate with, for DRAFTS and PROJECTS alike. Accepts one id or a comma list for bulk changes (e.g. switch every seedance draft to gemini-omni); each id may be a project id, a Drafts-tab content item id (get_studio_overview statuses=drafts — concept-stage drafts update their concept script and auto-resize its clip plan, re-running the checks), or a concept script id (get_content_batch). Projects re-split the stored script into clips under the new model's duration limits, except a project with a words_in_prompt clip (get_project), whose clips keep their prompts and are stamped with the new model, each duration coerced into its set — already generated videos are untouched until regenerated; costs nothing by itself. Ids mid-automation or without a concept yet are skipped with a per-id status.

Parameters:

• •project_ids (string, required): One id, or a comma-separated list: project ids (list_projects), Drafts-tab item ids (get_studio_overview statuses=drafts) or concept script ids (get_content_batch).
• •video_model (string, required): grok-imagine-1.5 | seedance | gemini-omni.

start_render

Start render. Changes data. Spends no credits.

Start a background render job that bakes the project's editor_state (trims, text hooks, captions, adjustments, audio) into the final video. Uses the saved editor_state; pass editor_state_json (same shape as set_editor_state, same rules: copy existing items verbatim and change only the fields you mean to change; Overlay item shapes — text: {"id","type":"text","start","duration","text","x","y","w","style"} with x/y/w normalized 0..1 (x 0.5 = horizontally centered; y is the vertical CENTER, 0 = top edge — a 'top' hook is y≈0.12-0.2, bottom ≈0.8); always set x and y on text items, null renders center-frame. style.font_size is NOT normalized: it is px on the 1080x1920 reference frame — 64.0 is the platform hook default, 24.0 the readable minimum; a fraction-scale value here renders as unreadable glyph dust. Text never auto-wraps (break lines with \n in "text") unless "text_wrap":true, which makes w an explicit box width the text wraps inside — the editor's side-handle wrap box. adjust: {"id","type":"adjust","start","duration","adjust":{"saturation","contrast","brightness","temperature","tint"}} sliders -100..100, 0 = neutral. image/video (media inserts — logos, screenshots, product shots from list_assets, or any public url): {"id","type":"image"|"video","start","duration","src","x","y","w"} — src must be a DURABLE public url (an asset's signed url expires; re-host via the project's editor-asset upload before placing); w is the width fraction (1.0 = fullscreen, ~0.6 = floating pip, ~0.4 = logo flash), aspect ratio keeps itself; video items also take "media_in" (source trim start), "speed" (0.5-2.0 playback rate; start/duration stay timeline seconds — the item consumes duration×speed source seconds) and "volume" (set 0 so an inserted demo clip never talks over the presenter).) to save and render new edits in one step. Returns the job id — poll get_render_job until it completes. If a render is already running, returns it instead of starting another — renders cannot be cancelled; wait for the running one and start again if the edits changed. Prefer this over render_project when overlay tracks must be applied.

Parameters:

• •project_id (string, required): The project id.
• •editor_state_json (string, optional): Optional full editor_state JSON to save before rendering; omit to render the saved state.
• •rebind_scheduled_post (boolean, optional): Re-point the project's pending scheduled posts at this render's output. Default false.

transcribe_clips

Transcribe clips. Spends credits: runs Speech-to-Text over the clips (~2 credits/min of video; identical repeat calls are served from cache free).

Transcribe a project's generated clips with word-level timestamps (seconds within each clip). Use to build word-timed caption overlays for set_editor_state or to check what is actually spoken.

Parameters:

• •project_id (string, required): The project id.

update_project

Update project. Changes data. Spends no credits.

Update a project's settings: rename it, set notes, approve it for posting (user_review_state "approved" — an automated scheduled post only publishes once approved), set posted_state, or change visibility ("archived" hides it and cancels its pending posts, "visible" restores an archived project). Only the fields you pass change.

Parameters:

• •project_id (string, required): The project id (from list_projects).
• •project_name (string, optional): Optional new project name. When inventing one, use sentence case: capitalize only the first word, proper nouns, and the pronoun I.
• •notes (string, optional): Optional notes to store on the project.
• •user_review_state (string, optional): Optional: not_reviewed | approved.
• •posted_state (string, optional): Optional: unapproved | approved | scheduled | posted | draft_created.
• •user_visibility (string, optional): Optional: visible | archived. "visible" unarchives a project.

Toolset avatars

acknowledge_avatar_generation

Acknowledge avatar generation. Changes data. Spends no credits.

Mark a finished avatar job as seen so it stops surfacing as "needs you" on Home (e.g. after the user listened to a generated premium voice). Id from list_avatar_generations.

Parameters:

• •job_id (string, required): The avatar job id.

apply_preset_voice

Apply preset voice. Changes data. Spends no credits.

Apply one basic (curated roster) voice from get_preset_voices to the avatar — free, no credit charge. Pass the voice_id that get_preset_voices returned.

Parameters:

• •avatar_project_id (string, required): The avatar's project id (from list_avatars).
• •voice_id (string, required): The chosen basic voice_id (from get_preset_voices).

cancel_avatar_wizard

Cancel avatar wizard. Changes data. Spends no credits.

Cancel an in-progress avatar wizard (id from list_avatar_wizards or create_avatar), discarding its generated scenes and voices.

Parameters:

• •wizard_id (string, required): The wizard id.

claim_auto_generated_avatars

Claim auto generated avatars. Changes data. Spends no credits.

Adopt ready-made avatars into the workspace (ids from list_auto_generated_avatars). Each claimed avatar gets its own avatar project and appears in list_avatars, ready for videos.

Parameters:

• •avatar_ids (string, required): JSON array of avatar ids from list_auto_generated_avatars, e.g. ["<uuid>"].

create_reference_frame

Create reference frame. Changes data. Spends no credits.

Internal Pamba users only. Add a shared reference frame from a TikTok url: the video's first frame becomes a scene template for generate_scenes_from_tiktoks and bulk generation.

Parameters:

• •tiktok_url (string, required): The reference TikTok video url.
• •camera_style (string, optional): Optional: selfie | tripod | tripod_full_body_visible | podcast. Defaults to selfie.
• •tags (string, optional): Optional JSON array of tags.

delete_avatar

Delete avatar. Changes data. Spends no credits.

Delete an avatar project and its avatar (pass the avatar_project_id from list_avatars). This removes the avatar from the workspace; it cannot be undone from chat.

Parameters:

• •avatar_project_id (string, required): The avatar's project id (from list_avatars).

delete_reference_frame

Delete reference frame. Changes data. Spends no credits.

Internal Pamba users only. Delete a shared reference frame (id from list_reference_frames).

Parameters:

• •reference_id (string, required): The reference frame id (from list_reference_frames).

delete_scene_frames

Delete scene frames. Changes data. Spends no credits.

Delete scene frames from an avatar's library by id (from list_scene_frames or list_scene_variations). Deleting a scene also deletes its variations. The avatar's profile image cannot be deleted — set another profile frame first.

Parameters:

• •frame_ids (string, required): JSON array of frame ids to delete, e.g. ["<uuid>"].

discard_wizard_scene

Discard wizard scene. Changes data. Spends no credits.

Remove one candidate scene from an avatar wizard (frame ids come from create_avatar or get_avatar_wizard). Use before accept_avatar_appearance to drop scenes the user dislikes.

Parameters:

• •wizard_id (string, required): The wizard id.
• •frame_id (string, required): The scene frame id to discard.

dismiss_avatar_generation

Dismiss avatar generation. Changes data. Spends no credits.

Dismiss a finished (usually failed) avatar job from the workspace's job list (id from list_avatar_generations). Jobs still generating cannot be dismissed.

Parameters:

• •job_id (string, required): The avatar job id.

generate_premium_voice

Generate premium voice. Spends 1500 credits: 1500 credits (premium voice).

Regenerate an avatar's voice as a premium video-model voice (spends premium-voice credits); nothing else about the avatar changes. Runs in the background — poll get_avatar_generation(job_id).

Parameters:

• •avatar_project_id (string, required): The avatar's project id (from list_avatars).
• •video_model (string, optional): Optional: grok-imagine-1.5 | seedance | gemini-omni. Defaults to seedance (text-to-video). Non-seedance models train image-to-video and require the avatar to have an appearance image.

generate_scene_frames

Generate scene frames. Spends 15 credits: 15 credits per image.

Generate new scene/starting-frame images for an avatar from a text prompt (spends image credits, 15 per image). The frames land in the avatar's library inactive — activate the keepers with update_scene_frame so videos can use them.

Parameters:

• •avatar_project_id (string, required): The avatar's project id (from list_avatars).
• •prompt (string, required): The scene to generate (setting, outfit, framing).
• •count (integer, optional): How many images (1-10). Defaults to 3.
• •camera_style (string, optional): Optional: selfie | tripod | tripod_full_body_visible | podcast. Defaults to selfie.
• •tags (string, optional): Optional JSON array of tags for the new frames.

generate_scene_variations

Generate scene variations. Spends credits: up to 90 credits — 15 per missing variation (tops up to 6).

Top a scene frame up to 6 pose/angle variations, generating the missing ones in the background (spends image credits, 15 per missing variation). Generates from the scene's own image — promote_scene_variation changes which image that is. Poll list_scene_variations(frame_id) for progress. Only works on library scenes, not on a variation itself.

Parameters:

• •frame_id (string, required): The scene frame id (from list_scene_frames).

generate_scenes_from_tiktoks

Generate scenes from tiktoks. Spends credits: 15 credits per generated image (urls x results_per_reference).

Recreate reference TikTok videos' scenes around an avatar: pass up to 5 TikTok urls; each gets results_per_reference frame candidates generated in a background job (spends image credits, 15 per image). New frames appear in list_scene_frames as they complete.

Parameters:

• •avatar_project_id (string, required): The avatar's project id (from list_avatars).
• •tiktok_urls (string, required): JSON array of 1-5 reference TikTok video urls.
• •results_per_reference (integer, optional): Frames to generate per reference (2-6). Defaults to 2.
• •camera_style (string, optional): Optional: selfie | tripod | tripod_full_body_visible | podcast. Defaults to selfie.

generate_wizard_scenes

Generate wizard scenes. Spends credits: 15 credits per scene image.

Generate more candidate scenes for an in-progress avatar wizard (spends image credits, 15 per scene). Waits for them and returns the wizard's current scene list.

Parameters:

• •wizard_id (string, required): The wizard id.
• •count (integer, optional): How many scenes to add (1-5). Defaults to 3.

get_avatar

Get avatar. Read-only.

Get an avatar project's full detail (pass the avatar_project_id from list_avatars): the avatar's appearance, status, tags, voice sample, linked TikTok/Instagram/Facebook accounts, warming state and the latest avatar job. Read this before changing settings or voices.

Parameters:

• •avatar_project_id (string, required): The avatar's project id (from list_avatars).

get_avatar_generation

Get avatar generation. Read-only.

Check one avatar job by id (from list_avatar_generations, get_avatar's latest_job, or a tool that started a job): status and error.

Parameters:

• •job_id (string, required): The avatar job id.

get_preset_voices

Get preset voices. Read-only.

Three curated basic voices for an existing avatar — human roster recordings matched to its gender and age. Browsing and applying basic voices is completely free. Pass direction "deeper" or "higher" to steer past previously returned picks (also pass exclude_voice_ids with those picks); omit for a fresh random spread.

Parameters:

• •avatar_project_id (string, required): The avatar's project id (from list_avatars).
• •direction (string, optional): Optional: "deeper" or "higher" to steer past the excluded picks; omit for random.
• •exclude_voice_ids (string, optional): Optional: comma-separated voice_ids already shown, so new picks rotate away from them.

import_avatar

Import avatar. Changes data. Spends no credits.

Create an avatar from an existing photo instead of generating one: pass a public image url (source_url), a name and a gender; a free basic voice is assigned to match. Returns the new avatar, ready for list_avatars and create_video_project.

Parameters:

• •name (string, required): The avatar's name.
• •gender (string, required): MALE or FEMALE.
• •source_url (string, required): Public http(s) url of the avatar's photo.
• •accent (string, optional): Optional voice accent. Defaults to Neutral American.
• •background_description (string, optional): Optional scene/background description. Defaults to bedroom.
• •speaker_description (string, optional): Optional description of how the avatar sounds.

list_auto_generated_avatars

List auto generated avatars. Read-only.

List the ready-made avatars Pamba has pre-generated and approved. These are available to adopt with claim_auto_generated_avatars instead of creating one from scratch with create_avatar.

No parameters.

list_avatar_wizards

List avatar wizards. Read-only.

List the workspace's in-progress avatar-creation wizards with their current step. Use get_avatar_wizard(wizard_id) for a wizard's scenes and voice options.

No parameters.

list_bulk_frame_generations

List bulk frame generations. Read-only.

Internal Pamba users only. List your bulk scene-generation jobs, or pass job_id for one job's detail including its generated frames and avatars.

Parameters:

• •job_id (string, optional): Optional bulk job id for full detail; omit to list your jobs.

list_reference_frames

List reference frames. Read-only.

List the shared golden reference frames (TikTok-derived scene templates used to generate avatar scenes), optionally filtered by tag. Each carries vision-derived content_labels (same fixed vocabulary as scene labels) and a content_description paragraph of its cover frame — match these against the avatar's look and the scenes you want when picking references. Reference ids feed update_reference_frame and delete_reference_frame.

Parameters:

• •tag (string, optional): Optional tag to filter by.

list_scene_frames

List scene frames. Read-only.

List an avatar's scene/starting-frame library with frame ids (pass the avatar_project_id from list_avatars): active and inactive frames, camera style, tags, profile flag and variation count. frame_id feeds update_scene_frame, delete_scene_frames, set_avatar_profile_frame, list_scene_variations and generate_scene_variations.

Parameters:

• •avatar_project_id (string, required): The avatar's project id (from list_avatars).

list_scene_variations

List scene variations. Read-only.

List a scene frame's pose/angle variations and the latest variation job (pass a frame_id from list_scene_frames). Prune a variation by deactivating or deleting it (update_scene_frame / delete_scene_frames); top the scene back up with generate_scene_variations.

Parameters:

• •frame_id (string, required): The scene frame id (from list_scene_frames).

promote_scene_variation

Promote scene variation. Changes data. Spends no credits.

Make one of a scene's variations the scene's reference frame. The two SWAP images: the variation becomes the scene (what the library shows and what generate_scene_variations starts from) and the image it replaces stays under the scene as a variation, so nothing is lost and promoting the demoted image swaps them back. Free. Clip frame urls and frame pools are unaffected — the set of images under the scene is identical, only which one is the reference changes.

Parameters:

• •frame_id (string, required): The scene frame id (from list_scene_frames).
• •variation_id (string, required): The variation to promote (from list_scene_variations).

redesign_avatar

Redesign avatar. Spends credits: may regenerate the appearance image and scenes (15 credits per image); voice changes assign a free preset.

Change an existing avatar with free-form instructions (e.g. 'blonde hair, gym setting, softer voice'): the avatar agent regenerates the appearance (spends image credits) and/or assigns a different free basic voice accordingly. Waits for the update, then returns the refreshed avatar. Not for creating avatars — use create_avatar.

Parameters:

• •avatar_project_id (string, required): The avatar's project id (from list_avatars).
• •instructions (string, required): What to change about the avatar.

rename_wizard_avatar

Rename wizard avatar. Changes data. Spends no credits.

Rename the avatar an in-progress wizard is creating (free). Available once the wizard's appearance is accepted and its avatar exists; names are capped at 80 characters.

Parameters:

• •wizard_id (string, required): The wizard id.
• •name (string, required): The new avatar name (1-80 characters).

replace_scene_image

Replace scene image. Changes data. Spends no credits.

Point a scene or variation at an edited image, DISCARDING the image it currently holds. Use save_scene_variation instead to keep both — that stores the edit as a new variation and leaves the original in place. Free: edit_image already charged for the image. The image_url must be an edit_image result (a Pamba storage url).

Parameters:

• •frame_id (string, required): The scene or variation whose image is being replaced.
• •image_url (string, required): The edited image url returned by edit_image.

save_scene_variation

Save scene variation. Changes data. Spends no credits.

Save an already-edited image as a new variation of a scene — the way to keep the result of edit_image in the avatar's library. Free: edit_image already charged for the image. Non-destructive, the edited frame itself is untouched. frame_id may be a scene or one of its variations; either way the new variation lands under the top-level scene.

Parameters:

• •frame_id (string, required): The scene or variation that was edited (from list_scene_frames or list_scene_variations).
• •image_url (string, required): The edited image url returned by edit_image.

select_avatar

Select avatar. Changes data. Spends no credits.

Set which avatar instance an avatar project displays and uses (after redesign_avatar generates new instances, get_avatar's chat history holds their ids). Free — an instance without a voice gets a free basic roster voice.

Parameters:

• •avatar_project_id (string, required): The avatar's project id (from list_avatars).
• •avatar_id (string, required): The avatar instance id to select.

set_avatar_profile_frame

Set avatar profile frame. Changes data. Spends no credits.

Set which scene frame is the avatar's profile image (id from list_scene_frames). The avatar's appearance descriptions re-sync to the new scene.

Parameters:

• •avatar_project_id (string, required): The avatar's project id (from list_avatars).
• •frame_id (string, required): The frame id to make the profile image.

set_tiktok_account_status

Set tiktok account status. Changes data. Spends no credits.

Set the operational status of one TikTok account linked to an avatar: TRACK_ANALYTICS_AND_POST_VIDEOS (fully active) or ONLY_TRACK_ANALYTICS (paused — no posting or warming). Get usernames from get_avatar's tiktok_accounts.

Parameters:

• •avatar_project_id (string, required): The avatar's project id (from list_avatars).
• •username (string, required): The linked TikTok username.
• •account_status (string, required): TRACK_ANALYTICS_AND_POST_VIDEOS | ONLY_TRACK_ANALYTICS.

track_external_tiktok_account

Track external tiktok account. Changes data. Spends no credits.

Attach a TikTok account the user owns (they post from their own phone — it does not need to be on a Pamba device) to an avatar for analytics-only tracking. Verifies the username on TikTok, then its metrics refresh hourly alongside managed accounts. Posting and warming stay unavailable for it; for accounts on workspace devices use update_avatar_settings instead.

Parameters:

• •avatar_project_id (string, required): The avatar's project id (from list_avatars).
• •username (string, required): The TikTok username to track, with or without @.

update_avatar_settings

Update avatar settings. Changes data. Spends no credits.

Update an avatar's operational settings (pass the avatar_project_id from list_avatars): status (active|inactive), the linked TikTok usernames (replaces the full set — accounts must already exist on a workspace device), tags, the warming search terms, and the avatar's default video-generation model (applies wherever this avatar generates video unless a campaign per-member override or an explicit per-video choice wins). Only the fields you pass change.

Parameters:

• •avatar_project_id (string, required): The avatar's project id (from list_avatars).
• •avatar_status (string, optional): Optional: active | inactive.
• •tiktok_usernames (string, optional): Optional JSON array of TikTok usernames to link, e.g. ["handle1"]. Replaces the current set.
• •tags (string, optional): Optional JSON array of tags. Replaces the current tags.
• •warming_search_terms (string, optional): Optional JSON array of search terms the avatar's warming sessions browse on TikTok, e.g. ["crossfit tips"]. Replaces the current set; an empty array clears it so sessions fall back to the workspace's auto-generated niche terms.
• •default_video_model (string, optional): Optional: gemini-omni | seedance | grok-imagine-1.5, or 'default' to clear — the avatar then follows the workspace routing rules, falling back to Gemini Omni.

update_reference_frame

Update reference frame. Changes data. Spends no credits.

Internal Pamba users only. Update a shared reference frame's tags and/or camera style (id from list_reference_frames).

Parameters:

• •reference_id (string, required): The reference frame id (from list_reference_frames).
• •camera_style (string, optional): Optional: selfie | tripod | tripod_full_body_visible | podcast.
• •tags (string, optional): Optional JSON array of tags. Replaces the current tags.

update_scene_frame

Update scene frame. Spends credits: free unless activating a scene with no variations, which auto-generates 6 (15 credits each).

Update a scene frame (id from list_scene_frames or list_scene_variations): activate or deactivate it (active frames are what videos use; deactivating a variation prunes it), or change its camera_style/tags. Activating a scene with no variations auto-generates 6 (spends image credits).

Parameters:

• •frame_id (string, required): The frame id.
• •active (boolean, optional): Optional: true to activate, false to deactivate.
• •camera_style (string, optional): Optional: selfie | tripod | tripod_full_body_visible | podcast.
• •tags (string, optional): Optional JSON array of tags. Replaces the current tags.

update_wizard_appearance

Update wizard appearance. Spends credits: regenerates the appearance and scene images (15 credits per image).

Redo an avatar wizard's appearance from a new prompt before it is accepted: regenerates the appearance and scene images (spends image credits). Waits for the new scenes and returns them.

Parameters:

• •wizard_id (string, required): The wizard id.
• •appearance_prompt (string, required): The new appearance description.

upload_scene_frame

Upload scene frame. Spends 90 credits: the upload is free but auto-generates 6 scene variations (15 credits each).

Add a user-provided image to an avatar's scene library from a public url (source_url). The frame is stored active, and 6 pose variations are auto-generated for it (spends image credits).

Parameters:

• •avatar_project_id (string, required): The avatar's project id (from list_avatars).
• •source_url (string, required): Public http(s) url of the image to add.
• •camera_style (string, optional): Optional: selfie | tripod | tripod_full_body_visible | podcast. Defaults to selfie.
• •tags (string, optional): Optional JSON array of tags for the frame.

Toolset accounts

acknowledge_account_profile_edit

Acknowledge account profile edit. Changes data. Spends no credits.

Mark a finished TikTok profile-edit job as seen (job_id from list_account_profile_edits) so it leaves the avatar page's activity tray. Jobs still queued or applying can't be acknowledged.

Parameters:

• •avatar_project_id (string, required): The avatar's project id (from list_avatars).
• •job_id (string, required): The profile-edit job id.

cancel_account_seat

Cancel account seat. Changes data. Spends no credits.

Cancel one managed account's paid seat. The account keeps posting until the already-paid period ends (the returned effective date), then it stops posting and stops billing — no refund is issued because the period was already paid. The monthly saving is the seat's monthly_cents from get_seat_billing: $50 when it's the bundled half of a TikTok+Instagram pair (its partner then bills at the full $100), $100 otherwise. Undo before the date with reinstate_account_seat. Only accounts funded by a purchased seat can be cancelled (see get_seat_billing).

Parameters:

• •platform (string, required): tiktok | instagram | facebook.
• •username (string, required): The account handle, without @.

cancel_scheduled_post

Cancel scheduled post. Changes data. Spends no credits.

Cancel a PENDING scheduled post (frees its slot and returns the project to approved-to-post), or dismiss a FAILED post so it disappears from the queue. Optionally archive the post's project too. Pass a post id from list_scheduled_posts.

Parameters:

• •post_id (string, required): The scheduled post id (from list_scheduled_posts).
• •archive_project (boolean, optional): Also archive the post's project when cancelling. Defaults to false.

cancel_warming_session

Cancel warming session. Changes data. Spends no credits.

Cancel a PENDING warming session so it never runs. Pass a session id from list_warming_sessions; in-progress or finished sessions cannot be cancelled.

Parameters:

• •session_id (string, required): The warming session id (from list_warming_sessions).

check_account_username

Check account username. Read-only.

Whether a username is currently free on TikTok or Instagram — the check behind the post-purchase username picker. Returns availability: available | taken | invalid (with the format rule broken) | unknown (provider hiccup, proof of nothing). Availability is a strong hint, not a reservation: the real claim happens on the phone during account setup.

Parameters:

• •platform (string, required): tiktok or instagram.
• •username (string, required): The handle to check, with or without @.

close_account_incident

Close account incident. Changes data. Spends no credits.

Manually close an account incident from list_account_incidents (for example after the suspension appeal succeeded and the account is verified restored). Closing a SUSPENDED incident resumes posting and warming; closing a TikTok health incident (ACCOUNT_WARNING / VIDEO_REMOVED / VIDEO_NOT_RECOMMENDED) is the user's Dismiss: it stops counting against the account, the Home item retires once the account has no other open issue, and later checks will not reopen or re-alert it. Incidents also close automatically when a session runs clean.

Parameters:

• •incident_id (string, required): The incident id from list_account_incidents.

create_social_account

Create social account. Changes data. Spends no credits.

Create a brand-new TikTok, Instagram or Facebook account for an avatar on one of the workspace's posting iPhones (runs the full on-device signup with a managed email). Returns a job_id — poll get_account_creation_status(platform, job_id). Get device udids from list_posting_devices. Internal Pamba users only.

Parameters:

• •platform (string, required): tiktok | instagram | facebook.
• •avatar_project_id (string, required): The avatar's project id (from list_avatars).
• •device_udid (string, required): The posting device udid (from list_posting_devices).
• •identity_name (string, optional): Optional full name seeding the account identity; defaults to the avatar's name.
• •replace_username (string, optional): TikTok only: an existing account to log out of the device before creating the new one.

enable_instagram_ai_creator

Enable instagram ai creator. Changes data. Spends no credits.

Turn on the Instagram 'AI creator' profile label for a connected account (runs live on the hosting iPhone; idempotent — an already-on label is left untouched). The label can only be enabled from Pamba, never disabled.

Parameters:

• •username (string, required): The Instagram account username.

get_account_creation_status

Get account creation status. Read-only.

Check an account-creation job started with create_social_account: state, stage, the created username/email once available, and any error. Internal Pamba users only.

Parameters:

• •platform (string, required): tiktok | instagram | facebook.
• •job_id (string, required): The creation job id (from create_social_account).

get_account_link_status

Get account link status. Read-only.

Check an account-link job started with link_social_account: running, completed or failed, plus any error. A job that is no longer found is terminal — re-check the account with list_posting_devices.

Parameters:

• •job_id (string, required): The link job id (from link_social_account).

get_account_warming_config

Get account warming config. Read-only.

Get the account-level warming configuration for a social account that belongs to NO avatar — unassigned workspace accounts warm on their own by default, governed by this config. Returns enabled/status, the account's explicit search terms, the workspace's auto-generated niche fallback terms (returned only when no explicit terms are set — that is when sessions use them), the last run time, and any error. If the account IS assigned to an avatar it returns that avatar_project_id instead — the avatar's config governs then, so use get_warming_config with it.

Parameters:

• •platform (string, required): "tiktok" or "instagram".
• •username (string, required): The account handle, with or without @.

get_scheduled_post

Get scheduled post. Read-only.

Get one scheduled/posted video's full detail (the Content > Schedule queue): account, platform, caption, scheduled time, status, error message, attempt count, posted TikTok url and Facebook cross-post flag. Pass a post id from list_scheduled_posts. Use before update_scheduled_post, cancel_scheduled_post or retry_scheduled_post.

Parameters:

• •post_id (string, required): The scheduled post id (from list_scheduled_posts).

get_seat_billing

Get seat billing. Read-only.

What the workspace pays for managed account seats: paid seat count (with how many of those are cancelled and stop at the next renewal), the next renewal's monthly total (TikTok+Instagram pairs bill the second seat at the bundle price), renewal date, and each seat-funded account's state (active, or pending_cancel with the date it stops) with its monthly_cents — what that seat adds to the bill and exactly what cancelling it saves ($50 for the bundled half of a pair, $100 otherwise). Use before cancelling or reinstating a seat, and for 'what am I paying for accounts' questions.

No parameters.

get_tiktok_account_health

Get tiktok account health. Read-only.

What TikTok itself is showing about one of this workspace's TikTok accounts: the latest account-health check (screenshots of the Profile tab, the recent video grid and the newest videos' analytics, captured once a day by the account's phone) and the open issues the vision pass found: ACCOUNT_WARNING (a warning label by the username), VIDEO_REMOVED (a video TikTok removed for a Community Guidelines violation) and VIDEO_NOT_RECOMMENDED (a video kept out of the For You feed). Each issue carries TikTok's stated reason when visible, evidence screenshot URLs, and whether an appeal was requested. Use when the user asks why a TikTok video has no reach, whether a video was removed or flagged, or what the last account check found.

Parameters:

• •username (string, required): The TikTok username (with or without @).

get_warming_config

Get warming config. Read-only.

Get the automatic warming configuration for an avatar project's accounts: whether warming is enabled, its status, the daily minutes/session anchors, the explicit search terms sessions browse, the workspace's auto-generated niche fallback terms (returned only when no explicit terms are set — that is when sessions use them), and any error. Pass an avatar_project_id from list_avatars.

Parameters:

• •avatar_project_id (string, required): The avatar's project id (from list_avatars).

link_social_account

Link social account. Changes data. Spends no credits.

Link a pre-existing Instagram or Facebook account to an avatar. Instagram has two modes: omit password to adopt one of the workspace's SPARE accounts — already signed in on a Pamba phone with no avatar assigned (list_posting_devices' instagram_accounts minus the linked ones in list_accounts) — which links instantly, free, and sends any posts waiting for the avatar's first Instagram account; or pass password + device_udid to log an outside account in on a posting iPhone. Facebook always needs credentials: the profile name as username, plus login_identifier (the login phone number or email) and password. Credential links return a job_id — poll get_account_link_status(job_id).

Parameters:

• •platform (string, required): instagram | facebook.
• •avatar_project_id (string, required): The avatar's project id (from list_avatars).
• •device_udid (string, optional): The posting device udid (from list_posting_devices). Required with password; omit for a spare adoption — the account already sits on its device.
• •username (string, required): The Instagram handle, or the Facebook profile name (e.g. 'Maya Bennett').
• •password (string, optional): The account password. Omit to adopt an Instagram spare account instead of logging one in.
• •login_identifier (string, optional): Facebook only: the login phone number or email.

list_account_incidents

List account incidents. Read-only.

Account incidents for this workspace's social accounts. SUSPENDED is opened when a device job hits Meta's suspension wall (Instagram/Facebook); while it is open the account shows a SUSPENDED health flag in list_accounts and Pamba pauses its posting and warming. The TikTok health kinds ACCOUNT_WARNING, VIDEO_REMOVED and VIDEO_NOT_RECOMMENDED are opened per video by the warming-session check and never pause the account; read them with get_tiktok_account_health and answer appeals with request_tiktok_appeal. Incidents close automatically when a session runs clean (or, for the TikTok kinds, when a later check no longer shows the issue), or manually via close_account_incident. Use when an account stopped posting, shows a health flag, or the user asks about a suspension or restriction.

Parameters:

• •platform (string, optional): Optional platform filter: tiktok | instagram | facebook.
• •username (string, optional): Optional account username filter (Facebook uses the profile name).
• •include_closed (boolean, optional): Include closed incidents too (default false).

list_account_profile_edits

List account profile edits. Read-only.

List an avatar's unresolved TikTok profile-edit jobs (pass avatar_project_id from list_avatars): edits queued or applying on the hosting iPhone, plus finished-but-unreviewed results. Each job carries per-field operations (display_name / username / profile_picture / disable_ai_comments) with success, error_code and a user-readable error_reason — the same feed as the avatar page's activity tray.

Parameters:

• •avatar_project_id (string, required): The avatar's project id (from list_avatars).

list_accounts

List accounts. Read-only.

The workspace's social-account inventory (the Creators > Accounts page): every TikTok, Instagram and Facebook account linked to an avatar, with its status (posting, track_only, archived), health flags (SHADOWBAN_RISK, only raised once the account has been tracked for 3+ weeks; NOT_RECOMMENDED; SUSPENDED while a Meta suspension incident is open; and the TikTok health kinds ACCOUNT_WARNING, VIDEO_REMOVED, VIDEO_NOT_RECOMMENDED while the warming-session check has those open; details and screenshots via get_tiktok_account_health), assigned avatar, hosting device, posts-per-day cap, last-7-day views, and last completed post. Use for 'which accounts do I have', account health questions, and before changing an account's status or cap.

Parameters:

• •platform (string, optional): Optional platform filter: tiktok | instagram | facebook.

list_posting_devices

List posting devices. Read-only.

List the workspace's managed posting iPhones with the TikTok and Instagram accounts logged in on each, plus posting readiness: device count and self-post mode. Pass tiktok_username to also check whether that specific account is on a device (account_on_device). Use for 'which accounts can post automatically' and before schedule_post. An account not on a device posts once a purchased account seat replaces it — see purchase_account_seats.

Parameters:

• •tiktok_username (string, optional): Optional TikTok username to check device readiness for.

list_warming_sessions

List warming sessions. Read-only.

List the workspace's account-warming sessions (automated TikTok/Instagram/Facebook feed browsing that keeps accounts healthy): per session the account, platform, scheduled time, status (pending, in_progress, completed, failed, cancelled), duration and any error. Filter by status, account username or avatar_project_id (from list_avatars).

Parameters:

• •status (string, optional): Optional status filter: pending | in_progress | completed | failed | cancelled.
• •account_username (string, optional): Optional account username filter.
• •avatar_project_id (string, optional): Optional avatar project id filter (from list_avatars).

purchase_account_seats

Purchase account seats. Changes data. Spends no credits.

Buy managed social-account seats for the workspace ($100/month each, Stripe subscription; every 3 seats include a dedicated posting phone; any quantity up to 1000 per checkout can be bought — accounts beyond the phones free right now stay 'being set up' until the team adds phones — TikTok and Instagram are purchasable; Facebook rides Instagram cross-posting instead of its own seat). free_seats_remaining lists seats an operator granted the workspace for free, per platform: a purchase that fits the remaining grant on every platform checks out at $0 with no card (say so instead of quoting $100), while one seat past the grant prices the WHOLE purchase at list, so split it into the free part and a paid part. Platform bundle: every TikTok+Instagram PAIR across the subscription prices its second account at $50/month instead of $100 (1+1=$150/mo, 2+2=$300/mo, 2+3=$400/mo; never within one platform; top-ups and cancels re-price the pairs). Call with no seat counts to see the options (price, current seats, purchases still being set up); pass tiktok_seats and/or instagram_seats to get a checkout_url the user must open to pay. After payment brand-new accounts are created on the workspace's phones — a purchase never adopts an existing spare (link those free instead); setup progress shows on the Accounts tab and in this tool's being_set_up field. A workspace already subscribed to seats gets a Stripe confirm-page link instead of a new checkout: it shows the prorated amount for the added seats and raises the existing subscription's quantity on Confirm. Pass link_avatar_project_id when the user is buying the account FOR a specific avatar: the created account then links to that avatar automatically (and any TikTok posts scheduled ahead via schedule_post's await_new_account go out with no further action).

Parameters:

• •tiktok_seats (integer, optional): How many TikTok account seats to buy. Omit or 0 for none.
• •instagram_seats (integer, optional): How many Instagram account seats to buy. Omit or 0 for none. Omit both counts to just read the options.
• •return_path (string, optional): App path Stripe returns the user to after checkout. Defaults to /.
• •link_avatar_project_id (string, optional): Avatar project the created accounts should auto-link to. Omit for an unassigned purchase the user links later.

reassign_account

Reassign account. Changes data. Spends no credits.

Move a social account to a different avatar in this workspace (the Accounts inventory's reassign action). Only the avatar binding moves — the account keeps its posting status, device, cap, and analytics history. Get the account (and its current avatar_project_id, passed as from_avatar_project_id) from list_accounts and the target avatar_project_id from list_avatars.

Parameters:

• •platform (string, required): The account's platform: tiktok | instagram | facebook.
• •username (string, required): The account's username (with or without @).
• •from_avatar_project_id (string, required): The avatar project the account is currently assigned to (from list_accounts).
• •avatar_project_id (string, required): The target avatar's project id (from list_avatars).

reconcile_tiktok_rename

Reconcile tiktok rename. Changes data. Spends no credits.

TikTok only: reconcile an account @handle that was renamed on TikTok itself (not via Pamba). Moves the avatar's active account and ALL forward-looking work — draft/approved scripts, plan slots, pending scheduled posts, warming, device + tracking — to the new handle so generation stops failing with 'not a postable tracked account'. Old, already-posted content stays under the old handle. Pass the account's current (old) handle and the new handle; both are on the same avatar.

Parameters:

• •old_username (string, required): The account's current TikTok handle before the rename.
• •new_username (string, required): The new TikTok handle the account was renamed to.

reinstate_account_seat

Reinstate account seat. Changes data. Spends no credits.

Undo a not-yet-lapsed seat cancellation (from cancel_account_seat): the account keeps posting and billing resumes from the next invoice. Costs nothing extra for the current period.

Parameters:

• •platform (string, required): tiktok | instagram | facebook.
• •username (string, required): The account handle, without @.

request_tiktok_appeal

Request tiktok appeal. Changes data. Spends no credits.

Ask TikTok to review a restricted or removed video (a VIDEO_REMOVED or VIDEO_NOT_RECOMMENDED issue from get_tiktok_account_health). Records the workspace's decision and alerts the Pamba team, who file the appeal from the account's phone by hand; TikTok allows one appeal per video. Confirm the user wants to appeal that specific video before calling. Not available for ACCOUNT_WARNING issues.

Parameters:

• •incident_id (string, required): The incident id of the issue from get_tiktok_account_health.

resume_account_creation

Resume account creation. Changes data. Spends no credits.

Resume a FAILED TikTok account-creation job from the step it died on, reusing the Outlook mailbox it already provisioned instead of paying for a new one. Use this rather than create_social_account after a downstream failure. Internal Pamba users only.

Parameters:

• •job_id (string, required): The failed creation job id.

retry_scheduled_post

Retry scheduled post. Changes data. Spends no credits.

Retry a FAILED (or cancelled) post: re-plans the next available device slot and requeues it. If the project's final render is failed or stale, a fresh render starts automatically and the requeued post publishes its output. Facebook posts can't be retried directly — reschedule via schedule_instagram_post with share_to_facebook instead.

Parameters:

• •post_id (string, required): The scheduled post id (from list_scheduled_posts).

schedule_instagram_post

Schedule instagram post. Changes data. Spends no credits.

Schedule an Instagram Reel post for an avatar's connected Instagram account, optionally cross-posting to the linked Facebook account (share_to_facebook: omit for auto — cross-posts when the linked Facebook account is posting-ready). This is also the ONLY way to post to Facebook. video_url must be a Pamba storage url (e.g. a project's rendered video from get_project), OR omit it with a project_id to post the project's final video as it stands at post time (like schedule_post — works even before the video is rendered; the post fails cleanly if the project isn't approved/rendered by then). A precise time gets a 30-minute minimum lead and bumps to the next free device slot on conflict; a date-only time auto-picks a slot in the device's posting window. When the avatar has NO Instagram account yet, pass await_new_account=true (with project_id, no username): the post persists waiting and goes out automatically once a purchased account is created and linked (buy with purchase_account_seats + link_avatar_project_id). TikTok posts use schedule_post instead.

Parameters:

• •avatar_project_id (string, required): The avatar's project id (from list_avatars).
• •video_url (string, optional): The video to post — a Pamba storage url. Omit (with project_id) to resolve the project's final video at post time.
• •caption (string, required): The post caption.
• •scheduled_at (string, required): When to post: ISO 8601 UTC (e.g. 2026-12-25T14:00:00Z), or a date only (yyyy-MM-dd) to auto-pick a time that day.
• •instagram_username (string, optional): Which of the avatar's Instagram accounts to post to; omit when it has exactly one.
• •project_id (string, optional): Optional project to attribute the post to (from list_projects).
• •share_to_facebook (boolean, optional): true to force Facebook cross-posting, false to disable it; omit for auto.
• •await_new_account (boolean, optional): true to schedule to the avatar's first Instagram account BEFORE it exists (schedule-then-buy). Requires project_id; cannot be combined with instagram_username or video_url.

set_account_username

Set account username. Changes data. Spends no credits.

Save the username for one purchased account seat that is waiting for its name — this is what starts that seat's account creation (a bought seat waits until it has a name). Pass use_default_name=true instead of a username to create the account with a platform default the user can rename later. The name is applied where the platform allows: Instagram types it at signup; TikTok assigns its own handle and the pick is applied as a rename right after creation — that rename is TikTok's one username change per 30 days, so say so when the user picks. If the name can't be used when applied, close variations are tried; if none works the account keeps its platform-assigned handle and can be renamed later from Edit profile. Call suggest_account_usernames first for checked ideas; find waiting seats in purchase_account_seats' being_set_up field (seat_request_id + unnamed_seats).

Parameters:

• •seat_request_id (string, required): The pending seat request the name is for (from purchase_account_seats / suggest_account_usernames).
• •username (string, optional): The chosen handle, with or without @. Omit when use_default_name is true.
• •use_default_name (boolean, optional): True to provision with a platform default name instead of a pick.

set_account_warming_search_terms

Set account warming search terms. Changes data. Spends no credits.

Replace the warming search terms of an UNASSIGNED social account (one that belongs to no avatar). Terms steer the account's automated browsing sessions; an empty array clears them so sessions fall back to the workspace's auto-generated niche terms. For an avatar-assigned account use update_avatar with warming_search_terms instead.

Parameters:

• •platform (string, required): "tiktok" or "instagram".
• •username (string, required): The account handle, with or without @.
• •search_terms (string, required): JSON array of search terms, e.g. ["crossfit tips"]. Replaces the current set; [] clears.

set_social_account_status

Set social account status. Changes data. Spends no credits.

Pause or resume posting on a connected Instagram or Facebook account. Paused accounts keep tracking analytics but schedule no posts or warming, and pausing cancels the account's pending activity. TikTok accounts use set_tiktok_account_status instead.

Parameters:

• •platform (string, required): instagram | facebook.
• •username (string, required): The account username (Facebook: profile name).
• •posting_enabled (boolean, required): true to resume posting, false to pause (analytics-only).

suggest_account_usernames

Suggest account usernames. Read-only.

A checked, currently-free username suggestion for purchased account seats still waiting for their name, up to 100 per purchase. Suggestions derive from the linked avatar's persona and are each confirmed free before being offered (a seat whose search found nothing free, or one past the 100, comes back without a username — the user names those). Offer them to the user, then save the accepted ones with set_account_username.

No parameters.

update_account_profile

Update account profile. Changes data. Spends no credits.

Edit a connected account's on-device profile: display name, username/handle, profile picture (a Pamba storage image url), bio (TikTok up to 160 characters, Instagram up to 150; Facebook has none) and — TikTok only — the AI-comment filter (disable_ai_comments) and its automation (auto_block_ai_comments, which applies once the account is linked to an avatar). The edit runs live on the hosting iPhone; if the device is busy the TikTok edit is queued and applied automatically. Facebook accounts are keyed by profile name (e.g. 'Maya Bennett'), not a handle.

Parameters:

• •platform (string, required): tiktok | instagram | facebook.
• •username (string, required): The account's current username (TikTok/Instagram handle, or Facebook profile name).
• •new_display_name (string, optional): Optional new display name.
• •new_username (string, optional): Optional new username/handle (Facebook: new profile name).
• •new_profile_picture_url (string, optional): Optional new profile picture image url.
• •new_bio (string, optional): Optional new bio text (TikTok and Instagram only). A URL typed here is plain bio text; the profile's link field is separate and untouched.
• •disable_ai_comments (boolean, optional): TikTok only: turn the AI-comment filter on (true) or off (false). Setting it also turns off the automatic filter — the user has taken over.
• •auto_block_ai_comments (boolean, optional): TikTok only: whether Pamba may turn the AI-comment filter on automatically for this Pamba-created account (on unless the user turned it off). It only applies once the account is linked to an avatar (an unassigned account is never filtered): linked at creation, the filter lands after the first post; linked later, it is queued at link time.

update_scheduled_post

Update scheduled post. Changes data. Spends no credits.

Edit a PENDING or FAILED scheduled post: time (PENDING only; ISO 8601 UTC), caption, privacy, target account, video url, keep-TikTok-song and draft-only flags, or the Facebook cross-post toggle (Instagram posts only). Rescheduling a PENDING TikTok post also moves the project's pending Instagram/Facebook cross-posts to follow it; rescheduling a cross-post directly moves only that post, bumping forward past occupied device slots instead of failing — check the returned scheduled_at_utc for the resolved time. A FAILED post stays failed after editing — call retry_scheduled_post to requeue it.

Parameters:

• •post_id (string, required): The scheduled post id (from list_scheduled_posts).
• •scheduled_at (string, optional): New post time: ISO 8601 UTC (e.g. 2026-12-25T14:00:00Z), or a date only (yyyy-MM-dd) to auto-pick a time that day. PENDING posts only.
• •caption (string, optional): New caption.
• •privacy (string, optional): public | only_you.
• •account_username (string, optional): New target account username (TikTok posts only).
• •video_url (string, optional): New video url to post (a Pamba storage url, e.g. from get_project).
• •share_to_facebook (boolean, optional): Toggle Facebook cross-posting (Instagram posts only).
• •keep_tiktok_song (boolean, optional): Keep the TikTok-suggested song on the post.
• •only_create_draft (boolean, optional): Save as a TikTok draft instead of publishing.

Toolset ideas

add_tracked_accounts

Add tracked accounts. Changes data. Spends no credits.

Start tracking external TikTok accounts as inspiration/research sources: their video history and metrics are fetched in the background and become searchable via search_tracked_videos (with include_research_accounts). Requires a subscription (a plan or account seats); the cap scales with the plan tier (Hobby 1: 1 account, other Hobby tiers: 3, Pro N: 5×N), floored at 3 while the workspace holds account seats. Over-cap attempts return the user's exact cap.

Parameters:

• •usernames (string, required): Comma-separated TikTok usernames to track (with or without @).

branch_idea

Branch idea. Changes data. Spends no credits.

Branch an idea into a child variant that shares the same analyzed reference video — use to explore a different angle on the same TikTok without losing the original. Requires a subscription (a plan or account seats).

Parameters:

• •idea_id (string, required): The parent idea id (from list_ideas).
• •new_title (string, required): Title for the new branched idea.
• •notes (string, optional): Optional notes for the branch.

create_idea

Create idea. Changes data. Spends no credits.

Add an idea to the Content > Ideas board. Pass a TikTok url to have the video downloaded, analyzed and transcribed in the background (check get_idea for status), or just a title/notes for a freestanding idea. Requires a subscription (a plan or account seats).

Parameters:

• •title (string, optional): Optional idea title.
• •tiktok_url (string, optional): Optional reference TikTok video url to analyze.
• •notes (string, optional): Optional notes on the idea.

delete_idea_script

Delete idea script. Changes data. Spends no credits.

Delete a script from an idea by its id (from get_idea).

Parameters:

• •script_id (string, required): The script id (from get_idea).

generate_script_from_idea

Generate script from idea. Changes data. Spends no credits.

Write a fresh 30-45s TikTok script from a free-text idea description with AI, folding in the workspace's brand/niche (pass promotional=false to leave the brand out entirely). Returns the script text only — it is NOT saved; use save_idea_script to keep it on an idea, or create_video_project to produce it. Requires a subscription (a plan or account seats).

Parameters:

• •idea_description (string, required): What the video should be about.
• •niche_description (string, optional): Optional niche override; defaults to the workspace's niche. Ignored when promotional=false.
• •promotional (boolean, optional): Optional, default true. Pass false for a NON-promotional script: the workspace's business context is not woven in (including niche_description) and nothing gets promoted.

get_idea

Get idea. Read-only.

Get one idea's full detail: the analyzed TikTok (stats, description and transcript), all saved scripts with their content, tagged avatars, linked video projects, and the parent/child ideas of a branch. Get idea ids from list_ideas.

Parameters:

• •idea_id (string, required): The idea id (from list_ideas).

get_tracked_account_metrics

Get tracked account metrics. Read-only.

Aggregate performance for one tracked TikTok account: totals and averages across all its tracked videos (views, engagement rate, duration, posting cadence) plus a per-day views/likes/comments series over the window. Get usernames from list_tracked_accounts.

Parameters:

• •username (string, required): The tracked account username (from list_tracked_accounts).
• •days (integer, optional): Per-day series window in days (1-365). Defaults to 30.

list_ideas

List ideas. Read-only.

List the workspace's research ideas (the Content > Ideas board): title, analysis status, notes, script count and the referenced TikTok's performance. Sort or filter to find the strongest references. Use get_idea for one idea's scripts and transcript.

Parameters:

• •include_archived (boolean, optional): Also include archived ideas. Defaults to false.
• •search (string, optional): Optional free-text filter over titles, notes and video descriptions.
• •sort_by (string, optional): Optional: date | views | views_per_follower | shares_per_view | likes_per_view | bookmarks_per_view | comments_per_view | engagement_rate.
• •sort_direction (string, optional): asc | desc. Defaults to desc.
• •days_lookback (integer, optional): Only ideas whose referenced video was posted in the last N days.
• •min_views (integer, optional): Only ideas whose referenced video has at least this many views.
• •exclude_low_feasibility (boolean, optional): Hide videos the replication feasibility judge marked hard to replicate (unjudged videos stay visible). Defaults to false.
• •page (integer, optional): Page number, 25 ideas per page. Defaults to 1.

list_tracked_accounts

List tracked accounts. Read-only.

List the TikTok accounts this workspace tracks: the user's own avatar analytics accounts (is_own_avatar_account true) and external inspiration/competitor accounts. Includes follower count, active state and the initial video-fetch status for accounts added recently. Usernames here feed search_tracked_videos and get_tracked_account_metrics.

No parameters.

remove_tracked_account

Remove tracked account. Changes data. Spends no credits.

Stop tracking a TikTok inspiration account by username. Accounts linked to one of the workspace's avatars can't be removed this way.

Parameters:

• •username (string, required): The tracked account username (from list_tracked_accounts).

save_idea_script

Save idea script. Changes data. Spends no credits.

Save a script on an idea: pass idea_id (from list_ideas) to create a new script, or script_id (from get_idea) to overwrite an existing one's content.

Parameters:

• •idea_id (string, optional): The idea to add a new script to. Omit when updating an existing script.
• •script_id (string, optional): An existing script to overwrite (from get_idea). Omit when creating.
• •content (string, required): The full script text.

search_tracked_videos

Search tracked videos. Read-only.

Search the videos of the workspace's tracked TikTok accounts with real performance data (views, engagement, views-per-follower) — the source of truth for what content actually performs. By default only the user's own avatar accounts are searched; set include_research_accounts to also search external inspiration accounts. Ground content recommendations in these numbers.

Parameters:

• •username (string, optional): Optional: limit to one tracked account (from list_tracked_accounts).
• •search (string, optional): Optional free-text filter over descriptions and transcripts.
• •sort_by (string, optional): Optional: date | views | views_per_follower | shares_per_view | likes_per_view | bookmarks_per_view | comments_per_view | engagement_rate.
• •sort_direction (string, optional): asc | desc. Defaults to desc.
• •days_lookback (integer, optional): Only videos posted in the last N days.
• •min_views (integer, optional): Only videos with at least this many views.
• •include_research_accounts (boolean, optional): Also include external inspiration accounts' videos. Defaults to false (own avatar accounts only).
• •page (integer, optional): Page number, 25 videos per page. Defaults to 1.

update_idea

Update idea. Changes data. Spends no credits.

Update an idea: replace its notes, attach a reference TikTok url (only if it has none yet), or archive/unarchive it. Get idea ids from list_ideas.

Parameters:

• •idea_id (string, required): The idea id (from list_ideas).
• •notes (string, optional): New notes text; replaces the existing notes.
• •tiktok_url (string, optional): A TikTok url to attach and analyze. Fails if the idea already has a linked video.
• •archived (boolean, optional): true to archive the idea, false to restore it.

update_idea_avatars

Update idea avatars. Changes data. Spends no credits.

Tag or untag avatars on an idea (marks which avatars the idea is intended for). Pass avatar_project_id values from list_avatars, comma-separated.

Parameters:

• •idea_id (string, required): The idea id (from list_ideas).
• •add_avatar_project_ids (string, optional): Comma-separated avatar_project_id values to tag (from list_avatars).
• •remove_avatar_project_ids (string, optional): Comma-separated avatar_project_id values to untag.

update_script_avatars

Update script avatars. Changes data. Spends no credits.

Tag or untag avatars on a script (marks which avatars should perform it). Pass avatar_project_id values from list_avatars, comma-separated; script ids come from get_idea.

Parameters:

• •script_id (string, required): The script id (from get_idea).
• •add_avatar_project_ids (string, optional): Comma-separated avatar_project_id values to tag (from list_avatars).
• •remove_avatar_project_ids (string, optional): Comma-separated avatar_project_id values to untag.

Toolset discover

bookmark_discover_video

Bookmark discover video. Changes data. Spends no credits.

Save a discovered video to the Saved tab for later, without starting production.

Parameters:

• •video_id (string, required): The Discover video id from a list tool.

browse_picker_videos

Browse picker videos. Read-only.

Browse the create-page source picker: every video a new AI-avatar video can replicate, across sources, in one uniform shape. source=for_you (default) is the ranked blend of saved hub videos (trending by views-per-follower, freshness-decayed so recent finds outrank stale outliers), the workspace's own posted renders, an inspiration slice (breakout videos from the workspace's tracked inspiration accounts — judged replicable and outperforming the creator's own median, at most one per account per page), and a slice of the Discover corpus (free plans see part of that slice as a locked_count paywall). The for_you order also interleaves videos the workspace can generate WITHOUT uploading new media — no required assets, or every required kind already covered by the labeled asset library (brand_supplied_kinds in this response) — to roughly half of each source's stream when enough exist and rank close enough; per-row required_assets lists the brand media a video's replication needs (absent when none are recorded). for_you also reports niche_status: no_niche means the workspace has no niche yet (set one via update_workspace_settings or the website analyzer and the feed personalizes); pending means the niche feed is still building; until it's ok the Discover slice serves the curated house shelf when configured. saved, own, discover, and inspiration scope to one source (inspiration = recent videos from tracked inspiration accounts; add accounts with add_tracked_accounts or the Discover track-author action). Search matches topics and transcripts. Each row carries a playable video_url (null means an un-enriched discover row — prepare it with use_discover_video first), poster, views, duration, and replication feasibility.

Parameters:

• •source (string, optional): for_you | saved | discover | own | inspiration. Defaults to for_you.
• •search (string, optional): Optional text search across labels, topics, and transcripts.
• •sort (string, optional): recommended | date | views. Defaults per source.
• •feed (string, optional): Discover only: trending | niche. Defaults to trending.
• •include_hard_to_replicate (boolean, optional): Default false shows only videos the feasibility judge passed (unjudged videos are hidden too) — and, when the promotion shelf is on, restricts discover-feed rows to formats that can carry a brand message (promotion_class promoting/slot); true shows everything. The user's own posts always show — the judges never run on them.
• •page (integer, optional): Page number, 24 per page. Defaults to 1.

get_breakout_creators

Get breakout creators. Read-only.

Creators breaking out across TikTok right now: 2+ videos this week each massively outperforming their follower count, under 1M followers. Ranked by breakout score (reach + best lift + hit rate — the share of their posted videos that broke out). Answers 'which small creators are blowing up'. Use track_breakout_creator to follow one; search_viral_videos with '@username' lists a creator's corpus videos.

No parameters.

get_discover_categories

Get discover categories. Read-only.

The content categories (shelves) of the viral-video corpus with video counts — the valid values for get_trending_videos' category filter. Largest shelves first.

No parameters.

get_discover_video

Get discover video. Read-only.

Full detail for one discovered video including its transcript (when enriched), content labels, and feasibility verdict. Use the transcripts of top trending videos to answer 'what hooks/formats are working'.

Parameters:

• •video_id (string, required): The Discover video id from a list tool.

get_format_trends

Get format trends. Read-only.

Cross-niche format trends this week — sounds and hook structures winning across multiple niches, the adapt-into-any-niche inventory. Use propose_format_trend_as_pattern to file one for review.

No parameters.

get_niche_feed

Get niche feed. Read-only.

Viral videos matched to this workspace's niche this week. Returns niche_status (ok | pending | no_niche) so you can explain an empty feed. Answers 'what is viral in my niche'.

Parameters:

• •window (string, optional): today | week. Defaults to week.
• •page (integer, optional): Page number, 20 per page. Defaults to 1.
• •include_unproducible (boolean, optional): Default false shows only videos the replication judge has watched and passed — and, when the promotion shelf is on, whose format can carry a brand message. Pass true to also see unjudged videos and content an AI avatar cannot replicate.

get_trending_videos

Get trending videos. Read-only.

The global viral-video leaderboard across all of TikTok. Filter by content category and sort by virality score, velocity, or views. Answers 'what is going viral in <category> this week'. Free workspaces see the top row plus blurred teasers — tell them to upgrade for the rest.

Parameters:

• •window (string, optional): today | week. Defaults to week.
• •category (string, optional): Optional content category filter (e.g. dating-relationships, fitness, money-finance).
• •sort (string, optional): virality | velocity | views. Defaults to virality.
• •min_views (integer, optional): Only videos with at least this many views.
• •page (integer, optional): Page number, 20 per page. Defaults to 1.
• •include_unproducible (boolean, optional): Default false shows only videos the replication judge has watched and passed — and, when the promotion shelf is on, whose format can carry a brand message (promotion_class promoting/slot). Pass true to also see unjudged videos, content an AI avatar cannot replicate (dance/edits/gameplay), and no_slot content.

propose_format_trend_as_pattern

Propose format trend as pattern. Changes data. Spends no credits.

File a cross-niche format trend into this workspace's discovery findings as a proposed pattern for review (approve it to a trialing pattern from the findings surface).

Parameters:

• •trend_id (string, required): The format-trend id from get_format_trends.

save_picker_video

Save picker video. Changes data. Spends no credits.

Save a picker video to the workspace's Saved shelf (the picker's saved source and the ideas hub). Takes the analyzed_video_id a browse_picker_videos row carries. Idempotent: re-saving a saved video just re-stamps it, and saving a video whose idea was archived revives that idea. Returns the idea_id; unsave by archiving that idea via update_idea (archived=true). Saving an inspiration video moves it from the For You inspiration slice to the saved shelf (one tile, the save wins).

Parameters:

• •analyzed_video_id (string, required): The analyzed_video_id from a browse_picker_videos row.

search_viral_videos

Search viral videos. Read-only.

Keyword search over the viral-video corpus (hooks, topics, transcripts). Falls through to a live TikTok search when the corpus is thin; live searches are day-capped per plan (live_searches_remaining_today reports the remaining budget). Requires a subscription (a plan or account seats).

Parameters:

• •query (string, required): The keyword or phrase to search for.
• •live (string, optional): auto | never | force. Defaults to auto (live only when the corpus is thin).
• •page (integer, optional): Page number, 20 per page. Defaults to 1.

track_breakout_creator

Track breakout creator. Changes data. Spends no credits.

Add a breakout creator (from get_breakout_creators) as a tracked inspiration account so their future videos flow into research automatically.

Parameters:

• •username (string, required): The creator's username from get_breakout_creators (without @).

track_video_author

Track video author. Changes data. Spends no credits.

Add a discovered video's creator as a tracked inspiration account.

Parameters:

• •video_id (string, required): The Discover video id from a list tool.

use_discover_video

Use discover video. Changes data. Spends no credits.

Put a discovered video on the Ideas board so scripts and videos can be created from it. Materializes the idea (enriching the video first if needed) and returns idea_id; idempotent per workspace.

Parameters:

• •video_id (string, required): The Discover video id from a list tool.

Toolset content

acknowledge_attention_item

Acknowledge attention item. Changes data. Spends no credits.

Mark a Home needs-you attention item as seen so it stops surfacing (item ids come from get_studio_overview view=home). Use after the user has acted on or dismissed the item.

Parameters:

• •item_id (string, required): The attention item id.

apply_script_revision

Apply script revision. Changes data. Spends no credits.

Act on a script revision (revision ids from get_content_script). action 'restore' makes an older revision current again; 'accept' applies a revision the AI writer proposed in writer chat; 'reject' declines it.

Parameters:

• •script_id (string, required): The script id.
• •revision_id (string, required): The revision id (from get_content_script revisions or writer_chat).
• •action (string, required): restore | accept | reject.

control_stage_run

Control stage run. Changes data. Spends no credits.

Retry a failed writer-engine stage run, or cancel a pending one (run ids from get_content_batch view=stage_runs).

Parameters:

• •run_id (string, required): The stage-run id.
• •action (string, required): retry | cancel.

decide_content_script

Decide content script. Changes data. Spends no credits.

Record a review verdict on batch scripts. Pass script_id for one script with verdict 'approved', 'needs_changes' or 'cut'. Or pass batch_id (no script_id) to approve every undecided script in the batch at once (verdict must be 'approved'; set require_green to skip scripts with failing checks). Approved scripts become pushable.

Parameters:

• •verdict (string, required): approved | needs_changes | cut.
• •script_id (string, optional): The script id (from get_content_batch) for a single decision.
• •batch_id (string, optional): The batch id to bulk-approve instead of a single script.
• •note (string, optional): Optional reviewer note (single-script decisions).
• •require_green (boolean, optional): Bulk mode only: skip scripts whose checks are not passing. Default false.

decide_learning_item

Decide learning item. Changes data. Spends no credits.

Decide a learning-loop item (ids from get_learning_overview). kind 'recommendation' with action accept (applies the tuning change) or reject. kind 'finding' with action approve (promotes the discovered format to a pattern; optional initial_lifecycle), reject, snooze (requires until), or undo (reverts an auto-adopted finding).

Parameters:

• •kind (string, required): recommendation | finding.
• •item_id (string, required): The recommendation or finding id.
• •action (string, required): recommendation: accept | reject. finding: approve | reject | snooze | undo.
• •reason (string, optional): Optional rejection reason.
• •until (string, optional): Snooze until, ISO date-time (snooze only).
• •initial_lifecycle (string, optional): Lifecycle for an approved finding's new pattern. Defaults to candidate.

delete_content_pattern

Delete content pattern. Changes data. Spends no credits.

Delete a content pattern by id. Fails when the pattern is still referenced.

Parameters:

• •pattern_id (string, required): The pattern id to delete.

delete_content_playbook

Delete content playbook. Changes data. Spends no credits.

Delete an account playbook by id. Fails when the playbook is still referenced.

Parameters:

• •playbook_id (string, required): The playbook id to delete.

delete_term_or_list

Delete term or list. Changes data. Spends no credits.

Delete a single term (pass term_id) or an entire termList and all its terms (pass term_list_id). Deleting a term list also unlinks any patterns that pointed at it. Prefer status=retired over deleting a term you might want back.

Parameters:

• •term_id (string, optional): A term id to delete.
• •term_list_id (string, optional): A term list id to delete (with all its terms).

edit_content_script

Edit content script. Changes data. Spends no credits.

Edit a batch script's content inline (creates a new revision and re-runs the checks). Pass only the fields to change. list_items_json and search_terms_json are JSON arrays of strings.

Parameters:

• •script_id (string, required): The script id (from get_content_batch).
• •transcript (string, optional): New spoken transcript.
• •text_hook (string, optional): New on-screen text hook.
• •spoken_hook (string, optional): New spoken hook.
• •text_description (string, optional): New caption/description.
• •list_items_json (string, optional): Optional JSON array of bullet list items.
• •search_terms_json (string, optional): Optional JSON array of search terms.
• •video_model (string, optional): Optional video model used when the concept is approved and generated: grok-imagine-1.5 | seedance | gemini-omni.

get_content_audits

Get content audits. Read-only.

Read the workspace's content audits — periodic health reports over recent output (pattern performance, account reads, gaps). Omit run_id to list recent runs; pass it for one run's full report. Start a fresh one with run_content_audit.

Parameters:

• •run_id (string, optional): Optional audit run id for the full report.

get_content_batch

Get content batch. Read-only.

Inspect one content batch (id from list_content_batches). view selects what to return: 'scripts' (default — every script card with hook, transcript, status and latest verdict; script ids feed the script tools), 'metrics' (review-time stats), 'push_status' (per-script push/project state after push_content_batch), 'generation_status' (video generation progress per pushed project), or 'stage_runs' (the writer engine's queued/running stage runs; run ids feed control_stage_run).

Parameters:

• •batch_id (string, required): The batch id (from list_content_batches).
• •view (string, optional): scripts | metrics | push_status | generation_status | stage_runs. Defaults to scripts.

get_content_item

Get content item. Read-only.

Resolve one content item (or a legacy project id) into its full spine view: item status and scheduling, the concept script, the video project and generation status, and the scheduled post. Item ids come from get_studio_overview (grid cells and review queue).

Parameters:

• •item_id (string, required): A content item id or project id (from get_studio_overview).

get_content_profile

Get content profile. Read-only.

Get the workspace's content pipeline profile: which optional pipeline hooks are enabled and whether it is the platform default.

No parameters.

get_content_script

Get content script. Read-only.

Inspect one script in a content batch (id from get_content_batch). view selects what to return: 'revisions' (default — the edit history; revision ids feed apply_script_revision), 'starting_frames' (the avatar frames selectable for this script; frame ids feed set_script_starting_frame), or 'writer_chat' (the revision conversation with the AI writer; reply with send_writer_chat_message).

Parameters:

• •script_id (string, required): The script id (from get_content_batch).
• •view (string, optional): revisions | starting_frames | writer_chat. Defaults to revisions.

get_engine_prompts

Get engine prompts. Read-only.

Read the writer engine's prompt assets and this workspace's overrides. Omit kind for a summary of every prompt (kind, version, whether a workspace override is active); pass a kind (e.g. WRITER, TEXT_HOOK, CHECKER_SPEC) for the full prompt body. Edit with update_engine_prompt.

Parameters:

• •kind (string, optional): Optional prompt kind for full detail (see the summary list for kinds).

get_knowledge_exports

Get knowledge exports. Read-only.

Read the workspace's rendered knowledge exports — the markdown files (patterns, principles, playbooks) the writer engine is briefed with. Omit file_key to list them; pass one to read its content.

Parameters:

• •file_key (string, optional): Optional file key (from the list) to fetch full content.

get_learning_overview

Get learning overview. Read-only.

Read the learning loop (the Content section's learning digest). view: 'digest' (default — what changed in the last week: pending recommendations, proposed and auto-adopted discovery findings, account health events), 'recommendations' (the tuning inbox; ids feed decide_learning_item), 'findings' (discovered format candidates from breakout scans; ids feed decide_learning_item), or 'autonomy' (the per-gate autonomy dials; change with set_autonomy_dial).

Parameters:

• •view (string, optional): digest | recommendations | findings | autonomy. Defaults to digest.
• •status (string, optional): Optional status filter for recommendations/findings.
• •source (string, optional): Optional source filter for findings.

get_llm_usage_summary

Get llm usage summary. Read-only.

Summarize the content engine's LLM spend for this workspace: total cost and tokens, broken down by agent role and model. Optionally scope to one batch or a start time.

Parameters:

• •batch_id (string, optional): Optional batch id to scope the summary.
• •since (string, optional): Optional ISO date-time lower bound (e.g. 2026-06-01T00:00:00).

get_pattern_references

Get pattern references. Read-only.

The pattern's LIVE claim-time reference selection — exactly what a write run claiming now would study (fresh-first, window widening 14d→30d→90d→all-time), with transcripts and ages. Use this to inspect or debug the writer's inputs. Curate the underlying pool with list_pattern_links / manage_pattern_link.

Parameters:

• •pattern_id (string, required): The pattern to preview references for.

get_studio_overview

Get studio overview. Read-only.

The Studio's at-a-glance reads. view: 'home' (default — total views, current winner, the 'needs you' action list), 'review_queue' (content items by lifecycle bucket — pass statuses=drafts for the Drafts tab's population, or the Videos buckets, with item ids for get_content_item), or 'grid' (the avatar/account-by-day roster of planned and made content).

Parameters:

• •view (string, optional): home | review_queue | grid. Defaults to home.
• •days (integer, optional): Grid only: how many days wide (default 11).
• •offset (integer, optional): Grid only: day offset from today, -180..180 (default 0).
• •source (string, optional): Grid only: 'content' (made items, default) or 'plan' (planned slots).
• •statuses (string, optional): review_queue only: comma list of drafts|queue|failed|approved|scheduled|posted|archived to read those buckets windowed with exact totals ('drafts' = concept-stage items awaiting generation; 'failed' = push/generation failures plus items whose every posting leg failed (failureKind says which: generation vs post); a dead leg with a live sibling stays on the post — list_scheduled_posts has per-post failures; 'posted' history and 'archived' projects are only reachable here). Omit for the classic full queue (capped at 50, unfilterable, and drafts sort below everything else so a busy queue's cap can hide them — for drafts always pass statuses=drafts).
• •limit (integer, optional): review_queue only: max items when statuses is set (default 60, max 200).
• •sort (string, optional): review_queue only, when statuses is set: newest (default), oldest, or posttime (failed items first — generation failures and all-legs-dead post failures alike — then the posting queue soonest-first — overdue then upcoming, untimed items next, posted/archived history most-recent-first). Decides which items make the window, not just their order. Drafts are the exception to newest/oldest: they order by build pickup (oldest-created first, the Drafts tab's order) and sort AFTER every non-draft item; oldest reverses that whole list. For drafts by creation date, request statuses=drafts alone.

get_term_lists

Get term lists. Read-only.

List the workspace's term lists, or one term list's terms. A term list is a reusable, tiered pool of terms (search-bait words, hashtags, product names, ...) that patterns draw from so the writer picks real terms instead of inventing them. Omit term_list_id for the list (with counts); pass it to get that term list's full term list with tiers, status, risk flags and evidence.

Parameters:

• •term_list_id (string, optional): Optional — a term list id from the list to get its terms.

list_content_batches

List content batches. Read-only.

List the workspace's content batches (Content review). A batch is a planned set of scripts moving through review, generation and push; campaign fires (run_campaign_now) and seed_content_batch both create one. Returns each batch's id, label, stage and per-status script counts. Use the id with get_content_batch.

No parameters.

list_content_outcomes

List content outcomes. Read-only.

List posted-video outcomes attributed to patterns: views at maturity and lift vs the account's baseline. Use to answer 'which patterns are working'. Filter by look-back days, pattern_id or account username.

Parameters:

• •days (integer, optional): Optional look-back window in days.
• •pattern_id (string, optional): Optional pattern id filter (from list_content_patterns).
• •username (string, optional): Optional TikTok username filter.

list_content_patterns

List content patterns. Read-only.

List the workspace's content patterns (proven script formats the writer engine reuses): slug, name, lifecycle stage (candidate/trialing/proven/cooling/retired), category and linked-video count. Pattern ids feed save_content_pattern, list_pattern_links and get_pattern_references.

No parameters.

list_content_playbooks

List content playbooks. Read-only.

List the workspace's account playbooks — per-TikTok-account writing guides (what to copy, what to avoid, audience notes) distilled from tracked accounts. Pass playbook_id for the full guide. Ids feed save_content_playbook.

Parameters:

• •status (string, optional): Optional status filter (e.g. active, research_only).
• •playbook_id (string, optional): Optional playbook id — returns that playbook's full detail.

list_content_principles

List content principles. Read-only.

List the workspace's taste principles — review rules the checker enforces on every script (scoped global, per-pattern, per-avatar or per-batch). Principle ids feed save_content_principle.

Parameters:

• •status (string, optional): Optional filter: active | retired | candidate.
• •scope (string, optional): Optional filter: global | pattern | avatar | batch.
• •pattern_id (string, optional): Optional pattern id filter.

list_pattern_links

List pattern links. Read-only.

List the evidence links between analyzed TikTok videos and patterns. Pass pattern_id (from list_content_patterns) to see one pattern's linked reference videos plus its lifecycle event history; or pass analyzed_video_ids (comma-separated) to see AI-proposed links for captured videos. link_id feeds manage_pattern_link.

Parameters:

• •pattern_id (string, optional): Optional pattern id — returns that pattern's links and events.
• •analyzed_video_ids (string, optional): Optional comma-separated analyzed-video ids to filter proposed links.

list_video_classifications

List video classifications. Read-only.

Get the content classifications (pattern, lane, hook/retention/payoff structure, production format) recorded for specific video projects. Pass project ids from list_projects or get_content_batch push status.

Parameters:

• •project_ids (string, required): Comma-separated project ids to look up.

log_llm_usage

Log llm usage. Changes data. Spends no credits.

Record LLM usage rows against this workspace's content-engine spend (the engine's own bookkeeping path). rows_json is a JSON array of objects with agent_role, provider, model, input_tokens, output_tokens, cost_usd_micros, and optional batch_id / stage_run_id.

Parameters:

• •rows_json (string, required): JSON array of usage rows (see tool description).

manage_pattern_link

Manage pattern link. Changes data. Spends no credits.

Manage the video-evidence knowledge base. action 'capture': save a TikTok url into the analyzed library (with optional notes), or directly link it to a pattern when pattern_id is passed. action 'confirm' / 'reject': decide an AI-proposed link (link_id from list_pattern_links; confirm can pass pattern_id to pick the pattern). action 'delete': remove a link.

Parameters:

• •action (string, required): capture | confirm | reject | delete.
• •tiktok_video_url (string, optional): The TikTok video url (capture only).
• •notes (string, optional): Optional capture notes.
• •pattern_id (string, optional): Pattern id: capture links directly; confirm assigns the pattern.
• •link_id (string, optional): The link id (confirm/reject/delete).

push_content_batch

Push content batch. Spends credits: each pushed script becomes a fully-automated video project (video credits per clip at the model's rate, e.g. Grok ~15.6/sec).

Preflight or push a reviewed batch's approved scripts into video projects (each pushed script becomes a fully-automated project that generates and schedules its video — spends video credits). Scope with script_ids for one-by-one pushes or scheduled_date for a posting day. Safe default: without preflight_id or push_now it only runs preflight; set push_now=true to preflight and push the clean scoped set in one call.

Parameters:

• •batch_id (string, required): The batch id (from list_content_batches).
• •preflight_id (string, optional): The preflight id from the preflight step; omit to run preflight only unless push_now is true.
• •script_ids (string, optional): Optional comma-separated script ids to preflight/push one-by-one or as a small scoped set.
• •scheduled_date (string, optional): Optional posting date (YYYY-MM-DD) to preflight/push only approved scripts scheduled for that day.
• •push_now (boolean, optional): Set true to run preflight and immediately push if the scoped set has no preflight blockers.

run_content_audit

Run content audit. Changes data. Spends no credits.

Start a content audit over the last N days (pattern performance, account reads, knowledge gaps). Runs in the background; read the report with get_content_audits(run_id).

Parameters:

• •days (integer, optional): Look-back window in days. Defaults to 30.

run_content_engine

Run content engine. Changes data. Spends no credits.

Start the AI writer engine on a content batch: it queues stage runs that build reference packs and write the batch's scripts (uses the workspace's LLM budget). Set examples_only to instead release the batch's example scripts for generation. Track progress with get_content_batch view=stage_runs.

Parameters:

• •batch_id (string, required): The batch id (from list_content_batches).
• •examples_only (boolean, optional): Release the batch's example scripts instead of a full engine run. Default false.

save_content_pattern

Save content pattern. Changes data. Spends no credits.

Create or update a content pattern. Omit pattern_id to create (name required); pass it to update only the given fields. lifecycle_stage: candidate | trialing | proven | cooling | retired. category is the pattern's canonical content format — 'lipsync' marks a lip-sync/sing-along pattern (avatar mouths an audio track); lipsync patterns are classification-only for now and are never planned for generation. Set archived true to archive.

Parameters:

• •pattern_id (string, optional): The pattern id to update; omit to create.
• •name (string, optional): The pattern name (required when creating).
• •description (string, optional): What the format is and why it works.
• •lifecycle_stage (string, optional): candidate | trialing | proven | cooling | retired.
• •category (string, optional): The canonical content format this pattern belongs to (must already exist; e.g. yapper, lipsync, podcast).
• •lore (string, optional): Operator notes / history for the pattern.
• •archived (boolean, optional): Set true to archive, false to unarchive (update only).

save_content_playbook

Save content playbook. Changes data. Spends no credits.

Create or update an account playbook. To create, pass username of a TikTok account already tracked in the workspace (starts as research_only). To update, pass playbook_id with any of lane, writer_tldr, what_to_copy_json / what_to_avoid_json (JSON arrays of strings), audience_notes, status.

Parameters:

• •playbook_id (string, optional): The playbook id to update; omit to create from username.
• •username (string, optional): Tracked TikTok username to create a playbook for.
• •lane (string, optional): The account's content lane.
• •writer_tldr (string, optional): One-paragraph writing guide for the account.
• •what_to_copy_json (string, optional): JSON array of strings: things to copy.
• •what_to_avoid_json (string, optional): JSON array of strings: things to avoid.
• •audience_notes (string, optional): Notes on the audience.
• •status (string, optional): Playbook status (e.g. active, research_only).

save_content_principle

Save content principle. Changes data. Spends no credits.

Create or update a taste principle (a review rule the checker enforces on future scripts). Omit principle_id to create (text required; scope global | pattern | avatar | batch). Pass principle_id to update text/status/category — set status 'retired' to turn a principle off. Pass recheck_batch_id when creating to re-check that batch's scripts against the new principle.

Parameters:

• •principle_id (string, optional): The principle id to update; omit to create.
• •text (string, optional): The principle text (required when creating).
• •scope (string, optional): global | pattern | avatar | batch. Defaults to global.
• •status (string, optional): Update only: active | retired | candidate.
• •category (string, optional): Optional category label.
• •pattern_id (string, optional): Pattern id when scope is pattern.
• •avatar_project_id (string, optional): Avatar project id when scope is avatar.
• •batch_id (string, optional): Batch id when scope is batch.
• •source_note (string, optional): Optional note on where the rule came from.
• •recheck_batch_id (string, optional): Optional batch id to re-check against the new principle (create only).

save_term_list

Save term list. Changes data. Spends no credits.

Create a term list, or rename/re-hint/relink an existing one. Omit term_list_id to create (slug + name + kind required); pass it to update. link_pattern_slugs binds patterns to this term list so their scripts draw terms from it. Then add terms with save_terms.

Parameters:

• •term_list_id (string, optional): Omit to create; pass to update.
• •slug (string, optional): Stable slug (create only), e.g. coreflow-dont-search-terms.
• •name (string, optional): Human name.
• •kind (string, optional): What it is for: search_terms | hashtags | product_names | hook_openers | blocklist | ...
• •usage_hint (string, optional): One line telling the writer how to use terms from this term list.
• •link_pattern_slugs (string, optional): Optional pattern slugs to bind to this term list (JSON array or comma list).

save_terms

Save terms. Changes data. Spends no credits.

Add or update terms in a term list. To add: pass term_list_id + terms (JSON array of {value, tier?, status?, category?, notes?, best_views?, risk_flagged?}); for values already present, only the fields you pass change (best_views only rises, and risk_flagged can be raised but never cleared this way — clear it via a term_id edit). To edit one existing term: pass term_id + the fields to change. tier is proven|testing|exploratory|candidate (only the first three are writer-eligible); status is active|held|retired.

Parameters:

• •term_list_id (string, optional): TermList to add terms to (with terms).
• •terms (string, optional): JSON array of term objects to add/upsert into term_list_id.
• •term_id (string, optional): Edit a single existing term instead of adding.
• •value (string, optional): Edit: new value.
• •tier (string, optional): Edit: new tier.
• •status (string, optional): Edit: new status.
• •risk_flagged (boolean, optional): Edit: set the risk flag (blocks writer eligibility).

seed_content_batch

Seed content batch. Changes data. Spends no credits.

Create a content batch from ready-made scripts (the Studio Create-content flow). scripts_json is a JSON array, one object per script: [{"avatar_name":"Maya","tiktok_username":"maya.b","transcript":"...","avatar_project_id":"<optional uuid>"}]. Scripts land in review; approve them with decide_content_script, then push with push_content_batch.

Parameters:

• •scripts_json (string, required): JSON array of scripts (see tool description).
• •label (string, optional): Optional batch label.
• •window_start (string, optional): Optional posting window start, YYYY-MM-DD. Defaults to today.
• •window_end (string, optional): Optional posting window end, YYYY-MM-DD.

send_writer_chat_message

Send writer chat message. Changes data. Spends no credits.

Send a revision request to the AI writer about one batch script (e.g. 'make the hook punchier'). The writer replies asynchronously with a proposed revision — read the thread with get_content_script view=writer_chat, then accept or reject the proposal with apply_script_revision. On lip-sync/scene-clip concepts the spoken/lyric lines are locked — the writer can only revise the caption, text hook, and description.

Parameters:

• •script_id (string, required): The script id (from get_content_batch).
• •message (string, required): What to change about the script.

set_autonomy_dial

Set autonomy dial. Changes data. Spends no credits.

Set one learning-loop autonomy dial: how independently the system may act at a gate (gates and current levels from get_learning_overview view=autonomy). Optionally set a weekly cap on autonomous actions.

Parameters:

• •gate (string, required): The gate to set (from get_learning_overview autonomy).
• •level (string, required): The autonomy level for the gate.
• •weekly_cap (integer, optional): Optional weekly cap on autonomous actions.

set_batch_share_page

Set batch share page. Changes data. Spends no credits.

Turn a content batch's public share page on or off. Enabling returns a tokened public url outside reviewers can react on without logging in; disabling revokes it.

Parameters:

• •batch_id (string, required): The batch id (from list_content_batches).
• •enabled (boolean, required): true to create the share page, false to revoke it.

set_script_starting_frame

Set script starting frame. Changes data. Spends no credits.

Set a batch script's starting frame (the avatar scene image its video opens on). Pass a frame_id from get_content_script(starting_frames), or omit it to reroll to a random active frame.

Parameters:

• •script_id (string, required): The script id.
• •frame_id (string, optional): The frame id to set; omit to reroll randomly.

update_engine_prompt

Update engine prompt. Changes data. Spends no credits.

Override one of the writer engine's prompts for this workspace, or reset the override back to the platform default. Pass body with the full new prompt text (read the current one first with get_engine_prompts), or set reset true to remove the workspace override.

Parameters:

• •kind (string, required): The prompt kind (from get_engine_prompts).
• •body (string, optional): The full new prompt body (omit when resetting).
• •reset (boolean, optional): Set true to remove the workspace override and revert to the global default.

update_video_classification

Update video classification. Changes data. Spends no credits.

Overwrite a video project's content classification. classification_json is a JSON object with any of: pattern_id, pattern_name, lane, hook_structure, retention_structure, payoff_type, product_integration, production_format, target_audience. Read current values with list_video_classifications.

Parameters:

• •project_id (string, required): The video project id.
• •classification_json (string, required): JSON object of classification fields (see tool description).

Toolset automation

add_pattern_constraint

Add pattern constraint. Changes data. Spends no credits.

Add a standing constraint on a content pattern: IDENTITY_LOCK or VISUAL_FORMAT_LOCK gate the pattern by avatar tag (mode REQUIRES_TAG or BLOCKS_TAG with the tag), and cap_per_week limits weekly usage. pattern_id comes from get_pattern_performance. Constraints and their ids are in get_content_strategy; remove with delete_pattern_constraint.

Parameters:

• •pattern_id (string, required): The pattern id (from get_pattern_performance).
• •constraint_type (string, required): IDENTITY_LOCK | VISUAL_FORMAT_LOCK | CAP.
• •mode (string, optional): REQUIRES_TAG | BLOCKS_TAG (for lock constraints).
• •tag (string, optional): The avatar tag the lock checks.
• •cap_per_week (integer, optional): Max slots per week for this pattern.
• •reason (string, optional): Why the constraint exists.

add_strategy_exception

Add strategy exception. Changes data. Spends no credits.

Add a standing exception — a plain-language instruction the planner honors, optionally scoped to one batch (scope BATCH + batch_id), assignment, avatar or pattern. Exceptions and their ids are in get_content_strategy; lift one with revoke_strategy_exception.

Parameters:

• •exception_type (string, required): A short type label, e.g. AVOID_TOPIC or FORCE_PATTERN.
• •instruction (string, required): The instruction the planner should honor.
• •scope (string, optional): DURABLE (default) | BATCH (with batch_id).
• •batch_id (string, optional): Optional batch id the exception is limited to.
• •assignment_id (string, optional): Optional assignment id (from list_campaign_assignments) to target.
• •avatar_id (string, optional): Optional avatar id (from list_avatars) to target.
• •pattern_id (string, optional): Optional pattern id (from get_pattern_performance) to target.

approve_all_content_plans

Approve all content plans. Spends credits: approves every pending plan; each starts script writing and generation (spends credits).

Approve every plan-stage batch in the workspace at once (the Automation page plan grid's 'Approve plan' action). Each approved batch starts writing and generating content, which spends credits.

No parameters.

approve_content_plan

Approve content plan. Spends credits: approval starts script writing and video generation for the whole batch (spends credits).

Approve a batch plan (the Brief gate): the batch advances to writing — scripts are written and content generated for every slot, which spends credits. Refused while the plan has error-severity violations (fix them with edit_plan_slots first).

Parameters:

• •batch_id (string, required): The batch id (from get_content_plan).

delete_campaign

Delete campaign. Changes data. Spends no credits.

Delete an automation campaign (its members move back to the Default campaign). The Default campaign itself cannot be deleted.

Parameters:

• •campaign_id (string, required): The campaign id (from list_campaigns).

delete_content_taxonomy

Delete content taxonomy. Changes data. Spends no credits.

Delete a workspace-defined content format or audience by id. Global defaults are read-only, and entries still referenced by a strategy can't be deleted.

Parameters:

• •kind (string, required): What to delete: format or audience.
• •id (string, required): The taxonomy entry id.

delete_pattern_constraint

Delete pattern constraint. Changes data. Spends no credits.

Remove a pattern constraint by its id (from get_content_strategy).

Parameters:

• •constraint_id (string, required): The constraint id (from get_content_strategy).

delete_plan

Delete plan. Changes data. Spends no credits.

Delete a pending plan batch outright (planning/brief_pending only) — the batch and its slots are removed; video projects are never touched. Destructive; confirm with the user before calling.

Parameters:

• •batch_id (string, required): The batch id (from get_content_plan or list_content_batches).

edit_plan_slots

Edit plan slots. Changes data. Spends no credits.

Apply structured edits to an unapproved batch plan and re-validate it server-side. edits_json is a JSON array of ops: {"op":"MOVE_SLOT","slot_id","date":"YYYY-MM-DD","assignment_id"} (date and/or target assignment — assignment_id is preferred; avatar_project_id or account are supported), {"op":"REMOVE_SLOT","slot_id"}, {"op":"SWAP_PATTERN","slot_id","pattern_slug"|"idea_id"} (replace the slot's source with a pattern OR a research idea), {"op":"ADD_SLOT","assignment_id","pattern_slug"|"idea_id","date","slot_type"}, {"op":"PAUSE_AVATAR","avatar_name","scope":"batch_local|standing"}. Slot ids and pattern slugs come from get_content_plan; idea ids from list_ideas.

Parameters:

• •batch_id (string, required): The batch id (from get_content_plan).
• •edits_json (string, required): JSON array of edit ops (see tool description).

get_avatar_content_strategy

Get avatar content strategy. Read-only.

Get one avatar's automation profile: its avatar type, target audience, pattern selection (ALL_ELIGIBLE or CURATED with curated pattern ids), tags, linked TikTok accounts, patterns blocked by constraints, the video model each account resolves to, 14-day pattern-per-account performance, and how many unposted videos are stocked in its pipeline. avatar_id comes from list_avatars.

Parameters:

• •avatar_id (string, required): The avatar id (from list_avatars).

get_content_plan

Get content plan. Read-only.

Get a content batch's plan: status, posting window, the planned slots (slot_id, account, avatar, pattern, date, video model), policy deviations, violations and per-avatar rationale. batch_id comes from plan_content_batch or run_campaign_now.

Parameters:

• •batch_id (string, required): The batch id (from plan_content_batch or run_campaign_now).

get_content_strategy

Get content strategy. Read-only.

Get the workspace's automation content strategy (Content > Automation): planning mode, hit-bar view threshold, tests per avatar per week, content-mix targets, pattern constraints and standing exceptions (with the ids delete_pattern_constraint / revoke_strategy_exception take), per-account daily posting caps, and the cycle policy schedule. Canonical avatar-account bindings live in list_campaign_assignments.

No parameters.

get_model_routing

Get model routing. Read-only.

List the workspace's video-model routing rules (which video model each account/pattern/avatar is planned with). Pass account (and optionally pattern_slug / avatar_id) to also resolve the model that combination would get.

Parameters:

• •account (string, optional): Optional TikTok username to resolve a model for.
• •pattern_slug (string, optional): Optional pattern slug to resolve with.
• •avatar_id (string, optional): Optional avatar id (from list_avatars) to resolve with.

get_pattern_performance

Get pattern performance. Read-only.

The pattern-per-account performance cross-tab the planner allocates from: for each (pattern, TikTok account) pair in the look-back window, the video count, average views and hit rate. Use to answer 'what's working' and to pick pattern slugs for edit_plan_slots or add_pattern_constraint.

Parameters:

• •lookback_days (integer, optional): Look-back window in days (1-90). Defaults to 14.

list_content_taxonomies

List content taxonomies. Read-only.

List the workspace's content taxonomies used by the automation planner: content formats, target audiences, and avatar types (each type maps to the format ids it can produce). Ids feed upsert_content_taxonomy and set_avatar_content_strategy. Global (is_global) entries are read-only defaults.

No parameters.

list_strategy_changes

List strategy changes. Read-only.

The strategy audit log, newest first: who/what changed the automation strategy (edits, brief edits promoted to standing, imports) and when.

Parameters:

• •limit (integer, optional): Max changes to return (1-200). Defaults to 50.

plan_content_batch

Plan content batch. Changes data. Spends no credits.

Create a planned content batch now (instead of waiting for the cycle), or re-run allocation into an existing unapproved batch by passing batch_id. Optional window_start/window_end (YYYY-MM-DD) set the posting window; assignment_ids_json (from list_campaign_assignments) restricts which avatar+account pairs are planned. Returns the batch id — review with get_content_plan, adjust with edit_plan_slots, then approve_content_plan to start writing.

Parameters:

• •batch_id (string, optional): An existing unapproved batch to re-plan; omit to create a new batch.
• •window_start (string, optional): Posting window start, YYYY-MM-DD. Omit for the next cycle window.
• •window_end (string, optional): Posting window end, YYYY-MM-DD. Omit for the next cycle window.
• •label (string, optional): Optional batch label.
• •assignment_ids_json (string, optional): Optional JSON array of assignment ids to plan for (from list_campaign_assignments).

preview_content_plan

Preview content plan. Read-only.

Dry-run the planner over the next cycle window without creating anything: the slots it would allocate per account and day, unmet needs, policy deviations and violations. Use before plan_content_batch to show the user what a batch would contain.

No parameters.

retry_failed_runs

Retry failed runs. Changes data. Spends no credits.

Requeue a batch's terminally failed writing runs (FAILED/TIMED_OUT) with a fresh attempt budget — use when some script groups failed to write and the user wants to try again.

Parameters:

• •batch_id (string, required): The batch id (from list_content_batches).

revoke_strategy_exception

Revoke strategy exception. Changes data. Spends no credits.

Revoke a standing exception by its id (from get_content_strategy) so the planner stops honoring it.

Parameters:

• •exception_id (string, required): The exception id (from get_content_strategy).

set_account_daily_cap

Set account daily cap. Changes data. Spends no credits.

Set the max automated posts per day the planner may schedule for one TikTok account (usernames come from list_campaign_assignments). The workspace default is in get_content_strategy.

Parameters:

• •tiktok_username (string, required): The TikTok account username.
• •max_posts_per_day (integer, optional): The cap; omit to reset to the workspace default.

set_assignment_status

Set assignment status. Changes data. Spends no credits.

Pause or reactivate an avatar's canonical TikTok account binding (PAUSED bindings get no planned content; nothing is deleted). Get assignment_id from list_campaign_assignments.

Parameters:

• •assignment_id (string, required): The assignment id (from list_campaign_assignments).
• •status (string, required): ACTIVE | PAUSED.
• •reason (string, optional): Optional reason, recorded when pausing.

set_avatar_content_strategy

Set avatar content strategy. Changes data. Spends no credits.

Set an avatar's automation strategy: its avatar type (from list_content_taxonomies), target audience (ALL, MALE or FEMALE) and pattern selection — ALL_ELIGIBLE, or CURATED with curated_pattern_ids_json listing the allowed pattern ids. Only the fields you pass change.

Parameters:

• •avatar_id (string, required): The avatar id (from list_avatars).
• •avatar_type_id (string, optional): The avatar type id (from list_content_taxonomies). Omit to keep.
• •target_audience (string, optional): ALL | MALE | FEMALE. Omit to keep.
• •pattern_selection (string, optional): ALL_ELIGIBLE | CURATED. Omit to keep.
• •curated_pattern_ids_json (string, optional): JSON array of pattern ids for CURATED selection. Omit to keep.

set_campaign_member_cadence

Set campaign member cadence. Changes data. Spends no credits.

Set how many scripts per day a campaign plans for one of its member assignments. Get assignment_id from list_campaign_assignments and campaign_id from list_campaigns.

Parameters:

• •campaign_id (string, required): The campaign id (from list_campaigns).
• •assignment_id (string, required): The member assignment id (from list_campaign_assignments).
• •scripts_per_day (integer, required): Scripts per day for this member (minimum 1).

set_campaign_member_seed

Set campaign member seed. Changes data. Spends no credits.

Override what fills the batch for ONE member of a campaign (Content > Automation). Mode 'categories' or 'patterns' narrows that avatar's pattern pool to the given values instead of the campaign seed; mode 'inherit' clears the override. Mimic/ideas seeds stay campaign-level (update_campaign_settings). campaign_id from list_campaigns, assignment_id from list_campaign_assignments, pattern ids from list_patterns.

Parameters:

• •campaign_id (string, required): The campaign id (from list_campaigns).
• •assignment_id (string, required): The member assignment id (from list_campaign_assignments).
• •mode (string, required): inherit | categories | patterns.
• •values (string, optional): Comma-separated category names (categories mode) or pattern ids (patterns mode). Ignored for inherit.

set_campaign_member_video_model

Set campaign member video model. Changes data. Spends no credits.

Set the video-generation model this campaign's automation batches use for ONE member avatar (Content > Automation). Pass video_model 'inherit' (or empty) to clear the override — the member then follows the workspace model-routing rules, falling back to the Gemini Omni default. campaign_id from list_campaigns, assignment_id from list_campaign_assignments.

Parameters:

• •campaign_id (string, required): The campaign id (from list_campaigns).
• •assignment_id (string, required): The member assignment id (from list_campaign_assignments).
• •video_model (string, optional): gemini-omni | seedance | grok-imagine-1.5, or 'inherit' to clear the override.

set_cycle_policy

Set cycle policy. Changes data. Spends no credits.

Edit the workspace's automation cycle schedule (when plans are drafted for review): cadence mode, planning days, review windows, lead time and rolling stock. Review-window local times run in the WORKSPACE timezone (changed via workspace settings, not here). Only the fields you pass change; the current policy is in get_content_strategy. Turning the cycle on/off is enable_campaign / disable_campaign on the Default campaign (from list_campaigns).

Parameters:

• •cadence_mode (string, optional): MANUAL | CALENDAR. Omit to keep.
• •calendar_days_json (string, optional): JSON array of weekday names the cycle plans on, e.g. ["MONDAY","THURSDAY"]. Omit to keep.
• •lead_time_hours (integer, optional): Hours before posting the plan is drafted. Omit to keep.
• •review_windows_json (string, optional): JSON array like [{"day":"SUNDAY","local_time":"09:00"}], times in the workspace timezone. Omit to keep.
• •rolling_stock_min_days (integer, optional): Minimum days of content to keep stocked. Omit to keep.

set_mix_targets

Set mix targets. Changes data. Spends no credits.

Replace the workspace's content-mix targets (what share of planned posts each content category should get). targets_json is a JSON array replacing ALL targets: [{"category":"storytime","target_share":0.4,"rationale":"..."}]. Shares are fractions of 1. Read the current targets from get_content_strategy first.

Parameters:

• •targets_json (string, required): JSON array of {category, target_share, rationale?} replacing all mix targets.

update_campaign_settings

Update campaign settings. Changes data. Spends no credits.

Edit an automation campaign's settings (Content > Automation): name, planning mode, content formats it makes, fire interval, hit-bar views, tests per avatar per week, script auto-approve, review windows and lead time. Only the fields you pass change. Use enable_campaign / disable_campaign to turn it on or off, and assign_avatar_to_campaign for members.

Parameters:

• •campaign_id (string, required): The campaign id (from list_campaigns).
• •name (string, optional): New campaign name. Omit to keep.
• •planning_mode (string, optional): PATTERN_LED | MIMIC_LED. Omit to keep.
• •content_formats_json (string, optional): JSON array of content-format names the campaign should make, e.g. ["storytime"]. Omit to keep.
• •interval_unit (string, optional): Fire interval unit, e.g. DAILY or WEEKLY. Omit to keep.
• •interval_count (integer, optional): Fire every N interval units. Omit to keep.
• •hit_bar_views (integer, optional): Campaign hit-bar view override. Omit to keep.
• •tests_per_avatar_week (integer, optional): Campaign experimental-tests override. Omit to keep.
• •auto_approve_scripts (boolean, optional): Auto-approve the campaign's scripts without review. Omit to keep.
• •lead_time_hours (integer, optional): Hours before posting the plan is drafted for review. Omit to keep.
• •review_windows_json (string, optional): JSON array like [{"day":"SUNDAY","local_time":"10:00"}]. Omit to keep.

update_content_strategy

Update content strategy. Changes data. Spends no credits.

Update the workspace's automation strategy settings. Only the fields you pass change: planning_mode (PATTERN_LED or MIMIC_LED), working_threshold_views (the hit bar for a pattern to count as proven), experimental_double_posts_per_avatar (tests per avatar per week), basis_description.

Parameters:

• •planning_mode (string, optional): PATTERN_LED | MIMIC_LED. Omit to keep.
• •working_threshold_views (integer, optional): Views for a pattern to count as proven. Omit to keep.
• •experimental_double_posts_per_avatar (integer, optional): Experimental tests per avatar per week. Omit to keep.
• •basis_description (string, optional): Free-text description of what the strategy is based on. Omit to keep.

upsert_campaign_assignment

Upsert campaign assignment. Changes data. Spends no credits.

Update content-planning settings for an avatar's existing TikTok account binding. The account must already be linked to the avatar through account management; this tool never creates a second roster. Pass assignment_id when available (preferred), or avatar_project_id for the exact avatar project; avatar_id + username is a legacy fallback and is rejected when ambiguous. Bindings are in list_campaign_assignments.

Parameters:

• •tiktok_username (string, required): The TikTok account username to plan posts for.
• •avatar_id (string, required): The avatar id (from list_avatars).
• •lane (string, optional): Optional content lane label.
• •scripts_per_day (integer, optional): Roster cadence in scripts per day. Omit to keep the current value.
• •status (string, optional): ACTIVE | PAUSED. Omit to keep the current value.
• •tier (string, optional): Optional tier label.
• •assignment_id (string, optional): Preferred exact assignment id (from list_campaign_assignments).
• •avatar_project_id (string, optional): Exact avatar project id when assignment_id is unavailable.

upsert_content_taxonomy

Upsert content taxonomy. Changes data. Spends no credits.

Create or edit a taxonomy entry (Content > Automation): kind is format, audience or avatar_type. Omit id to create (name required); pass id (from list_content_taxonomies) to edit label/description. For avatar_type, format_ids_json (JSON array of format ids) sets which content formats the type can produce. Global default entries are read-only.

Parameters:

• •kind (string, required): format | audience | avatar_type.
• •id (string, optional): The entry id to edit (from list_content_taxonomies); omit to create.
• •name (string, optional): The entry name (required when creating).
• •label (string, optional): Optional display label.
• •description (string, optional): Optional free-text description.
• •format_ids_json (string, optional): avatar_type only: JSON array of content-format ids the type can produce.

Toolset workspace

accept_workspace_invitation

Accept workspace invitation. Changes data. Spends no credits.

Accept a workspace invitation on the signed-in user's behalf using the token from an invite link (pamba.app/invite/<token>). Adds them to the inviting workspace.

Parameters:

• •token (string, required): The invitation token from the invite link.

add_workspace_member

Add workspace member. Changes data. Spends no credits.

Invite an existing Pamba user into this workspace by email (admins only). The person must already have a Pamba account. Role is member (default) or admin.

Parameters:

• •email (string, required): The invitee's Pamba account email.
• •role (string, optional): admin | member. Defaults to member.

capture_website_media

Capture website media. Changes data. Spends no credits.

Scan a website and pull its brand media into the asset library: the logo, App Store screenshots of their app, the social banner, product images and embedded videos. Already-captured files are skipped, so re-running is safe. Defaults to the workspace's website when website_url is omitted. Captured assets are AI-analyzed within seconds and become available to replication's media planning (media scenes and media overlays).

Parameters:

• •website_url (string, optional): Site to capture from; defaults to the workspace's website.

complete_onboarding

Complete onboarding. Changes data. Spends no credits.

Mark onboarding completed so the app stops routing the user through the flow. The device step must be resolved first (devices purchased or skipped via skip_onboarding_step).

No parameters.

complete_onboarding_media

Complete onboarding media. Changes data. Spends no credits.

Onboarding media step: mark the media review done and advance. The step shows the media captured from their website (see capture_website_media / list_assets) and encourages uploading extras — videos of their app in action, product photos, demo clips (upload_asset). Reviewing and uploading are both optional, so completing and skipping are the same action.

No parameters.

connect_daimon_account

Connect daimon account. Changes data. Spends no credits.

Connect one of the workspace's tracked TikTok accounts to a Daimon creator so its posts get attributed on the Daimon partner platform (Daimon partner workspace only). Pass the avatar_project_id from list_avatars and the account's TikTok username; an existing connection is returned unchanged.

Parameters:

• •avatar_project_id (string, required): The avatar's project id (from list_avatars).
• •tiktok_username (string, required): The tracked TikTok account username to connect.

contact_support

Contact support. Changes data. Spends no credits.

Send a message to the Pamba team (human support). Use when the user wants to reach a person, report a problem the tools cannot fix, or send feedback or a request beyond the product's capabilities. The team replies by email. Limited to a few messages per workspace per day, so bundle the ask into one clear message with any context that helps (relevant ids, what was already tried).

Parameters:

• •message (string, required): What the user needs, in their words, plus helpful context.
• •contact_email (string, optional): Optional reply-to email; omit to use the account's email.

create_api_key

Create api key. Changes data. Spends no credits.

Create a workspace API key for calling the Pamba API programmatically. Returns the full secret key ONCE — it cannot be retrieved again, so relay it to the user to store now.

Parameters:

• •name (string, required): A name describing what the key is for.

create_billing_portal_session

Create billing portal session. Changes data. Spends no credits.

Create a Stripe billing-portal link where the user manages their subscription, payment method and invoices. Returns a portal_url to send the user to.

No parameters.

create_checkout_session

Create checkout session. Changes data. Spends no credits.

Create a Stripe checkout link for buying a plan or credits. Pass the Stripe price_id of the chosen plan. Returns a checkout_url to send the user to; payment completes on Stripe's page. For a workspace that already has an active subscription the link is Stripe's confirm page instead: it shows the prorated amount due today and changes the plan in place when the user confirms.

Parameters:

• •price_id (string, required): The Stripe price id of the plan to buy.

create_onboarding_concept_projects

Create onboarding concept projects. Changes data. Spends no credits.

Turn selected onboarding first-video concepts into draft video projects bound to the chosen presenter (avatar_project_id if given, else the presenter picked with select_onboarding_presenter, else the onboarding-generated avatar). concept_indexes is a JSON array of 0-based indexes from get_onboarding_state (e.g. [0,2]); concepts that already have a video_project_id are skipped. Creating the projects is free — generating their videos later spends credits.

Parameters:

• •concept_indexes (string, required): JSON array of 0-based concept indexes, e.g. [0,1].
• •avatar_project_id (string, optional): Optional avatar project id to present the videos; omit to use the presenter chosen during onboarding.

create_topup_checkout_session

Create topup checkout session. Changes data. Spends no credits.

Create a Stripe checkout link for a one-off credit top-up (no plan change). Each unit is 1000 credits; 1-20 units per purchase. Requires an active subscription — offer create_checkout_session with a plan instead when there is none. Returns a checkout_url to send the user to.

Parameters:

• •units (integer, required): Top-up units to buy (each is 1000 credits).

create_workspace

Create workspace. Changes data. Spends no credits.

Create a new, separate workspace owned by the user. With website_url it is set up like an onboarded workspace in one call (the same two-step setup the app runs when a user adds a workspace): the site is read (about half a minute) into a company brief, the workspace is named after the company, and its media library, niche feed and three niche-matched avatars are seeded in the background. With niche_description and no website, the brand is set by hand (name required) and the avatars are matched to it. With neither, a bare named workspace. This conversation stays bound to the current workspace — the user switches to the new one in the app.

Parameters:

• •name (string, optional): The new workspace's name. Optional when website_url is given: the company name read from the site is used.
• •timezone (string, optional): Optional IANA timezone (e.g. America/Los_Angeles) for the workspace clock; invalid values are ignored.
• •website_url (string, optional): Optional company website; reading it sets up the brief, media, niche feed and matched avatars.
• •niche_description (string, optional): Optional one-sentence niche (what the business is about), used instead of or on top of the site's reading.

delete_asset

Delete asset. Changes data. Spends no credits.

Delete an asset from the workspace library by id (from list_assets). The stored file is removed too; this cannot be undone.

Parameters:

• •asset_id (string, required): The asset id (from list_assets).

delete_workspace

Delete workspace. Changes data. Spends no credits.

Delete (soft-delete) a workspace by id (from list_workspaces). Admins only; the user's default workspace cannot be deleted, and deleting this conversation's current workspace ends its context — confirm the user really means it.

Parameters:

• •workspace_id (string, required): The workspace id to delete (from list_workspaces).

dismiss_onboarding

Dismiss onboarding. Changes data. Spends no credits.

Dismiss onboarding: stop routing the user back into the flow while keeping it resumable from the dashboard at the step they were on. Use complete_onboarding to finish it for good instead.

No parameters.

edit_image

Edit image. Spends 15 credits: per edited image.

Edit an existing Pamba-hosted image with a text instruction using the Nano Banana image models and return the edited image's url. model: nano-banana-2 (Gemini 3.1 Flash, fast, default), nano-banana-2-lite (Gemini 3.1 Flash Lite, fastest/cheapest), or nano-banana-pro (Gemini 3 Pro, highest quality, slower). Charges image-generation credits per edited image. To change a clip's scene, edit the clip's starting_frame_url and set the returned url as that clip's new starting frame — editing a registered frame registers the result (usable_as_starting_frame: true), so it is valid for later generation; a url that was never a frame yields a plain image that can't start a clip.

Parameters:

• •image_url (string, required): The Pamba storage url of the image to edit (e.g. a clip's starting_frame_url).
• •edit_prompt (string, required): The change to make, e.g. 'give the person a red baseball cap'.
• •model (string, optional): Optional: nano-banana-pro, nano-banana-2 (default), or nano-banana-2-lite.

generate_image

Generate image. Changes data. Spends no credits.

Internal-operator only: generate a standalone image from a text prompt (optionally guided by reference image urls) and return its url. For avatar scene/starting-frame images use generate_starting_frames or generate_scene_frames instead — this is for one-off images not tied to a project.

Parameters:

• •prompt (string, required): What the image should show.
• •reference_image_urls (string, optional): Optional JSON array of image urls to guide the generation, e.g. ["https://..."].

generate_onboarding_concepts

Generate onboarding concepts. Changes data. Spends no credits.

Onboarding first-video step: research top TikToks and generate first-video concepts, stored on the onboarding state (returned with their index). Topic is optional — omit it to seed from the confirmed niche. keep_concept_indexes redraws only the other concepts (keeping those as-is, reusing the existing references); it must not list every concept. Next: pick concepts and call create_onboarding_concept_projects.

Parameters:

• •topic (string, optional): Optional topic to research; omit to use the workspace niche.
• •keep_concept_indexes (string, optional): Optional JSON array of 0-based concept indexes to keep as-is, e.g. [0,2]; only the rest are redrawn.

get_credit_plans

Get credit plans. Read-only.

List the purchasable credit plans from the live Stripe catalog: plan name, tier (hobby/pro), billing interval (month or year), the credit allowance PER PERIOD (yearly plans carry 12x the credits, granted upfront for the year), price_usd charged per period, and the Stripe price_id to pass to create_checkout_session. ALWAYS state the interval and the per-period charge when quoting a yearly plan. Pair with get_credit_pricing to size a plan against usage.

No parameters.

get_credit_pricing

Get credit pricing. Read-only.

Get what each operation costs in credits: video generation per second for each video model (rate varies by model), image/scene generation per image, and voice creation. Pair with get_credit_balance to estimate what the user can afford.

No parameters.

get_notification_preferences

Get notification preferences. Read-only.

The signed-in user's email notification preferences: which categories (posting_activity, weekly_digest, account_and_credits, tips_and_onboarding) are enabled. Yearly renewal notices are exempt and always send.

No parameters.

get_onboarding_state

Get onboarding state. Read-only.

Get this workspace's onboarding flow state: status (in_progress or completed), the current step (website, brand, media, first_video, avatar, plan or device), the analyzed company profile, the website media capture status (media_capture_status: not_started/running/done/failed), generated first-video concepts (with index and selected flag for select_onboarding_concepts / create_onboarding_concept_projects) and reference TikToks, and which steps were skipped. Use for 'where am I in onboarding' before advancing any step.

No parameters.

get_user_profile

Get user profile. Read-only.

Get the signed-in user's account profile: email, whether the email is verified, subscription plan and status, billing period end (unix seconds) and credit usage (paid monthly + coupon credits). When unlimited_credits is true, credits are not enforced for this user in this workspace and the credit fields are not a meaningful balance.

No parameters.

heal_signup_bootstrap

Heal signup bootstrap. Spends 0 credits: grants the missing signup coupon (300 credits).

Repair a torn signup: when the user's own default workspace has no signup coupon and they own no avatars (the signup bootstrap aborted mid-flight), re-run the missing grants — the onboarding row and the signup credit coupon. Idempotent: each grant only fires when its absence proves it never ran, so repeated calls can never double-award. Returns not_needed when setup is already complete, and an error for non-owner or non-default workspaces.

No parameters.

invite_workspace_member

Invite workspace member. Changes data. Spends no credits.

Invite someone to this workspace by email (admins only). Works whether or not they have a Pamba account yet: they receive an email with a link to accept (existing users) or to create an account and land directly in this workspace (new users). Role is member (default) or admin.

Parameters:

• •email (string, required): The invitee's email address.
• •role (string, optional): admin | member. Defaults to member.

list_api_keys

List api keys. Read-only.

List the user's workspace API keys (Settings > API keys): name, key prefix, workspace and last-used time. The full secret is only shown once, when create_api_key makes it.

No parameters.

list_assets

List assets. Read-only.

List the workspace's uploaded media assets (images, videos, audio) with a temporary signed url for each. Asset ids feed rename_asset and delete_asset.

Parameters:

• •limit (integer, optional): Max assets to return (1-100). Defaults to 24.
• •offset (integer, optional): How many assets to skip, for paging. Defaults to 0.

list_daimon_connections

List daimon connections. Read-only.

List which of the workspace's TikTok accounts are connected to Daimon creators (Daimon partner workspace only). Each connection pairs an avatar project + TikTok username with its creator; posts on connected accounts get attributed to that creator on Daimon.

No parameters.

list_daimon_creators

List daimon creators. Read-only.

List the creators registered on the Daimon partner platform (id, name, profile urls, contract status). Only available to the Daimon partner workspace.

No parameters.

list_onboarding_presenter_options

List onboarding presenter options. Read-only.

Onboarding avatar step: the avatars the flow presents as presenter options — the starter avatars an LLM matched to the workspace's niche once the brand step is saved (cloning any missing into the workspace, free). Empty while the match is still running — poll again shortly rather than treating it as no avatars. avatar_project_id feeds select_onboarding_presenter.

No parameters.

list_social_videos

List social videos. Read-only.

List the workspace's tracked Instagram or Facebook videos with per-video performance (views, likes, comments, caption, post url), most-viewed first. Use for per-video questions get_analytics_summary's account totals can't answer (which reel did best, views on a specific post). For TikTok videos use search_tracked_videos.

Parameters:

• •platform (string, required): instagram | facebook.
• •limit (integer, optional): Max videos to return (1-200). Defaults to 50.

list_workspace_invitations

List workspace invitations. Read-only.

List this workspace's pending email invitations (admins only).

No parameters.

list_workspace_members

List workspace members. Read-only.

List this workspace's members with user_id, email, role (admin or member) and join date. user_id is what set_workspace_member_role and remove_workspace_member take.

No parameters.

list_workspaces

List workspaces. Read-only.

List every workspace the user belongs to with its settings: name, niche description, website, timezone, role and member count. is_current marks this conversation's workspace — its name/niche/website feed the assistant's context. Switching to another workspace happens in the app, not here.

No parameters.

mark_tours_seen

Mark tours seen. Changes data. Spends no credits.

Record UI walkthrough tours as seen for this user across browsers, so their auto-triggers stay quiet. Comma-separated tour names from the walkthrough list (e.g. "home,drafts"). The UI calls this itself when a tour shows; use it only if a user asks to silence the intro tours without sitting through them.

Parameters:

• •tours (string, optional): Comma-separated tour names to mark seen.

purchase_onboarding_plan

Purchase onboarding plan. Changes data. Spends no credits.

Onboarding plan step: start a Stripe subscription checkout for a monthly credit plan (the Stripe price_id comes from the plan the user picks on the app's pricing screen). Returns a checkout_url the user must open to pay; fails if they already have an active credit plan.

Parameters:

• •price_id (string, required): The chosen plan's Stripe price id (starts with price_).
• •credits (integer, optional): Optional monthly credit amount of the chosen plan, for display.

remove_workspace_member

Remove workspace member. Changes data. Spends no credits.

Remove a member from this workspace (admins only; the workspace creator cannot be removed). Get user_id from list_workspace_members.

Parameters:

• •user_id (string, required): The member's user id (from list_workspace_members).

rename_asset

Rename asset. Changes data. Spends no credits.

Rename an asset in the workspace library (asset ids come from list_assets).

Parameters:

• •asset_id (string, required): The asset id (from list_assets).
• •label (string, required): The new display name.

resend_verification_email

Resend verification email. Changes data. Spends no credits.

Resend the account email-verification email to the signed-in user's address. Use when get_user_profile shows email_verified is false and the user can't find the original email.

No parameters.

revoke_api_key

Revoke api key. Changes data. Spends no credits.

Revoke (delete) one of the user's API keys by id (from list_api_keys). Requests using it stop working immediately.

Parameters:

• •api_key_id (string, required): The API key id (from list_api_keys).

revoke_workspace_invitation

Revoke workspace invitation. Changes data. Spends no credits.

Revoke a pending workspace invitation so its link stops working (admins only). Get the invitation id from list_workspace_invitations.

Parameters:

• •invitation_id (string, required): The invitation id (from list_workspace_invitations).

search_help_articles

Search help articles. Read-only.

Search Pamba's help-center articles (how-tos, feature reference, troubleshooting). Returns the best-matching articles with their full text. When answering from an article, include its public link (https://pamba.app/help/<slug>) so the user can read and share it.

Parameters:

• •query (string, required): What the user is trying to do or asking about.

select_onboarding_concepts

Select onboarding concepts. Changes data. Spends no credits.

Onboarding first-video step: record which generated concepts the user wants (marks them selected and resolves the step). concept_indexes is a JSON array of 0-based indexes from get_onboarding_state, e.g. [0,2]. Projects are created later via create_onboarding_concept_projects once a presenter is chosen.

Parameters:

• •concept_indexes (string, required): JSON array of 0-based concept indexes, e.g. [0,1].

select_onboarding_presenter

Select onboarding presenter. Changes data. Spends no credits.

Onboarding avatar step: pick one of the workspace's existing ready avatars as the presenter for the first video (instant, no generation). avatar_project_id is the avatar's project_id from list_avatars. The alternative is start_onboarding_avatar, which generates a new avatar.

Parameters:

• •avatar_project_id (string, required): The chosen avatar's project id (from list_avatars).

set_notification_preference

Set notification preference. Changes data. Spends no credits.

Turn one of the signed-in user's email notification categories on or off. Categories: posting_activity (post live + failed posts), weekly_digest, account_and_credits (accounts ready, profile edits the phone could not apply, low balance, credit follow-ups), tips_and_onboarding.

Parameters:

• •category (string, required): posting_activity | weekly_digest | account_and_credits | tips_and_onboarding
• •enabled (boolean, required): true to receive these emails, false to stop them.

set_onboarding_brand

Set onboarding brand. Changes data. Spends no credits.

Onboarding brand step: confirm the company name and niche description. They become the workspace name and niche, which feed the assistant's context on future turns, and the niche seeds the first-video research. Optionally corrects the profile's what-they-do text — when it differs from the stored value, the rest of the company profile (products, audience, tone) is automatically reconciled to match the correction.

Parameters:

• •company_name (string, required): The confirmed company name.
• •niche_description (string, required): The confirmed niche description.
• •what_they_do (string, optional): Optional corrected 'what the company does' text, 1-2 sentences.

set_onboarding_referral

Set onboarding referral. Changes data. Spends no credits.

Onboarding referral question: record where the user heard about Pamba. source must be one of: tiktok, instagram, youtube, x_twitter, linkedin, google_search, ai_chatbot, friend_colleague, other (anything else is rejected); put free text like a podcast or event name in detail with source=other. Answering is optional and never gates complete_onboarding.

Parameters:

• •source (string, required): Where they heard about Pamba.
• •detail (string, optional): Optional free-text detail, e.g. what 'other' means.

set_onboarding_website

Set onboarding website. Changes data. Spends no credits.

Onboarding website step: analyze the user's company website. Scrapes the site, stores the extracted company profile (what they do, products, audience, tone, logo) and prefills the brand step. While onboarding is live this also updates the workspace branding, which feeds the assistant's context on future turns. Analysis is best-effort — an unreachable site still records the url and advances.

Parameters:

• •website_url (string, required): The company website url.

set_workspace_member_role

Set workspace member role. Changes data. Spends no credits.

Change a member's role in this workspace to admin or member (admins only; the workspace creator cannot be demoted). Get user_id from list_workspace_members.

Parameters:

• •user_id (string, required): The member's user id (from list_workspace_members).
• •role (string, required): admin | member.

skip_onboarding_step

Skip onboarding step. Changes data. Spends no credits.

Skip an optional onboarding step and advance: website (no site to analyze), media (no media to review), devices (no posting iPhones for now) or plan (no credit plan for now). The device step must be resolved — purchased or skipped — before complete_onboarding.

Parameters:

• •step (string, required): website | media | devices | plan.

start_onboarding_avatar

Start onboarding avatar. Spends credits: spends image credits (avatar scenes).

Onboarding avatar step: start generating the workspace's first avatar from a natural-language description (spends image credits) and record the job on the onboarding state. Poll progress with get_avatar_generation using the returned avatar_generation_job_id.

Parameters:

• •description (string, required): Describe the avatar's appearance, vibe and niche.

unskip_onboarding_step

Unskip onboarding step. Changes data. Spends no credits.

Undo the skipped plan onboarding step so it is offered again. The user is still on the go-live step — this only reopens the half they skipped.

Parameters:

• •step (string, required): plan.

update_company_profile

Update company profile. Changes data. Spends no credits.

Update this workspace's company brief field by field (admins only): what_they_do, products_and_services, target_audience, brand_tone and/or logo_url. Omitted fields keep their value; pass an empty string to clear one. The brief grounds scripts, ideas and the assistant's own context from the next message onward. Note: update_workspace_settings with website_url re-scrapes the site and replaces the whole brief — use this tool for targeted edits.

Parameters:

• •what_they_do (string, optional): What the company does, 1-2 sentences. Empty string clears.
• •products_and_services (string, optional): The products and services offered. Empty string clears.
• •target_audience (string, optional): Who the content should reach, one sentence. Empty string clears.
• •brand_tone (string, optional): The brand voice in a few words, e.g. 'confident, playful'. Empty string clears.
• •logo_url (string, optional): URL of the company logo image. Empty string clears.

update_workspace_settings

Update workspace settings. Changes data. Spends no credits.

Update this workspace's settings (admins only): name, niche description, IANA timezone (the clock for scheduling and analytics day-bucketing) and/or website url. Setting website_url re-scrapes the site and refreshes the stored company profile (and the niche, unless it was hand-written). Name, niche and company profile feed the assistant's own context, so changes take effect from the next message onward.

Parameters:

• •name (string, optional): Optional new workspace name.
• •niche_description (string, optional): Optional new niche description (what the business is about).
• •timezone (string, optional): Optional new IANA timezone, e.g. America/New_York.
• •website_url (string, optional): Optional new company website url — triggers a fresh analysis of the site.

upload_asset

Upload asset. Changes data. Spends no credits.

Add a media file to the workspace's asset library from a public url (source_url): images (png, jpeg, webp, gif), videos (mp4, mov, webm) or audio (mp3). Returns the stored asset with its id and url.

Parameters:

• •label (string, required): A short display name for the asset.
• •source_url (string, required): Public http(s) url of the file to store.