Neurodance

Developer documentation

Build with the Neurodance API and MCP server.

Use the REST API for deterministic integrations or connect the remote MCP server to let compatible AI clients operate Neurodance with user approval. Both surfaces share the same workspace, scopes, rate limits and capability model.

Reviewed by Neurodance ·

REST API foundations

The OpenAPI 3.1 contract exposes 200 operations across 160 paths. Authenticate server-side requests with a workspace-scoped nd_live_ or nd_test_ API key in the Authorization Bearer header.

Every write made with an API key requires an Idempotency-Key header; resend the same key to retry safely after a lost response. Long-running template, generation, test-plan and distribution operations return a job_id; poll GET /v1/jobs/{job_id} using poll_after_seconds instead of creating a duplicate operation.

  • Production base URL: https://api-public.neurodance.ai
  • OpenAPI contract: https://api-public.neurodance.ai/v1/openapi.json
  • Scopes: read, generate and distribute

Common workflows

Most integrations combine a few operations. Each line lists the calls in order; the operation index below has every field.

  • Generate and approve: POST /v1/generations, poll GET /v1/jobs/{job_id}, then POST /v1/generations/{generation_id}/review.
  • Publish and measure: GET /v1/account for connected accounts, POST /v1/distributions (now, or later with scheduled_at), GET /v1/metrics, then POST /v1/performance-briefs to brief the next creative.
  • Iterate on a template: GET /v1/templates/{id}/canvas, POST /v1/templates/{id}/canvas, and undo with GET /v1/templates/{id}/history and POST /v1/templates/{id}/history/{version_id}/restore.
  • Test variations: POST /v1/templates/{id}/variations, GET /v1/templates/{id}/test-plan, then POST /v1/templates/{id}/test-plan/runs.
  • Organize campaigns: POST /v1/distribution-planning/campaigns, POST /v1/distribution-planning/assignments, then GET /v1/distribution-planning.
  • Manage Meta ads: GET /v1/meta/insights, then PATCH /v1/meta/objects/{kind}/{object_id} for budgets or POST /v1/meta/objects/{kind}/{object_id}/status to pause or resume.
  • Build a brand kit: POST /v1/brands, POST /v1/uploads/reference, POST /v1/brand-kit/assets, then PATCH /v1/brands/{brand_id} for the palette.

Complete REST operation index (200)

The interactive documentation includes searchable parameters, request fields, response codes, scope, rate tier, async-job and idempotency metadata for every operation.

  • GET /v1/account — Get account status [read]
  • GET /v1/templates — List templates [read]
  • POST /v1/templates — Create a template from a complete manifest (synchronous) [generate]
  • GET /v1/templates/{id} — Get a template [read]
  • GET /v1/templates/{id}/canvas — Get a template's editable canvas [read]
  • POST /v1/templates/{id}/canvas — Bulk-rewrite a template's canvas from a complete manifest (synchronous) [generate]
  • POST /v1/templates/build — Build a template (async) [generate]
  • POST /v1/templates/{id}/variations — Create a variation (synchronous) [generate]
  • GET /v1/assets — List asset library [read]
  • GET /v1/brands — List brands [read]
  • POST /v1/brands — Create brand [generate]
  • GET /v1/brands/{id}/kit — Get a brand kit [read]
  • GET /v1/campaigns/{id}/kit — Get a campaign's effective kit [read]
  • GET /v1/generations — List generations [read]
  • POST /v1/generations — Create a generation (async) [generate]
  • GET /v1/generations/{id} — Get generation status [read]
  • GET /v1/distributions — List distributions [read]
  • POST /v1/distributions — Distribute a generation (async) [distribute]
  • GET /v1/distributions/{id} — Get distribution status [read]
  • DELETE /v1/distributions/{id} — Delete an Instagram post or remove a local YouTube distribution record [distribute]
  • POST /v1/distributions/{job_id}/activate — Activate a paused Ads distribution [distribute]
  • POST /v1/distributions/{job_id}/dismiss — Dismiss a Meta Ads distribution [distribute]
  • POST /v1/distributions/{job_id}/cancel — Cancel a Meta Ads distribution [distribute]
  • POST /v1/distributions/{job_id}/sync — Sync one distribution [distribute]
  • POST /v1/distributions/sync-all — Sync distributions [distribute]
  • GET /v1/metrics — List performance metrics [read]
  • GET /v1/metrics/diagnostics — Diagnose metrics polling [read]
  • GET /v1/metrics/{platform_post_id} — Get post metrics time series [read]
  • POST /v1/performance-briefs — Compose a performance brief [generate]
  • GET /v1/performance-briefs/{platform_post_id} — List performance briefs [read]
  • GET /v1/jobs/{job_id} — Get any job's status [read]
  • POST /v1/uploads/reference — Upload reference media [generate]
  • GET /v1/keys — List API keys [read]
  • POST /v1/keys — Create an API key [read]
  • DELETE /v1/keys — Revoke an API key [read]
  • GET /v1/activity — List recent API activity [read]
  • GET /v1/shared/{token} — View a share link [read]
  • POST /v1/shared/{token}/feedback — Leave a guest note on a shared creative or file [generate]
  • POST /v1/shared/{token}/upload-url — Get a presigned upload URL for a guest contribution [generate]
  • POST /v1/shared/{token}/confirm-upload — Confirm a guest upload completed [generate]
  • POST /v1/shared/{token}/invite — Email a share link to named recipients [generate]
  • GET /v1/capabilities — Search the typed capability catalog [read]
  • GET /v1/search — Search workspace [read]
  • GET /v1/campaigns/{campaign_id}/memory — List campaign memory [read]
  • POST /v1/campaigns/{campaign_id}/memory — Record campaign memory [generate]
  • GET /v1/notes — List workspace notes [read]
  • POST /v1/notes — Add workspace note [generate]
  • PATCH /v1/notes/{note_id} — Edit note [generate]
  • DELETE /v1/notes/{note_id} — Delete workspace note [generate]
  • GET /v1/generations/{generation_id}/review-thread — List review thread [read]
  • POST /v1/review-entries/{source}/{entry_id}/resolution — Resolve review entry [generate]
  • PATCH /v1/campaign-memory/{entry_id} — Update campaign memory [generate]
  • GET /v1/memory-ledger — List decision ledger [read]
  • GET /v1/workspace/memory — List workspace memory [read]
  • GET /v1/organization/decisions — List organization decision log [read]
  • GET /v1/campaigns/{campaign_id}/related-learnings — List related campaign learnings [read]
  • GET /v1/assets/library — List asset library [read]
  • PATCH /v1/assets/{asset_id}/library — Rename, file, or tag asset [generate]
  • GET /v1/archive/generations — List generations [read]
  • GET /v1/trash — List trash [read]
  • DELETE /v1/archive/{entity_type}/{entity_id} — Move object to trash [generate]
  • POST /v1/archive/{entity_type}/{entity_id}/restore — Restore object from trash [generate]
  • PATCH /v1/templates/{template_id}/name — Rename template [generate]
  • GET /v1/campaigns/{campaign_id}/asset-folders — List campaign asset folders [read]
  • POST /v1/campaigns/{campaign_id}/asset-folders — Create campaign asset folder [generate]
  • PATCH /v1/asset-folders/{folder_id} — Rename campaign asset folder [generate]
  • DELETE /v1/asset-folders/{folder_id} — Delete campaign asset folder [generate]
  • POST /v1/generations/{generation_id}/cancel — Cancel active generation [generate]
  • POST /v1/generations/{generation_id}/review — Record generation QC verdict [generate]
  • PATCH /v1/generations/{generation_id}/library — Rename or tag creative [generate]
  • GET /v1/generation-workflow-status — Get batch, carousel, or reusable generation status [read]
  • DELETE /v1/carousels/{carousel_id} — Delete carousel group [generate]
  • GET /v1/shares/targets — List share targets [read]
  • GET /v1/shares — List object shares [read]
  • POST /v1/shares — Create object share [generate]
  • PATCH /v1/shares/{share_id} — Update link share [generate]
  • DELETE /v1/shares/{share_id} — Revoke object share [generate]
  • GET /v1/shares/teammates — List workspace teammates [read]
  • POST /v1/shares/teammates — Send creative or file to teammates [generate]
  • GET /v1/shares/incoming — List shares received [read]
  • GET /v1/generations/{generation_id}/lineage — Get generation lineage [read]
  • GET /v1/assets/{asset_id}/review-thread — List file review thread [read]
  • GET /v1/assets/{asset_id}/model-annotations — List 3D point comments [read]
  • POST /v1/assets/{asset_id}/model-annotations — Add 3D point comment [generate]
  • DELETE /v1/assets/{asset_id}/model-annotations/{annotation_id} — Delete 3D point comment [generate]
  • GET /v1/distribution-planning — Load distribution planning workspace [read]
  • POST /v1/distribution-planning/campaigns — Create campaign [generate]
  • PATCH /v1/distribution-planning/campaigns/{campaign_id} — Update campaign [generate]
  • DELETE /v1/distribution-planning/campaigns/{campaign_id} — Delete campaign [generate]
  • POST /v1/distribution-planning/campaigns/{campaign_id}/archive — Archive campaign [generate]
  • POST /v1/distribution-planning/campaigns/{campaign_id}/restore — Restore campaign [generate]
  • POST /v1/distribution-planning/assignments — Organize distribution assignment [generate]
  • GET /v1/distribution-planning/generation-assignments/{generation_id} — List generation assignments [read]
  • GET /v1/performance/workspace — Load performance workspace [read]
  • GET /v1/performance/attributes — List performance attributes [read]
  • POST /v1/performance/attributes — Add performance attribute [generate]
  • DELETE /v1/performance/attributes/{attribute_id} — Delete performance attribute [generate]
  • GET /v1/performance/attributes/analysis — Analyze performance cohorts [read]
  • GET /v1/performance/audience-balance — Assess audience balance [read]
  • GET /v1/editor/presets — Search editor presets [read]
  • GET /v1/editor/media — List editor media [read]
  • GET /v1/editor/projects — Load editor project [read]
  • POST /v1/editor/projects — Save editor project [generate]
  • POST /v1/editor/projects/operations — Apply editor operations [generate]
  • POST /v1/editor/sources/resolve — Resolve editor sources [read]
  • PATCH /v1/editor/asset-names — Set editor asset name [generate]
  • DELETE /v1/editor/asset-names — Delete editor asset name [generate]
  • POST /v1/editor/assets/attach — Attach asset to editor [generate]
  • POST /v1/editor/uploads — Begin editor media upload [generate]
  • POST /v1/editor/uploads/confirm — Confirm editor media upload [generate]
  • POST /v1/editor/audio/music — Generate editor music [generate]
  • POST /v1/editor/audio/sound-effects — Generate editor sound effect [generate]
  • POST /v1/editor/audio/voiceover — Generate editor voiceover [generate]
  • GET /v1/editor/exports/{export_id} — Get editor export [read]
  • GET /v1/campaign-folders — List campaign folders [read]
  • POST /v1/campaign-folders — Create campaign folder [generate]
  • PATCH /v1/campaign-folders/{folder_id} — Rename campaign folder [generate]
  • DELETE /v1/campaign-folders/{folder_id} — Delete campaign folder [generate]
  • PATCH /v1/distribution-campaigns/{campaign_id}/folder — Move campaign to folder [generate]
  • GET /v1/performance/experiments — List saved performance experiments [read]
  • POST /v1/performance/experiments — Save performance experiment [generate]
  • GET /v1/performance/cohorts — List performance cohorts [read]
  • POST /v1/performance/cohorts — Create performance cohort [generate]
  • DELETE /v1/performance/cohorts/{cohort_id} — Delete performance cohort [generate]
  • DELETE /v1/performance/experiments/{experiment_id} — Delete saved performance experiment [generate]
  • PATCH /v1/brands/{brand_id} — Update brand [generate]
  • DELETE /v1/brands/{brand_id} — Delete brand [generate]
  • PATCH /v1/distribution-planning/campaigns/{campaign_id}/brand — Move campaign to brand [generate]
  • GET /v1/brand-kit/assets — List kit assets [read]
  • POST /v1/brand-kit/assets — Add to brand kit [generate]
  • PATCH /v1/brand-kit/assets/{asset_id} — Update kit asset [generate]
  • DELETE /v1/brand-kit/assets/{asset_id} — Remove kit asset [generate]
  • GET /v1/brands/{brand_id}/characters — List brand characters [read]
  • POST /v1/brands/{brand_id}/characters — Create brand character [generate]
  • PATCH /v1/brand-characters/{character_id} — Update brand character [generate]
  • DELETE /v1/brand-characters/{character_id} — Delete brand character [generate]
  • GET /v1/moodboard — List moodboard [read]
  • POST /v1/moodboard — Add to moodboard [generate]
  • DELETE /v1/moodboard/{item_id} — Remove moodboard item [generate]
  • POST /v1/campaigns/{campaign_id}/kit/exclusions — Hide brand asset in campaign [generate]
  • PATCH /v1/campaigns/{campaign_id}/kit/palette — Set campaign palette [generate]
  • GET /v1/cuts — List cuts [read]
  • POST /v1/cuts — Create cut [generate]
  • GET /v1/cuts/{cut_id} — Get a cut [read]
  • PATCH /v1/cuts/{cut_id} — Update cut [generate]
  • DELETE /v1/cuts/{cut_id} — Delete cut [generate]
  • POST /v1/cuts/{cut_id}/items — Add to cut [generate]
  • PATCH /v1/cuts/{cut_id}/items — Reorder cut [generate]
  • DELETE /v1/cuts/{cut_id}/items/{item_id} — Remove from cut [generate]
  • POST /v1/templates/{template_id}/reuse — Reuse template in campaign [generate]
  • GET /v1/files/folders — List workspace folders [read]
  • POST /v1/files/folders — Create workspace folder [generate]
  • POST /v1/files/move — Move files [generate]
  • POST /v1/files/trash — Move files to trash [generate]
  • GET /v1/files/storage — Get storage usage [read]
  • GET /v1/unsorted — List unsorted work [read]
  • PATCH /v1/generations/{generation_id}/campaign — File creative to campaign [generate]
  • PATCH /v1/distribution-planning/campaigns/{campaign_id}/accounts — Set campaign accounts [generate]
  • POST /v1/distribution-planning/assignments/mark-distributed — Mark creatives distributed [generate]
  • GET /v1/editor/projects/list — List editor projects [read]
  • GET /v1/editor/exports — List editor exports [read]
  • POST /v1/editor/transcripts — Get clip transcripts [read]
  • GET /v1/shares/{share_id}/invites — List link invites [read]
  • POST /v1/shares/{share_id}/invites — Email a link [generate]
  • POST /v1/shares/file-request — Get file request link [generate]
  • POST /v1/review-threads/unresolved-counts — Count open feedback [read]
  • GET /v1/notifications — List notifications [read]
  • GET /v1/meta/campaigns — List Meta campaigns [read]
  • GET /v1/meta/adsets — List Meta ad sets [read]
  • GET /v1/meta/ads — List Meta ads [read]
  • GET /v1/meta/insights — Get Meta insights [read]
  • GET /v1/meta/targeting/search — Search Meta targeting [read]
  • GET /v1/meta/targeting/countries — List Meta countries [read]
  • POST /v1/meta/reach-estimate — Estimate Meta reach [read]
  • POST /v1/meta/ad-previews — Preview a Meta ad [read]
  • GET /v1/meta/custom-audiences — List Meta audiences [read]
  • POST /v1/meta/custom-audiences — Create Meta audience [distribute]
  • GET /v1/meta/audience-imports/{job_id} — Get audience upload status [read]
  • DELETE /v1/meta/custom-audiences/{audience_id} — Delete Meta audience [distribute]
  • PATCH /v1/meta/objects/{kind}/{object_id} — Edit Meta campaign, ad set, or ad [distribute]
  • POST /v1/meta/objects/{kind}/{object_id}/status — Pause or resume Meta ads [distribute]
  • GET /v1/meta/jobs/{meta_job_id} — Get Meta ad draft [read]
  • PATCH /v1/meta/jobs/{meta_job_id} — Edit Meta ad draft [distribute]
  • GET /v1/distribution-planning/campaigns/{campaign_id}/actions — List Copilot suggestions [read]
  • POST /v1/distribution-planning/campaigns/{campaign_id}/actions — Ask Distribution Copilot [generate]
  • PATCH /v1/distribution-actions/{action_id} — Edit Copilot suggestion [generate]
  • POST /v1/distribution-actions/{action_id}/decision — Approve or run Copilot suggestion [generate]
  • POST /v1/captions/drafts — Draft captions [generate]
  • POST /v1/distributions/{job_id}/redrive — Retry failed distribution [distribute]
  • GET /v1/connections/reconnect-required — List accounts to reconnect [read]
  • GET /v1/templates/{id}/history — List a template's canvas snapshots [read]
  • POST /v1/templates/{id}/history/{version_id}/restore — Restore an earlier canvas snapshot [generate]
  • POST /v1/templates/{id}/segments/rebuild — Recompose one segment's prompt [generate]
  • GET /v1/templates/{id}/test-plan — Preview a template's test plan [read]
  • POST /v1/templates/{id}/test-plan/runs — Run test plan versions (async) [generate]
  • POST /v1/node-prompts/enhance — Draft a canvas node prompt from a rough idea [generate]
  • POST /v1/node-prompts/rewrite — Weave a reference into a node prompt [generate]
  • POST /v1/node-prompts/refine — Apply one precise change to a node prompt [generate]
  • POST /v1/generations/{generation_id}/edits — Edit a window of a finished video (async) [generate]
  • POST /v1/carousels — Create an image carousel (async) [generate]

Connect the MCP server

The Neurodance MCP v3.2.0 server uses Streamable HTTP at https://mcp.neurodance.ai/mcp. Compatible clients discover OAuth automatically, open Neurodance sign-in and request read, generate or distribute scopes. No API key is pasted into the client.

The server supports direct tools, embedded MCP Apps workflow views and a typed capability bridge. A client may show fewer tools if it does not support MCP Apps or applies its own connector curation.

  • Claude.ai and Claude Desktop: Settings → Connectors → Add custom connector
  • ChatGPT: Settings → Apps → Developer Mode → Create App, then choose OAuth
  • Other clients: configure the remote Streamable HTTP endpoint and follow OAuth protected-resource discovery

Complete MCP tool index (135)

These are the tools the server returns from tools/list. If none fits a request, search_capabilities finds the rest of the typed catalog and run_capability runs one. The interactive reference has full descriptions, inputs, workflow, scope and safety annotations.

  • upload_attachment — Save a file the user attached to the chat (image, video clip, or audio) to their Files and return its media_id, ready for reference_images on create_generation, generate_image, or create_image_carousel. Never list_assets afterward; the id is final. IN CHATGPT: as soon as the user attaches a file, call this tool right away with no other step. ChatGPT fills the `file` argument itself; do not describe the file, ask which workspace, or open the upload panel. IN CLAUDE: Claude does not pass chat attachments to tools, so this tool cannot see them. Call open_upload_picker and ask the user to drop the same file in the panel. Only use create_upload_session instead when the user says they allowed Neurodance's domain for code execution. Never transcribe or base64-encode an attachment yourself. media_url and media_base64 are only for a public HTTPS link or bytes you really hold. Fails with code storage_limit_exceeded when the workspace is out of storage; tell the user to free space or upgrade instead of retrying. Requires: generate scope. [generate; direct_tool]
  • open_upload_picker — Show the Neurodance upload panel in the chat so the user can drop or choose images, video clips, or audio from their device (and, in ChatGPT, from their ChatGPT files). The panel cannot see files already attached to the chat. IN CHATGPT: use it only when nothing is attached; for an attached file call upload_attachment instead. IN CLAUDE: use this for an attached file too, and ask the user to drop the same file in the panel (Claude does not pass attachments to apps). After calling, tell the user to add their files in the panel below. Do not say a file was selected or uploaded until the panel reports it; you receive the media_ids when it does. If the user says no panel appeared, this chat app cannot show it: send them to Files in the Neurodance app. Requires: generate scope. [generate; direct_tool]
  • list_templates — List the templates in the workspace, newest first, with names, ids, and metadata. Pass a template id to create_generation or get_template_canvas. Optional filters: campaign (name or id — only templates filed to it) and search (matches name, description, and scene prompt text). Requires: read scope. [read; direct_tool]
  • list_campaigns — List the workspace's campaigns. A campaign is the main way work is organized: a launch, product line, funnel, or experiment, with an optional optimization goal and notes, filed under a brand. Templates and generations are filed to campaigns. Call this when the user refers to an existing campaign by name, then pass campaign on write_template_json, rewrite_template_canvas, or create_generation so new work is filed as it is created. Requires: read scope. [read; direct_tool]
  • create_campaign — Create a campaign: the folder work is filed to, such as a launch, product line, funnel, or experiment. Use this when the user explicitly asks to create or set up a campaign; to file new work, passing a new campaign name on a creation tool is enough. If a campaign with that name already exists, it is returned instead of a duplicate. Requires: generate scope. [generate; direct_tool]
  • get_template — Get details of a specific template by ID. Requires: read scope. [read; direct_tool]
  • list_cuts — List cuts: templates that host several other templates combined into one final assembled video. A cut's host_template_id is a normal template you can pass to get_template_canvas, editor.media.list, create_generation, etc. — a cut only changes which generations the editor offers, not how the host template itself is generated. Requires: read scope. [read; direct_tool]
  • get_cut — Get one cut's member templates in running order, with the starred (winning) one flagged. Requires: read scope. [read; direct_tool]
  • list_brands — List the brands in your workspace, each with its identity color and color palette. Read a brand's kit with get_brand_kit before generating so the ad matches its identity. Requires: read scope. [read; direct_tool]
  • get_brand_kit — Get one brand's full kit: palette, named characters, and every kit asset (logo, style_reference, character, product_shot, font, audio) with a signed, fetchable url. Read this before generating for a brand so references, colors, and characters stay consistent with its identity. Editing the kit is not supported here. Requires: read scope. [read; direct_tool]
  • get_template_canvas — Load the editable canvas for a template, including node ids, prompts, narrative roles, stored variation counts, and testable nodes. The node summaries include reference_images; ['product'] means the node should use generation-level product references. Start here before editing the canvas, creating canvas variations, previewing test plans, or generating from an edited template. Some older canvases may show generic roles such as Scene; that is valid canvas state. For variations, pass the node_id and variation_axis to create_canvas_variation and let the backend resolve the node's effective role from canvas context. Recommended workflow: get_template_canvas → rewrite_template_canvas (bulk edit the full manifest for an existing template) → get_template_canvas again to verify → create_generation or run_test_plan. Requires: read scope. [read; direct_tool]
  • write_template_json — Create a NEW video ad template instantly from a complete video-manifest-v1 payload that YOU, the MCP agent, have already generated as JSON. This tool directly inserts the caller's template row; it does not call any queued builder. For a user's request to make a new template, use this tool once with no template_id. Do NOT use list_templates to find an existing template unless the user explicitly asked to edit an existing template. For bulk edits to an existing template, use rewrite_template_canvas instead; it requires template_id and preserves builder-owned metadata and stored variants for stable node ids. Manifest shape: { templateName, segments: [{ id: 'video1', promptText, duration (1-15), usesProductReference?, nodes: [{ id, promptText, duration (1-15), narrativeRole }] }] }. Every node narrativeRole must be one of the app component names: Hook, Problem, Demo, Proof, Social proof, Transformation, Objection, CTA. The server stores node labels as those canonical component names; do not invent custom component names. Set segments[].usesProductReference=true on every segment that should use the product image supplied to create_generation. Do not replace product details with {{product_name}} or {{cta_url}} placeholders; use literal creative prompts and blueprintSummary for the story summary. Include blueprintSummary (product, audience, whyCare, cta, duration) when you want the canvas brief (story, goal, and CTA) populated. Node durations must sum to a total between 4 and 120 seconds. DURATION EQUATIONS (server-enforced): for every segment, segment.duration MUST equal the sum of that segment's nodes[].duration; totalDurationSeconds MUST equal the sum of all segments[].duration. Example: a 4s node requires one segment with duration: 4. A mismatch is rejected and must never be sent to create_generation. SEGMENTATION: a segment is ONE video model call of up to 15 seconds, and its nodes are the internal cuts of that call. A standalone template may be 4-15 seconds as one segment; longer templates should use segments no longer than 15 seconds. Never emit one short segment per beat when one coherent provider call would fit: each segment generates as a separate clip conditioned on the first, which degrades quality. PROMPTTEXT CONTRACT (server-enforced by a deterministic realism lint; violations return a 400 with per-finding remediations — fix and retry): every promptText must OPEN with a physical capture anchor — what camera and where it physically is (e.g. 'Vertical phone video filmed by a friend across the counter', 'Handheld documentary footage on the rig deck', 'Locked-off studio macro shot'). Name ONE practical light source ('grey overcast daylight', 'warm tungsten practicals') and never style words — banned vocabulary includes: cinematic, photorealistic, dramatic lighting, stunning, 8K, vibrant colors, golden glow. Stage any subject — fantastical ones included — as the closest shot a real crew could film: reframe the camera, never drop the idea. Keep faces mid-distance or partially occluded unless the capture anchor is phone/UGC. Specify the soundscape in every prompt (one ambient bed grounded in the scene, plus the exact spoken line with speaker or explicitly 'no speech'). Do NOT request any on-screen text, captions, titles, subtitles, or overlays — rendered text never looks right; deliver messaging through voiceover instead. Restate persistent state in every cut (product color/variant, wardrobe, worn props). For product/UGC ads: keep the product in the real scene, held or used (never floating/rotating on a plain, seamless, gradient, or blurred backdrop, and no display-only beat); keep its real container and form (a rigid box does not tear open like a packet); keep any device off/dim/out-of-focus (screen content renders as gibberish); keep the brand only on the hero product; and for UGC keep eyelines and dialogue to who is actually in frame (one or more presenters both fine). Avoid beauty/skin tells (flawless/glowing skin, ring light) — write real skin under flat light. Soft findings are returned as realism_warnings on success. Requires: generate scope. [generate; direct_tool]
  • rewrite_template_canvas — Bulk edit an existing template by replacing its canvas with a complete video-manifest-v1 manifest. This is the preferred MCP editing path after a template has been created by start_template/write_template_json: call get_template_canvas first, keep stable node ids where you want stored variants and scene metadata preserved, include blueprintSummary to update the canvas brief (story, goal, and CTA), then call get_template_canvas again to verify. The MCP agent must provide the full edited manifest JSON directly; this tool does not call a queued builder. Every node narrativeRole must be a canonical app component name: Hook, Problem, Demo, Proof, Social proof, Transformation, Objection, CTA. When the user asks to add/use product references on nodes, set segments[].usesProductReference=true for each product-visible segment so the rebuilt canvas has reference_images ['product']; do not invent template variables like {{product_name}} or {{cta_url}}. Unlike write_template_json, this requires template_id and preserves builder-owned fields such as agent instructions/model, activation state, examples, guide, and stored variants for node ids that still exist. It prunes scene-block metadata for deleted node ids. Use create_canvas_variation for single-node test variants instead of rewriting the whole template. Keep segments at 15 seconds with beats as internal nodes (a 30s ad is two 15s segments, not eight thin ones); the server packs over-segmented manifests but correct segmentation is preferred. PROMPTTEXT CONTRACT: any promptText you add or modify must follow the same server-enforced realism lint as write_template_json — open with a physical capture anchor (what camera, where it physically is), one named practical light source, no banned style vocabulary (cinematic, photorealistic, dramatic lighting, 8K, vibrant colors, golden glow, ...), a specified soundscape (ambient bed + exact spoken line or 'no speech'), NO on-screen text/captions/overlays of any kind, and persistent state (product color, wardrobe, props) restated per cut. For product/UGC: product stays in the real scene held or used (never isolated on a plain/blurred backdrop, no display-only beat), keeps its real form, devices off/out-of-focus, brand on the hero product only, UGC eyelines/dialogue matched to who is in frame, and no beauty/skin tells (flawless/glowing skin, ring light). Violations return a 400 with per-finding remediations — fix and retry. Prompts you pass through UNCHANGED from get_template_canvas are grandfathered and reported as non-blocking realism_warnings instead. Requires: generate scope. [generate; direct_tool]
  • rebuild_segment — Regenerate one template segment's execution prompt into a single coherent, filmable scene, without redoing the rest of the template. Use this after editing a segment's node-level beats (e.g. with refine_node_prompt_detail) when you want the server's builder AI to recompose them into one filmable instruction, rather than authoring segments[].promptText yourself with rewrite_template_canvas. Preserves every other segment/node id, duration, and prompt exactly. Free — no token cost. Requires: generate scope. [generate; direct_tool]
  • get_template_history — List a template's canvas snapshots, newest first. A snapshot is taken automatically whenever an AI regeneration replaces the canvas — including rewrite_template_canvas and rebuild_segment — so you can see what changed and restore an earlier one with restore_template_version. Requires: read scope. [read; direct_tool]
  • restore_template_version — Put an earlier canvas snapshot back as the template's current canvas. The canvas being replaced is snapshotted first, so a restore can always be undone with another restore. Call get_template_history first to find the version_id. Requires: generate scope. [generate; direct_tool]
  • start_template — Start a new template by asking the user the five intake questions yourself (product, main benefit, call-to-action, ad format, duration), then generate a complete video-manifest-v1 payload and call write_template_json with no template_id to save it. Requires: generate scope. [generate; direct_tool]
  • create_generation — Submit a new video ad generation job. Provide a template, product name, and product description. Optionally attach reference media (product photos, style references, or a completed generation to reuse) — pass whatever id the source tool returned as media_id; Neurodance resolves it to a fresh URL server-side. Use this only after the canvas is already ready and verified. If you manually changed nodes or edges, call get_template_canvas again before generating so you confirm the final canvas state. If you want to test node-level variations, create them on the canvas first and use preview_test_plan/run_test_plan. Do not use this tool to invent variations after the fact. See the video_model and video_resolution field descriptions for per-model tier, pricing, and reference/first-frame requirements. Product/style reference_images are prompt context and do not count as Kling's required first frame. Returns a job_id immediately. Use wait_for_job to wait for completion (takes 2–10 minutes for video). Check get_account first to confirm you have enough tokens. PREFER A REFERENCE IMAGE: if the user has not already provided or uploaded one, ask whether they want to attach a product/style reference and, if so, call upload_attachment (ChatGPT: a file already attached to this message) or open_upload_picker (a local/device file, and the only working path on Claude.ai even for an already-attached file) and wait for the upload to complete BEFORE submitting this job. Only submit without a reference when the user explicitly confirms they don't want one. This advice does not apply to minimax-h3-max, which accept no reference media at all — submit those without one. Requires: generate scope. [generate; direct_tool]
  • edit_generation — Whole-clip edit: cut a window out of a COMPLETED video generation's actual rendered footage and send that footage — not a from-scratch composition — to the provider's edit route with a change instruction. Use this to iterate on a finished ad (e.g. 'make the lighting warmer in the first 5 seconds') without regenerating the whole clip. Only Seedance 2.5 (the control generation's own video model) supports this. Pass the window you want edited as crop_start_seconds/crop_end_seconds measured from the start of the control's output; the server derives the actual padded provider window at execution time — pass your best estimate of the intended range, not a pre-padded one. The window must lie inside the control's rendered length: the server measures that length before queueing and rejects a range past the end with an error stating it. The edit renders at the control's own resolution and is billed on the replaced window (its source and result seconds) at that resolution's edit rate. Returns a job_id immediately. Use wait_for_job to wait for completion. Requires: generate scope. [generate; direct_tool]
  • list_assets — Browse the product images, reference videos, and reference/voiceover audio saved in the user's asset library — the same files shown on the Assets page in the app. Use this only to discover a pre-existing file the user refers to without an id, or to browse their library; it is never required after upload_attachment, open_upload_picker, or a completed generation, all of which already return an id that plugs directly into reference_images[].media_id. Filter with campaign (one campaign's asset library) or scope=general (references not filed into any campaign). Requires: read scope. [read; direct_tool]
  • list_generations — List the user's past generations, newest first. Returns id, product_name, status, job_id, has_media/media_kind (no URLs — call get_generation on one id to actually see it), ad_format, template_id, video_model, created_at, and tokens_used. Use this to find a previous generation to distribute, re-run, reference, or anchor a later run_test_plan variation. Never ask the user to paste IDs; inspect this list and choose the matching generation yourself, asking a plain-language clarification only if ambiguous. Requires: read scope. [read; direct_tool]
  • generate_image — Submit an AI image generation job and return the job_id immediately. Unlike create_generation (which makes a video ad), this produces a still image. For image carousels that need previous-slide visual continuity, call this sequentially: wait for slide N, then pass its job_id as reference_images[].media_id for slide N+1. For batch carousels whose references are already known, prefer create_image_carousel. After calling this tool, ALWAYS call wait_for_job with the returned job_id — wait_for_job will return the image inline in the chat window once it's ready. Do NOT call generate_image again while waiting — that wastes tokens by creating duplicate jobs. Provide your product name, a description of what to generate, and optional reference media (product photos, style refs, or a prior generation to reuse). PREFER A REFERENCE IMAGE: if the user has not already provided or uploaded one, ask whether they want to attach a product/style reference and, if so, call upload_attachment (ChatGPT: a file already attached to this message) or open_upload_picker (a local/device file, and the only working path on Claude.ai even for an already-attached file) and wait for the upload to complete BEFORE submitting this job; only submit without one on explicit confirmation. Costs 1 token below 4K medium, 2 tokens at 4K medium, and 3 tokens at 4K high quality or above. Check get_account first to confirm you have enough tokens. Requires: generate scope. [generate; direct_tool]
  • create_image_carousel — Create an ordered image carousel by submitting 2-10 still-image generation jobs as one group. Use this when the user asks for a carousel, swipe-through ad, multi-card image concept, or Meta/Instagram carousel creative and the card prompts/references are already known. The agent must write the individual image prompt for every card in product_features; the backend does not infer a story arc or know that 'slide 3' should say anything specific. Each card becomes an ordinary image generation with shared carousel_group_id metadata; after every returned job_id is complete, publish with create_distribution using post_type=carousel, generation_id set to the first card, and carousel_generation_ids set to the completed generation ids in order. Instagram carousel publishing requires 2-10 completed image generations. Meta Ads can also use the same ordered ids for a carousel creative, alongside its normal campaign/ad set/targeting/copy fields. If slide-to-slide visual consistency depends on the previous generated slide, create the cards sequentially with generate_image instead: wait for each slide, then pass its job_id as reference_images[].media_id for the next slide. Call wait_for_jobs with every returned job_id and do not create duplicate carousel jobs while waiting. Each card is billed by the shared image settings: 1 token below 4K medium, 2 tokens at 4K medium, and 3 tokens at 4K high quality or above. Requires: generate scope. [generate; direct_tool]
  • create_canvas_variation — Create a pre-generation variation on a specific canvas node inside a template. This is the correct workflow for testing hooks/tones/CTAs: load the canvas, pick a node_id, choose a variation_axis, create one or more variations, preview the test plan, then run the test plan. You normally do not need to pass narrative_role; the backend resolves the effective role from the canvas, scene-block metadata, prompt, and node position, so older generic Scene roles do not block variation testing. By default the variant is saved onto the template's scene-block state for later testing. Costs 0.3 tokens per call, charged whether or not you keep the variant. Requires: generate scope. [generate; direct_tool]
  • enhance_node_prompt — Expand a rough one-line idea into a production-ready generation prompt for a single canvas node, with a suggested narrative role and (for video) duration. Free, stateless — does not read or write a template. Use this to draft a node's prompt before calling write_template_json or rewrite_template_canvas; it does not save anything itself. Requires: generate scope. [generate; direct_tool]
  • rewrite_node_prompt — Free mode: weave a dragged/attached reference's usage into one canvas node's EXISTING prompt in concrete visual terms, preserving everything else — this is what makes attaching a reference actually change the generated result instead of being cosmetic. Stateless — does not read or write a template; write the returned prompt onto the node yourself with rewrite_template_canvas. For any other targeted edit not driven by a reference (e.g. 'make the lighting warmer'), use refine_node_prompt_detail instead. Requires: generate scope. [generate; direct_tool]
  • refine_node_prompt_detail — Paid mode: surgically rewrite one canvas node's EXISTING prompt to apply a specific requested change, preserving everything the change does not touch. Costs 0.3 tokens per call. Stateless — does not read or write a template; write the returned prompt onto the node yourself with rewrite_template_canvas. For incorporating a dragged/attached reference specifically, use the free rewrite_node_prompt instead. Requires: generate scope. [generate; direct_tool]
  • preview_test_plan — Preview the pre-generation test plan for a template from stored canvas variations. Returns a control plus one version per saved node variation, including the node_overrides that would be sent to generation. Use this before run_test_plan. Requires: read scope. [read; direct_tool]
  • run_test_plan — Run one or more pre-generation canvas test versions for a template. This is the preferred way to test variations: upload references first if needed, preview the test plan, select version ids, then run. The tool creates one generation job per selected version and returns all job_ids together — call wait_for_jobs with all of them rather than polling one at a time. When the user asks for a variation of an ad that already exists, do not ask them for IDs: use control_strategy='auto' and either let this tool find the latest matching control generation or pass control_job_id/control_generation_id from list_generations or a previous run_test_plan result. video_model and video_resolution have the same Seedance/Kling constraints and token multipliers as create_generation. Billing: the control is a full generation, while each variant bills only the seconds it actually regenerates — the scenes its node_overrides touch — at the model's per-second rate. On Seedance 2.5 a variant also bills the control-reference seconds it sends as continuity context. Requires: generate scope. [generate; direct_tool]
  • create_distribution — Distribute a completed generation or any uploaded image/video creative to Instagram organic, YouTube Shorts, Meta Ads, X Organic/Ads, or TikTok Organic/Ads. Provide exactly one of generation_id, asset_id, or an HTTPS media_url. Instagram supports captions, Reel, Story, Carousel, user/location tags, alt text, paid partnership labels, and trial Reels. YouTube supports title, description, tags, privacy, and made-for-kids. Meta Ads supports video, single image, or carousel creatives and requires explicit campaign, ad set, targeting, destination URL, primary text, and CTA fields; it will not infer creative copy or targeting. For carousel publishing, first use create_image_carousel or completed image generations, then pass post_type=carousel, generation_id as the first image, and carousel_generation_ids as the 2-10 completed image ids in display order. For Instagram or YouTube, use get_account once if you need account ids, then call create_distribution directly. For Meta Ads, ask the user for any missing campaign/ad set/budget/targeting/copy fields before calling so the trace stays clean. Returns a job_id immediately; use wait_for_job/get_job_status to track progress. Requires: distribute scope. [distribute; direct_tool]
  • list_distributions — List distribution history across Instagram organic, YouTube Shorts, Meta Ads, X, TikTok, and Snapchat Ads. Returns stable job_id values such as dist:ig:<id>, dist:yt:<id>, dist:meta:<id>, dist:xorg:<id>, dist:ttads:<id>, and dist:snap:<id>, plus raw id values for compatibility, platform ids/permalinks, generation/template metadata, publishing fields, and metrics polling error state where relevant. Requires: read scope. [read; direct_tool]
  • activate_distribution — Activate a paused Meta Ads, X Ads, or TikTok Ads distribution. Pass the job_id from create_distribution or list_distributions, e.g. dist:meta:<id>, dist:xads:<id>, or dist:ttads:<id>. The provider state is re-read before the worker enables delivery. Unsupported for organic posts. Requires: distribute scope. [distribute; direct_tool]
  • dismiss_distribution — Dismiss or cancel a non-active Meta Ads distribution job from public API/MCP. Pass the job_id from create_distribution or list_distributions, e.g. dist:meta:<id>. Unsupported for organic posts. Requires: distribute scope. [distribute; direct_tool]
  • delete_distribution — Delete an Instagram organic post or remove a local Neurodance record for a YouTube Short. Removing a YouTube record does not delete the video from YouTube. Delete an X organic post that was created by Neurodance. Pass the job_id from list_distributions, e.g. dist:ig:<id>, dist:yt:<id>, or dist:xorg:<id>. Meta Ads deletion is intentionally not exposed here; use dismiss_distribution before activation or manage active campaigns in Meta. Requires: distribute scope. [distribute; direct_tool]
  • sync_distribution — Sync one distribution against its platform to verify the remote object still exists. Supports Meta Ads, Instagram organic, and YouTube Shorts. Pass the job_id from list_distributions, e.g. dist:meta:<id>, dist:ig:<id>, or dist:yt:<id>. Requires: distribute scope. [distribute; direct_tool]
  • sync_all_distributions — Sync distributions against their remote platforms and report how many were checked and how many appear missing. Supports all platforms together or one of Meta Ads, Instagram organic, and YouTube Shorts. This mirrors the app's distribution maintenance action. Returns at most one page: if next_cursor is non-null, call again with the same platform and that cursor. rate_limited=true means a provider quota stopped the page early. Requires: distribute scope. [distribute; direct_tool]
  • get_metrics — Read performance metrics for published posts and ads on Instagram, YouTube, Meta Ads, X, and TikTok. By default returns the latest snapshot per post; set latest_only=false for raw paginated snapshots. Filter by platform, generation_id, platform_post_id, since, and until. Requires: read scope. [read; direct_tool]
  • get_metric_timeseries — Return the full oldest-first metrics time series for one published post. Use this for trend charts, checking hourly polling, or before composing a brief. Requires: read scope. [read; direct_tool]
  • compose_performance_brief — Compose and persist an AI performance brief from the latest metrics for a published post. Returns the same structured brief used by the app to re-brief the next generation, including generationRequirementsPrompt. Requires: generate scope. [generate; direct_tool]
  • list_performance_briefs — List previously composed performance briefs for one platform post, newest first. Use this to retrieve re-brief history and generationRequirementsPrompt values. Requires: read scope. [read; direct_tool]
  • get_job_status — Get the current status of any async job by its job_id. Works for generation, template build, variation, and distribution jobs. Status values: pending | running | complete | failed. When complete, output_url is set for generations and published organic distribution jobs. Requires: read scope. [read; direct_tool]
  • wait_for_job — Wait briefly for an async job to complete and return the final result. Each call polls every 8 seconds for max_wait_seconds (default and maximum about 20 seconds), then returns status=still_running if the job is not done yet. Call wait_for_job again with the same job_id until complete; never submit a duplicate generation/image/distribution while waiting. Use this after create_generation, generate_image, run_test_plan, or create_distribution to get the final result without manual polling. Requires: read scope. [read; direct_tool]
  • wait_for_jobs — Wait briefly for a set of async jobs together — a carousel's cards, a test plan's variants, or any other parallel batch — instead of calling wait_for_job once per job_id. Polls every 8 seconds for about 20 seconds, then returns status=still_running for any job not done yet. Call wait_for_jobs again with the same job_ids until every job is complete or failed; never submit duplicate jobs while waiting. Requires: read scope. [read; direct_tool]
  • get_account — Get your account status: token balance and every connected publishing account — Instagram Organic, YouTube Shorts, Meta Ads, X Organic, X Ads, TikTok Organic, and TikTok Ads, and Snapchat Ads. Check token_balance before creating generations — video jobs cost tokens based on duration, model, and resolution. If a platform is missing, open your Neurodance Settings → Connections to connect it. The accounts arrays carry the ids create_distribution needs: ig_account_id, yt_account_id, meta_account_id, and the exact connection_id for X/TikTok (plus advertiser_account_id from social_advertiser_accounts for x_ads, tiktok_ads, and snapchat_ads). A social Ads connection whose token_status is no longer 'valid' is still listed under accounts but reports false in connected_platforms — tell the user to reconnect it rather than publishing to it. Platforms named in unavailable_platforms could not be read just now — retry get_account instead of telling the user to reconnect them. Requires: read scope. [read; direct_tool]
  • search_capabilities — Look up a typed Neurodance capability that is not part of the curated dedicated-tool set. The catalog covers everything the app can do, including brands and brand kits (palettes, characters, moodboards), cuts, Files folders and bulk moves, template reuse, Meta Ads management (campaigns, ad sets, ads, audiences, targeting, reach, previews, budgets), the Distribution Copilot, caption drafts, retries, link-share settings and invites, notifications, memory and decisions, and editor projects. mode='search' (default) returns up to 10 lightweight matches ({id, title, one_line, workflow}, no schemas) for a query and/or workflow id; if nothing matches, returns the list of real workflow ids instead of an empty result. mode='describe' takes an exact capability_id from a search result and returns its full input/output schema, scope, rate tier, and idempotency requirement. Run the chosen capability with run_capability. Requires: read scope. [read; capability_bridge]
  • open_library_workspace — Open the user's generations and files as a visual grid of their actual creatives, product photos, references, and clips, with search and type filters. They can open any item and pick it as the reference for the next generation, see what is filed to a campaign, and reach what they moved to trash. Use when the user asks what they have, wants to find or reuse something, needs to choose a product reference, or is looking for something they deleted. Requires: read scope. [read; workflow_app]
  • run_capability — Run one typed capability returned by search_capabilities (mode: 'describe'). Dispatch re-checks the selected capability's own required scope and rate tier, and requires a stable idempotency_key for any mutation. Not an HTTP proxy — arguments must match the capability's input_schema. [read; capability_bridge]
  • create_upload_session — Send a file the user attached to the chat from your code sandbox (Claude with code execution keeps attachments in /mnt/user-data/uploads/). Use this ONLY when the user has said they allowed Neurodance's domain (`allow_domain` in the result) under Settings > Capabilities; by default Claude's sandbox cannot reach Neurodance, so use open_upload_picker instead. Returns a short script: run it and its last line prints JSON with media_id, ready for reference_images. Up to 50 MB. If curl fails with 'CONNECT tunnel failed, response 403', the domain is not allowed: use open_upload_picker. Requires: generate scope. [generate; direct_tool]
  • workspace_search — Searches templates, generations, campaigns, and assets in the current workspace. Requires: read scope. [read; direct_tool]
  • campaign_memory_list — Returns the campaign memory timeline with evidence and lifecycle state. Requires: read scope. [read; direct_tool]
  • notes_list — Lists internal team notes for one tenant-owned template, asset, campaign, or generation. Requires: read scope. [read; direct_tool]
  • notes_add — Adds an internal team note to one tenant-owned template, asset, campaign, or generation. Pass a stable idempotency_key; reuse it after a lost response. Requires: generate scope. [generate; direct_tool]
  • notes_delete — Deletes a workspace note. Only notes written by this API key's user can be deleted. Pass a stable idempotency_key; reuse it after a lost response. Requires: generate scope. [generate; direct_tool]
  • reviews_thread_list — Returns the merged guest-feedback and internal-note review thread for one creative (generation_id) or file (asset_id). Exactly one id, never both. Requires: read scope. [read; direct_tool]
  • reviews_thread_resolve — Resolves or reopens one guest-feedback or internal-note review entry. Pass a stable idempotency_key; reuse it after a lost response. Requires: generate scope. [generate; direct_tool]
  • campaign_memory_create — Atomically records a campaign observation, insight, hypothesis, decision, outcome, or learning with evidence. Pass a stable idempotency_key; reuse it after a lost response. Requires: generate scope. [generate; direct_tool]
  • campaign_memory_update — Accepts or dismisses a suggested memory entry, moves an entry through its lifecycle (open, testing, decided), or promotes it to the playbook. Pass a stable idempotency_key; reuse it after a lost response. Requires: generate scope. [generate; direct_tool]
  • memory_ledger_list — Lists the workspace's permanent record of creative decisions and changes, newest first. Filter by campaign or action and page with the cursor. Requires: read scope. [read; direct_tool]
  • workspace_memory_list — Lists the curated workspace memory stream for any member with workspace read access, including activity not tied to a campaign. Requires: read scope. [read; direct_tool]
  • organization_decisions_list — Lists the organization decision stream. Access is enforced by the database for members with organization decision-log permission. Requires: read scope. [read; direct_tool]
  • campaign_memory_related — Finds accepted playbook learnings from other campaigns with optional tag overlap. Requires: read scope. [read; direct_tool]
  • assets_library_list — Lists tenant assets across general, campaign, folder, and media-type scopes with short-lived signed media URLs. Requires: read scope. [read; direct_tool]
  • assets_library_update — Renames an asset, moves it into General, a campaign library, or a validated campaign folder, and tags what it IS as reference material (product, style, character, logo, other) or clears the tag for a plain asset. Pass a stable idempotency_key; reuse it after a lost response. Requires: generate scope. [generate; direct_tool]
  • archive_generations_list — Lists the Generations page: terminal creatives with search, status, filing (sorted = filed to a campaign, unsorted = not), cursor paging, and performance rollups. status 'all' is what the page shows — complete, cancelled, and rejected; failed jobs are queue diagnostics and are returned only on request. Requires: read scope. [read; direct_tool]
  • trash_list — Lists soft-deleted generations, assets, and templates in the current workspace. Requires: read scope. [read; direct_tool]
  • archive_delete — Moves one file, template, or generation to trash. It can be restored with archive_restore. Pass a stable idempotency_key; reuse it after a lost response. Requires: generate scope. [generate; direct_tool]
  • archive_restore — Restores one soft-deleted asset, template, or generation in the current workspace. Pass a stable idempotency_key; reuse it after a lost response. Requires: generate scope. [generate; direct_tool]
  • templates_rename — Renames a template. The canvas and its history are unchanged. Pass a stable idempotency_key; reuse it after a lost response. Requires: generate scope. [generate; direct_tool]
  • assets_folders_list — Lists the folder hierarchy for one tenant-owned campaign asset library. Requires: read scope. [read; direct_tool]
  • assets_folders_create — Creates a validated folder within one campaign asset library. Pass a stable idempotency_key; reuse it after a lost response. Requires: generate scope. [generate; direct_tool]
  • assets_folders_rename — Renames a tenant-owned campaign asset folder. Pass a stable idempotency_key; reuse it after a lost response. Requires: generate scope. [generate; direct_tool]
  • assets_folders_delete — Deletes a campaign asset folder; contained assets remain in the campaign library. Pass a stable idempotency_key; reuse it after a lost response. Requires: generate scope. [generate; direct_tool]
  • generation_cancel — Cancels one tenant generation if it is still queued or processing. Pass a stable idempotency_key; reuse it after a lost response. Requires: generate scope. [generate; direct_tool]
  • generation_review_qc — Records a human review verdict on one tenant generation. By default the verdict is all it writes. Pass move_to_trash=true with qc_status=rejected to also move the creative to trash, which is what the app's Reject does — the verdict clears it from the review queue and the soft delete clears it from Generations, restorable from Trash. Archiving its distribution assignment only hides the output from Distribute. Pass a stable idempotency_key; reuse it after a lost response. Requires: generate scope. [generate; direct_tool]
  • generations_library_update — Renames a creative (its Generations display name) or tags what it IS as reference material — product, style, character, logo, other — or clears the tag. Pass a stable idempotency_key; reuse it after a lost response. Requires: generate scope. [generate; direct_tool]
  • generation_workflow_status — Returns one generation batch, carousel group, or latest reusable control for a template. Requires: read scope. [read; direct_tool]
  • generation_carousel_delete — Deletes a carousel grouping while retaining its generated images as standalone work. Pass a stable idempotency_key; reuse it after a lost response. Requires: generate scope. [generate; direct_tool]
  • sharing_targets — Lists other active workspaces available to the current API actor as share recipients. Requires: read scope. [read; direct_tool]
  • sharing_list — Lists live workspace and public-link shares for one tenant-owned entity. Requires: read scope. [read; direct_tool]
  • sharing_create — Creates a member-workspace share or public view link with optional password, expiry, download, and upload controls. Pass a stable idempotency_key; reuse it after a lost response. Requires: generate scope. [generate; direct_tool]
  • sharing_revoke — Revokes a workspace or public-link share immediately. Pass a stable idempotency_key; reuse it after a lost response. Requires: generate scope. [generate; direct_tool]
  • sharing_teammates_list — Lists the teammates in this workspace a creative or file can be sent to, with their roles. The current API identity is flagged so a caller never sends to itself. Requires: read scope. [read; direct_tool]
  • sharing_teammate_send — Hands one creative or file to up to 20 teammates in this workspace. They already have access through membership, so this creates each recipient's inbox event and, with a note, the same review-thread note the share dialog leaves. All recipients are delivered together or not at all. Your own user id is skipped (reported in skipped_recipient_user_ids); an id that is not a teammate fails the send with 404. Pass a stable idempotency_key; reuse it after a lost response. Requires: generate scope. [generate; direct_tool]
  • sharing_incoming_list — Lists what other workspaces have shared INTO this one, by entity type, with the sharing workspace's name. Shared media carries a short-lived URL only where the app can sign it too; anything else returns metadata and says why. Requires: read scope. [read; direct_tool]
  • generation_lineage_get — Returns ancestry, descendants, campaign filing, posts, performance rollup, and creative-loop briefs. Requires: read scope. [read; direct_tool]
  • reviews_asset_thread_list — The file half of the review thread: guest notes left on a file's share link merged with the team's internal notes on it. Same reader as the creative thread, addressed by asset_id. Requires: read scope. [read; direct_tool]
  • assets_model_annotations_list — Lists the point comments pinned to physical spots on one 3D model, in pin order. Each carries its rendered world-space anchor, so a pin reopens on the same spot. Requires: read scope. [read; direct_tool]
  • assets_model_annotations_add — Pins a comment to a point on one 3D model. position is the viewer's rendered world-space coordinate [x, y, z] — take it from an existing pin or from the viewer, not from the raw file's own units. Pass a stable idempotency_key; reuse it after a lost response. Requires: generate scope. [generate; direct_tool]
  • assets_model_annotations_delete — Removes one point comment from a 3D model. The model and every other comment on it are untouched. Pass a stable idempotency_key; reuse it after a lost response. Requires: generate scope. [generate; direct_tool]
  • distribution_planning_workspace — Loads everything the Distribute planner shows: campaigns (each with its brand_id), their brands, creative assignments, templates, and assigned generations. Requires: read scope. [read; direct_tool]
  • distribution_campaign_update — Renames a campaign or changes its goal and notes. Pass a stable idempotency_key; reuse it after a lost response. Requires: generate scope. [generate; direct_tool]
  • distribution_campaign_archive — Archives a campaign so it leaves the active list. Published posts and ads are not touched. Undo with distribution_campaign_restore. Pass a stable idempotency_key; reuse it after a lost response. Requires: generate scope. [generate; direct_tool]
  • distribution_campaign_restore — Restores an archived campaign to the active list. Pass a stable idempotency_key; reuse it after a lost response. Requires: generate scope. [generate; direct_tool]
  • distribution_campaign_delete — Permanently deletes a campaign. This cannot be undone, so confirm with the user first; prefer distribution_campaign_archive. Published posts and ads are not touched. Pass a stable idempotency_key; reuse it after a lost response. Requires: generate scope. [generate; direct_tool]
  • distribution_assignment_upsert — Files a creative into a campaign, or updates its assignment: status (incoming, approved, organized, distributed, archived), enabled, and caption. Creates or updates atomically. Pass a stable idempotency_key; reuse it after a lost response. Requires: generate scope. [generate; direct_tool]
  • distribution_assignment_list_generation — Lists the campaigns one generation is filed to. Requires: read scope. [read; direct_tool]
  • performance_workspace — Loads generation rollups, recent metric snapshots, and distribution status for analysis. Requires: read scope. [read; direct_tool]
  • performance_attributes_list — Lists workspace-defined creative attribute cohorts. Requires: read scope. [read; direct_tool]
  • performance_attributes_add — Adds a phrase used to compare a creative cohort with the workspace baseline. Pass a stable idempotency_key; reuse it after a lost response. Requires: generate scope. [generate; direct_tool]
  • performance_attributes_delete — Removes a workspace performance attribute definition. Pass a stable idempotency_key; reuse it after a lost response. Requires: generate scope. [generate; direct_tool]
  • performance_attributes_analyze — Compares median completion and engagement for every saved attribute against the workspace baseline. Requires: read scope. [read; direct_tool]
  • performance_audience_balance — Computes an observational Instagram audience-balance diagnostic without claiming randomization or significance. Requires: read scope. [read; direct_tool]
  • editor_presets_list — Searches the editor's shipped effect, title, caption, text-animation, and transition presets. Include values to retrieve exact editable style patches. Requires: read scope. [read; direct_tool]
  • editor_media_list — Lists editor uploads, paged completed generation sources, node clips, and shared custom names. Requires: read scope. [read; direct_tool]
  • editor_project_load — Loads a tenant project and its current immutable timeline revision. Requires: read scope. [read; direct_tool]
  • editor_project_apply_operations — Applies up to 50 typed timeline edits—including advanced clip/audio fields, effect and title presets, text animations, transitions, and transcript captions—then saves one immutable revision and returns generated ids. Pass a stable idempotency_key; reuse it after a lost response. Requires: generate scope. [generate; direct_tool]
  • editor_asset_attach — Makes an existing tenant-owned image, video, or audio asset available in one editor project's media tray so it can be placed on the timeline. Pass a stable idempotency_key; reuse it after a lost response. Requires: generate scope. [generate; direct_tool]
  • editor_upload_begin — Reserves an idempotent signed upload URL for a validated video or audio editor source. Refused with 402 storage_limit_exceeded when size_bytes would exceed the workspace storage limit. Pass a stable idempotency_key; reuse it after a lost response. Requires: generate scope. [generate; direct_tool]
  • editor_upload_confirm — Verifies a reserved upload and records it as a tenant-owned editor asset. Refused with 402 storage_limit_exceeded (and the object removed) when its real size would exceed the workspace storage limit. Pass a stable idempotency_key; reuse it after a lost response. Requires: generate scope. [generate; direct_tool]
  • editor_audio_music_generate — Generates an ElevenLabs Music track, stores it as an editor asset, and returns its asset id and duration. Pass a stable idempotency_key; reuse it after a lost response. Requires: generate scope. [generate; direct_tool]
  • editor_audio_sound_effect_generate — Generates an ElevenLabs sound effect, stores it as an editor asset, and returns its asset id and duration. Pass a stable idempotency_key; reuse it after a lost response. Requires: generate scope. [generate; direct_tool]
  • editor_audio_voiceover_generate — Generates an ElevenLabs voiceover, stores it as an editor audio asset, and returns its asset id and duration. Pass a stable idempotency_key; reuse it after a lost response. Requires: generate scope. [generate; direct_tool]
  • editor_export_get — Returns current upload/completion status for one tenant editor export. Requires: read scope. [read; direct_tool]
  • campaign_folders_list — Lists campaign folders in the current workspace. Requires: read scope. [read; direct_tool]
  • campaign_folders_create — Creates a folder for organizing workspace campaigns. Pass a stable idempotency_key; reuse it after a lost response. Requires: generate scope. [generate; direct_tool]
  • campaign_folders_rename — Renames a campaign folder in the current workspace. Pass a stable idempotency_key; reuse it after a lost response. Requires: generate scope. [generate; direct_tool]
  • campaign_folders_delete — Deletes a folder and leaves its campaigns unfiled. Pass a stable idempotency_key; reuse it after a lost response. Requires: generate scope. [generate; direct_tool]
  • campaign_folders_assign — Files a campaign in a folder or removes it from its folder. Pass a stable idempotency_key; reuse it after a lost response. Requires: generate scope. [generate; direct_tool]
  • performance_experiments_list — Lists named comparison definitions saved in the workspace. Requires: read scope. [read; direct_tool]
  • performance_cohorts_list — Lists saved performance groups and their curated member ids. Requires: read scope. [read; direct_tool]
  • performance_cohorts_create — Saves a named group of generations or campaigns to compare in performance analysis. Pass a stable idempotency_key; reuse it after a lost response. Requires: generate scope. [generate; direct_tool]
  • performance_cohorts_delete — Deletes a saved performance group and its membership rows. Pass a stable idempotency_key; reuse it after a lost response. Requires: generate scope. [generate; direct_tool]
  • performance_experiments_create — Saves a named comparison definition that can be reopened against live performance data. Pass a stable idempotency_key; reuse it after a lost response. Requires: generate scope. [generate; direct_tool]
  • performance_experiments_delete — Deletes a saved comparison definition from the workspace. Pass a stable idempotency_key; reuse it after a lost response. Requires: generate scope. [generate; direct_tool]
  • brand_update — Renames a brand or changes its color or color palette. The palette replaces the stored one. Pass a stable idempotency_key; reuse it after a lost response. Requires: generate scope. [generate; direct_tool]
  • brand_kit_asset_add — Adds an uploaded file (asset_id from upload_attachment or POST /v1/uploads/reference) to a brand or campaign kit as a logo, style reference, character, product shot, font, or audio. For a font with no file, pass font_family instead. Pass a stable idempotency_key; reuse it after a lost response. Requires: generate scope. [generate; direct_tool]
  • generation_campaign_file — Files a finished generation into a campaign so it appears in that campaign's planner, or returns it to Unsorted when campaign_id is null. To file an uploaded file instead, use assets_library_update. Pass a stable idempotency_key; reuse it after a lost response. Requires: generate scope. [generate; direct_tool]
  • notifications_list — What the notification bell shows for the last 14 days: teammates' notes, guest feedback and render requests on your links, work shared into the workspace, and pending promotions, newest first. Requires: read scope. [read; direct_tool]
  • meta_insights_get — Reads Meta Ads reporting (spend, impressions, clicks, results, and more) for a date range at account, campaign, ad set, or ad level, optionally by day and with breakdowns such as age or placement. Requires: read scope. [read; direct_tool]
  • meta_object_update — Changes a live Meta campaign, ad set, or ad: name, daily or lifetime budget, spend caps, bid strategy and amount, schedule, or targeting. Budgets are in cents. This changes real spend; confirm with the user first. Pass a stable idempotency_key; reuse it after a lost response. Requires: distribute scope. [distribute; direct_tool]
  • meta_object_status_set — Sets a Meta campaign, ad set, or ad to ACTIVE (resume), PAUSED, or ARCHIVED. Resuming starts real spend; confirm with the user first. Pass a stable idempotency_key; reuse it after a lost response. Requires: distribute scope. [distribute; direct_tool]
  • distribution_action_create — Gives the Distribution Copilot an instruction for a campaign (e.g. 'shift budget to the best performer') and returns a proposed action listing the exact setting changes. Nothing changes until it is approved and executed. Pass a stable idempotency_key; reuse it after a lost response. Requires: generate scope. [generate; direct_tool]
  • distribution_action_decide — Approves, executes (applies the changes to the campaign's settings), or rejects a Copilot action. Executing changes campaign settings only; publishing stays separate. Confirm with the user before approving or executing. Pass a stable idempotency_key; reuse it after a lost response. Requires: generate scope. [generate; direct_tool]
  • captions_draft — Writes platform-ready captions for finished generations, using each one's template and creative intent, the campaign and brand, and your prompt. Returns drafts to review; nothing is posted. Pass a stable idempotency_key; reuse it after a lost response. Requires: generate scope. [generate; direct_tool]
  • get_generation — See one generation: returns a real inline image the model can look at (a ~512px preview, not the full-resolution original), plus its status, product name, and a link to the full-resolution output. For a video generation the image is a poster frame — the response also includes a resource_link to the video itself, which this tool never inlines. Use this after list_generations to actually judge a specific result rather than just reading its status. Requires: read scope. [read; direct_tool]

Rate limits and errors

Current per-credential, per-workspace limits: read 120 per 60 seconds, creative write 60 per 60 seconds, external write 10 per 60 seconds, credential write 10 per 60 seconds. Follow Retry-After after a 429 and use exponential backoff with jitter for transient failures.

Errors provide a stable machine-readable type, human message, remediation when available, documentation URL and request ID. Integrations should branch on the error type rather than message text.