MCP server: drive Pamba from Claude Code, Codex or any MCP client

Pamba's MCP server exposes every tool the in-app assistant has, over the Model Context Protocol, at one endpoint: https://api.pamba.app/mcp. Your client's model gets the same product knowledge the assistant runs on, so it can chain the tools into whole workflows (research a format, build the avatar, create the projects, generate, schedule) without you translating screens into API calls. This guide covers what the reference cannot: how the surface is cut, how a call behaves, what waits, what costs credits, and the ordering rules that trip people up. The exact tool list, with every parameter, is the MCP tool reference.

Connect from a chat app

Choose your chat app in the visual setup guide: Claude, ChatGPT, Grok or Gemini. Each walkthrough shows the provider’s menus, where to paste the URL, how to approve access on Pamba and a read-only prompt to try. Account requirements and links to the provider’s current instructions are included.

In a chat app that supports remote MCP with OAuth, add https://api.pamba.app/mcp as a custom connector. Pamba opens an approval page: sign in and choose one or more workspaces, or enter your workspace API key on that Pamba page. Review the requesting app's return address and approve. Never paste the key into a chat message.

Find the URL in Settings → Connected apps and choose Copy URL. The same setup instructions and URL are available on Connected apps, where you can also disconnect apps later.

If signing in takes you to Pamba's onboarding flow, finish that setup, then return to your chat app and connect Pamba again. The original connection request does not resume automatically. You need an existing workspace to approve access.

OAuth connections get every tool an API-key connection has: projects, avatars and generation, scheduling and publishing posts, campaigns, social accounts, workspace settings and members, billing checkouts and API keys. They act in the workspaces you approved. Tool calls run immediately; your chat app controls any per-action confirmation. URL filters can narrow a connection but cannot expand it.

Beyond the approved workspaces, the app can read the name and company details of every workspace you belong to, create workspaces, accept workspace invitations, list or revoke your API keys in any workspace, disconnect your other connected apps, and change your notification settings.

What the app sets up keeps running after you disconnect it or the connection ends: posts it schedules still publish, campaigns it turns on keep spending credits, and API keys, invite links and members it adds keep working until you turn them off or remove them in Pamba.

Each authorization lasts up to 90 days. Access tokens expire after one hour and the client refreshes them automatically; reconnect when the authorization expires. Disconnect anytime from Connected apps. Losing membership or deleting a workspace stops access to that workspace. Revoking a source API key stops the connection. Disconnecting stops the entire connection in every approved workspace, including queued calls that have not started; it does not cancel generation already running. Disconnecting an app does not revoke an existing API key.

One connection can cover up to 50 workspaces you explicitly select at approval. Ask your chat app to use a workspace by name. It calls list_connected_workspaces to find approved IDs, then passes workspace_id on each action. A multi-workspace grant requires that ID; the server never silently switches workspaces. Projects, avatars and credit charges stay within the selected workspace. New memberships and workspaces are not added automatically—reconnect to approve a different selection. Existing connections keep their original workspace. API-key approval remains limited to that key’s workspace.

Pamba staff accounts cannot connect a chat app; staff connect Claude Code or Codex with a workspace API key instead.

Availability and setup menus depend on the chat provider, account and administrator settings. A supported connector must be installed; an API key pasted into regular chat does not give the model an API tool. The API-key setup for Claude Code and Codex below continues to work.

Connect using an API key

• •Endpoint: https://api.pamba.app/mcp, Streamable HTTP, one JSON-RPC message per POST.
• •Credential: an X-API-Key header with a workspace API key. Create one in workspace settings (open the workspace switcher, then Settings, then API keys); the secret is shown once. A key belongs to exactly one workspace and every call runs there; sending an X-Workspace-Id header that names a different workspace is refused. To work in another workspace, connect with that workspace's key. A key can make one for a workspace it created itself: create_workspace over the key, then create_api_key with key_workspace_id set to the new workspace's id, sets up a new workspace and gives its key without opening the app; it never makes keys for the person's other workspaces. Three tools act on the person behind the key rather than the connected workspace, because that is what they do in the app too: delete_workspace accepts any workspace the person administers, and list_api_keys and revoke_api_key cover their keys in every workspace. The instructions tell the model to confirm with the person before the destructive two. Deleting the person's own Pamba account is not available over MCP, to the in-app assistant or with an API key: only the person can delete it, in the app's Settings. An Authorization: Bearer <JWT> plus X-Workspace-Id header works too, the same way it does on the REST API.

Claude Code:

claude mcp add --transport http pamba https://api.pamba.app/mcp --header "X-API-Key: <your workspace API key>"

Codex (~/.codex/config.toml or the project's .codex/config.toml):

[mcp_servers.pamba]
url = "https://api.pamba.app/mcp"
http_headers = { "X-API-Key" = "<your workspace API key>" }

Any client that takes a JSON server list:

{
  "mcpServers": {
    "pamba": {
      "type": "http",
      "url": "https://api.pamba.app/mcp",
      "headers": { "X-API-Key": "<your workspace API key>" }
    }
  }
}

Once connected, ask the model "What can you do with Pamba?": the answer comes from the product map the server sends at connection, not from guesses.

Choose how much of the surface to load

The full surface is about four hundred tools. Most clients work best with fewer in context, and a script that only reads analytics has no reason to see the tools that spend money. Three switches on the endpoint URL shape a connection: two cut the surface, one caps spend.

• •?toolsets=videos,avatars loads only the named toolsets. The names: videos (create, generate, replicate, drafts, scheduling, campaigns, the avatar wizard, and list_avatars, because every project starts from an avatar id), editing (the editor: concepts, takes, renders, text hooks, captions, model switches), avatars (appearance, voices, scene libraries, image editing), accounts (the account fleet, seats and billing, profile edits, warming, health, comments, individual scheduled posts, and upload_editor_media with create_draft_project for the project it files under, because a profile picture or a post's media must be a Pamba URL first), ideas (the ideas library and tracked inspiration accounts), discover (the viral corpus, niche feed, trends, the source picker), content (script batches and their drafts, knowledge base, writer engine, learning loop), automation (campaign strategy and content plans), workspace (settings, members, onboarding, billing and credits, the media library, API keys, help, support).
• •?readonly=true loads only read-only tools. A tool outside the connection's scope is unknown to it, so this is a guard, not a hint: a read-only connection cannot be talked into a write.
• •?max_credits=500 refuses any single credit-spending call whose up-front estimate is above five hundred credits, or that cannot be estimated, with status: spend_limit_exceeded and nothing charged. It is a gate on the estimate, not a meter on the charge: the estimate is what the tool would charge on its first attempt, and a tool's own retries and model fallbacks follow its usual accounting once it runs. The in-app assistant's per-turn spend tripwire does not apply over MCP, so an autonomous client without a ceiling has only the workspace's balance as a brake.

Combine them: https://api.pamba.app/mcp?toolsets=accounts,videos&readonly=true. A toolset name the server does not know is refused at connection time with the list of known names, and so is a toolsets value that names nothing, so a typo or an empty computed list shows up in your client's connection error rather than as a silently widened surface.

Every tool is annotated. readOnlyHint is true on reads; everything else carries destructiveHint, which is what clients such as Claude Code use to decide when to ask you before a call. The description of every tool that spends credits ends with its cost basis.

What else the client receives

• •Instructions. The initialize response carries the transport rules below, workspace selection rules (or, for API keys, the connected workspace's name, niche and website), and the assistant's full product map. Clients inject this into the model's context, which is why the model knows the order of operations without you explaining it.
• •Prompts. Four golden-path workflows, listed as prompts (Claude Code shows them as slash commands): first_video, replicate_tiktok, new_avatar, performance_review. Each is the tool chain the assistant runs for that goal, with the waits and the spend points named. A connection only lists the prompts whose every tool is inside its scope, so a read-only or narrowed connection is not offered a workflow it cannot run.
• •Resources. Every help-center article, including this one and the tool reference, as pamba://help/<slug> in markdown. The model can read them on demand, and clients that let you attach resources let you drop an article into the conversation.

Following changes

Every public change to the MCP tools and the REST API is on the API & MCP changelog, newest first (bug fixes are not listed): what was added, changed, deprecated or removed, the tools, routes and fields it touches, and, for a change that can break a working caller, what to change on your side (breaking changes only). To follow it without visiting the page:

• •Atom feed: https://pamba.app/changelog/api/feed.xml, in any feed reader.
• •JSON: GET https://api.pamba.app/changelog?audience=api, public, no key needed. since=YYYY-MM-DD returns the entries made or amended since that day and breaking=true only the breaking ones, so a scheduled job can flag a breaking change once it is listed. Poll with since a few days before your last read and keep each entry's id with its updated day: an entry is dated the day it went live, which can be a day or two before it reaches the list, and a later amendment keeps its id and sets updated, so treat a new updated as news.
• •From your client's model: get_recent_changes, in the workspace toolset, reads the same entries (the last fourteen days when since is left out; audience=api for API and MCP changes only). Ask it what changed since a given day, or why a tool you relied on behaves differently.

How a call behaves

• •Nothing waits for your approval on Pamba's side. In the app, the assistant parks writes and credit spends on a confirmation card, and a turn that accumulates about eight hundred credits of estimated spend parks too. Over MCP there is no card and no per-turn tripwire: a write or credit-spending tool runs the moment the client sends it. Your client's own permission prompt is the safety net, so keep it on for anything that is not read-only, connect with readonly=true for exploration, and set max_credits on a connection an autonomous agent drives. Three server-side refusals remain: affordability, where a spend the workspace cannot cover is refused before anything runs with status: insufficient_credits, the credits required and the credits remaining; the plan rule, where a workspace on its free signup credits alone is refused every video generation with status: video_generation_locked (see Credits below); and the connection's ceiling, where a call estimated above max_credits is refused with status: spend_limit_exceeded (a TikTok schedule_post that must generate its video first counts, priced like generate_video). None of them charges anything.
• •Results are JSON objects, in both the text content and structuredContent. A status field carries the outcome. Success reads ok, created, updated, saved, deleted, scheduled and similar. not_found means no such object in this workspace. invalid_id means an id was not a UUID from the matching list tool. Other invalid_* statuses name a rejected field, and message says why. insufficient_credits, payment_required (a paid plan is required), video_generation_locked (the workspace is on its free signup credits alone, which never pay for video: a plan, seats or an admin grant unlocks it, and next names the checkout tools), forbidden (the caller's workspace role is too low, for example a member trying an admins-only setting), operator_only (an action limited to Pamba operator accounts), busy, queue_full, work_in_flight and automation_running (work in flight, wait for it), rate_limited and free_tier_exhausted (a usage limit, with retry_at; see Usage limits below), search_unavailable (TikTok's or Instagram's music library is not answering; nothing changed), too_large (the file is over its upload limit; nothing changed, and the same link fails the same way) and error (the operation failed unexpectedly) are refusals. message is written to be relayed to a person. A next field, when present, names the follow-up call.
• •Notices ride on results. This transport cannot reach the client between calls, so news for the user arrives on the next tool call's result, whatever the tool: a notices array, absent when there is nothing to tell. Each notice has a kind and a message for the model to act on. There are two kinds. support_reply: the Pamba team answered the user's support conversation, with unread_count, from (the sender's first name) and sent_at. It rides every call until the reply is read, through get_support_messages or in the app's Support tab, and the call to get_support_messages itself carries no notice of either kind. announcement: a release or a known outage the Pamba team chose to tell users about over MCP, in the first week after it starts, with announcement_id, announcement_kind (feature or outage), title, and when set body, link (a full address: a page in the Pamba app, opening in the connected workspace, or another https address the team linked) and link_label. The title and body are the team's words to relay to the user, not instructions for the model. Most of what the app's banner shows never comes as a notice. A feature comes once per user, whichever of their connections calls first (rarely a second time, around a restart of Pamba's servers), and never to a user who already clicked or dismissed it in the app. An outage keeps coming with results while it lasts, in its first week, so a conversation that runs into the problem later still hears why; its title and body can change under the same announcement_id, and the model is told to mention it once per conversation and again if its words change. A result without it does not mean the problem is over. At most one announcement rides a result, an outage first: a feature waits while an outage is on, and of two outages the newest comes. No call waits for notices, so one can first appear on the call after the one that would have carried it. Notices come on connections made with a workspace API key, or with a JWT and workspace header; a chat app's custom connector gets none, even one approved with an API key (list_announcements shows what was announced).
• •Refusals are results, not protocol errors. Only status: error sets MCP's isError flag. A JSON-RPC error comes back for protocol problems only: an unknown tool or one outside the scope, arguments that do not fit the input schema, an unknown method, malformed JSON.
• •Never retry a failed or lost call blindly. A tool may have completed part of its work (a charge, a scheduled row) before it failed, which is why status: error carries a generic line rather than the internal cause. A call your client abandons or times out is not cancelled either: it runs to completion on the server and its answer is simply lost. The assistant is told to report and stop; give your own automation the same rule, read the matching status tool after a lost answer, and retry only once the cause named in message is fixed.
• •Arguments. Omit an optional argument to leave it unset; do not send an empty string in its place unless the tool says an empty string clears the field (the company profile fields do). Every argument is checked against the tool's input schema before anything runs, and every refusal names the argument: a name the tool does not declare is refused with the accepted names, a missing or null required argument is refused, a whole-number parameter takes a JSON integer or an integral numeric string and refuses a fraction, a boolean takes true or false, a string must be a JSON string (a parameter whose description says it carries JSON, a list of ids say, also takes the JSON list or object itself), and a parameter with listed choices refuses a value outside them. A typo therefore never runs the tool with a default in place of your value. Ids are UUIDs; take them from the matching list tool and pass them back verbatim. An avatar is addressed by its avatar project id: list_avatars returns both id and avatar_project_id, and almost every other tool wants the latter. Dates are YYYY-MM-DD. Scheduling tools take a precise ISO-8601 time in UTC (2026-12-25T14:00:00Z) or a date-only value that auto-picks a time in the posting window. The workspace timezone (update_workspace_settings) is the clock for posting windows and campaign schedules.
• •Lists are truncated, not paged. Most list tools return the full count alongside a fixed-size slice and no cursor: list_projects forty (archived excluded unless include_archived=true), list_scheduled_posts and list_accounts two hundred, list_workspaces twenty, list_scene_frames one hundred, list_video_generations forty clips with ten takes each, or twenty-five takes when asked for one clip, list_creative_concepts twenty versions. Narrow with the tool's filters rather than expecting a next page. The exceptions that do page or take a limit: list_ideas and search_tracked_videos (page, twenty-five per page), the Discover tools (page, twenty per page), browse_picker_videos (page, twenty-four per page), list_assets (limit and offset), get_studio_overview (limit up to two hundred), list_post_analytics (limit up to one hundred, thirty by default, with total the full count).
• •Result size. get_project returns the complete editor state and get_content_batch the whole batch. Read the narrower tools (list_projects, get_render_job, list_video_generations) when you only need a status.
• •Media URLs come in two kinds. A source_url on an ingest tool (upload_editor_media, set_edited_video, upload_scene_frame, upload_asset, import_avatar) is fetched from Pamba's servers: public http(s) only, anything resolving to a private or loopback address is refused, and redirects are re-checked. Every other media field (an editor item's src, a post's video_url, edit_image's image_url, a starting frame, update_account_profile's new_profile_picture_url) takes a file already on Pamba storage (https://storage.googleapis.com/pamba_videos/..., pamba_images/... or pamba_audio/..., with no query string) and refuses a link to another host with a message naming the fix. Slideshow pictures and sounds, a story's image_url and video_url and a replication source_video_url also take a media-library link. So bring an outside file in with the ingest tool that fits and pass on the Pamba URL it returns: upload_editor_media for timeline media, set_edited_video for a project's final video (then schedule the project and leave video_url out), upload_scene_frame for a starting frame, upload_editor_media for a profile picture (a media-library link or another host is refused with the error code profile_picture_invalid). A media-library link from upload_asset is signed and expires: to put a library file on the timeline, pass its link to upload_editor_media and place the URL that comes back. Over REST, POST /uploads/videos and POST /projects/{projectId}/upload-editor-asset take the file itself and return its Pamba URL.
• •Conversation id. get_conversation_info returns mcp as the conversation id because there is no chat transcript over this transport. The workspace id it returns is what support needs.

Waiting for work

Most tools that produce media are asynchronous: the tool returns at once with a status, and the work finishes in the background over minutes. Poll the matching read tool about once a minute, and do not re-trigger the same work while a status reads pending, queued, generating, building, rendering or applying; a second call either reuses the live job or is refused.

• •Clips and videos: get_project and list_video_generations. A failed clip generation retries itself up to three times, including an AI reword of the script after a content refusal, and falls back to the more permissive Grok Imagine model when the chosen model's safety filter still blocks it (the clip's video_model_fallback_from records the blocked model, and the clip's model preference then follows the fallback). A clip whose model keeps failing for a reason other than its content falls back the same way, a Grok Imagine clip to Gemini Omni, charged at no more than the chosen model's price: video_model_fallback_from names the chosen model and the clip's model preference stays on it. An on-camera talking take (not an edit_clip_videos edit) whose speech plays over a closed mouth, or that does not say its line as written (a word that carries meaning missing, added or swapped, a phrase said twice, or the line cut off before its end), is generated again on the same model, at most twice for both together, and its clip reads pending again while it waits. So a clip can sit in pending or generating for several minutes before it completes or fails for good. A project stays "generating" through the editing pass, captions, render and text hook, not just until the first clip lands.
• •Drafts and replications: get_replication_status (build step, failure kind, whether a retry applies). A review-queue item with building: true is a draft still writing its concept, frames and script; do not generate or edit it until that clears.
• •Renders: get_render_job, and render_state on the project (none, current, dirty, rendering, failed). Renders are never cancelled: an in-flight one settles and the next render supersedes stale output.
• •Avatars: get_avatar_wizard for the wizard, get_avatar_generation and list_avatar_generations for redesigns, voices and scene jobs.
• •Accounts: list_accounts shows a purchased seat's setup progress until the account is ready and get_seat_billing each seat's state; list_account_profile_edits tracks an avatar's profile edits, get_account_profile_edit one edit by its job_id, get_account_link_status a link and get_account_import_status an account import (every few seconds while it may stop on a verification code). These run on Pamba-managed phones; a profile edit takes about two minutes and a creation longer.
• •Onboarding jobs: get_onboarding_state (media_capture_status, the presenter match, the avatar job).

A few tools block instead, for up to minutes, and return the finished result: create_avatar, update_wizard_appearance, generate_wizard_scenes, redesign_avatar, render_project, update_account_profile when it edits a TikTok profile, and create_workspace with a website_url, or with niche_description and what_they_do (it reads the site, or writes the brief from what the company does, in the call). Give them a generous client timeout.

Credits, plans and money

• •Metered operations consume credits: video generation per second at the clip model's rate (roughly sixteen credits a second on Grok Imagine, twenty-two on Gemini Omni, fifty-three on Seedance, rounded up per clip; get_credit_pricing is the live list), avatar photos, scenes and variations at fifteen credits an image, replication frames at about sixteen (generation plus a realism pass), clip transcription for captions at about two credits per minute of video (repeat calls served from cache), content-engine script runs, and Ideas script generation by tokens. Voices are free. get_credit_balance is the balance, and reads unlimited rather than a number for internal accounts.
• •Charging is reserve-then-charge. Credits are reserved when work starts, the charge commits only on success, and a failed generation is never charged. A reservation holds for up to two hours and reduces the reported balance meanwhile, so a balance can look low while work is in flight.
• •The affordability refusal is skipped for a project that already has live video work, so a repeat "generate it" reads the tool's own in-flight answer instead of a false shortfall.
• •A new workspace starts with a signup grant of three hundred credits and its first avatar is free (photo, scenes, voice). A workspace on the grant alone cannot generate video: until it has a paid plan, account seats or an admin credit grant, generate_video, generate_replication_draft, a replicate_project without draft_only, a create_video_project with generate_video, and a schedule_post that would generate answer video_generation_locked (with next naming the checkout tools), whatever the balance. Analysis, drafts, scripts, photos, scenes and voices spend the grant as usual, and once video is unlocked the grant pays for it too. A workspace you add with create_workspace starts at zero.
• •Top-ups come in units of one thousand credits, one to twenty units per purchase, and are available to subscribed workspaces only; create_topup_checkout_session returns the Stripe link. Plans: get_credit_plans (yearly plans grant twelve times the monthly credits up front), then create_checkout_session with the plan's price_id; for a workspace that already subscribes, the link is Stripe's confirm page, and confirming changes the plan in place: a pricier plan starts a new billing period that day with its full credits, priced at the new plan's price less what the current plan's unspent credits cost (on a subscription that has a promotion code those credits stay in the balance instead), and a cheaper plan takes effect when the current period ends. No money is refunded. Asking for the plan the workspace is already on cancels a change scheduled for the period's end and is otherwise refused. Downgrading a yearly plan is refused and goes through support. The checkout page of a new plan takes a Stripe promotion code, which the person types there; top-up and seat checkouts take none. create_billing_portal_session opens subscription management (payment method, invoices, billing details, cancellation; plans change only through create_checkout_session); a cancellation there takes effect at the period end, and access lasts until then. When a renewal is declined, seat-funded accounts keep posting and the plan's monthly credits pause while the renewal is past due or unpaid (get_seat_billing says renewal_declined; for the plan, get_user_profile's subscription_status); update_payment_card returns a page for a new card, which Pamba puts on every subscription and charges the declined renewals to at once (a card changed in the billing portal does not reach subscriptions that carry their own card). A workspace's seats bill to one card unless the Pamba team split them across cards at the customer's request: then get_seat_billing lists cards (each card's seats, monthly total and renewal, all renewing on the same day), purchase_account_seats lists the cards a purchase can add to (pass subscription_id), and update_payment_card replaces one card only (pass the subscription_id of the card being replaced). Every one of these returns a URL a person completes in a browser; the purchase lands on the workspace when the payment settles, so re-read get_credit_balance or get_seat_billing afterwards.
• •Purchases need the caller to be a billing admin of the workspace; other members get forbidden.
• •A paid-plan gate returns payment_required: inspiration accounts, ideas and Discover details require an active subscription (a credit plan or account seats), and enabling or firing a campaign requires an active subscription on the workspace owner. Discover shows free workspaces the first rows and blurs the rest; create_video_project with an idea_description has no such gate.
• •Booking a call with the Pamba team at pamba.app/book-a-call earns twenty dollars of credits, added by the team after the call.
• •Usage limits are separate from credits: daily ceilings on the operations that cost Pamba compute without charging credits, set far above real use. A workspace with no plan and no account seats may start 100 renders a day (5 running at once), upload 50 videos a day and run 200 AI assists a day (edit_video, reposition_bullets, generate_project_description, suggest_account_usernames, website analysis, the title a concept save writes, the slide copy create_slideshow writes, the rewrite set_draft_scene makes, the look description a product's photos write, and the search terms written for an account's or avatar's own warming niche); a workspace with a plan or account seats may start 1,000 renders a day (25 at once), upload 500 videos and run 2,000 AI assists. Limits reset at midnight UTC. A refused call answers status: rate_limited with retry_at, or status: free_tier_exhausted when the free tier's shared daily budget is spent (paid workspaces are never affected). Wait for retry_at instead of retrying; a start_render refused this way has already saved the editor state you passed. Two assists degrade instead of refusing, because the request they ride on must still succeed: past the cap a concept save keeps its title, and a website analysis reports failed with no profile.

What needs a browser or a phone

• •Checkout. Every purchase is a Stripe URL the person opens.
• •Files. Tools take URLs, never an upload body: an ingest tool's source_url is any public http(s) URL, and every other media field takes a Pamba URL (see Media URLs above). upload_asset stores a URL in the media library (png, jpeg, webp, gif, mp4, quicktime, webm, mp3); avatar and scene tools take image URLs. The library holds up to thirty image and video files (audio does not count) and answers library_full until one is deleted. Asset URLs the tools return are signed and expire within twelve hours: never store one in editor state.
• •Visual judgment. Watching generated footage and comparing scene images is the person's call. Hand over the URLs the tools return.
• •Accounts. TikTok and Instagram accounts are created, edited and posted from on Pamba-managed iPhones by background device jobs; a Facebook account rides the Instagram account it is linked to, posting through its cross-posts, and is never signed in on its own; update_account_profile edits its name, username and picture (one picture shared with that Instagram account) on that account's phone, turns on its profile's professional mode (facebook_professional_mode), and sets up a Facebook Page for it (facebook_page_name with facebook_page_category), after which its Instagram account's reels post to the Page, the profile is no longer edited from Pamba, and new_profile_picture_url and new_bio change the Page's picture and bio; a Page is not renamed or removed here yet, so confirm with the person first. The client never touches a phone; it schedules the job and polls. An account import is the exception that needs the person: the verification code TikTok or Instagram sends them, passed on within minutes.

Ordering and nuance, by area

These are the rules the assistant follows and the ones people most often get wrong when driving the tools directly.

Projects and generation

• •Two ways to start a project with an avatar: create_video_project with script (spoken verbatim) or with idea_description (a fresh script is written on every call, so fanning one idea across avatars gives each a distinct script; never copy one generated script to several avatars). Passing both or neither is invalid_request; a script run that fails is generation_failed, and rephrasing the idea usually fixes it. promotional=false writes a non-promotional script with no brand weaving. A video is spoken in the language its script is written in: a verbatim script keeps its language, and an idea_description written in or naming a language gets a script written in it. Latin-alphabet languages work best. Creation costs nothing; generate_video is the spend.
• •The project returns before its concept exists. A background job writes the script split, the default scene and the title within a minute or so; while it runs, review-queue items show building: true and get_project reports the concept as none. A failed build marks the project failed rather than shipping an empty draft.
• •The clip split is automatic, on natural speech boundaries, with durations the project's video model allows. Non-automated creations also pick a default scene automatically from the avatar's labeled library scenes, at random among those that fit the script, so two creates from the same script can differ; when nothing fits, a random face-visible library scene stands in. Override frames only when a specific look is wanted: set_draft_scene moves a built script or idea draft onto another scene of the avatar's library (every clip re-deals from that scene and its pose variations at once, and its place and video prompts are rewritten for the new scene in the background, free, until anything generates; a generate that arrives first applies the rewrite before it shoots). preview_script_clips shows a split without saving anything.
• •Authoring and generating are separate steps. Changing frames, scenes, script, concept or timeline is complete when saved; rendering or generating is a further, explicit request. The assistant is told never to queue a spend to "finish" an edit, and a script that drives the tools should not either.
• •A project can exist without an avatar: create_draft_project with no avatar plus set_edited_video turns a ready-made video into a postable project. The avatar stays unassigned forever; it cannot be added later.
• •Video models: grok-imagine-1.5, seedance, gemini-omni. The default resolves in this order: the project's explicit model, the campaign's per-member model, the avatar's default_video_model, the workspace routing rules (campaign videos only), then the platform default: a campaign video, a video created from a script or an idea, and a replication whose avatar speaks a line on camera currently get grok-imagine-1.5, from an MCP client, an API key and the Pamba app alike (clips saved by hand with set_creative_concept on a project that has no model yet keep gemini-omni unless they name one); any other video, such as a replication with no line spoken on camera, gets gemini-omni when an MCP client or API key creates it, while in the Pamba app an experiment currently splits it between gemini-omni and grok-imagine-1.5. set_video_model switches drafts and projects in bulk and re-splits the stored script under the new model's limits (skipped when every duration is already legal, because a re-split mints new clip rows). Every model authors clips of four to fifteen seconds and shares the four-second floor, and a concept save with a clip outside its model's range is refused whole.
• •get_project uses sentinel strings: concept and editor_state_json read none until they exist, final_video_duration_seconds reads unknown until the file is probed, and generated_at stays empty until every clip has a generated video. Prefer the measured duration over summing clip durations, which are the plan. promotional reads true, false or not_applicable (verbatim scripts decide nothing).
• •update_project changes only the fields passed: name, notes, user_review_state (not_reviewed or approved), posted_state, user_visibility. Archiving also cancels the project's pending posts. list_projects with posted_only means the project actually went live, which posted_state alone does not tell you (a cross-post downgrades a live project to scheduled, and cancelling a pending post resets it to approved).
• •Approving or scheduling is refused with a conflict while the video is still generating, with one exception: clips in their final 60fps upscaling pass (the take is already playable: active_generation_status is null while preview_video_url is set) do not block; approve or schedule, and the automatic render waits for the upscaled files before anything posts.
• •generate_clips takes optional zero-based clip_indices; on a clip in that upscaling pass it replaces the take: a fresh take starts, the superseded pass finishes and parks in the clip's take history (billed like any completed take, revertable with select_clip_video). A clip still producing its take keeps that generation. keep_raw_voice=true keeps the model's own audio and skips the avatar voice dub and the speech trim.
• •Refusals from the clip-starting tools: insufficient_credits, automation_active (a pipeline owns the project), queue_full (try again in a few minutes), work_in_flight (a draft still building, or clips, an edit or a render from a previous generate still running). A pipeline stamp older than two hours is treated as dead, so a crashed run cannot lock a project out forever.
• •duplicate_project clones a shell (concept and frames, no script, clips or videos); duplicate_project_full clones an exact independent copy, nothing re-billed. Neither carries scheduled posts, approval state or in-flight generations.

Editing

• •edit_video is the entry point for timeline edits: pass the intent in natural language and a dedicated editing agent, which sees the full timeline, the concept and the media library, applies validated operations and reports applied or no_changes with what it rejected and why. edit_clip_videos is different: it changes a clip's pixels via video-to-video on Gemini Omni whatever model made the clip, on clips that already have a video and are three to ten seconds long; for a longer clip, pass in_point and out_point to edit a window, one clip at a time, billed for the window at the Omni rate. Each edit lands as a new take, auto-selected, with the prior take still available. A failed edit leaves the working take untouched and reports on latest_edit_status.
• •set_editor_state replaces the whole editor state object. Always read it from get_project, modify, and write it back; a partial object deletes what it omits. When changing one field of an existing item, copy the item verbatim: an item with the same id inherits its earlier placement and style for fields you leave null, but explicit values always win.
• •Editor item shapes: text items place with x, y, w normalized zero to one (x 0.5 centered, y the vertical center: a top hook sits near 0.12 to 0.2, a bottom one near 0.8), and style.font_size is pixels on a 1080 by 1920 reference (default sixty-four, readable minimum twenty-four). Always set x and y or the text renders center-frame. Text wraps only at its own line breaks unless text_wrap is true, which makes w the box width. Prefer style_preset ids from list_text_style_presets over hand-built styles. Media items (and audio items) need a Pamba image, video or audio URL: bring an outside file in with upload_editor_media and place the URL it returns (a signed library asset URL is refused). They take w as a width fraction (1.0 fullscreen, about 0.6 for a picture-in-picture, about 0.4 for a logo flash); video items also take speed 0.5 to 2 and volume, which you set to zero so a demo clip never talks over the presenter.
• •Clip ids are re-minted on every concept save. An id held across a save answers "Clips not found in the selected concept"; re-read the project. Changing a clip's starting frame also drops that clip's generated video, which comes back only by reverting to the prior concept version (list_creative_concepts, then revert_creative_concept, which restores script, clips and editor state together and is refused while automation runs).
• •select_clip_video needs a completed take of the same project; re-render afterwards to bake the change in. A main-track entry with use_original_voice: true keeps the clip's pre-dub audio in renders, and the flag is dropped when the clip re-points to a new generation.
• •Captions come from transcribe_clips, which is English only, so the on-screen captions timed from the speech suit English videos. Word timings arrive in spoken order and must not be re-sorted.
• •Renders are automatic when saved edits are newer than the last render: approving, scheduling and leaving the editor re-render, scheduled posts wait briefly for an in-flight render rather than posting stale video, and a sweeper renders recently active projects once they have been quiet a few minutes. render_state: failed means the last attempt for the saved edits failed and only the next edit or commit point retries it. A video supplied directly is recorded as the current render and is never re-rendered over: set_edited_video copies whatever file it is given, and a video_url on update_scheduled_post, schedule_instagram_post or the REST schedule route counts only when it is a file from outside the project's own outputs. A url the project itself produced (its edited_video_url or stitched_video_url, an earlier render, a file it was given before) is ignored on those post routes, and the pending post keeps following the project's latest render.
• •set_clip_voice_effects adjusts the acoustic environment baked into generated clips' audio: free, seconds per clip, frames untouched.

Replication and drafts

• •replicate_project takes exactly one source: a tiktok_url, an instagram_url (a reel; inspect_instagram_reel reads a pasted link first), a source_video_url from the workspace, or a source_project_id of one of the workspace's own projects (its rendered video is the reference, so it needs a finished video). draft_only=true builds a reviewable draft and stops before clip generation, so video credits are spent only when the draft is generated. max_duration_seconds is a target, not a cap: it shortens or lengthens the replica, and every replica is capped at one hundred sixty seconds whichever model generates it. variation_instructions cap at four thousand characters. In a workspace whose replications draw motion graphics (a trial in a few workspaces), the graphics follow how the reference draws and animates its own; ask for simpler or more impressive ones in variation_instructions. A workspace runs ten replication jobs at once; requests past that queue automatically.
• •For source_video_url, use a Pamba-hosted video or a video asset owned by the selected workspace's media library. Upload an external source to that library first; arbitrary remote URLs and local files are refused before replication starts.
• •Replicating from a TikTok URL also captures the source into the ideas library, deduplicated on the video URL; a replicated Instagram reel is not captured. Replication plans media from the workspace asset library on its own: an app demo the original cut to becomes a media scene, partial cards and logo flashes become timed overlays on a Media track. A non-promotional replica does not use the brand media library.
• •A hub video judged hard to replicate returns low_feasibility_warning until the call repeats with acknowledge_low_feasibility=true. A video that needs the brand's own digital files returns missing_brand_assets naming what to upload (upload_asset) rather than starting; the same acknowledgement proceeds anyway and the replica drops those beats. Physical products are never a requirement.
• •get_replication_status reports build_step (source, analyze, concept, scenes, frames, assemble, done) and, on failure, failure_kind (transient, timeout, safety, quality, content, unknown), retriable and a next hint. retry_draft_build resumes from the last completed checkpoint, so finished stages are never re-paid; prefer it for transient and timeout failures and request_draft_edits for safety or content failures, because a blocked look keeps getting blocked. A failed request-edits revision restores the draft intact and reports failed_revision with the preserved feedback.
• •An ungenerated replication draft's editor is read-only: direct set_editor_state is refused. Its edit surface is the draft itself, through the edit ladder: words only, on one scene, edit_scene_script (free); the whole read, edit_draft_script; one scene should look or play differently, edit_scene (image credits); the whole video's look, regenerate_look_canon; restructure, duration, add or remove scenes, request_draft_edits, which edit_scene refuses and which cannot serve script drafts. Scene edits of different scenes run in parallel; same-scene and whole-script edits serialize. Every completed edit_scene is undoable with revert_scene_edit, per scene, free.
• •A draft can complete with some scene frames failed; regenerate_scene_frame retries them, and generate_replication_draft is gated until every scene has a frame.
• •generate_replication_draft approves the reviewed draft into clip generation plus the final editing pass and render, honoring editor changes present on the draft as deliberate overrides. generate_video on a draft instead runs the standard automation pipeline and does not carry draft edits as overrides.

Scheduling and posting

• •schedule_post posts a project's video to TikTok (tiktok_username), to the avatar's Instagram (also_post_to_instagram), or both in one atomic schedule: if either platform has no slot (device busy, no slot left that day), nothing is scheduled and the whole request is rejected. schedule_instagram_post schedules a standalone Reel. Facebook gets an Instagram video reel only through Instagram's share: a reel goes to the account's linked Facebook account while the account's Cross-post reels to Facebook switch is on (set_account_facebook_cross_posting, update_avatar_settings's facebook_cross_post_enabled for an avatar's Instagram accounts, on for a new account; list_posting_accounts names the accounts whose switch is on in instagram_cross_posting_to_facebook) and that Facebook account is posting, checked again when the reel posts. Leave share_to_facebook out to follow the switch, pass false to keep one reel off Facebook; true is refused when it cannot happen (facebook_cross_post_off while the switch is off, no_linked_facebook_account, facebook_account_paused). A post's share_to_facebook says what it will do as of now and share_to_facebook_choice what it asked (empty: follows the switch). An Instagram Reel can go out as a trial (schedule_post's instagram_trial_reel, trial_reel on schedule_instagram_post and update_scheduled_post): release_to_followers_once_it_performs_well lets Instagram share it to everyone if it performs well in its first 72 hours, release_to_followers_never keeps it a trial that is never shared to the account's followers; leave it out for a regular reel, and update_scheduled_post's remove_trial_reel takes a trial off. Instagram shows a trial to non-followers first and keeps it off the profile; it never goes to Facebook (refused with share_to_facebook true), Instagram offers it only to professional accounts with at least 200 followers (an account under 200 is refused with instagram_trial_reel_ineligible: its last read follower count decides, or, for an account Pamba has not read yet, its profile read when the post is scheduled; list_posting_accounts and get_project name the accounts known to be under it in instagram_below_trial_floor; a personal account is refused the same way, and they name the ones Pamba knows in instagram_personal: switch one to creator with update_account_profile's instagram_account_type and the trial can be scheduled as soon as the switch is queued), and a slideshow's carousel has none. update_scheduled_post, cancel_scheduled_post and retry_scheduled_post manage the queue; list_scheduled_posts and get_scheduled_post read it. A completed post is the phone's word that it posted, and its verification_status says whether Pamba then found it on the account's public profile: pending while the checks run (20 minutes after posting, then an hour, another hour and a day later), verified once it matched (its link in posted_tiktok_video_url or posted_instagram_video_url; an Instagram slideshow post (a carousel, or a reel built from its slides), an Instagram trial reel (linked once a reel with its own caption appears on the account), and an Instagram reel posted before 2026-10-03, read verified on the phone's word alone until the link is known), video_not_found when no new post appeared, frame_mismatch when a new post appeared that is not this one, error when the check could not finish; verification_message says it in one sentence. The check runs once, so verified says the post was found, not that it is still up. The app shows these as Posted, Verified (for an Instagram post, once its link is known), Not visible and Not matched. A post deleted through Pamba (delete_account_posts) before the check found it, on TikTok or Instagram, is not checked further once the deletion is confirmed: its verification_status turns empty and the app shows Posted. Pamba knows it by the video id the phone read as it posted, or, for a post without one (an Instagram reel, a TikTok photo post), by the deleted post of its kind that went up while it was being posted, with its caption; such a reel keeps the deleted reel's link in posted_instagram_video_url, which is no longer live. A post without a caption, or one whose deletion is still being confirmed at the last check, is checked as usual and can read video_not_found or error. A failed post whose retry already failed again, in a way that alerted Pamba's engineers, reads being_fixed true: it is theirs to fix and retry, usually within a few hours, and retry_scheduled_post refuses it with status being_fixed (the REST route answers 409 post_being_fixed). A hold nobody works ends a day after the failure, and the retry is yours again. A failure you remedy yourself (another Instagram song or sound, the slideshow's missing images, the TikTok Shop link, approving the project, reconnecting a signed-out account you connected: account_needs_reconnect, new audio for a video TikTok would mute for copyrighted music: copyrighted_sound_muted, where a TikTok sound added on top keeps the video's own audio, another TikTok sound for a post on a TikTok Business account whose sound isn't cleared for commercial use: sound_not_licensed, another TikTok sound for a post whose sound TikTok says isn't available: sound_unavailable, a reel Instagram offered no trial: ig_trial_reel_unavailable, fixed by switching the account to creator with update_account_profile or removing the trial with update_scheduled_post's remove_trial_reel, a caption Instagram flagged after Share as similar to others that have been reported: ig_caption_flagged, nothing posted, fixed by a new caption with update_scheduled_post) stays yours to retry. A trial reel whose outcome was lost reads being_fixed true from its first failure, and that hold does not end after a day: it may be live and no lookup can prove a trial absent, so Pamba's engineers check it on the phone and settle it, and retry_scheduled_post refuses it with status being_fixed. A post is never retried, by anyone, while another post of the same video or slideshow to the same account is scheduled, posting or already posted, so nothing posts twice. And one video or slideshow goes to one account per platform: schedule_post, schedule_instagram_post and update_scheduled_post refuse with status duplicate_content, and schedule_slideshow_post with status rejected and code duplicate_content (over REST, error_code duplicate_content, and code on the slideshow schedule route), a post whose content another account of the workspace has scheduled, is posting or posted on the same platform (a draft-only post, only_create_draft, on TikTok or Instagram, never counts: it never goes public): the same project or slideshow, or a file with the same bytes (the same upload twice; a carousel all of whose slides another account's carousel holds, or that holds all of another's). TikTok and Instagram flag the same content on a second account. The same video on TikTok from one account and on Instagram from another is fine, and an upload re-cut, re-encoded or with other words on it is another file.
• •Pick a time the phone has free. Each account posts from one Pamba iPhone, and a phone runs one post or task at a time for every account on it (an avatar's TikTok and Instagram accounts usually share one). An exact TikTok time that overlaps another post, a task running on the phone or booked on it to set up an account, or a maintenance window is refused as schedule_conflict with the next free time in message; an exact Instagram time there is moved to the next free slot that day (read the returned scheduled_at) and is refused only when the day has no room left. The refusal carries a next field pointing at get_account_schedule: schedule_post and schedule_instagram_post answer it as their status, schedule_slideshow_post as its code, and update_scheduled_post as update_failed with code schedule_conflict. That tool (platform tiktok or instagram, username, optional from and to in UTC, seven days by default and fourteen at most) returns openings, the stretches in which a post picked at an exact time is kept as picked (a schedule with automate, or while its video is still being finished, waits at least 30 minutes from the request instead) (whole minutes, both ends included, none before earliest_post_at, which moves with the clock: a pick must still be that far ahead when it is sent), busy, what holds the phone (post with this workspace's post_id, post_platform and post_username, task, or maintenance), and post_minutes, how long one post holds the phone. Read it before scheduling at exact times. A new account being set up on a phone goes first: its setup is booked on the phone from the start, listed in busy as a task at the time it is expected to reach the phone, and a post that comes due while Pamba creates an account on its phone waits for the setup and goes out soon after it, its scheduled_at moved to the new time, and the wait costs none of its retries. Each post you schedule holds its phone for post_minutes from its time, so space exact picks on one phone at least that far apart. When a TikTok and an Instagram account share a phone, the Instagram post takes the first free time after the TikTok one that day (Pacific time; right after it when the phone is free), and a day with no room left for it refuses both, so leave post_minutes free after a TikTok time that cross-posts; a Facebook share rides the Instagram post. A post you move with update_scheduled_post is not blocked by itself or its pending cross-posts; the cross-posts then follow it to the first free time after the new time that day, and one with no room left keeps its old time, so leave post_minutes free after the new time for each cross-post on the same phone. A new caption on the TikTok post likewise carries to its Instagram cross-posts in the same status (pending with pending, failed with failed) that still had the old caption; one whose caption no longer matched keeps it, and editing a cross-post never changes the TikTok post. A post schedule_post booked away from the exact time asked for carries moved_from (that time) and move_reasons, a list of too_soon, video_to_make, video_finishing, accounts_setting_up and phone_busy in the order they applied, with a note: tell the user the new time and why. A date-only scheduled_at finds a free slot by itself. The openings are a read, not a booking: another schedule can take the time first, and on rare occasions the fleet-wide cap on posts at one time refuses a pick inside one, again with the next free time. Over REST it is GET /devices/accounts/schedule.
• •How often an account should post. An account Pamba created less than 10 days ago does best posting once a day, and any account at most 2 or 3 times a day: past that each post brings diminishing returns and makes TikTok or Instagram likelier to flag the account. Pamba warns and never refuses. A post that makes a new account's 2nd post in a day (the workspace's day, counting its pending, posting and posted posts) or any account's 4th is booked all the same and carries posting_warning in the result of schedule_post, schedule_instagram_post, schedule_slideshow_post, and update_scheduled_post when the edit moves the post: tell the user the warning and offer to move the post to another day. list_accounts sets new_account_until_utc on each account on the workspace's phones that Pamba created less than 10 days ago, so spread several posts on one account across days before scheduling them. Over REST the schedule and edit responses carry posting_warning as { code, message, day, posts_that_day, posts_per_day }, code being new_account_posts_per_day or posts_per_day.
• •A project with an avatar may only post to a TikTok account linked to that avatar. A project with no avatar can post to any account on the workspace's fleet, linked or unassigned; posting to an avatar's account attributes the analytics to that avatar, posting to an unassigned account attributes them to none. get_project's posting_accounts (and get_slideshow's, for a slideshow) lists the accounts a schedule may name, the choices the app's schedule dialog offers, and list_posting_accounts lists every avatar's and the no-avatar pool at once: read one before schedule_post. A listed TikTok account that is not signed in on one of the workspace's phones, or one with an open suspension, is still refused.
• •Posting a video you already have (nothing generated, rendered or credit-metered): create_draft_project makes an empty project with no avatar, so it can post to any account on the fleet; set_edited_video attaches the file from a publicly reachable video url and records it as the project's completed render; then schedule_post or schedule_instagram_post posts it. There is no upload body over MCP: a file on the client's machine is staged with the REST upload (POST /uploads/videos, multipart, the same API key) and its returned url passed to set_edited_video. To attribute an uploaded video's analytics to an avatar, create the project in the app's Upload button or with the REST create call and its avatar field, then attach and schedule from here; the avatar choice is permanent. set_edited_video is refused while automation runs on the project or a replication draft is locked, and a scheduled post for the project picks up the new video.
• •What schedule_post posts depends on the project: a project with a concept whose clips have no video yet is generated and rendered first (the result says mode: generate_then_post, credits are spent); a project whose video was supplied (set_edited_video, the app's Upload button) posts that video as is (mode: post_project_video, nothing generated); a project with neither a video nor a concept is refused as nothing_to_post. The REST automate flag follows the same rule: it is 400 on a project with no concept to generate from. generate_video follows it too: a project whose video was supplied, or one with no concept at all, is refused as nothing_to_generate instead of starting a pipeline that has nothing to build.
• •A post goes out only if its project is approved at its slot. schedule_post says where that stands in its result's approval field: approved_by_schedule when it posts a video that already exists (the schedule approves the project, nothing more is owed), and required_before_slot in generate_then_post mode, where the schedule does not approve a video that does not exist yet and someone must approve the rendered video before the slot. update_project with user_review_state=approved approves, with or without a schedule; approving is refused while the video is still generating. A post that failed at the gate is recovered by approving the project and then calling retry_scheduled_post. Automated pipelines (campaigns, content pushes) generate, render and schedule but never approve on their own, so a scheduled post whose project nobody approved fails at its slot with the message "Project not approved at scheduled time". That is the review step working, not an outage.
• •Captions: generate_project_description writes a hook line plus exactly five hashtags from the script and company profile, but only returns the text; pass it as the caption yourself. schedule_post's caption goes out on every platform it schedules; pass instagram_caption as well to give the Instagram Reel its own (the Facebook share carries it too) while TikTok keeps caption. It needs an Instagram leg, and each caption is checked against its own platform's rules. A TikTok caption with one of the commercial-disclosure hashtags #ad, #ads, #sponsored, #partnership or #paidpartnership is posted with TikTok's commercial content disclosure on, as Branded content ("You are promoting another brand or third-party"), so TikTok labels it "Paid partnership" and Pamba cannot take the label off once it is live. TikTok publishes no post with such a hashtag without the disclosure. generate_project_description never writes one: whether a post is an ad is the user's call. An @handle in a caption, a video's or a slideshow's, posts as a linked mention on TikTok and Instagram alike: on TikTok the phone picks each account from TikTok's mention list as it types, so a TikTok caption holds at most 5 mentions, uses @ only to start one (no email addresses, no handle run into other letters such as @my-brand) and never names its own posting account, and a handle TikTok's list does not offer fails the post with mention_not_offered before anything is posted (fix the handle with update_scheduled_post, then retry_scheduled_post). An Instagram caption, a reel's or a carousel's, holds at most 2,200 characters and 5 hashtags: Instagram keeps no more than 5 hashtags on a post, so a longer list is refused rather than posted with the rest stripped to plain words.
• •When the avatar has no account on a platform yet, schedule_post with await_new_account=true (TikTok) or await_new_instagram_account=true, or schedule_instagram_post with await_new_account=true, persists the post as waiting; purchase_account_seats with link_avatar_project_id then buys the account, and once it is created the waiting post books a real slot and goes out with no further action, independently per platform.
• •TikTok Shop. A TikTok account enrolled in TikTok Shop can link one product of its shop to each post, chosen per post (there is no default product). get_tiktok_shop reads the shop as the account's phone last saw it (linked, the showcase, the catalog's products with their ids and showcase_state); sync_tiktok_shop reads it again on the phone, which takes a few minutes. The account's daily phone visit also looks for the Shop tab and reads the shop by itself when the tab appears or goes, so an account TikTok enrolls shows up without a sync. Pass tiktok_product_id (and optionally tiktok_product_link_name, at most 30 letters, numbers, spaces, apostrophes or hyphens) to schedule_post or update_scheduled_post; remove_tiktok_product takes it off a pending or failed post, and a post moved to another account drops a product it does not restate. Only a video post links a product; a slideshow cannot. A post links from the showcase only, so a product not in it is queued for adding the moment the post is scheduled (add_tiktok_showcase_products does the same on its own), and the post goes out only after the phone can have added it: an exact time before that is refused with status tiktok_product_not_in_showcase_yet and earliest_at_utc, and a date-only time is given a slot after it. The phone reads a product's title off the screen, so a long one reads cut short with … at its end; rename_tiktok_shop_product gives a product its display_title, the name to show for it (the phone keeps finding it by its title, and a read of the shop never changes the name). The phone reads each of the showcase and the catalog up to about 80 products; a list it could not read whole (longer than that, or with a product the phone saw but could not read) reads showcase_complete or catalog_complete false, and the lists then hold part of the shop. The phone adds the link before its Post tap, and a post whose link cannot be added fails rather than go out without it. TikTok caps a new shop's shoppable videos (shoppable_videos_left, as the latest post that linked a product left it).
• •AI label. ai_label: true on schedule_post labels the video as AI-generated on every platform that call schedules (TikTok's "AI-generated content" label, and Instagram's "Add AI label" switch, which shows on the post as "AI info"); schedule_instagram_post takes it for the reel, and update_scheduled_post turns it on or off for one pending or failed post. TikTok and Instagram video posts only: a slideshow post and a Facebook post refuse it. The phone sets the label before its Post or Share tap, and a post it cannot label fails and is retried rather than go out unlabeled. Pamba cannot take the label off once the post is live, so set it only when the user asks.
• •First-frame cover. Left alone, TikTok and Instagram pick a video's cover from a frame a few seconds in. first_frame_cover: true on schedule_post makes the video's first frame, where its burned-in hook is, the cover on every platform that call schedules; schedule_instagram_post takes it for the reel, and update_scheduled_post sets it (true) or leaves the cover to the platform again (false) for one pending or failed post. TikTok and Instagram video posts only: a slideshow post and a Facebook post refuse it. The phone sets the cover in the app's Edit cover before its Post or Share tap, and a post it cannot set it on fails and is retried rather than go out with another cover.
• •If a schedule is rejected, read the reason and offer the valid accounts or another time; do not retry blind.

Slideshows

• •A slideshow is a TikTok photo post or an Instagram carousel (or, with as_reel, one reel Instagram builds from the slides): up to twenty pictures with words burned in, and one sound per platform under the whole post: a TikTok sound for the photo post, an Instagram track for the Instagram post. It is made from pictures the workspace already holds — nothing about a slideshow spends credits, and there is no slide image generation. Get the pictures in first: upload_asset with a public url (or list_assets for ones already there), then create_slideshow with slide_images (one Pamba-hosted url per slide, in order) and lines (write_with_ai=false keeps them verbatim; no lines gives picture-only slides). Both are strings: a JSON array serialised as a string, or one entry per line; the JSON array itself is taken too. A slide with a picture but no line has no text element.
• •The tools are in the content toolset (list_slideshows, get_slideshow, create_slideshow, update_slide, add_slide, remove_slide, reorder_slides, add_slide_image, update_slide_image, remove_slide_image, suggest_slide_lines, search_tiktok_sounds, set_slideshow_sound, search_instagram_audio, set_slideshow_instagram_sound, schedule_slideshow_post, get_slideshow_scheduled_post, duplicate_slideshow, export_slideshow, update_slideshow). Every edit re-burns the slide; get_slideshow reports each slide's status (ready once burned) and its image_url.
• •Sound: search_tiktok_sounds with no query returns TikTok's Hot chart (source hot, in chart order, the editor's default listing); with a query it pages TikTok's own library (cursor from the previous page's next_cursor), and set_slideshow_sound picks one for the whole post by tiktok_music_id (the search result's music_id); the search is a plain read, not one of the capped AI assists. Searches that reach TikTok run at most 5 a second, 30 a minute and 1,000 a day per workspace (a repeat the day's cache answers is free); past that the tool answers rate_limited with retry_at (midnight UTC once the day's are used), and the REST route a 429 with a Retry-After header. Every result carries commerce_right: whether TikTok clears the sound for commercial use, which a Business account needs to post with it (its sound page shows no Use sound otherwise), so prefer a cleared sound for such an account. When TikTok's sound search or sound page is not answering, search_tiktok_sounds, set_slideshow_sound and set_video_tiktok_sound answer search_unavailable (nothing changed; try again in a minute) and the REST routes a 503.
• •Instagram sound: the Instagram post's sound is picked apart from the TikTok one, because the two platforms' libraries are different. search_instagram_audio with no query returns Instagram's Trending chart (source top, read from a US account's picker); with a query it returns Instagram's own results for the words, ten at most with no further page, and the same per-workspace rate and daily limit as the TikTok search. set_slideshow_instagram_sound picks one by instagram_audio_id (the result's audio_id; none clears it). The track starts where Instagram's picker starts it (highlight_start_seconds), and the phone picks it in Instagram's own music picker when the Instagram post goes out. One it cannot find there goes out as the same song by the same artist at another length, else as a song Instagram picks, and get_scheduled_post and list_scheduled_posts name it in audio_fallback. The searches run on accounts outside the US, which list some songs US Instagram lacks, so a song a Pamba phone did not find, posting from an account Pamba knows is not a Business account (a Business account's picker lists only commercial music), is recorded and left out of every later search and of the chart. A pending or failed post still using such a song reads instagram_song_unavailable true on get_scheduled_post and list_scheduled_posts: set another song before it goes out to choose it yourself. A pick the chart or the day's searches did not list is looked up on Instagram's audio page, and that lookup counts against the same per-workspace rate as a search (not the daily limit, which counts searches only). No provider says which songs an Instagram Business account may use, so the whole library is listed. When Instagram's music search or audio page is not answering, the tool answers search_unavailable and the REST route a 503.
• •Posting: schedule_slideshow_post schedules the slides on a Pamba-managed iPhone and approves the slideshow; it is refused while any slide still has no picture. A TikTok photo post takes a single slide, and so does an Instagram post (platform instagram or both), where one slide goes out as a single photo and two or more as a carousel; a reel built from the slides (as_reel) needs at least 2. With platform tiktok (the default: tiktok_username, scheduled_at, caption; the caption is the post's description, capped at TikTok's 4,000 characters with the same hashtag and mention rules as a video, and the post has no separate title) it is a public photo post carrying the slideshow's sound; with platform instagram (instagram_username, omitted when the avatar has one Instagram account; scheduled_at; caption, at most 2,200 characters and 5 hashtags, its @handles linked by Instagram) it is a public carousel carrying the slideshow's Instagram sound, each slide fitted whole into Instagram's square or 3:4 feed frame (square when the slides are square or wider), and it is refused until the slideshow has one (set_slideshow_instagram_sound): without a track Instagram does not treat the carousel as a reel and shows it only to followers, and the track cannot be cleared while an Instagram post waits; as_reel=true posts it instead as one reel Instagram builds from the slides, each 4 seconds with the same track under it (which the reel needs too), in the full 9:16 frame with the first slide as its cover (refused with platform tiktok; with platform both the TikTok photo post is unchanged); with platform both (tiktok_username, and instagram_username as above) the two are booked together in one plan, both or neither, under one caption that must pass both platforms' rules, and the result's posts lists each. A slideshow posts once per platform. get_slideshow_scheduled_post follows them (posts holds one per platform: pending, in_progress, completed, failed), and cancel_scheduled_post with a post's id cancels it while it is still pending. A TikTok photo post is verified against the account's profile and gets analytics like a video. An Instagram carousel is verified on the phone's word (the phone reads it as the profile's newest post), and the account's hourly analytics refresh then links it to its live post (posted_url, a /p/ link) and tracks its likes and comments; Instagram publishes no views for a carousel. A slideshow's reel is verified the same way, then linked among the account's reels (a /reel/ link) with its public views; each Instagram post in posts carries as_reel.

Avatars and voices

• •The wizard, in order: create_avatar (blocks until the candidate scenes exist and charges seventy-five credits: one appearance plus four scenes), then any of discard_wizard_scene, generate_wizard_scenes (fifteen credits a scene) and update_wizard_appearance (regenerates the look) before accept_avatar_appearance locks the appearance, then select_avatar_voice, which finishes the wizard. get_avatar_wizard polls and already lists the free voice_options; reroll_preset_voices swaps in three other free picks (direction accepts only deeper or higher). Completion auto-starts pose and angle variations for every kept scene, free on the workspace's first avatar and charged per image after, so do not also call generate_scene_variations on a fresh avatar. The first kept scene becomes the profile image.
• •Voices are curated human recordings matched to the avatar's gender and age, all free (called "preset" in tool names for historical reasons). Each comes labeled by position, Voice 1, Voice 2 and Voice 3, the only name to give it. get_preset_voices then apply_preset_voice changes an existing avatar's voice; browsing, rerolling and applying are free. There are no paid voices: an avatar that already has a premium voice keeps it.
• •update_avatar_settings replaces whole sets: tiktok_usernames, tags and warming_search_terms are overwritten with what you pass (an empty list clears, and warming then falls back to niche terms), and the TikTok accounts must already exist on a workspace device. One exception keeps a new account from being dropped: a TikTok account get_avatar lists with name_pending (its picked username is still being applied) stays linked while its rename runs and for an hour after it lands, whatever set you pass, and the set names it by its picked username; unlink_account removes it. default_video_model takes default to clear back to the workspace routing rules.
• •Scene library: every scene and library frame carries vision-derived content_labels from a fixed vocabulary plus a scene_description; match those against a clip's needs rather than picking by name. generate_scene_frames (one to ten, default three) lands frames inactive; activating one with update_scene_frame auto-generates six pose variations (ninety credits) when it has none, and upload_scene_frame is stored active and does the same. delete_scene_frames also deletes a scene's variations, and the profile frame cannot be deleted; set another first. Replication-generated scenes stay out of the avatar's active library on purpose.
• •edit_image edits any Pamba-hosted image with a text instruction (fifteen credits) and returns a new URL; on a registered frame the result is itself usable as a starting frame. save_scene_variation keeps that result as a variation (original untouched), replace_scene_image points the frame at it instead, losing the original. promote_scene_variation swaps a variation with the scene's reference, so promoting it back undoes the swap.
• •Camera styles are selfie, tripod, tripod_full_body_visible and podcast on the avatar tools; generate_starting_frames spells the full-body style tripod_full_body, and the other spelling falls through to selfie there.
• •import_avatar creates an avatar from a photo URL with gender MALE or FEMALE and a free voice; redesign_avatar applies free-form appearance or voice changes and blocks until they land. track_external_tiktok_account attaches an account you post to from your own phone, for analytics only: posting and warming stay unavailable for it. A free workspace (signup credits only) can connect up to five such accounts; the sixth answers connected_account_limit, and any plan, account seat or credit purchase lifts the limit.
• •Operator-only tools are listed only to Pamba staff. A customer workspace or a connected chat app never sees them, and calling one by name is an unknown tool: the reference-frame tools (create_reference_frame, update_reference_frame, delete_reference_frame), create_social_account, get_account_creation_status, resume_account_creation, generate_image, the writer-engine controls (run_content_engine, push_content_batch, apply_script_revision, set_script_starting_frame, decide_learning_item, set_autonomy_dial, set_batch_share_page, send_writer_chat_message), and the engine's spend bookkeeping (log_llm_usage, and get_llm_usage_summary, which reports the model spend at Pamba's cost). control_stage_run is listed to everyone, but cancelling a run, and retrying some runs, answers operator_only for a customer workspace.

Accounts, seats and devices

• •list_accounts is the inventory of every TikTok, Instagram and Facebook account on the workspace's fleet, including accounts assigned to no avatar (their avatar fields are null), and, listed last, its old accounts: an archived account it held (one of its seats named it, or it posted from it) stays on the list, frozen and with on_device false, after it leaves its phones, as an account a recreation replaced does. Status is posting, track_only or archived; health flags include BANNED, SHADOWBAN_RISK (after the account's first three weeks of tracking), NOT_RECOMMENDED and SUSPENDED.
• •set_account_order saves the order the workspace's Accounts page lists accounts in, for everyone in the workspace, and list_accounts reports each account's position in it. A save replaces the whole order, so moving one account means sending every account in its new place; accounts left out, and accounts added later, follow in the default order (open issues first, then the most viewed, a recreated account counting its seat's views so it keeps the row of the one it replaced), and under a saved order archived accounts are listed last. An empty list goes back to that default.
• •Managed account seats cost one hundred dollars a month each, and every two of a platform get a phone of their own for that platform. A workspace whose owner signed up before the TikTok plus Instagram pair discount ended for new customers keeps it (purchase_account_seats with no seat counts returns bundle_eligible true): every TikTok plus Instagram pair across the subscription prices its second account at fifty dollars, re-priced when seats are added or cancelled. Every other workspace pays one hundred dollars for every seat, and its unpaired_seats is empty. From Monday, November 16, 2026 at midnight Pacific no new seat pairs: bundle_eligible, which says whether the seats bought now pair, is false and unpaired_seats is empty unless Pamba agreed a different price with you, so every seat bought from then on is one hundred dollars a month. The price of the seats you have is on get_seat_billing and each account in the inventory, never bundle_eligible. Seats bought before then keep their pair price for as long as both seats of the pair bill, an account recreated on its seat or a seat the Pamba team moved to another card included; a seat cancelled and bought again is a new seat at one hundred dollars. Until then, for a workspace with the discount, a paid purchase also pairs with seats already on the subscription it raises, the newest one that is active and not set to cancel: purchase_account_seats called with no seat counts returns unpaired_seats, per platform the seats on that subscription with no partner yet, and the next paid purchase pairs up to that many seats of the other platform with them. One Instagram seat next to one unpaired TikTok adds fifty dollars a month, not one hundred; two Instagram seats next to it add one hundred fifty. Only what unpaired_seats lists pairs this way: an account with no seat, a seat on a free-seat grant (free_seats_remaining) or on another subscription, and a seat cancelled with cancel_account_seat (even while it posts until its period ends) pair with nothing, and when no subscription can be raised, the purchase starts a new one where only its own seats pair. Any quantity up to a thousand accounts per checkout can be bought; the seats the phones cannot back yet stay being set up until the team adds phones. While Pamba's phones are short of room for new accounts, purchase_account_seats returns high_demand true and every checkout it creates carries high_demand_notice, whatever its seats: new accounts may take up to 5 days to be created (for purpose connect, the accounts may wait up to 5 days for a phone to sign in on), and the user hears so before paying. Facebook is an add-on to an Instagram account: a flat one hundred dollars a month on top of its Instagram seat that never pairs (Instagram with Facebook is two hundred dollars a month, a TikTok plus Instagram pair with Facebook three hundred, or two hundred fifty with the pair discount). It is rolling out: purchase_account_seats called with no seat counts returns facebook_addon_offer, none or with_new_accounts. facebook_for_instagram adds it to Instagram accounts the workspace already has: only one Pamba created, whose list_accounts row reads facebook_addon_eligible true (facebook_addon_refusal says why not), all paid on one card, and for now each phone takes one, so rows with the same facebook_addon_phone_group are a choice of one. facebook_seats adds it to the order's new Instagram accounts, at most one each and for now one per phone they fill (facebook_addon_unusable_slots, a refusal says how many; an order that also names facebook_for_instagram counts those accounts' phones as taken, so it can take fewer), and an order to connect takes no Facebook. Both go in one order, and purchase_account_seats called with no seat counts lists the accounts that can take it now as facebook_addon_accounts, each with its phone_group. A post scheduled ahead of the purchase (await_new_instagram_account) whose order takes facebook_seats waits for that Facebook account too, so its reel goes to both. The Facebook account is created from its Instagram account, with the same name, birthday and, when Facebook allows, handle, and its Instagram reels cross-post to it. purchase_account_seats returns a checkout URL: a purchase that raises an existing subscription gets Stripe's confirm page raising its quantity with proration, and one that starts a new subscription gets a new checkout. When Stripe cannot list the workspace's seat subscriptions or open the confirm page, the tool answers purchase_unavailable with a message to try again, and nothing is charged or started. A checkout paid by bank transfer completes before its payment clears (usually up to four business days): until then its seats are listed under waiting_for_payment, nothing is created for them, and they move to being_set_up once Stripe confirms the payment; a payment that fails drops them. Do not buy again while seats are waiting for their payment.
• •A purchase never adopts a spare account already sitting on the workspace's phones. Check for spares first: an unassigned spare links to an avatar free with reassign_account and no from_avatar_project_id (TikTok or Instagram; no password, no phone work). The same tool moves an assigned account when from_avatar_project_id names its current avatar; without it an assigned account is never moved. A TikTok or Instagram account can post for several avatars (a Facebook account follows its Instagram account): link_account_to_avatar adds one without taking the account from the others, so a video for a second avatar can go to an account the first one already uses instead of a new purchase. unlink_account is the reverse: it drops one avatar's binding, and an account no other avatar links is a spare again, still signed in on its phone, with its status and history.
• •A bought seat waits for its username before creation starts. suggest_account_usernames returns a checked, currently free idea per waiting seat (names for a waiting order are prepared in the background, so a call usually answers at once; otherwise a few seconds each, so for a large order pass batch_size, for example 8, and call again with exclude set to the names already offered; a batch answers within 90 seconds), check_account_username verifies a pick (availability is a hint, not a reservation), set_account_username saves it and starts that seat's creation, or use_default_name=true creates with a platform default. The account's name goes with the pick: with display_name_from_username=true (the app's default; leave it out to keep TikTok's own) a TikTok account's display name is set to the username it ends up with, in its own edit once the rename lands, which spends TikTok's one display-name change per 7 days; an Instagram account is created under first_name and last_name (30 characters together at most). suggest_account_usernames offers each Instagram seat a name with its username, the linked avatar's or else the username's first name (Claire for wanderwithclaire) with a surname picked for it, and check_account_username shows that name for any Instagram handle. A seat saved without a name is created under the avatar's name (a one-word one with a surname drawn at signup), else its username's, else (no username) a generated one, so pass an offered name back with the username it came with to keep it, and never send a typed handle's name on a seat linked to an avatar. An account made on a phone that already holds an Instagram account, where Instagram asks for no name at signup, gets a name given for it (an offered one sent back included) or its avatar's about three days after it is made, a name changed in the meantime winning, and no name otherwise. Instagram gets the typed name at signup; TikTok assigns its own handle and applies the pick as a rename right after, which spends TikTok's one username change per thirty days; until the rename lands (usually a few minutes) the account stays off list_accounts' accounts, listed under accounts_being_named with its pick, and its seat shows in purchase_account_seats' being_set_up at stage applying_username. A name that fails when applied falls back to close variations, then keeps the platform handle; the account-ready email and Home item then say which pick was not used, and list_accounts carries it as picked_username_not_applied for thirty days or until the account is renamed. Progress shows per account on list_accounts until the account is ready.
• •cancel_account_seat keeps the account posting until the paid period ends, then stops posting and billing, no refund; reinstate_account_seat undoes it before that date at no cost, the seat billing again from the next renewal; a seat subscription cancelled on Stripe's billing page renews with it, its other seats included. Cancelling an Instagram seat cancels its Facebook add-on with it, on the same date, and reinstating it brings the add-on back; a Facebook add-on can be cancelled on its own, and reinstated on its own only while its Instagram seat is kept. An Instagram account with a Facebook add-on can't be recreated for now (has_facebook_addon). Once a workspace holds no seats, the phones its seats came with are signed out and returned to the pool three days after its last seat subscription ends, even while a credit plan runs. When a whole seat subscription ends (its seats cancelled, or Stripe gave up on a failed payment), its accounts stop posting at once but stay on their phone for those three days: get_seat_billing lists them under restore_offers, and restore_account_seats returns a checkout that brings them all back at the price that subscription billed (an account the workspace had paused itself comes back paused); after that, resubscribing can't bring them back. An offer's payment_failed is true when Stripe ended the subscription because its renewal payment didn't go through; Pamba then voids that subscription's unpaid invoices, so the old bill can't be paid for nothing. get_seat_billing shows the next renewal's total per seat. recreate_social_account replaces a seat-funded Instagram account with a new one on the same seat, on its phone unless that phone takes no new accounts, when the new account goes on another of the workspace's phones or a new one (once every 10 days per seat, admins only; the old account keeps counting in the workspace's analytics with nothing new read for it, flagged archived, its videos are not deleted and Pamba keeps its credentials in case they are ever needed; its pending posts move to the new account, or with move_scheduled_posts: false are cancelled when the new account lands and their videos stay to schedule again); get_account_recreation says whether an account can be recreated now and how a recreation is going. A TikTok account cannot be recreated by the workspace (unsupported_platform) unless TikTok banned it and it carries the free replacement_offer below: otherwise only Pamba's team replaces one. While any recreation runs, list_accounts leaves the old account out and lists it under recreations_in_flight.
• •import_social_account brings a TikTok or Instagram account the user already owns onto Pamba: a seat still waiting for an account takes it at the normal seat price, one bought to connect before one bought to create (no_open_seat means buy seats with purchase_account_seats and purpose connect first: the same prices and pair discount, no usernames asked, and each seat waits in being_set_up, purpose connect, until an import fills it, so ten accounts are paid for once and connected one by one, whenever the user is ready), and one of the workspace's phones signs it in with the handle, password and, when it is not the handle, the email or phone the user signs in with. Accounts that sign in only with Google or Apple need a password set in the app first. The sign-in usually stops on a verification code the platform sends the user: poll get_account_import_status every few seconds, and the moment its code_request is set (kind email, sms, authenticator or approve_on_device, the masked destination, wrong_code after a refused code, expires_at) ask the user for the code and pass it to submit_account_import_code; codes expire within minutes, and resend_account_import_code asks the phone to send a new one (after resend_available_at: the apps hold their own resend about a minute). For an email or text code the app also asks on the user's own phone whether the sign-in is theirs, and approving there works with no code. password_rejected true means the app said the password was wrong and sent the code to an address it chose: the user enters it only if the address is theirs, and if it is not, the handle reached someone else's account (cancel_account_import and start again with the right handle, or, once the code wait ends and the import reads needs_customer, retry_account_import with the right username). needs_customer carries a failure the user must fix (a wrong password, a code never given, too many tries, a suspended account, or passkey_required: TikTok only lets the account in with a passkey on the user's own phone, which they remove in TikTok under Settings and privacy, Account, Passkey; or approve_on_device: the app asked them to approve the sign-in on their own phone, so they retry when that phone is with them and approve it there), then retry_account_import with the new password, login or handle (username: a mistyped handle reads account_not_found; a retry after five sign-in attempts hands the import to Pamba's team instead). failure.code wrong_account means the user's login opened another of their accounts, named in opened_username, which the phone has already signed back out: ask whether it is the one they meant, and if so retry_account_import with username set to it (the same login and password), otherwise with the username and login of the account they meant (a reconnect leaves opened_username empty and keeps its handle); with_team means Pamba's team is finishing the sign-in by hand and settles any code it needs with the user directly, or hands it back as needs_customer when only the user can move it on. cancel_account_import stops an import and frees its seat; a reconnect is refused (reconnect_not_cancellable) while its account still fills its seat, and Pamba closes one 3 days after its seat ended, when the seat can no longer be bought back. Pamba changes nothing on an imported account by itself (no AI-comment filter, no AI-creator label, no rename); it warms like every account on a phone. If TikTok or Instagram later signs it out of its phone (a password change, or the app ending its session), its import reopens as needs_customer with failure.code signed_out and the user is emailed: until retry_account_import reconnects it (the stored password unless the user gives a new one, then the code the app sends, as on the first connect) it can't post or warm, schedule_post, schedule_instagram_post, schedule_slideshow_post, post_instagram_story and post_tiktok_story refuse it with account_needs_reconnect, its scheduled posts fail with that code (retry them once it is reconnected), and list_announcements leads with a warning (kind warning, label Signed out) naming it. An import connects only the account it names: Instagram also signs in every account that shares a Meta Accounts Center with it, and Pamba never lists, warms or posts from those; connecting one takes its own seat and import.
• •A workspace that only buys accounts and posts its own videos runs this order, and nothing in it spends credits: list_accounts to rule out a spare, purchase_account_seats (pass link_avatar_project_id when the account is for an avatar) and the person pays at the checkout URL, suggest_account_usernames then set_account_username per seat (creation starts only once a seat has a name), list_accounts until the account reads posting, then create_draft_project, set_edited_video and schedule_post with the new username (see Scheduling and posting). To queue the post before the account exists, the project needs the avatar the purchase links to, and schedule_post takes await_new_account=true in place of a username.
• •follow_accounts has a TikTok or Instagram account on a Pamba phone follow a list of usernames or profile links. An account's lists keep to a daily limit, because TikTok and Instagram can flag an account that follows too much: none in its first seven days on a Pamba phone (counted from its first warming session or follow list), so the first follow lands once the account is a week old, then one a day at most, however old the account. Warming's own follows are separate and do not count toward it. get_account_follows reports the limit today as daily_limit (with starts_at_utc while a new account's first days last). A list waits for the limit, and a waiting list's next session time says when it continues. The phone follows one account per session, at a different time each day between 8 AM and 1 AM Pacific, around the account's posts and warming, and at most fifty wait at once; a session that followed no one (already followed, not found) leaves the day's follow for the next session, at least three hours later (up to half an hour more). A request while a list is running joins it (up to a hundred accounts on one list in all; a list being stopped takes nothing new, so the request opens the next list), and a new list starts no sooner than three hours after the account's last session. A profile the account already follows is left alone, and the account never follows itself. It runs in the background: get_account_follows shows the running list with each account's outcome (followed, requested for a private account, already_following, not_found, failed (where a mistyped or deleted username usually lands, with a reason to check it), cancelled when a stop reached it first, or skipped when the request failed before reaching it), and cancel_account_follows stops what is still waiting; a session already on the phone finishes its one account first.
• •delete_account_posts deletes published posts from an account on a Pamba phone, videos and slideshows alike (TikTok videos and photo posts; Instagram reels, carousels and pictures), up to twenty per request and fifty waiting per account: it removes them from the platform itself, so confirm the exact posts first. Name each by its post_id or by its link: a project's posted_tiktok_video_url or posted_instagram_video_url deletes that project's post, and a slideshow post's posted link deletes that slideshow post. list_account_posts lists the account's posts newest first with each one's post_id, its kind (video, slideshow or picture) and its deletion state (pending, deleting, deleted, not_found when the post was already gone, not_confirmed when the phone could not prove the post on screen was the one asked for and deleted nothing, delete_unconfirmed when the phone may have deleted it but its link did not show it gone (the delete was confirmed, or the post was in a session nobody heard back from), which is not final: Pamba checks the account's own listing about fifteen minutes after the session and settles the post deleted once the account no longer lists it, or failed when it still shows it (a post the listing cannot see, such as an Only-you TikTok post or an Instagram reel off the profile grid, is settled by Pamba's team instead), failed, cancelled or skipped). A post the phone reported deleted that the account still lists on both checks turns failed too. The phone deletes five per session, around the account's posts and warming; TikTok and Instagram keep a deleted post 30 days in Recently deleted, where only someone on the phone can restore it. With post_ids (ids or links) it returns only those posts, and still returns a deleted post the platform no longer lists, with its state. cancel_post_deletion stops what is still waiting; a session already on the phone finishes its own few first. In the app it is Delete from TikTok or Delete from Instagram on a posted post (the project's More menu, and the post's row and calendar card on the Schedule page, slideshow posts included).
• •list_comments lists the comments on the workspace's own TikTok and Instagram videos from the last sixty days (only the accounts it pays for, on its Pamba phones or under a live seat; an account it only tracks for analytics has none), each top-level comment with its replies and its video: newest thread first, or with sort the most liked first (most_liked) or in the order TikTok or Instagram itself ranks the video's comments as of Pamba's last read (top). Comments are read about every fifteen minutes once a video's comment count grows, so a new one shows within about an hour; checked_at is when Pamba last checked the accounts' videos for new comments, synced_at when it last read one of the listed videos. hidden_by_platform marks a comment Instagram hides under "See hidden comments", and the replies under it: replying to it, liking, pinning or deleting it is refused (comment_hidden), since the phones never find it there, and comment automations skip it. questions_only=true keeps the comments that ask the creator something or ask for something the video offered, mine=true keeps the threads the workspace's accounts took part in, and q searches the text, the authors and the replies. about_ai marks a comment that says or asks whether the video or the person in it is AI or not real, and each TikTok account on the workspace's phones carries ai_comment_block_state and auto_block_ai_comments: when such comments sit on an account whose filter is failed, or off with auto_block_ai_comments true (false means the user allowed AI comments), update_account_profile with disable_ai_comments and auto_block_ai_comments both true turns on TikTok's filter for them, as the Comments tab's Block AI comments line does. list_comment_videos gives the same comments per video, newest activity first, with how many match and how many are questions, for going through them one video at a time; it also lists every post from the last seven days before its first comment, so the account can leave that first comment with comment_on_video. reply_to_comment answers a top-level comment and comment_on_video adds a new comment to one of the workspace's own videos, from any of the workspace's accounts on that platform (account, the video's own by default); either is typed within minutes on that account's phone, or at scheduled_for (an ISO-8601 time with its offset, from a minute to thirty days ahead), so only an account on the workspace's phones can send (the accounts list says which can_reply), up to one hundred fifty characters on TikTok and two thousand two hundred on Instagram, and at most thirty in any rolling day per account. On TikTok an @username in the text is picked from TikTok's own list as the phone types it, so it posts as a tappable mention showing that account's display name; a username TikTok does not offer fails the comment unsent (failed, with a reason naming it), since typed as it is it would not link. Instagram links a typed @username by itself. TikTok and Instagram lock an account that comments on other accounts' videos too early or too often for suspicious activity, so on another account's video (another of the workspace's), an account Pamba created comments only after its first seven days (status new_account), and any account at most the workspace's cross_account_per_day in any rolling day (one unless the Pamba team raised it; cross_account_daily_limit); each account in accounts that can reply carries cross_account_blocked_reason and cross_account_available_at while it is held, and its own videos are never held. Two accounts signed in on the same phone never comment on each other's videos, nor reply to or like a comment on them or one the other wrote (same_phone, at any time); each account's phone_mates names the accounts on its phone. A comment, reply or like that reaches the phone anyway, because the two came to share a phone after it was asked for, is cancelled before it is sent, its status_detail saying why. Every limit counts at the time the comment goes out, against the account's comments before and after it, so a refusal's available_at passed as scheduled_for queues it, and a workspace spreads comments across days by scheduling them. What an account is asked to do now on one video, comments, replies, likes, pins and deletes alike, goes out together in one phone session, as a creator does it in one sitting: each request waits two minutes for the next, the run goes out at most ten minutes after its first, and a session takes up to ten; requests given scheduled_for go out at their own times, so the same time groups them and different times keep them apart. comment_on_video with pin true has an Instagram reel's own account pin the new comment once it is live. like_comment likes a top-level comment from one of the workspace's accounts (the video's own by default on its own videos) and pin_comment pins one on the workspace's own Instagram reel from the reel's account (Instagram keeps up to two pinned comments per post; TikTok no longer lets creators pin comments, pin_not_available), and delete_comment deletes a comment or a reply from the workspace's own TikTok video or Instagram reel through the video's own account (only a video's owner can delete other people's comments on it, so never on a video the workspace added, delete_not_allowed; nor a comment with no words of their own (only a sticker, photo, GIF, @mentions or punctuation), or a reply under such a comment, not_deletable; it cannot be undone, a comment's replies go with it, it withdraws the workspace's queued replies, likes and pins of the comment and deletes of its replies, and the comment takes no more while the delete is on its way, comment_being_deleted, also the answer for a reply whose comment is being deleted; a reply's delete shows in its thread's reply_actions, and once the phone saw the comment gone list_comments no longer lists it); all three are typed on the phone like a comment, likes and pins now or at scheduled_for and a delete now, thirty a day per account together, never counted against the comment limits; a like from an account that does not own the video (another of the workspace's accounts' videos) keeps to the workspace's cross_account_likes_per_day in any rolling day (one unless the Pamba team raised it; cross_account_daily_limit, with available_at), each account in accounts carrying cross_account_like_blocked_reason and cross_account_like_available_at while it is held, so likes in bulk are spread across days by giving each its scheduled_for; and list_comments shows them in each thread's actions (list_outgoing_comments lists them with action like, pin or delete; it lists comments alone by default). To reply in advance, pass reply_to_comment the outgoing id of one of the workspace's own comments that is not live yet: the reply waits for it, and up to three replies can wait behind one comment, going out one at a time in the order they were asked for, each once the one before it is live and fifteen to forty-five minutes after it was sent (reply_to_outgoing_id names the comment it answers and waiting_for_id the one it waits for). Once a comment has replies in advance behind it (on their way or live), another reply to it, by its outgoing id or by its comment id once it is live, joins the end of that line. If a comment before them fails, is cancelled or still does not show two days after it was sent, the replies behind it are cancelled too; a fourth reply answers chain_full, and a reply to a comment that will not go live answers parent_not_live. list_outgoing_comments follows each one: queued, sending, posted (the phone sent it, or Pamba lost the phone's answer; a read of the video settles which), live once a read of the video shows it, not_visible when no read has six hours later, or failed; cancel_outgoing_comment withdraws one while it is still queued, with the replies waiting behind it.
• •create_comment_automation answers comments by direct message: when someone comments one of its keywords on one of the workspace's TikTok or Instagram videos (its accounts, or with all_accounts every account on the workspace's phones, those added later included; every post), the account's phone reaches them from their comment (it opens the post, finds the comment and taps their name) and sends them dm_text, a first message with no link that asks them to reply (a link in it is refused, link_in_first_message), once per person; once they reply yes (or anything that says they want it), within seven days, the phone sends follow_up_text, the message with the link (required, follow_up_required; a few words with the link: one that is only a link is refused). Instagram shows a link to someone who does not follow the account only after they reply, and waiting for a reply keeps the account from looking like spam. Then, in the same visit, replies under the comment with one of its reply_variants, or fallback_reply when the person's settings refuse the message (a reply counts toward the account's thirty comments a day; one the comment queue refuses is left out). A keyword matches as whole words, ignoring capitals, accents, punctuation and emoji (match_mode exact: the comment is the word and nothing else), and {username} in the message or a reply becomes the commenter's @handle. Each account sends up to twenty first messages a day, spread out through the day (list_comment_automations reports the limit as daily_dm_limit; the messages with the link do not count toward it), on TikTok the oldest comment first and on Instagram each post's newest waiting comment first, the posts taking turns (a comment the phone cannot find ends not_sent, comment_not_found, and does not count toward the limit); a TikTok message goes out as one paragraph. It is on at once (enabled false: created off) and also answers matching comments from the last seven days unless answer_recent_comments is false; no automation answers a comment older than seven days, or one by the workspace's own accounts. update_comment_automation changes any field and turns it off or on (enabled); turned back on, or set to answer other comments (its keywords, match mode or accounts), it answers only comments made from then on, and a new dm_text or follow_up_text goes to the messages and people still waiting too; while it is off, the links of people who said yes wait as well. An automation that is off can have no follow_up_text (one saved before the two messages whose message had no link to send second): turning it on needs follow_up_text. Two automations that are on cannot share a keyword on one account (keyword_in_use), and a comment that says the words of two of them gets one message, the older automation's. list_comment_automations lists them with their last seven days and the accounts that can send; list_comment_automation_activity lists every comment one answered and its message's status (queued with next_attempt_at while it waits for the daily limit or the account's next session, sending, sent, not_sent with why, skipped for someone already messaged or, on Instagram, a commenter whose profile is private (no message is tried, it does not count toward daily_dm_limit, and the comment gets fallback_reply), or a comment Instagram hides (comment_hidden: the phone never finds it, so nothing is sent), cancelled when the account's seat ended) and, once the first message went out, where the link stands (follow_up_status: waiting for their yes, sent, not_sent, no_reply, cancelled, with follow_up_detail; replied_at is their yes), and list_comments marks each answered comment in its thread's automations. delete_comment_automation deletes one; its waiting messages and links are not sent, and what it sent still counts toward the account's daily limit.
• •update_account_profile edits display name, handle, picture and bio on the hosting phone. Bios are capped at one hundred sixty characters on TikTok and one hundred fifty on Instagram; a URL typed into a bio is plain text, the link field is separate and untouched. On TikTok the phone picks each @handle in a bio from TikTok's mention suggestions, so it lands as a tappable mention that TikTok shows as @ and that account's display name; a handle TikTok offers no account for fails the bio field with the error code bio_mention_not_found, and a mention the phone could not show links the account asked for (a pick on a suggestion whose caption TikTok cut short, or a bio TikTok already held whose mentions are not drawn as links) with bio_mention_unconfirmed; an email address stays text. list_accounts reports each account's current bio, whichever is newer of the one Pamba last set and the one last read off the phone (on TikTok, a read that is the bio Pamba set with each mention shown as @ and a display name still reports the bio as set, with the handles an edit sends again); every linked account's bio is read once a day, so an in-app change shows within a day. Only the fields an edit asked for count as outcomes: a bio-only edit reports one operation, not three. On TikTok the phone gets time for each field and each @handle an edit asks for; a field it had no time left to start comes back not applied with the error code field_out_of_time, beside the fields it did apply. An Instagram bio with a link, put on an account Pamba created less than seven days ago, still goes through, and the result carries a warning: Instagram often restricts link sharing on accounts that add a link this early. A queued answer, from this tool or from enable_instagram_ai_creator and disable_instagram_ai_creator, carries the edit's job_id, which get_account_profile_edit reads to its outcome.
• •update_account_profile also switches an Instagram account between personal and creator with instagram_account_type, sets its profile category with instagram_category (any case, one of Digital creator, Artist, Musician/band, Blogger, Clothing (Brand), Community, Education, Entrepreneur, Health/beauty, Writer, Personal blog, Product/service, Gamer, Restaurant, "Beauty, cosmetic & personal care", Grocery Store, Photographer, Shopping & retail, Reel creator, Gaming video creator, Social Media Agency, Camera/photo, Computer Company, Makeup Artist or Creator) and whether the profile shows it with instagram_show_category, sent in a call of their own with no other field: the account type is its own job on the phone, answered queued with a job_id that get_account_profile_edit reads (its kind is instagram_account_type, its fields account type, category and show category). Pamba never switches an account to business, since Business accounts can't use most of Instagram's licensed music: business is refused with the error code instagram_account_type_invalid, and an account that is a Business account already is never switched to creator (instagram_account_business) but can go to personal or change its category; when the phone finds a Business account Pamba had not read yet, the job fails with ig_account_business and nothing changes. creator on an account that is creator or business while its switch to personal still waits for the phone, never yet sent to it, withdraws that switch instead: the call answers withdrawn with withdrawn_job_ids and the account stays as it is (a category or display in the same call is queued as its own change); a switch to personal already sent to the phone is refused with change_in_progress, and on a creator account after an earlier type switch of it ended unread the call is queued over the waiting switch instead (it answers queued), for the phone to read the type the account has. A personal account, or one list_accounts gives no instagram_account_type for, switched to creator takes the category Digital creator unless the call (or a change already queued) names one, and a hidden display unless it names one; an account that is creator or business already changes only the fields the call names. A category or its display alone needs an account that is creator or business, or has a switch to creator queued (one Pamba knows is personal, or with a switch to personal queued, is refused with the error code instagram_account_not_professional; one whose type Pamba has not read goes to the phone, whose job fails with ig_account_not_professional when the account is personal), a category Pamba does not offer answers instagram_category_invalid with the list, and a call for TikTok is refused, since TikTok's only switch is to a Business account, which limits it to TikTok's commercial music library. Switching makes the profile public, and Instagram also turns on stricter filtering for professional accounts, which hides more comments and message requests; going back to personal turns its insights off. list_accounts reports each Instagram account's instagram_account_type, instagram_category and instagram_show_category, the newer of what Pamba last set and what the hourly analytics refresh last read. Instagram trial reels need a creator or business account with at least two hundred followers.
• •update_account_profile also keeps a Creator or Business Instagram account's audience in chosen countries with instagram_audience_countries, in a call of its own: us_only, tier1 (the US, Canada, the UK, Australia, New Zealand, Ireland, Singapore and Western Europe), tier1_tier2 (adds Central, Southern and Baltic Europe, Japan, South Korea, Israel, the Gulf, Hong Kong and Taiwan) or all to clear it. It works through Instagram's Minimum age setting: outside the chosen countries Instagram shows the account only to people it knows are 25 or older, so it does not block a country. A personal account is refused with instagram_account_not_professional. The change is its own job on the phone, answered queued with a job_id that get_account_profile_edit reads (its kind is instagram_audience_countries, its field minimum_age, whose applied value is the choice the phone read back); it takes a few minutes for us_only. Instagram takes only about 15 such changes a day on an account, so a bigger change continues by itself the next day (tier1_tier2 from scratch takes three days); between runs the job reads queued, and a choice sent meanwhile joins it. list_accounts reports the account's instagram_audience_countries, custom when it was set by hand in Instagram, and none after a change that failed partway, until the next change reads the page again.
• •Pamba-created TikTok accounts block AI comments automatically once linked to an avatar: an account linked at creation gets the filter after its first post is live, one linked later gets it queued at link time, and an unassigned account is never filtered. disable_ai_comments turns it off per account. get_avatar reports the state per account as applied, queued, scheduled, failed or off, and null when the account is not on one of the workspace's phones.
• •enable_instagram_ai_creator and disable_instagram_ai_creator turn the label on and off; each leaves a label already where it asks untouched, and a change still queued for a busy phone takes the newest call's direction. While the phone is applying one direction, a call for the other is refused with change_in_progress; call again once it settles. list_accounts reports each Instagram account's ai_creator_label_state: turning_on or turning_off while the phone is queued or running to change it, then on or off, failed when the newest attempt to turn it on failed, or turn_off_failed when the newest attempt to turn it off failed (the label is still on); each TikTok account carries its AI-comment filter as ai_comment_block_state. Both are empty for an account on none of the workspace's phones.
• •Warming (human-like browsing on the account's phone, so it reads as a real person before and between posts) is always on for every device-hosted account and cannot be turned off from the tools; Pamba sets its pace, which is not configurable. Every account warms under its own config (get_account_warming_config, set_account_warming_search_terms), whichever avatars link it. An avatar's config (get_warming_config, terms via update_avatar_settings) is the one its accounts start from: an edit there is written onto every account the avatar links, shared ones included, and an account linked to its first avatar takes that avatar's settings. A linked account warms while every link of it posts and at least one linking avatar is active. Search terms steer what warming looks for. Terms cap at twenty-five of eighty characters, and a save carrying a term with "porn" is refused with a message naming it, since TikTok and Instagram show no results for it; without explicit terms, sessions fall back to terms generated from the workspace niche (search_terms_source niche), while an empty list saved with use_niche_terms false is kept as the owner's own and its sessions search nothing (search_terms_source none; use_niche_terms true with an empty list goes back to the niche terms). A term TikTok answers with its guidelines page on the phone leaves the account's terms, the terms of the avatars linking it and of every account those avatars link, and the niche terms by itself, and the workspace gets a Home item at once and an email about two hours later; a "No results found" on either app removes nothing. The workspace's defaults, which a new avatar and a new TikTok or Instagram account with no avatar start with (an account added to an avatar takes the avatar's setting), are update_workspace_settings warming_searches and warming_follows (list_workspaces reports both); either needs apply_warming_to_existing_accounts: true also writes it onto every existing account and avatar, false changes the default for new ones only, and without it the call changes nothing and answers needs_choice. Warming keeps running either way. set_account_warming_switches sets one account's own switches: follows_enabled false and its sessions follow no one, searches_enabled false and they never search while its terms are kept for when searches are back on; get_account_warming_config reports both. update_avatar_settings with warming_searches_enabled or warming_follows_enabled sets them for every account an avatar links, shared ones included, and for an account it links later that no other avatar links; get_warming_config reports what the avatar's last edit set, as it does its terms. An Instagram account's Cross-post reels to Facebook switch rides the same config and is set two ways, with no workspace default (a new account starts on): set_account_facebook_cross_posting for one account, update_avatar_settings' facebook_cross_post_enabled for an avatar's Instagram accounts; get_account_warming_config and get_warming_config report it as facebook_cross_post_enabled. cancel_warming_session works only on pending sessions. get_account_activity is one feed per account of what the phone did for it, newest first: warming sessions (status, length, videos watched, likes, comment reads, creators followed, the search term, a few sample screenshot URLs), daily TikTok health checks, posts, profile edits, finished follow requests and post deletions, and the comments and replies the account posted with every screenshot the phone took of each; pass a page's next_before back as before to read further back, and an empty next_before ends the feed.
• •Every device-held linked TikTok account gets one account-health check a day. Findings open incidents (ACCOUNT_WARNING, VIDEO_REMOVED, VIDEO_NOT_RECOMMENDED), shown as health flags and cards and surfaced on Home, and emailed to the workspace about two hours later; these kinds never pause the account. get_tiktok_account_health returns the latest screenshots and open issues with each appeal's progress; request_tiktok_appeal records the decision to appeal a removed or restricted video or an account warning, one appeal per issue, and nothing is appealed without it unless the account's auto-appeal is on (set_tiktok_auto_appeal, reported by get_tiktok_account_health as auto_appeal): then every open issue is appealed when it goes on, and each new one as the daily check finds it. The account's phone then files the appeal itself, submitting only once a TikTok screen prints that video's posted time (a video it cannot pin down is filed by the Pamba team by hand; an ACCOUNT_WARNING is appealed through the video TikTok removed with it: appealing it also appeals the one removed video the same daily check found, and one verdict decides both; with none or several, the Pamba team files it by hand), and reads TikTok's verdict off the account's notifications once a day until it answers: appeal_verdict APPROVED closes the issue as restored, REJECTED keeps it open. An appeal TikTok has not answered four days after filing sends the phone back to the video to read TikTok's answer on its page. A removed video reappearing also closes its issue and approves its appeal, a video the phone finds no longer restricted when it goes to file closes its issue as restored, other issues close after two clean daily checks, except one whose appeal is still being filed or still waits for TikTok's verdict (up to 21 days after filing). A video the workspace deletes through Pamba (delete_account_posts) takes the open issues that predate the deletion with it once the deletion confirms it gone (closed as DELETED): its appeal stops wherever it stood, and nothing is filed, read or rechecked for it. An ACCOUNT_WARNING TikTok gave for that video stays open; if its appeal was not filed yet, the Pamba team checks whether TikTok still takes it. When Pamba replaces an account with a new one, every open issue of the old account closes (closed_by MANUAL) and its appeals stop. close_account_incident dismisses an issue for good.
• •Accounts suspended by Meta open a SUSPENDED incident that stops Pamba's warming, daily reads and posting on the account until the incident is closed with close_account_incident, only after the account is verified restored: its warming sessions are cancelled, its pending posts fail saying why, and every new post, retry, profile edit, comment or other request on it is refused, as on an account TikTok or Instagram banned (below). A suspended Instagram account is signed out of its phone, so Meta's page stops blocking the phone's other accounts: it stays listed on its phone and is signed back in once its incident is closed. Its phone then takes no new Instagram account (a banned account's phone takes no new account of its platform either), so recreate_social_account refuses the suspended or banned account itself with phone_on_hold (Pamba's team replaces it on another phone) and makes the new account of any other Instagram account on that phone on another phone: another of the workspace's phones with room, else a new one, the old account staying where it is. One exception: an Instagram account suspended by Meta, or asked by Instagram for identity verification with a video selfie (an IDENTITY_VERIFICATION health flag, its incident's error_code ig_identity_verification), after its first day can be replaced for free, and so can a TikTok account TikTok banned after its first day (its new account goes on a phone that never hosted an account). get_account_recreation and list_accounts report it as replacement_offer, and recreate_social_account then takes it with no cooldown and makes the new account on a new phone (suggest_account_usernames with replacing_platform and replacing_username offers free usernames for it; a seat gets one free replacement a month, and without an offer the account is the team's to replace; posts_start_after_days starts the moved posts at least a few days after the new account is ready, each at its own time of day). An account Pamba confirmed TikTok or Instagram banned carries a BANNED health flag and incident (a TikTok ban about an hour after Pamba finds it, before which its work waits): it takes nothing more, its pending posts fail saying why and every new post, retry, profile edit, comment or other request on it is refused, so schedule its videos again on another account or the new one; a TikTok one past its first day carries that free replacement_offer for the user to take, otherwise Pamba replaces it with a new account on its seat at no extra cost, and only Pamba closes the incident (close_account_incident answers pamba_closes), with closed_by RESTORED when the account comes back or MANUAL once a new account replaces it. While any account is banned, list_announcements leads with a warning (kind warning, label Banned) naming them, the strip shown across the top of the app; a Signed out warning about accounts to reconnect comes after it. A ban outranks a SUSPENDED incident on the same account: don't suggest an appeal or close the suspension. Instagram can also restrict one feature of an account that keeps working ("You can't share links" until a date): the phone closes Instagram's restriction page and Pamba opens a FEATURE_RESTRICTED incident whose detail carries the restriction and its ends_on. It never pauses posting or warming, shows through its end date and closes the day after. reconcile_tiktok_rename repairs an account renamed on TikTok itself, moving the avatar's active account and all forward-looking drafts, plan and scheduling to the new handle; old posts stay under the old handle.

Ideas, discover and research

• •list_ideas and get_idea read the library (twenty-five per page, sortable by date, views and engagement ratios); every hub video carries a replication feasibility_verdict (pass, fail, unjudged) with the judge's reason, and exclude_low_feasibility=true hides failed ones while unjudged stay visible. get_idea lists required_brand_assets with in_library per kind, which tells you before replicating whether an upload is needed. A workspace holds up to one hundred ideas.
• •Research needs an active subscription, a credit plan or account seats; free workspaces browse but every addition (create_idea, branch_idea, add_tracked_accounts) answers payment_required. generate_script_from_idea also runs for a workspace holding credits it was given or bought, while any are left. Saving a video that is already analyzed is allowed on every plan. The inspiration-account cap scales with the plan tier. Tracking an account feeds its breakout videos into the create page's For You blend once the feasibility judge passes them; remove_tracked_account cannot remove an account linked to one of the workspace's avatars.
• •search_tracked_videos searches the workspace's own accounts by default (avatar-linked, signed in on its phones, or with a post it scheduled); pass include_research_accounts=true for the inspiration accounts. Ground recommendations there rather than in memory. generate_script_from_idea writes a fresh script, thirty to forty-five seconds unless the idea asks for another length and in the idea's language, and does not save it; save_idea_script or create_video_project does.
• •Discover: get_trending_videos (by default only avatar-replicable content, screened for promotion carriage; include_unproducible=true reveals everything), get_niche_feed (returns niche_status pending or no_niche for an empty feed), search_viral_videos (paid only; falls through to a live TikTok search when the corpus is thin, with a daily budget reported as live_searches_remaining_today), get_breakout_creators. To act: use_discover_video puts a video on the Ideas board (idempotent), bookmark_discover_video saves it, track_video_author adds the creator as an inspiration account. browse_picker_videos is the create page's shelf; a row whose video_url is null is an un-enriched Discover row, so prepare it with use_discover_video first.

Content review, knowledge and automation

• •Campaigns are autonomous cycles that plan, write, generate and queue posts for their member avatar and account bindings on a schedule, gated by review windows unless auto-approve is on. Schedules run in the workspace timezone and plans are ready for review by nine in the morning local time by default. Every workspace has a Default campaign that owns unassigned members and cannot be deleted; create_campaign copies its schedule and starts disabled with no members; assign_avatar_to_campaign is a complete move. enable_campaign spends credits on every future cycle until disable_campaign, and both need an active subscription on the workspace owner. run_campaign_now plans the gap days up to the next scheduled cycle without stealing that cycle's window.
• •preview_content_plan is a dry run that creates nothing; plan_content_batch plans (or re-plans an unapproved batch via batch_id); get_content_plan explains, per avatar, why each got its slots; edit_plan_slots moves, removes, swaps, adds or pauses. approve_content_plan or approve_all_content_plans is where credit spend starts, and approval is refused while the plan has error-severity violations. set_mix_targets replaces all targets, so read get_content_strategy first. delete_plan only removes a planning or brief-pending batch and never touches projects.
• •push_content_batch is safe by default: without push_now=true or a preflight_id it only runs the preflight. With push_now, each pushed approved script becomes a fully automated project that generates and schedules, and spends video credits. decide_content_script with a batch_id and no script_id approves every undecided script; require_green=true skips scripts with failing checks. send_writer_chat_message answers asynchronously: read the thread with get_content_script (view=writer_chat), then apply_script_revision.
• •Knowledge base: patterns (a pattern's category is its canonical format; lipsync patterns are classification-only, the planner never allocates them), principles, playbooks and term lists (tiered pools of real terms the writer draws from: proven, testing and exploratory tiers are writer-eligible, candidate and risk_flagged terms are not). The writer's references are chosen automatically at claim time from pattern links; curate them with manage_pattern_link and preview with get_pattern_references.
• •get_studio_overview is the one read for the Drafts and Videos tabs. Always pass statuses: drafts is the Drafts population (concept-stage items awaiting generation), the others (queue, failed, approved, scheduled, posted, archived) are the Videos tab's filter, and posted history and archived projects are reachable only here. Omitting statuses returns the classic queue capped at fifty with drafts sorted below everything else, which hides them on a busy workspace. sort (newest, oldest, posttime, views) decides which items make the window and requires statuses; views puts the items with the most views across their TikTok and Instagram posts first, with each item's count in views, an item with no views yet carries no views, and other sorts never send it (statuses=posted&sort=views lists your top videos); a typo in either errors rather than defaulting. view=home also returns the getting-live setup, where ready_to_post (not account_connected) says whether posting would actually work.

Analytics

• •get_analytics_summary (days one to three hundred sixty-five, default thirty; platform tiktok, instagram or facebook, default TikTok; optional avatar) gives views and followers per platform, broken down by up to twenty avatars. An inactive avatar's accounts stay in it as an archived account does, marked archived: their old views keep counting and nothing new is read for them until the avatar is active again. search_tracked_videos is per-video TikTok performance, list_social_videos per-video Instagram and Facebook performance, get_tracked_account_metrics an account's lifetime totals and cadence.
• •An Instagram slideshow or picture (media_kind photo) has no public view count: Instagram shows its views only to the account that posted it, so the account's Pamba phone reads them off the post's own insights, about three days after posting and a final time about four weeks after, and views_read_at says when. Every post list_social_videos, search_tracked_videos and get_post_analytics return carries views_source, where its views come from: public (the count the platform shows publicly, read by Pamba's hourly scrape: every TikTok and Facebook post, an Instagram reel, a slideshow posted as one included) or insights (read off the post's insights by the account's phone: every other slideshow, and every picture). An insights post with no views_read_at has not been read yet: its views, 0 in a list and null on get_post_analytics, mean not known yet rather than zero views (the app shows a ? there). Its likes and comments come from the hourly read like a reel's.
• •get_post_analytics (platform tiktok or instagram, video_id the TikTok video id or the Instagram shortcode) is one post's page: its counts with their daily history and its audience (gender, age from 18 (no age under 18 is ever served), top locations, new vs returning viewers, followers vs not, watch time, finish rate, and its retention curve: the percent still watching at each second, with TikTok's average share watched and the moment most viewers stopped, or Instagram's skip rate) and its engagement (the likes, comments, shares, saves and Instagram's reposts as the app counts them; when in the video viewers liked it, at each second, on the app's own scale: TikTok's chart runs to 100% at its most liked moment, Instagram's gives each moment's share of the likes; TikTok's most liked moment and the words its comments use most; the like, comment, share, save and repost rates, Instagram's own, or for TikTok, which prints none, the read's counts over its views with rates_from_counts true), and retention_moments, the percent still watching at 5 s, 10 s, halfway and the end with the skip rate, as list_post_analytics gives them, read by the account's phone off TikTok's Video analytics or Instagram's reel insights, with the screenshots behind each read. A post is first read once it has 200 views, at any age (or three days after posting with 100), and again as it passes 1,000, 5,000, 10,000 views and every doubling after, at most ten posts a day per account; next_read says when. list_post_analytics (platform all, tiktok or instagram, days 1-365 (default 30), sort newest, retention_5s, retention_end, skip_rate, like_rate, comment_rate, share_rate or save_rate, limit 1-100) lists the posts with a read, each read at a glance: the percent still watching at 5 s, 10 s, halfway and at the end (one second before it on a post up to 20 seconds long, the curve's second-to-last measured point on a longer one, since TikTok's chart falls to about zero in its last second), the skip rate (the app's own where it prints one, Instagram; otherwise the share gone in the first 3 seconds of the curve, with skip_rate_from_curve true), the share watched and the finish rate, and its engagement: the likes, comments, shares, saves and (Instagram) reposts the read counted, the share of viewers who did each (Instagram's own rates; TikTok prints none, so there each is the read's count over its views, with rates_from_counts true) and TikTok's most liked moment. Each post also carries the listing's own likes, comments, shares and saves. These are the Retention and Engagement columns of All Videos. Each row's retention is left empty there (get_post_analytics has the curve), and total says how many matched. get_account_audience is the account's own viewers (TikTok Studio, 28 days, read once the account has a post from the last 60 days) and followers breakdowns, read on its daily visit, with its latest daily health checks' screenshots; both apps show a followers breakdown only from 100 followers. get_audience_summary (segment viewers or followers, platform all, tiktok or instagram) is the workspace's audience across all its accounts on Pamba phones, each account counted by its size: viewers are TikTok Studio's (28 days) plus Instagram reels read in the last 28 days, followers are each app's followers breakdown; it lists the accounts folded in and when each was read, and is rebuilt as reads land. Each audience read and rollup these four tools return carries sample: how many people its numbers come from (viewers, or the views when the app printed no viewers, or followers on a followers read), the size from which such numbers are enough, and whether this read falls short of it, as most of a post's early reads and a small account's audience do. A read that falls short is low confidence: its shares, retention and rates can still move a lot as more people watch or follow, and the app marks an account's or the workspace's audience Low sample size (never a single post). A read with no count known carries no sample. These are the platforms' own estimates, as printed.
• •The numbers are snapshots and the surfaces end their windows and total differently, so do not expect them to reconcile to the view. The summary tool and the app's dashboard read the same daily rows, each dated on its workspace's calendar; the summary ends its window on today in UTC, the dashboard on today in the viewer's timezone. get_tracked_account_metrics dates its per-day series on the workspace's calendar too. The dashboard sums daily deltas, while per-account metrics sum lifetime view counts. A TikTok video's first snapshot carries everything it earned before Pamba first read it, and those counts land on the day the video was posted when Pamba first read it within 90 days of posting; a video it starts tracking later adds only its later growth. On every platform, the views a reading finds two or more days after a post's previous one (an account not read while its avatar was inactive, a scrape outage) are spread evenly over those days rather than landing on the day the reads resumed. Accounts assigned to a deactivated avatar keep posting and accruing views but do not appear in avatar-scoped dashboards. A TikTok rename keeps one account row: the hourly refresh follows the account through its stable id (or one of its own videos) and moves the row to the new handle, so both handles' videos stay together; a rename it cannot follow leaves the old row failing until it is reconciled by hand. Instagram's headline views are the play count the app shows, and the first observation of a reel attributes its whole lifetime to one day.

Workspace, members, onboarding and support

• •update_workspace_settings is admins only; setting website_url re-scrapes the site and replaces the stored company profile (and the niche, unless it was hand-written). update_company_profile edits the brief field by field and leaves the others alone; an empty string clears a field. Name, niche and profile feed the model's own context, from the next connection onward. list_workspaces returns at most twenty workspaces and list_workspace_members one hundred.
• •create_workspace with website_url sets a workspace up like an onboarded one in one call (brief, name, media library, niche feed, three matched avatars; the site read takes about thirty seconds); pass niche_description, what_they_do and name instead when there is no site (without what_they_do the brand stays unconfirmed and the result says how to finish it). Set up either way, the new workspace takes the goal of the workspace the call runs in (what it is for: accounts, videos or both). A new workspace has its own plan and starts with zero credits, and the connection stays bound to the workspace of its key. If setup fails after creation the error carries the workspace_id: finish or delete it, never create a second. delete_workspace is a soft delete and cannot remove the user's default workspace.
• •Onboarding state (get_onboarding_state) runs website, brand, media, first video, avatar, plan, device. A signup wizard with step_list_version 2 first asks what the workspace is for (set_workspace_goal); for accounts it runs only website, brand and the referral question before complete_onboarding, and the accounts are bought after with purchase_account_seats. The light flow of an added workspace ends after set_onboarding_brand and complete_onboarding. set_onboarding_website is best-effort (an unreachable site still records the URL and advances) and kicks a background media capture into the asset library (media_capture_status). list_onboarding_presenter_options returns an empty list while the niche match is still running, so poll again rather than treating it as no avatars. select_onboarding_presenter picks a matched starter avatar for free; start_onboarding_avatar generates one and spends image credits. create_onboarding_concept_projects is free and idempotent. The device half must be resolved (purchased or skipped) before complete_onboarding, which refuses otherwise, except on that accounts track, which needs only the brand. set_onboarding_referral accepts only its listed sources, with free text in detail under other. A user with no credits and no avatars right after signing up has a torn bootstrap; heal_signup_bootstrap re-runs the missing grants idempotently.
• •contact_support posts into the user's private support conversation with the Pamba team (up to five thousand characters, plus up to four public image links in screenshot_urls, PNG, JPEG or WebP, up to ten megabytes each); a user can send ten messages a minute and a hundred a day across every door, emails to support or to a team member included, and upload fifty screenshots a day. A contact_email stays on the conversation for later replies until another replaces it, and the result names the address replies go to. The team answers in the app's Support tab and by email, an unread answer rides every MCP tool result as a support_reply notice (see How a call behaves), and get_support_messages reads the conversation: who wrote each message, the text, screenshot links valid for an hour, and unread_count. Reading the newest page counts as the user seeing the replies, so the reply email is skipped. Over this transport no chat transcript is shared with the team, so put the context in the message. list_api_keys, create_api_key and revoke_api_key manage keys; a revoked key's MCP connection fails at its next call. create_api_key returns the new secret in its result, which over a hosted client lands in a transcript, so create the key for an MCP connection in the app and keep the tool for keys the agent itself will hand to a system. That includes the key create_api_key makes with key_workspace_id for a workspace the connection's key created: it lands in the transcript too, so it suits a system integration rather than a person's own connection.
• •Content rules: Pamba's Acceptable Use Policy is the public page https://pamba.app/acceptable-use-policy; point people there for what is allowed, why a generation was refused by safety filters, and what happens to accounts that break the rules.

Security model

• •A workspace API key resolves to one user in one workspace, where workspace-bound tools run. It makes keys only there and in the workspaces it created itself (create_api_key with key_workspace_id); a chat app's connection makes keys only in the workspace the call runs in. What acts on the person reaches past the key's workspace, as it does in the app: list_api_keys and revoke_api_key cover their keys everywhere, and delete_workspace and the REST /workspaces/{workspaceId}/… routes (settings, members, invitations) act on any workspace they administer. An OAuth token resolves to one user and an explicit set of approved workspaces; each tool call resolves one approved workspace and verifies current membership before execution. Ownership checks are the same the app enforces: an id from another workspace answers not_found, never data. Admins-only settings answer forbidden for members. Operator endpoints behind Pamba's admin key are not reachable through this server at all; the admin key is not a credential here.
• •Rotate a key by creating a new one and revoking the old; connections are stateless, so the next call after revocation is the one that fails. Revoking a key leaves the keys it made working, and the new key cannot make keys for the workspaces the old one created: keep a key made inside each of those, or make one later in that workspace's settings.
• •If a key leaks, revoke it, then clear what it made, since revoking removes none of it. Keys: GET /api-keys lists every key you own with its workspace_id and when it was made and last used (list_api_keys shows the fifty newest and counts them all; a workspace's settings list only that workspace's keys). Revoke each one made since the leak, judging by date rather than name, since a key's name is whatever its maker typed, or revoke them all and make new ones. Members: a key can invite people into any workspace you administer, and an invitation link admits whoever accepts it, so check the members and pending invitations of each of those in its settings in the app, and remove what you did not add (over MCP, list_workspace_members and list_workspace_invitations read only the workspace the connection runs in); check the key's own workspace's share links too (list_share_links). Workspaces: GET /workspaces lists every one you belong to with its owner (list_workspaces shows twenty and counts them all); delete any you own and do not recognize, and ask the admins of one you do not own to remove you. A leaked key could also have revoked your other keys or deleted a workspace you administer, never your default one.

Protocol details

• •Streamable HTTP, stateless: every POST is independent and carries its own credential, there is no session id, and no server-to-client stream (GET and DELETE answer 405). A deploy between two calls is invisible to the client.
• •One JSON-RPC message per POST, at most one megabyte (enough for a full editor state; media never travels in a message) and at most sixty-four levels of nesting; a larger body is answered with HTTP 413 and a deeper one with HTTP 400, each with a JSON-RPC error. Batches are refused. Responses are application/json; the server never opens an event stream. Sixteen tool bodies run at once across every connection and four per workspace: a call past the workspace's share answers status: busy at once, and one past the overall bound waits up to thirty seconds for a slot before answering the same, in both cases with nothing run, so a saturated server never hangs a client and one workspace's fan-out never starves another's. Protocol versions 2025-06-18 and 2025-11-25 are accepted; anything else, including 2025-03-26 (whose transport requires batches), negotiates to 2025-06-18.
• •Capabilities: tools, prompts and resources, none with change notifications; the listing changes only with a deploy. Regenerate the reference in your own docs from tools/list if you mirror it.
• •JSON-RPC errors: -32700 malformed JSON, -32600 invalid request or batch, -32601 unknown method, -32602 unknown tool, tool outside the scope, bad arguments, unknown prompt or a missing uri, -32002 resource not found (the data names the uri), -32603 internal error. Auth failures are HTTP 401 before any message is read; a bad toolsets, readonly or max_credits value on the URL is HTTP 400 with a JSON-RPC error body.