GEN is the creative AI video engineer. Free editor/social publishing; AI credits via card/x402.
Maintain this server? Claim it
Call this server's tools from your browser. Nothing to install.
Optional GEN PAT for clients without OAuth. Existing users: gen.pro/api. Agents: gen.pro/skill.md. Leave empty when using OAuth.
Requests go through mcptry because browsers can't call most MCP servers directly. Header values are sent to the server for that request only and are never stored or logged.
Tool list from our last check. Connect live to refresh it.
Manage assistants and their profiles. One call carries one or more typed actions: set_profile (flat brand_name | description | competitors | identity_type | goal | target_platforms | shortform | longform | look | personality | persona_inspirations | research_topics | content_themes | monitored) | set_name (name) | set_location (catalog_version + country_code + city_id, sent alone) | set_primary_voice (default_user_voice {voice_id, source}) | set_primary_photo (the agent profile photo: profile_photo_url; null removes) | add_reference_images | remove_reference_images (agent reference images) | add_linked_account | remove_linked_account | complete_profile (description + linked_accounts) | create_agent | update_agent | delete_agent | create_agent_avatar | delete_agent_avatar (agent profile photos, read with gen_discover agent.profile_photos; an avatar with looks and talking characters is gen_characters) | add_agent_inspiration | create_look | connect_agent_elevenlabs | reset_agent_profile. Every settings field is the agent-core AgentCorePatch field of the same name and an unknown field is refused before any call. delete_agent/update_agent/set_name act on the named agent — call this tool first, even when the agent is only loosely named ('the draft agent I made yesterday'); the action names the agent_id field to supply. Do not list agents via gen_discover agent.list first. Setting which platforms the agent posts to — 'make me post on YouTube and TikTok' with no content or schedule to ship — is set_profile target_platforms here, not gen_publish_action. Read settings with gen_discover agent.settings (GET /core) and the location options with gen_discover location.countries / location.cities. Agent sharing is manager/owner-gated (share_agent, set_agent_share_role, revoke_agent_share, transfer_agent_ownership); revoke_agent_share and transfer_agent_ownership return a CONFIRMATION_REQUIRED preview and confirm first, and set_project_share (public | private) needs editor access. The legacy agent tool names are retired; use this dispatcher.
One or more typed agent actions: set_profile (brand_name, description, competitors, identity_type, goal, target_platforms, shortform, longform, look, personality, persona_inspirations, research_topics, content_themes, monitored) | set_name (name) | set_location (catalog_version, country_code, city_id; sent alone) | set_primary_voice (default_user_voice {voice_id, source}) | set_primary_photo (the agent profile photo: profile_photo_url) | add_reference_images (agent reference images: content_resource_ids and/or images) | remove_reference_images (ids) | add_linked_account (url, optional display_name) | remove_linked_account (linked_account_id) | complete_profile (description and/or linked_accounts) | create_agent (name, optional description/organization_id) | update_agent (optional name/description) | delete_agent | create_agent_avatar (adds an agent profile photo) | delete_agent_avatar (avatar_id of an agent profile photo) | add_agent_inspiration (url, optional platform) | create_look | connect_agent_elevenlabs (api_key) | reset_agent_profile | share_agent (username_or_email, role viewer|editor|manager) | set_agent_share_role (username_or_email, role viewer|editor|manager) | revoke_agent_share (shared_agent_id) | transfer_agent_ownership (username_or_email) | set_project_share (project_id_or_uuid, permission public|private)
The agent ID that owns the assistant; merged into each action exactly where the legacy tool accepts it
Single-use token from a CONFIRMATION_REQUIRED error; repeat the same call with it to complete the destructive action it was issued for. Omit on the first call.
The server marks this tool as destructive. Running it may delete or overwrite data on the server or in any account you connected with your headers.
Manage assistants and their profiles. One call carries one or more typed actions: set_profile (flat brand_name | description | competitors | identity_type | goal | target_platforms | shortform | longform | look | personality | persona_inspirations | research_topics | content_themes | monitored) | set_name (name) | set_location (catalog_version + country_code + city_id, sent alone) | set_primary_voice (default_user_voice {voice_id, source}) | set_primary_photo (the agent profile photo: profile_photo_url; null removes) | add_reference_images | remove_reference_images (agent reference images) | add_linked_account | remove_linked_account | complete_profile (description + linked_accounts) | create_agent | update_agent | delete_agent | create_agent_avatar | delete_agent_avatar (agent profile photos, read with gen_discover agent.profile_photos; an avatar with looks and talking characters is gen_characters) | add_agent_inspiration | create_look | connect_agent_elevenlabs | reset_agent_profile. Every settings field is the agent-core AgentCorePatch field of the same name and an unknown field is refused before any call. delete_agent/update_agent/set_name act on the named agent — call this tool first, even when the agent is only loosely named ('the draft agent I made yesterday'); the action names the agent_id field to supply. Do not list agents via gen_discover agent.list first. Setting which platforms the agent posts to — 'make me post on YouTube and TikTok' with no content or schedule to ship — is set_profile target_platforms here, not gen_publish_action. Read settings with gen_discover agent.settings (GET /core) and the location options with gen_discover location.countries / location.cities. Agent sharing is manager/owner-gated (share_agent, set_agent_share_role, revoke_agent_share, transfer_agent_ownership); revoke_agent_share and transfer_agent_ownership return a CONFIRMATION_REQUIRED preview and confirm first, and set_project_share (public | private) needs editor access. The legacy agent tool names are retired; use this dispatcher.
| Argument | Type | Description |
|---|---|---|
| actions* | array | One or more typed agent actions: set_profile (brand_name, description, competitors, identity_type, goal, target_platforms, shortform, longform, look, personality, persona_inspirations, research_topics, content_themes, monitored) | set_name (name) | set_location (catalog_version, country_code, city_id; sent alone) | set_primary_voice (default_user_voice {voice_id, source}) | set_primary_photo (the agent profile photo: profile_photo_url) | add_reference_images (agent reference images: content_resource_ids and/or images) | remove_reference_images (ids) | add_linked_account (url, optional display_name) | remove_linked_account (linked_account_id) | complete_profile (description and/or linked_accounts) | create_agent (name, optional description/organization_id) | update_agent (optional name/description) | delete_agent | create_agent_avatar (adds an agent profile photo) | delete_agent_avatar (avatar_id of an agent profile photo) | add_agent_inspiration (url, optional platform) | create_look | connect_agent_elevenlabs (api_key) | reset_agent_profile | share_agent (username_or_email, role viewer|editor|manager) | set_agent_share_role (username_or_email, role viewer|editor|manager) | revoke_agent_share (shared_agent_id) | transfer_agent_ownership (username_or_email) | set_project_share (project_id_or_uuid, permission public|private) |
| agent_id | any | The agent ID that owns the assistant; merged into each action exactly where the legacy tool accepts it |
| confirm_token | any | Single-use token from a CONFIRMATION_REQUIRED error; repeat the same call with it to complete the destructive action it was issued for. Omit on the first call. |
{
"type": "object",
"required": [
"actions"
],
"properties": {
"actions": {
"type": "array",
"items": {
"oneOf": [
{
"type": "object",
"required": [
"action",
"url"
],
"properties": {
"url": {
"type": "string",
"description": "Full URL of the inspiration source"
},
"action": {
"const": "add_agent_inspiration"
},
"platform": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Optional platform for the account entry (e.g. 'tiktok', 'instagram', 'youtube'); agent-core infers it from the URL when omitted"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"url"
],
"properties": {
"url": {
"type": "string"
},
"action": {
"const": "add_linked_account"
},
"display_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
}
},
"additionalProperties": false
},
{
"type": "object",
"anyOf": [
{
"required": [
"content_resource_ids"
],
"properties": {
"content_resource_ids": {
"minItems": 1
}
}
},
{
"required": [
"images"
],
"properties": {
"images": {
"minItems": 1
}
}
}
],
"required": [
"action"
],
"properties": {
"action": {
"const": "add_reference_images"
},
"images": {
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
}
},
{
"type": "null"
}
],
"default": null
},
"content_resource_ids": {
"anyOf": [
{
"type": "array",
"items": {
"type": "integer"
}
},
{
"type": "null"
}
],
"default": null
}
},
"additionalProperties": false
},
{
"type": "object",
"anyOf": [
{
"required": [
"description"
]
},
{
"required": [
"linked_accounts"
]
}
],
"required": [
"action"
],
"properties": {
"action": {
"const": "complete_profile"
},
"description": {
"anyOf": [
{
"type": "string",
"maxLength": 5000,
"minLength": 3
},
{
"type": "null"
}
],
"default": null
},
"linked_accounts": {
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
}
},
{
"type": "null"
}
],
"default": null
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"api_key"
],
"properties": {
"action": {
"const": "connect_agent_elevenlabs"
},
"api_key": {
"type": "string",
"description": "The user's ElevenLabs API key"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"name"
],
"properties": {
"name": {
"type": "string",
"description": "Agent name (must be unique within the workspace)"
},
"action": {
"const": "create_agent"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Short description of the agent's purpose"
},
"hume_ai_api_key": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Hume AI API key for emotional voice"
},
"organization_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Workspace ID to create the agent in"
},
"eleven_lab_api_key": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "ElevenLabs API key for voice synthesis"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action"
],
"properties": {
"action": {
"const": "create_agent_avatar"
},
"degod_avatar_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "DeGod avatar ID to use as the agent profile photo"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action"
],
"properties": {
"action": {
"const": "create_look"
},
"version": {
"anyOf": [
{
"enum": [
"nano-banana",
"nano-banana-pro",
"nano-banana-2",
"nano-banana-2-lite"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"aspect_ratio": {
"anyOf": [
{
"enum": [
"1:1",
"9:16",
"16:9",
"4:3",
"3:4",
"3:2",
"2:3"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"instructions": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Extra styling/scene direction (outfit, setting, mood)"
},
"idempotency_key": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Stable retry key (sent as the Idempotency-Key header, max 255 chars). Reuse the same key when retrying this exact create so Rails replays the originally created resource (same id) instead of creating a duplicate. Omit to create unconditionally."
},
"reference_images": {
"anyOf": [
{
"type": "array",
"items": {}
},
{
"type": "null"
}
],
"default": null,
"description": "Public photo URLs of the character for identity preservation"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action"
],
"properties": {
"action": {
"const": "delete_agent"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"avatar_id"
],
"properties": {
"action": {
"const": "delete_agent_avatar"
},
"avatar_id": {
"type": "string",
"description": "The agent profile photo ID to delete, from gen_discover agent.profile_photos (use underscores for multiple, e.g. '7_8_9')"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"linked_account_id"
],
"properties": {
"action": {
"const": "remove_linked_account"
},
"linked_account_id": {
"type": "integer",
"exclusiveMinimum": 0
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"ids"
],
"properties": {
"ids": {
"type": "array",
"items": {
"type": "integer"
},
"maxItems": 50,
"minItems": 1
},
"action": {
"const": "remove_reference_images"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action"
],
"properties": {
"action": {
"const": "reset_agent_profile"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"shared_agent_id"
],
"properties": {
"action": {
"const": "revoke_agent_share"
},
"shared_agent_id": {
"type": "integer",
"description": "The share row id (shared_agent_id) from the agent.shares view"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"username_or_email",
"role"
],
"properties": {
"role": {
"enum": [
"viewer",
"editor",
"manager"
],
"type": "string",
"description": "New agent share role: viewer | editor | manager"
},
"action": {
"const": "set_agent_share_role"
},
"username_or_email": {
"type": "string",
"description": "Email (or username) of the existing share recipient"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"catalog_version",
"country_code",
"city_id"
],
"properties": {
"action": {
"const": "set_location"
},
"city_id": {
"type": "integer",
"exclusiveMinimum": 0
},
"country_code": {
"type": "string",
"maxLength": 2,
"minLength": 2
},
"catalog_version": {
"type": "string",
"maxLength": 128,
"minLength": 1
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"name"
],
"properties": {
"name": {
"type": "string",
"maxLength": 200,
"minLength": 1
},
"action": {
"const": "set_name"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"profile_photo_url"
],
"properties": {
"action": {
"const": "set_primary_photo"
},
"profile_photo_url": {
"anyOf": [
{
"type": "string",
"maxLength": 2000
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"default_user_voice"
],
"properties": {
"action": {
"const": "set_primary_voice"
},
"default_user_voice": {
"type": "object",
"required": [
"voice_id",
"source"
],
"properties": {
"source": {
"type": "string",
"title": "Source",
"maxLength": 100,
"minLength": 1
},
"voice_id": {
"type": "string",
"title": "Voice Id",
"maxLength": 200,
"minLength": 1
}
},
"description": "The ``default_user_voice`` object agent-core forwards to Rails.\n\nagent-core has no pydantic model for it: ``app/routers/agent_core.py``\nbuilds ``default_user_voice_attributes`` from exactly ``voice_id`` and\n``source`` at write time, so those two keys are the wire contract.",
"additionalProperties": false
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action"
],
"properties": {
"goal": {
"anyOf": [
{
"type": "string",
"maxLength": 100
},
{
"type": "null"
}
],
"default": null
},
"look": {
"anyOf": [
{
"type": "string",
"maxLength": 12000
},
{
"type": "null"
}
],
"default": null
},
"action": {
"const": "set_profile"
},
"longform": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null
},
"monitored": {
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
}
},
{
"type": "null"
}
],
"default": null
},
"shortform": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null
},
"brand_name": {
"anyOf": [
{
"type": "string",
"maxLength": 200
},
{
"type": "null"
}
],
"default": null
},
"competitors": {
"anyOf": [
{
"type": "array",
"items": {}
},
{
"type": "null"
}
],
"default": null,
"description": "Competitor handles or profile links to compare against (the full list: a set_profile PATCH replaces the stored competitors, so send the existing ones alongside the new ones)"
},
"description": {
"anyOf": [
{
"type": "string",
"maxLength": 500
},
{
"type": "null"
}
],
"default": null
},
"personality": {
"anyOf": [
{
"type": "string",
"maxLength": 20000
},
{
"type": "null"
}
],
"default": null
},
"identity_type": {
"anyOf": [
{
"enum": [
"brand",
"character"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"content_themes": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"default": null
},
"research_topics": {
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
}
},
{
"type": "null"
}
],
"default": null
},
"target_platforms": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"default": null
},
"persona_inspirations": {
"anyOf": [
{
"type": "array",
"items": {}
},
{
"type": "null"
}
],
"default": null
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"project_id_or_uuid",
"permission"
],
"properties": {
"action": {
"const": "set_project_share"
},
"permission": {
"enum": [
"public",
"private"
],
"type": "string",
"description": "public shares a token link; private removes all public links"
},
"project_id_or_uuid": {
"type": "string",
"description": "The project or vidsheet ID, or its UUID"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"username_or_email",
"role"
],
"properties": {
"role": {
"enum": [
"viewer",
"editor",
"manager"
],
"type": "string",
"description": "Agent share role: viewer | editor | manager"
},
"action": {
"const": "share_agent"
},
"username_or_email": {
"type": "string",
"description": "Email (or username) of the person to share with"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"username_or_email"
],
"properties": {
"action": {
"const": "transfer_agent_ownership"
},
"username_or_email": {
"type": "string",
"description": "Email (or username) of the new owner"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action"
],
"properties": {
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Updated agent name"
},
"action": {
"const": "update_agent"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Updated description"
},
"hume_ai_api_key": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Hume AI API key"
},
"eleven_lab_api_key": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "ElevenLabs API key"
}
},
"additionalProperties": false
}
]
},
"minItems": 1,
"description": "One or more typed agent actions: set_profile (brand_name, description, competitors, identity_type, goal, target_platforms, shortform, longform, look, personality, persona_inspirations, research_topics, content_themes, monitored) | set_name (name) | set_location (catalog_version, country_code, city_id; sent alone) | set_primary_voice (default_user_voice {voice_id, source}) | set_primary_photo (the agent profile photo: profile_photo_url) | add_reference_images (agent reference images: content_resource_ids and/or images) | remove_reference_images (ids) | add_linked_account (url, optional display_name) | remove_linked_account (linked_account_id) | complete_profile (description and/or linked_accounts) | create_agent (name, optional description/organization_id) | update_agent (optional name/description) | delete_agent | create_agent_avatar (adds an agent profile photo) | delete_agent_avatar (avatar_id of an agent profile photo) | add_agent_inspiration (url, optional platform) | create_look | connect_agent_elevenlabs (api_key) | reset_agent_profile | share_agent (username_or_email, role viewer|editor|manager) | set_agent_share_role (username_or_email, role viewer|editor|manager) | revoke_agent_share (shared_agent_id) | transfer_agent_ownership (username_or_email) | set_project_share (project_id_or_uuid, permission public|private)"
},
"agent_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The agent ID that owns the assistant; merged into each action exactly where the legacy tool accepts it"
},
"confirm_token": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Single-use token from a CONFIRMATION_REQUIRED error; repeat the same call with it to complete the destructive action it was issued for. Omit on the first call."
}
},
"x-gen-delegation": {
"actions": [],
"excluded_actions": []
},
"additionalProperties": false
}Analyze real social data and research the web: collect is the typed collection seam — one synchronous DW /collect call per request, answered as model-visible evidence + a per-target coverage summary + result cards (never a job id, never PENDING). For a request to analyze N videos, use collect with count:N and enrich:"full"; listing or showing posts leaves enrich omitted. Omitted enrich collects post metadata only and does not analyze video footage. Report the collected and actually analyzed counts separately, preserving any admission/exclusion disclosure; never claim collected rows were analyzed videos. With enrich:"full" collect waits on the DW's full-enrichment job (transcript, hooks, visual analysis on every row) and answers GEN's written analysis plus one display card per row (thumbnail, @handle, view/like/comment counts, post date, post URL); the enriched per-video fields stay server-side unless include names them (transcript|hooks|visual_description|description|stats), and a job still running when the budget expires answers a PENDING receipt whose collect_enrichment_status action ({job_id}) polls the completed rows in the same shape. For other research and trends requests, use research_web, trends, hooks, creators, comment_mining or video_analysis directly; these jobs own collection and synthesis, so do not collect separately first. It takes targets [{platform, scope, target}] over scope user|hashtag|keyword|search|url|id|asset|account|creators|comments|sounds|ads and platform tiktok|instagram|youtube|pinterest|twitter|kick|twitch|meta_ads|tiktok_ads and freshness live (the default) or cache_then_live_deficit (cache_then_live_deficit serves stored rows free and fetches only the missing count live; cache_only is refused; every account target is paired in the same call with the same handle's user scope for that account's latest posts unless options.profile_only=true, and a comments action scoped only by video_ids is served live by collect's comments scope), and it replaces the older social-data branches named below. discover trends (trends) across TikTok, Instagram, YouTube, and Kick; search comments server-side with sentiment (comments); synthesize scoped TikTok, Instagram, or YouTube comment themes and prose as a normalized table card (comment_mining: target is an @creator, a #hashtag — a bare word is read as a hashtag — or a video URL; platform optional, default TikTok), or analyze one video (video_analysis: video_url accepts a social video link or a public HTTPS .mp4/.mov/.webm/.m4v/.mkv file; for analysis-only requests about framing, shots or timing, use video_analysis with include_video_analysis=true. This watches the existing video without creating clips or drafts; include_video_analysis=false requests social metadata only). Both synthesis actions submit one owner-scoped job with an idempotency key and GET-only polling, not inline legacy cards. Read the DW aggregate trend report (report); and run bounded web research findings (research_web; save:true keeps the run as a Research Warehouse brief, save:false/omitted is one-shot). Analyze source videos for requested clips with clip_moments (1–10 social links, public HTTPS video files, GEN assets or numeric GEN video IDs; optional clip count, duration bounds, mode, presentation, aspect ratio, reframe, speed and enrich; one paid request returns per-source clips and failures). User-selected timestamp windows are exact media edits: use the existing media editor with the owned original source; clip_moments must carry source_start_seconds/source_end_seconds and refuses discovery for that selection. Do not replace a failed selected edit with viral discovery. The DW social warehouse is served directly too: search_posts (DEPRECATED — superseded by collect; still served; the GEN-3096 keyword search — the TikTok cached keyword path by default and the cross-platform search when platforms name more than tiktok, with the Common filter set on the entry), analyze_account (DEPRECATED — superseded by collect; still served: one account's profile + followers), transcribe and transcribe_status (DEPRECATED — superseded by collect url/id; still served: social video transcription by platform and its status), upload_by_ids (upload the stored media), comments_online (DEPRECATED — superseded by collect comments; still served: the live comment fetch beside the cached comments read), monitor_status (the DW monitoring read) and aura_user_stats (AURA stats by emails). hooks returns hook_text/pattern rows plus hook_clusters (pattern clusters) and a truthfulness block (returned, thin_result, note), and needs a scoped target: an @handle, #hashtag or keyword (HOOKS_TARGET_REQUIRED otherwise; HOOKS_UNAVAILABLE when the analyst is off). creators runs the same analyze job door and is served here. One call carries one or more typed actions. trends/hooks take query/mode/target/platform plus the reused CommonFilters bundle (no new dialect), an optional relevance_query, and a raw flag — results are analyzed by default and raw=True opts out to unanalyzed rows. comments takes a scope (query | video_ids | creator | hashtag) plus optional sentiment, days and limit; report takes window (1 | 7 | 30) and limit; research_web takes query plus optional mode (news|social|web|all), research-source platforms (x|news|web|reddit), days, limit, reddit_subreddits and save. A single URL reads its page; extract_assets discovers files, import_assets imports them, and asset_urls selects files. mode social is the community sources, X and Reddit. Research tie-break: 'Research X' the user wants kept or followed up is gen_analyze research_web with save:true (kept as a Research Warehouse brief); research_web is one-shot by default and never persists without save:true. research_scrape scrapes any source on the first call with bounded caps: source is a platform (tiktok, instagram, youtube, x/twitter, pinterest, kick, web) or any public URL, and input names the scrape target (keyword | hashtag | username | user URL; x serves user targets only, pinterest user walks take cursor, and a page source takes url/asset_types/limit/query, extract_assets, import_assets and selected asset_urls); web pages return readable text, headings, links and media; import_assets=true imports selected files through the existing owned-asset path. Success returns evidence and billing. apify_scrape runs one caller-named approved provider actor on the first call and bills: actor_id names the actor and input is its own run input, capped by max_items; success returns the dataset rows and billing. web_asset_scrape runs and bills on the first call, discovers public-page media candidates and optionally imports each through gen_asset_action; a valid legacy confirm_token remains accepted. Success returns candidates, imported_count, imported_assets, import_errors, proxy_used and fetcher.analyze_socials (DEPRECATED — superseded by collect; still served; its hidden legacy names social_posts_scrape and general_scrape are deprecated with it) is the one social-scrape write: a social target (platform + mode + target, with optional cursor/from_db/limit/period/sort_by/min_count) is a live social.posts scrape, and a wide scope (platform + one of keyword/hashtag/userPageURL/video_url, with optional days/last_num_videos/scrape_type/from_db/videoMonitoring) is the DW general scrape. analyze_socials serves Twitch and Kick channel/VOD URLs, resolves a Kick or Twitch mode + target to the wide scope it names, and forwards Kick/Twitch keyword and hashtag scopes to the DW general scrape; the DW's own provider path answers the scopes it does not serve. videoMonitoring forwards unchanged. The paid DW writes the read-only discover lane no longer serves live here: import_urls (paid first-call URL-to-S3 import: platform + public videos_urls, capped at 50 URLs per call, writes S3 and bills on the first call; from_db=true and from_db_only=true are refused as stored-only-unavailable before any request) and analyze_socials (subject to provider support); the DW result preserves returned S3 asset paths. sounds (DEPRECATED — superseded by collect sounds; still served) answers the DW sound endpoints by view (sounds_by_niche | sounds_by_creator | rising_sounds | sound_performance | sound_arbitrage | music | trending_sounds | sound_info) and analytics the DW aggregate endpoints (aggregate | sleepers | posting_times; by_demographics is owner-removed); each view takes its own endpoint fields plus the common GEN-3096 filters object. Paid DW writes and research_scrape execute on the first call — confirmation happens in the FE and a stray confirmed/confirm_token argument is accepted and ignored. Analysis runs and bills on the first call. Each result carries a truthfulness block as fields (requested echo, backend run identity and status, billing subject). Spending analysis and research: the run is billed to the envelope agent_id, which is required (no anonymous path). Demographic filters are owner-removed and rejected. Transcribing an audio or video URL into text is gen_generate (transcribe); the transcribe branch here is the DW transcription of stored social video ids into warehouse transcripts. Free-form questions with attachments belong to gen_ask (ask). Reddit is a research source served by the shared research branch, never a DW video collection: 'reddit' is a research platform, a subreddit scope is reddit_subreddits, a one-shot request carries that scope through the same analysis job as X, news and web, and a reddit.com URL carried by collect or research_web is answered as research, not refused. meta_ads and tiktok_ads are paid advertising platforms served by the DW's one ads lane over scope ads|keyword|user|id (scope ads takes a target object with exactly one of query/advertiser_id/ad_id plus optional country and status, and is forwarded verbatim; the alias scopes take a plain string: keyword->query, user->advertiser page id, id->ad id). That lane is what keeps an ad id from ever dispatching organic TikTok/Instagram retrieval. meta_ads serves live and cached ads; tiktok_ads is cache-only, so a live freshness reaches an unsupported coverage entry and never falls back to Meta or organic retrieval. enrich "full" is refused for every ads target: DW full enrichment selects video entities only and can never enrich an ad, so opt in to one creative's analysis with gen_asset_action analyze instead. Ideas, scripts, trends and stats come only from GEN calls: never invent them, call GEN.
Ask GEN anything in plain words: a question, or a build goal for the composer. gen_ask is for durable multi-step work and scheduled or recurring work: GEN plans it, pauses for approval and keeps it in one conversation. For a single action, call that action's typed tool directly. A chat sent without a conversation_id starts one; the result returns conversation_id and request_id, so send that conversation_id on the follow-up. gen_ask accepts any edit of existing media — trim/cut a time range, crop, reframe, extract audio, merge, speed, concat or overlay — run in GEN's compute environment, returning the produced file URL or draft. NOT record lookup: 'what did I ask/say before' is chat history — gen_discover platform.conversations — and when you already hold an id, use gen_discover. One call carries one or more typed actions: ask (question) | chat (message: a multi-step build goal; payment, publishing and other gated steps pause for approval via gen_task_action decide_agent_run). Content ideas are gen_content_action (generate_ideas | expand_idea | set_idea_status) and research is gen_analyze (research_web | report) — neither is served here. Uploaded files are analyzed on request — an image, video, audio, document or spreadsheet attachment — and a YouTube watch/shorts link is analyzed the same way; the answer comes back as text. ask and chat start agent runs and poll to completion by default; wait=false returns the run_id to poll with the gen_discover task.run_status view. A message into an active workflow conversation is refused with REQUEST_ACTIVE; ask/chat mode is refused there with WORKFLOW_INPUT_UNSUPPORTED. Legacy conversations may queue a message; the separate steer action, cancel_pending and stop drive that queue and the live run; reading the queue or the thread is a gen_discover platform.conversations / platform.conversation / platform.conversation_pending view, never a branch here. Do NOT ship posts here: gen_publish_action ships. The legacy ask tool names are retired; use this dispatcher.
| Argument | Type | Description |
|---|---|---|
| actions* | array | One or more typed ask actions: ask (question, required client_message_id, optional conversation_id/wait/attachments) | chat (message, required client_message_id, optional conversation_id/wait/attachments/metadata) | steer (conversation_id + message, or conversation_id + pending_id) | cancel_pending (conversation_id + pending_id) | stop (run_id). Workflow-routed ask/chat mode is refused with WORKFLOW_INPUT_UNSUPPORTED and a new message during active work is refused with REQUEST_ACTIVE; legacy steer calls keep their existing owner. Reading the queue or the thread is a gen_discover view (platform.conversations / platform.conversation / platform.conversation_pending), not a branch here. Content ideas are gen_content_action (generate_ideas | expand_idea | set_idea_status) and research is gen_analyze (research_web | report) — neither is served here. |
Manage the agent's asset library: analyze any asset_id or file url with kind video/image/audio (quoted, confirmed DW enrichment; documents are refused until DW supports them; cached repeats are free), poll the job with gen_discover domain=asset view=analysis, or upload a file in two steps (create_direct_upload, then complete_asset_upload with the signed_id), import a public video URL (import_asset_from_url), or delete an asset (delete_asset). Import takes a public HTTPS YouTube, TikTok, Instagram, or Kick video; arbitrary CDN/direct-file URLs are not supported. One call carries one or more typed actions. Deleting an asset is destructive — confirm with the user first. Read-only assets are gen_discover domain=asset (analysis | detail | list | libraries); this family's branch fields are gen_discover domain=asset view=actions (target=<branch action>). run_computer (command, optional profile default|media, secrets, egress_allowlist, run_id): run code in GEN's isolated computer — ffmpeg/ffprobe, Python with Pillow, a shell — to trim, cut, crop, reframe, overlay, merge, extract audio or transcode existing media, or any custom script no other tool covers; write produced files to /workspace/outputs/ and they come back as durable URLs in outputs; network is off unless egress_allowlist names hosts, and hosts other than GEN's asset hosts need a confirm_token round. The legacy asset tool names are retired; use this dispatcher.
| Argument | Type | Description |
|---|---|---|
| actions* | array | One or more typed asset actions: analyze (kind, exactly one asset_id or url) | create_direct_upload (filename, byte_size, checksum, content_type) | complete_asset_upload (signed_id, optional folder_id) | import_asset_from_url (url, optional folder_id) | delete_asset (resource_id) | run_computer (command, optional profile, secrets, egress_allowlist, run_id) |
| agent_id | any | The agent ID that owns the asset library (envelope; routed per branch) |
Open a Stripe payment page for a workspace plan or credit pack with open_checkout (organization_id, credit_plan_id from billing.plans). Use open_checkout when the user asks to open checkout or subscribe to a plan; it creates a payment link and never charges a saved card. Do not use gen_sign_in_link for checkout: Stripe needs no GEN sign-in. prepare_funding_recovery (agent_id) returns the ready, non-charging checkout Rails names for a workspace a funding refusal stopped, reusing one still open. Buy GEN credits on the saved card with buy_credits or create and settle an x402 crypto purchase (create_x402_credit_purchase, settle_x402_credit_purchase). One call carries one or more typed actions. Buying credits spends real money — always confirm the plan and price with the user first. When the user asks to buy/top up/add credits, buy_credits is the first call — do not read billing.plans or billing.balance first; if the plan is not yet chosen the action names the credit_plan_id to supply next. Read owned workspaces' subscription status and Stripe invoice history with list_owned_subscriptions and list_owned_invoices; these never change billing. Credit balance, usage and plans are gen_discover domain=billing views. This family's branch fields are gen_discover domain=billing view=actions (target=<branch action>). The legacy billing tool names are retired; use this dispatcher.
| Argument | Type | Description |
|---|---|---|
| actions* | array | Typed billing actions: open_checkout (organization_id, credit_plan_id, optional success_url/cancel_url; creates a Stripe payment page without charging), list_owned_subscriptions (no fields) | list_owned_invoices (organization_id, optional starting_after), both read-only for owned workspaces; or buy_credits, create_x402_credit_purchase, settle_x402_credit_purchase (purchase actions requiring user confirmation) |
| agent_id | any | The agent ID that owns the workspace (envelope; routed per branch) |
Characters: one person each, with looks (images of the person) and talking characters (talking videos of the person with their voice, generated from a look or uploaded). For 'create a character', op=create is the first call — do not list characters or read gen_discover agent.profile_photos first (those are the agent profile photos, not characters). Reads (a viewer is enough): list (source my | library | all, default my; query searches names), get (character_id: its looks, each look's talking characters, the uploaded talking characters, the talking characters still generating and the primary voice), get_talking_character (one talking character with its clips). create makes a character from an image content resource (its original look) or a video of a person: the video becomes an uploaded talking character, its first frame the first look (the cover), and its audio is cloned into the character's primary voice. Cloning is a paid job priced before it runs (it needs 30 seconds of speech); clone_voice false skips it. clone_voice true refuses a video without audio or too short; without clone_voice such a video is created without a voice and voice_clone_message says why. create answers look_id, talking_character_id, voice_id (null until the clone finishes, then the character's primary_voice), user_job_ids (poll with gen_discover generation) and voice_clone_status. name defaults to the file name. upload_look adds an image and upload_talking_character adds a video to a character (clone_voice true also clones its voice into that character's primary voice, same rules and answer fields as create; off by default); upload or import the file first with gen_asset_action. create_talking_character makes a talking character from a look, lip-synced so it is saved with its voice: clips is 3 to 10 clips, each {prompt, duration 5 or 10}, and the look is the start and end frame of every clip; aspect_ratio 9:16 | 16:9 | 1:1 sets its shape (default 9:16). script is optional (a default line is used when blank) and voice {voice_id, provider} defaults to the character's primary voice; with neither a voice nor a primary voice the call is refused. edit_talking_character saves a NEW talking character from a generated one and keeps the original: send the full clip list in the new order (reorder by order, delete by leaving a clip out), where {from_position} keeps that clip of the source. A kept clip whose prompt, duration and aspect_ratio are unchanged is reused: no render, no charge; give it a new prompt or duration to regenerate it. A {prompt, duration} item without from_position is a new clip and renders. The source's aspect_ratio applies unless one is sent. Every talking character carries aspect_ratio (9:16 | 16:9 | 1:1, or null when an uploaded video is none of them). Both are paid jobs priced before they run; they answer generation_id to poll with gen_discover generation, and op=get lists the talking character under generating_talking_characters until it is ready. Library characters are read-only: copy_to_mine makes your own copy, and create_talking_character or edit_talking_character on a library character saves into your copy. rename takes character_id and name, plus look_id or talking_character_id to rename that item instead. set_primary_voice sets the voice pre-selected for this character (voice {voice_id, provider}). delete_character, delete_look (its talking characters stay) and delete_talking_character are permanent: the first call answers CONFIRMATION_REQUIRED with would_destroy and confirm_token; repeat the call with confirm_token only after the user agrees. A talking-head video from an existing character is instead gen_vidsheet_action op generate, creation_card_type video_from_avatar (avatar_id = the character_id + video_url + audio_url).
Manage an agent's content: its content resource files — create one from an uploaded file (create_content_resource), rename one (update_content_resource), or permanently delete one (delete_content_resource) — and its content ideas. generate_ideas is the content-ideas handshake: its first call answers needs_input (the fields to supply), a proposal (proposal_id + summary + plan) or running; reply with proposal_id + feedback for a new proposal, or proposal_id + confirm:true + count to start the idea job (use the user's final count, or the approved plan count if unchanged) (then poll gen_discover content.idea_job with that returned job_id for the batch's persisted ideas; 'ideas from run X' is gen_discover content.ideas with run_id=<X>, never idea_job). confirm=true without proposal_id is a fresh request, with the same needs_input/proposal/running behavior as omitting confirm; the response explicitly says so. A new batch takes brief/count/video_type/requirements/sheet_rows (optionally grounded in source_content_resource_id, source_analysis_job_id for ideas based on an existing gen_analyze result (a trends/hooks/creators/research_web job id, read with gen_discover domain=analyze view=job), or a target_duration_seconds); a refine takes from_ideas + feedback. Send prompt verbatim, all attachments with roles, content_idea, style, content, reference_video, format and cast when provided. Thread conversation_id on every call, and pass external chat words in conversation_context. Proposals offer exactly confirm or text feedback; needs_input is an error with questions. set_content_preference and remove_content_preference use scope long_term or session (24 hours). content.directions reads prior directions. expand_idea fleshes one saved idea out with idea_id or idea_title; idea_id takes precedence when both are supplied. An authored request ('make a Draft with these scenes') first uses save_idea with the user's brief verbatim, title, video_type_id, duration and canvas. Preserve already-authored scenes and caption lines in scenes (scene_number, time_range, duration, action, dialogue, text_overlays), and spoken words in full_script; captions alone do not imply speech. Then use create_video_from_idea with its returned idea_id and creation_mode=draft for Draft only. This uses the same manifest writer and compiler as saved ideas: never generate a batch of ideas, clone a template manually, or hand-write cell/layer edits to build that Draft. A saved idea's Draft/Full always uses create_video_from_idea with idea_id or idea_title and creation_mode=draft|full, never generic gen_vidsheet_action create_sheet/actions[] create or an invented template_slug. Use idea_title for a named saved idea; MCP resolves a unique match on agent_id and asks one plain question for several matches. Do not ask the user for a UUID. Its attached resources stay with the saved idea. create_video_from_idea uses gen-agentic's deterministic idea-to-Vidsheet compiler, in creation_mode draft | full (the idea card's Draft only / Create full video). Draft requires credits for LLM cost plus markup; no paid subscription is required. Media generation is billed separately; full bills credits for generated media, and omitting creation_mode defaults to billed full. With vidsheet_id the idea is added to that Vidsheet as a new row, or built into an existing row_id of it; otherwise a new Vidsheet is created. recreate_video turns a video into one expanded idea that recreates it shot for shot; reimagine_video turns a recreate idea (or a video) into several new ideas with the same pacing and a different subject; build a row from any of them with create_video_from_idea. recreate_video and reimagine_video return the job ({job_id, status}) and their ideas land in the gen_discover content.ideas view. Read the accepted job with gen_discover domain=content view=idea_job and the original job_id, as for generate_ideas. Every idea read returns next_steps with the exact calls it currently allows. set_idea_status moves it through generated | approve_to_create | ready_for_review | change_idea | change_video | rejected | approved_to_post | posted. One call carries one or more typed actions. Deleting is permanent — confirm the file with the user first. Read-only content access is gen_discover domain=content (resource | list | ideas | idea); this family's branch fields are gen_discover domain=content view=actions (target=<branch action>). The legacy content-resource and content-ideas tool names are retired; use this dispatcher. Ideas, scripts, trends and stats come only from GEN calls: never invent them, call GEN.
READ-ONLY. Live per-request JSON Schema forms: domain=contracts view=form target=<tool>[.<branch>] or a published output kind (StoryboardV1 aliases BuildPlanV1), agent_id required. Forms use the accepted tool contract and live choices. Versioned stage/job/delivery schemas: domain=contracts view=schemas (optional target model name). NEVER call this before an action and never to look up a target, plan, connection or id first: when the user asks to create/update/delete/publish/buy/top up/generate/clone/pause/resume/revoke/rename/train/transcribe, or asks a watchlist what it found ('what did my watchlist say/find'), call the matching action tool as the FIRST call — gen_generate (create_image/create_video/create_song/create_song_mix/transcribe), gen_vidsheet_action (any sheet edit or creation-card generate: title card, intro, talking-head), gen_characters (list/create characters), gen_ask, or the gen_<noun>_action family (billing, platform, task, agent, voice, watchlist, publish, content, asset). Call the action first even when an id, sample, plan or connection is not yet known: the action returns the missing field or the options. Use gen_discover only for a pure read. EXISTING-VIDSHEET TEXT-LAYER EDIT EXCEPTION: when changing a text layer that already exists on a Vidsheet, read that row's vidsheet.layers view first to bind the exact layer, save with gen_vidsheet_action, then read the same vidsheet.layers view again to verify the exact saved text — the save's own response is not proof of the sheet's current state. Step 3 (Read anything): THE discovery tool — every GEN read is a domain + view here. Every action family's branches are readable the same way: domain=<family domain> view=actions lists them with one line each, and target=<branch action> (for example domain=content view=actions target=reimagine_video) returns that branch's fields — name, type, required, enum values, description and default — from the same model the family validates an entry with, so a cached tools/list never hides a branch's fields. Vidsheet domain (29 views) reads the editable video workspace; the other domains fold the legacy get/list tools: agent (detail | capabilities | core | settings | profile | profile_photos | list | shares | monitoring | execution_access) · asset (analysis | detail | libraries | list) · billing (balance | generation_access | usage | receipt | plans) · content (resource | list | ideas | idea | idea_job | video_job | directions) · location (countries | cities) · media (last_operation | operations | recommended_sounds | sound_library) · platform (me | organization | organizations | conversation | conversations | request_tree | preferences | api_keys | backups | members) · publish (post_status | rules | connect_url | connections | scheduled) · task (job | job_locator | run_status | list) · voice (list | mine | resource | preview_status | sample_status) · watchlist (detail | list) · social (comments | job; user_info/video_info/posts return typed unavailable with a live gen_analyze collect next step) · analyze (job — GET-only owner-scoped status/result for a gen_analyze trends/hooks/creators/research_web job by job_id; collect_enrichment — read the accepted collect enrichment job and its admitted analysis by job_id and agent_id; never resubmit either branch). Each view takes the id it names (resource_id, conversation_id, post_id, job_id, ...) plus that read's optional filters; publish.connect_url is the one non-pure view: the URL it returns STARTS the platform OAuth flow, so surface it to the user as a step. Social comments and job are provider-free DW reads. Social user_info, video_info and posts are not served as read-only data views because their legacy DW routes can refresh providers; they return a typed direction to the explicit live gen_analyze collect action. Social collection (typed, live, billed) is gen_analyze collect, never a view here. comments reads cached TikTok comment rows by video_ids; job reads one DW job status/result by job_id without resubmitting. The paid DW writes are NOT here: import URLs, live social scrapes and the wide general scrape are gen_analyze's import_urls / analyze_socials branches (they write S3 and bill). Vidsheet views: sheet (summary by default, include=["full"] for the whole dump) | rows | row | columns | cell | video (a row's video_settings + layers) | layers | layer | layer_analysis (one target's placement, media properties and the free read; the paid analysis is its own gen_analyze layer_analysis branch, one synchronous attributed model call behind a single-use confirm_token that answers the projected scene cuts, dead head/tail spans and suggested trim in/out in frames at 30 fps directly — no job to poll) | variables | available_variables | operations | last_operation | engine | template | templates | layout_validation | card_types (keyed by FE card type; produces/container/model filters) | card_schema (one creation card by FE card type, its job type, or the final-video render card) | card_matrix (the full Rails creation-card matrix: cards, models, per-model field rules, limits, talking_loop, song_max_duration_seconds — verbatim) | input_bindings (bind saved-input source_references into a card's fields through the served schema: returns bound_inputs + typed warnings, refuses an incompatible kind before any write) | card_from_job (map a completed job to a card without writing) | actions (the action envelope: every Rails action+target pair with its fields and one worked example, plus named workflows; focus one pair with target="<action>:<kind>", e.g. "update:column"; with a layer_type or audio_library filter it instead asks Rails' live discovery and returns that body — caption/text font: view actions with layer_type=caption lists the allowed styles.fontFamily values, set it with values.settings.styles.fontFamily; song recommendations: view actions with audio_library=recommended returns media with library_reference, put one on a sound layer with update values.card {type: song, inputs: {songTab: recommend, audio: <that media>}}) | generation (poll one generation job by generation_id: pending → processing → completed | failed | stopped; result + output_resources on completion) | final_video_probe (measured final-video readiness for vidsheet_id and optional row_id; ready, url, duration, has_audio, width, height, reasons; a URL alone is never ready) | generation_estimate (free credit-cost estimate for jobs[] before running them) | running_generations (what this sheet is generating right now: one line per running generation, empty when nothing is running — the read behind a target-less 'stop everything running here') | audio_matches (poll a sound_matching job by job_id; matches in .result.audio_matches when completed). Media views: recommended_sounds (sounds recommended/trending for this agent; optional query, commercial, mood, genre, min_bpm, max_bpm, limit) and sound_library (search the shared catalog by free text: query, mood, tags, commercial, page/per_page; empty query browses) — reach for recommended_sounds when the user asks for trending/recommended sounds. View disambiguation: media.last_operation is the same engine change-set read as vidsheet.last_operation (both take vidsheet_id) — 'is my video/song/generation ready yet?' is media.last_operation, and vidsheet.last_operation is for a sheet edit history. platform.me is only 'who am I / my own profile'. platform.organization is the workspace by organization_id: members and who can access it; platform.organizations lists the workspaces the caller belongs to. Use platform.organization for 'who can see/access X' (its members and visibility). asset.list searches/lists the user's own assets; asset.libraries lists stock/library collections. content.list is its generated content resources (project filter). 'ideas from run X' / 'saved ideas from run X' is content.ideas with run_id=<X> — a run id or its prefix of at least 8 characters — never content.idea_job: content.ideas lists bounded idea summaries (optional status, limit, page) and takes run_id for the ideas from a run; content.idea is one full idea by idea_id; content.idea_job takes only the job_id that generate_ideas returned for a confirmed batch and never a run reference. task.run_status is only the status poll for one agent run's own run_id (the run_id gen_ask/gen_analyze hand back); it never reads a saved run's ideas — a run reference in a content question is content.ideas run_id. billing.usage reports what was spent and the remaining quota this period; billing.generation_access says whether a generation type is allowed for this workspace. billing.receipt is one run's billed charges with each amount and the run total ('what did run X cost' / 'prove the charges for this run', exact run_id required); it reads the bill and never changes it. 'am I out of X this month' / 'how much have I used' is billing.usage, not billing.balance. 'Who can see / who can access X' is platform.organization (workspace visibility), not a vidsheet read. 'What did my watchlist say/find/summarize about X' is gen_watchlist_action query_watchlist (it starts a run and returns a run_id) — never a watchlist discover read; watchlist.list/detail only enumerate saved watchlist records. 'Who is on this workspace and what is their role' is platform.members; 'who has this agent been shared with' is agent.shares. agent.profile_photos lists the agent's own profile photos (the agent profile photo is set with gen_agent_action set_primary_photo) — never characters: a character (a person with looks and talking characters) is gen_characters. 'What is being monitored for this agent, and is anything paused for credits?' is agent.monitoring (each target's source, active vs paused-for-funding, last scrape). Two halves: ingredient cells (columns/rows/row/cell/variables) feed a row; video (video_settings + layers) composes the output. Agent choice: agent.list is the only agent-id lookup — when an agent-scoped view needs an agent and the conversation has not already named one, list the agents and ask the user which to use, never guess. This tool only reads and never edits or generates. Ideas, scripts, trends and stats come only from GEN calls: never invent them, call GEN.
Send feedback about GEN (a bug, an idea, praise) from the user to the GEN team. Call it whenever the user wants to report a problem, complain, suggest something or say thanks. Pass the user's words verbatim in message. The agent, the recent GEN calls of this session and the client are attached automatically; never ask the user for them. Always relay the returned thank-you to the user.
| Argument | Type | Description |
|---|---|---|
| rating | any | An optional satisfaction rating from 1 to 5. |
| message* | string | The user's feedback, in their own words. |
| agent_id | any | The agent this feedback is about, when the user names one. |
| category | any | What kind of feedback this is. Defaults to other. |
| conversation_id | any | The conversation the feedback came from, when the client knows it. |
{
"type": "object",
"required": [
"message"
],
"properties": {
"rating": {
"anyOf": [
{
"type": "integer",
"maximum": 5,
"minimum": 1
},
{
"type": "null"
}
],
"default": null,
"description": "An optional satisfaction rating from 1 to 5."
},
"message": {
"type": "string",
"description": "The user's feedback, in their own words."
},
"agent_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The agent this feedback is about, when the user names one."
},
"category": {
"anyOf": [
{
"enum": [
"bug",
"idea",
"praise",
"other"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "What kind of feedback this is. Defaults to other."
},
"conversation_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The conversation the feedback came from, when the client knows it."
}
},
"x-gen-delegation": {
"actions": [],
"excluded_actions": []
},
"additionalProperties": false
}Create media with GEN: generate an image (create_image), a video clip (create_video), an original song (create_song), a DJ-style song mix (create_song_mix), or transcribe audio or video into text (transcribe). One call carries one or more typed actions. Paid generations spend credits and each result carries generation_id, user_job_id and estimated_credits — poll the gen_discover generation view with generation_id until completed. create_image/create_video/create_song/create_song_mix/transcribe is the first call for those verbs (transcribe = any audio/video→text request, create_video = 'narrate a slideshow / make a video' — a plain narration/render belongs here, while a layered sheet/canvas edit is gen_vidsheet_action, create_song = 'make a song') — do not read gen_discover to find a resource, avatar or job first. Output is a standalone asset in the agent's library, not placed in a Vidsheet cell; to generate into a cell or layer use gen_vidsheet_action op=generate with creation_card_type. Narration/voiceover of a video goes to gen_generate create_video, not a vidsheet cell op, unless the user names a sheet cell. The legacy media tool names are retired; use this dispatcher.
| Argument | Type | Description |
|---|---|---|
| actions* | array | One or more typed media actions: create_image (prompt, optional version/aspect_ratio/number_of_images/reference_images/content_resource_ids) | create_video (prompt, optional model/aspect_ratio/resolution/duration/native_audio/reference_images) | create_song (prompt, optional model/duration/style/title/negative_tags/vocal_gender/instrumental/source_audio) | create_song_mix (tracks REQUIRED: at least two of {title|url|asset_id}; optional prompt/transition_style/output_format/auto_order/desired_duration_seconds/generate_missing_count) | transcribe (exactly one of audio_url/video_url/content_resource_id, optional trim window) |
| no_paid | boolean | Refuse paid media generation for this run. Text and LLM work still bills normally. |
Compose the weekly We Believe report's source-grounded ideas through the one billed content-ideas generator (the same path gen_content_action generate_ideas uses; this tool never calls a model directly). The caller injects the master playbook text, the measured comments and the verified first-party reference corpus with explicit freshness. The playbook text, the selected comment and the relevant verified references and peer evidence ground the one billed generation. This tool selects the unused comments at or above the like floor inside the rolling half-open window, runs one confirmed count=1 generation per selected comment with a stable idempotency key, reads exactly one saved idea back by that run's full run_id, and attaches the caller-known source identity and the approved alignment references. It never trusts a source key or citation the model echoes back. A missing, ambiguous or wrong-cardinality run refuses the whole build and leaves the last-good report untouched, and a credit refusal starts no generation. Ideas, scripts, trends and stats come only from GEN calls: never invent them, call GEN.
| Argument | Type | Description |
|---|---|---|
| count* | integer | How many report ideas to compose (at most one per selected comment) |
| sources* | array | Measured Instagram/TikTok comments; each carries its stable source_key, platform, url, text, likes, published_at, aliases and the master-playbook principle it serves |
| agent_id* | string | The agent ID the report ideas belong to (envelope; the generation is billed to it) |
| period_end | any | Window end instant (ISO 8601 UTC); defaults to now |
Workspace and access admin for an agent: create, rename, or delete an organization (create_organization, update_organization, delete_organization), upgrade its workspace plan (upgrade_workspace), manage its Personal Access Tokens (create_api_key, update_api_key, revoke_api_key, revoke_all_api_keys), set per-conversation session preferences (update_session_preferences), and back up GEN assets to Walrus for Proof of Genesis (create_proof_of_genesis_backup, remove_proof_of_genesis_backup). One call carries one or more typed actions. Deleting an organization, revoking all API keys, and upgrading a workspace are irreversible or spend money — always confirm with the user first. create_organization/update_organization/create_api_key/revoke_api_key act on the named workspace or key — call this tool first even when the id or new value is not yet known, and do not reply with a question before calling; the action names the missing field. Do not inventory organizations or api_keys with gen_discover first. Read-only platform views are gen_discover domain=platform (me | organization | organizations | conversation | conversations | preferences | api_keys | backups | members); this family's branch fields are gen_discover domain=platform view=actions (target=<branch action>). Workspace membership and roles are owner/manager-gated (invite_member, set_member_role, remove_member, leave_workspace); transfer_workspace_ownership, start_seat_checkout and upgrade_workspace return a CONFIRMATION_REQUIRED preview and confirm first. The first sign-in email of an agent-created account is added with request_email_link_code(email) then verify_email_link_code(request_id, code): the API emails a six-digit code, ask the user to read it from their inbox and pass it as a TEXT string, using resend_email_link_code(request_id) if it did not arrive. GEN never reads the inbox and never emits a code. Only an account with no email and no linked identity can link one; an account that already has an email or Google sign-in is refused with reauthentication_required, and that change is made in the browser profile (gen_sign_in_link opens it). The legacy platform tool names are retired; use this dispatcher.
| Argument | Type | Description |
|---|---|---|
Step 5 (Export & Publish): Ship posts to social platforms — schedule, publish, update, or remove posts. One call carries one or more typed actions: schedule_post_<platform> (media_url and that platform's fields; schedule_type 'now' or 'specific_time' with scheduled_time; a field of another platform is rejected) | publish_content (platform + media_url + description + schedule_type) | update_scheduled_post (post_id + fields) | delete_scheduled_post (post_id) | update_published_post (post_id + at least one of title/description/tags/category_id) | delete_published_post (post_id; removes a post that is ALREADY LIVE and is two-phase — resend with confirm_token) | disconnect_social (platform; disconnects that account and is two-phase — resend with confirm_token). Reconnecting or refreshing an account is gen_discover publish.connect_url only — never disconnect_social first; connecting again replaces the old token. Publishing is irreversible: confirm destination and content with the user first. Do NOT edit videos here — the vidsheet action owns the canvas, and it is never the ship path. publish_content / schedule_post_<platform> / disconnect_social is the first call for those verbs, even when the user says 'all connected socials' or has not attached the post content yet — publishing resolves the connected accounts and the action names any missing media_url/description; 'disconnect my <platform>' is disconnect_social here, never a publish.connections read. Setting which platforms the agent posts to — 'make me post on YouTube and TikTok' with no content or schedule to ship — is gen_agent_action set_profile target_platforms, not schedule_post here. Read gen_discover publish.connections or publish.rules only when the user asks what is connected or what a rule is, not before publishing or disconnecting. Publishing is asynchronous even for 'now' — poll the gen_discover publish.post_status view with the returned post_id. The legacy publish tool names are retired; use this dispatcher. platform: tiktok | instagram | facebook | youtube | x | linkedin. Per-platform scheduling rules (also the gen_discover publish.rules view): tiktok: media required, video/image, 1 item, text <= 2200 chars; requires tiktok_privacy_level, tiktok_disable_comment, tiktok_disable_duet, tiktok_disable_stitch instagram: media required, video/image, up to 10 items, text <= 2200 chars; options via instagram_music (mode, track_url) facebook: media required, video, 1 item, text <= 63206 chars; title <= 255 chars youtube: media required, video, 1 item, text <= 5000 chars; title <= 100 chars; requires title; options via youtube_options (category_id, made_for_kids, notify_subscribers, shorts, tags, visibility) x: text or media, video/image, up to 4 items, text <= 280 chars linkedin: text or media, video/image/document, up to 9 items, text <= 3000 chars; title <= 400 chars; options via linkedin_options (alt_text, carousel, visibility) Update a post that is ALREADY LIVE via update_published_post — fix a typo, retitle, change tags or category. What each platform can still change once published: tiktok: no post-publication edit instagram: no post-publication edit facebook: no post-publication edit youtube: title, description, tags, category_id x: no post-publication edit linkedin: description Sparse: send only the fields you want changed and every other field on the live post is preserved. The reply carries one result per platform: `updated` (with the readback), `unsupported_after_publish` (the network has no edit path — nothing was touched), `reauthorization_required` (the user must reconnect that account) or `failed` with the platform's reason. Delete a post that is ALREADY LIVE via delete_published_post — it is two-phase: the first call previews and returns a CONFIRMATION_REQUIRED confirm_token, and only the exact retry presenting that token deletes. The reply carries one result per platform: `deleted`, `already_deleted` (GEN already removed it), `unsupported_after_publish` (the network has no delete path — nothing was touched), `reauthorization_required` (the user must reconnect that account) or `failed` with the platform's reason. timezone_offset on schedule_post_<platform> is the local UTC offset in hours (e.g. -7 for LA daylight); on publish_content it is minutes.
Create a one-time GEN sign-in link for the caller's own account so its owner can open GEN in a browser. Requires the self-serve account owner's agent PAT. Use it when the user asks to sign in to GEN, open GEN, or get into the agent-created account from this client. For a plan or credit-pack checkout, use gen_billing_action open_checkout instead; Stripe needs no GEN browser sign-in. Pass the GEN URL they should land on, for example 'https://gen.pro/projects/123?view=editor#clip'; the same path, query and anchor are kept in the link. The link is valid for five minutes and works once, so treat it as a private handoff for the intended user alone: never post it publicly or send it to anyone else, because whoever opens it first signs in as this account. GEN applies its normal browser access checks when the link is opened, and the browser profile popup then offers to add an email address or link a Google account.
| Argument | Type | Description |
|---|---|---|
| url* | string | The GEN URL the signed-in browser should land on, e.g. https://gen.pro/projects/123?view=editor#clip |
{
"type": "object",
"required": [
"url"
],
"properties": {
"url": {
"type": "string",
"description": "The GEN URL the signed-in browser should land on, e.g. https://gen.pro/projects/123?view=editor#clip"
}
},
"x-gen-delegation": {
"actions": [],
"excluded_actions": []
},
"additionalProperties": false
}Run the task control plane: create, update, pause, resume, delete, duplicate, and run-now recurring jobs ('daily tasks' — a schedule plus a saved prompt), manage content-monitoring jobs, and approve or reject a gated agent run (decide_agent_run). One call carries one or more typed actions. pause_recurring_job/resume_recurring_job/delete_recurring_job act on the named job (update_recurring_job too) — call this tool first even when the job is only described ('my weekly report job'): name it by job_id OR by its exact display name (name; current_name on update_recurring_job, where name is the new title). Do not list jobs via gen_discover task.list first. The API resolves the name: several tasks with that name refuse with AMBIGUOUS_TASK_NAME and list candidates, so retry with one job_id; no match is NOT_FOUND. delete_recurring_job is two-phase: the first call only previews and returns a confirm_token; resend the same call with it to delete. Task results carry the API's card (a task_node with name, schedule_text, status, task_id) — show it. create_recurring_job answers reused=true when the task already exists (say it is already set up, do not report a new task) and conflict.fields when the request differed from the existing task (offer update_recurring_job). Hourly is a supported cadence; an unsupported cadence refuses with CADENCE_UNSUPPORTED and a suggested cadence. Read-only task views are gen_discover domain=task (list | job | run_status); this family's branch fields are gen_discover domain=task view=actions (target=<branch action>). The legacy task tool names are retired; use this dispatcher.
| Argument | Type | Description |
|---|---|---|
| actions* | array | One or more typed task actions (agent_id rides the envelope, never inside entries): create_recurring_job (job_type, prompt, optional name/schedule/delivery/next_run_at) | ensure_default_recurring_job | update_recurring_job (job_id + optional name/prompt/schedule/delivery/next_run_at) | pause_recurring_job (job_id) | resume_recurring_job (job_id) | delete_recurring_job (job_id) | run_recurring_job_now (job_id) | duplicate_recurring_job (job_id, vidsheet_url, optional name/activate) | create_monitoring_job (platform, search_type, value + optional days/max_results/monitoring/comment_monitoring) | update_monitoring_job (job_id, platform, search_type, value + same optionals) | decide_agent_run (run_id, approved) | list_grants | revoke_grant (grant_id) |
Upload a file into an agent's owned asset library without sending the bytes through the MCP call. One tool, three phases. phase=request_upload (default) takes agent_id, filename and content_type and returns upload_id, a same-origin signed PUT URL, a ready-to-run curl command and a browser drop_url; the signed capability expires in about 5 minutes and is single use. phase=create_drop returns the same thing framed for a browser when a client cannot run curl or hand over a host file. phase=status takes upload_id and returns the owned asset (id, url, filename, content_type, byte_size, checksum) once the bytes have landed, or an honest pending/unknown/expired/failed state. Claude and other sandboxed clients: put the bytes with the returned curl from the client sandbox. That requires mcp.gen.pro to be allowed in the Organization's Capabilities settings; change no customer setting, and use phase=create_drop if the PUT is blocked. Grok/Muse: there is no assumed laptop or sandbox path — use phase=create_drop. Local CLI: run the returned curl against a file you already have; the server never reads a path you name. ChatGPT and hosts that supply a file parameter: pass `file` with download_url, file_id and optionally mime_type/file_name; the server fetches it from the allow-listed host and returns the owned asset. Native file references are limited to 10 MiB; use create_drop for larger files. If the host gives no downloadable reference (or a 'chat_upload' placeholder), this answers with a create_drop fallback instead of guessing. Never send file bytes, a base64 blob or a local filesystem path through this tool.
| Argument | Type | Description |
|---|---|---|
| file | any | A host-provided file reference {download_url, file_id, optional mime_type/file_name}, or the host's placeholder string. The server fetches download_url; never a local path. |
| phase | string | request_upload: mint a signed PUT URL and curl. create_drop: the same, framed for a browser drop page. status: read the owned asset for an upload_id. |
Vidsheet: skill://gen/vidsheet-mcp/SKILL.md; host-approved resources/read or prompt vidsheet-mcp. Step 4 (Edit & Generate): the Vidsheet write tool for the editable video workspace. A direct saved idea draft/full uses gen_content_action action=create_video_from_idea; a separately authored scene-form storyboard uses apply_storyboard on one owned row. Generic create_sheet/actions[] create must not receive an idea_id. Discover template_slug with gen_discover vidsheet view=templates. Flat ops: create_sheet, clone_template, create_engine, duplicate_sheet, import_asset, validate_layout, continue_generation, refund_unused_output (service-only; completed output never delivered by an errored build; Rails owns eligibility and refund amount; requires agent_id, generation_id and idempotency_key), stop_generation (the provider may keep rendering and billing after an unconfirmed stop), add_column, set_cell, add_layer, update_layer and generate. apply_storyboard is MCP-only: applies a BuildPlanV1 to an owned row with read-back. Requires agent_id, vidsheet_id, storyboard, idempotency_key and row_id or row_position; recover=true reads without writes. A talking-head video from an existing avatar is the job card video_from_avatar (avatar_id + video_url + audio_url); the FE card video-from-talking-avatar generates a new talking-avatar video from a script and a voice — use video_from_avatar for a talking-head from an avatar, video-from-talking-avatar only when the user gives a script/voice or names that card. duplicate_sheet (name renames the copy) supports target_agent_id cross-agent copies. add_column validates position; set_cell validates media/take/song bindings and refuses job cards; add_layer/update_layer keep layer_row placement; trims send userHasTrimmed=true. Other edits use canonical actions[]; Rails validates with indexed errors. A row's column content (POST DESCRIPTION, IDEA, SCRIPT, any text or media cell) is a cell: update target {kind:'cell', vidsheet_id, row_id, column_id} (or the cell id) with values.value; row targets only take position, row_height and video_settings. Use gen_discover(domain='vidsheet', view='actions') for the full action schema. Card fields come from gen_discover view=card_schema. Creation-card generate accepts FE cards; job cards: sound_matching (overlays or row_id), recommend_song (audio_url — a PAID cover/remix of that one reference track, not a recommendation: for suggested songs read gen_discover view actions audio_library=recommended), song (prompt and duration, default 240), video_from_avatar and source_video_analysis. A whole column generates with the envelope {"action":"generate","target":{"kind":"column","vidsheet_id":..,"id":<column id>}}; Rails quotes the total first, refuses when credits cannot cover it, and returns per-row dispatched/failed/skipped. Prompt preview: creation_card_inputs.<text field>.ai.previewOnly=true; retry with the same idempotency_key while generating. Callers may delete layers, rows, cells and columns in Vidsheets they can edit. UI clients receive Rails' two-phase confirmation preview; headless clients send auto_confirm=true with each delete on its own to complete Rails' content-bound confirmation in one tool call. Export/render the final video = op generate, creation_card_type final-video, target the row's FINAL VIDEO cell; poll with gen_discover generation. This renders the VIDEO, not spreadsheet CSV export (envelope 'export' → Vidsheets::CsvExport). creation_card_inputs is optional; omitted, the row's layers build it. Call generate first for 'generate the intro' / 'talking-head' / 'title card', before reading the sheet — a 'title card' is creation_card_type text. Narration/voiceover of a video goes to gen_generate create_video, not a vidsheet cell op, unless the user names a sheet cell. A draft build or any edit that must not start paid dependent regeneration sends auto_regenerate=false: the batch performs only its writes, and Rails answers auto_regeneration: 'skipped'.
Build a custom voice for an agent: clone one from an audio sample (clone_voice), design one from a scripted prompt flow (generate_voice_script, generate_voice_description, generate_voice_samples, design_voice), audition one with a spoken preview (preview_voice), or remove one you own (delete_voice). One call carries one or more typed actions. Deleting a voice is permanent — confirm which voice first. clone_voice/design_voice is the first call for 'clone/design my voice' — call it even if the user has not attached the sample yet; the action names the missing field to supply next. Do not inventory voices via gen_discover voice.mine first. Output is a standalone asset in the agent's library, not placed in a Vidsheet cell; to generate into a cell or layer use gen_vidsheet_action op=generate with creation_card_type. Read-only voice views are gen_discover domain=voice (list | mine | resource | preview_status | sample_status); this family's branch fields are gen_discover domain=voice view=actions (target=<branch action>). The legacy voice tool names are retired; use this dispatcher.
| Argument | Type | Description |
|---|---|---|
| actions* | array | One or more typed voice actions: clone_voice (name, optional audio_url/audio_base64/gender/language/description) | design_voice (generation_id, name, REQUIRED sample audio: audio_base64 (the Rails base64_audio, required for fal voice resources) or audio_url, optional gender/language/description) | delete_voice (voice_id) | preview_voice (voice_id, text) | generate_voice_description (gender, optional voice_description/language/script) | generate_voice_samples (text, optional description) | generate_voice_script (optional language) |
| agent_id | any | The agent ID that owns the voices (envelope; routed into every branch) |
| confirm_token |
Run one or more watchlist operations in a single call: create, update, pause, resume or delete a watchlist, add or remove a monitoring source, or ask a question about a watchlist (query_watchlist starts an agent run and returns a run_id to poll). One call carries one or more typed actions. Deleting a watchlist or removing a source is destructive — confirm with the user first. delete_watchlist is two-phase like the vidsheet deletes: the first call returns a CONFIRMATION_REQUIRED preview with a single-use confirm_token and deletes nothing; resend the same call with that confirm_token to delete. remove_watchlist_source is two-phase the same way. Every branch that acts on one watchlist takes watchlist_id, or watchlist_name (a display name or its @list mention slug) as an alternative: a case-insensitive exact name or an equal @list mention slug as one candidate set, then a unique prefix. An ambiguous name returns the candidate watchlists and changes nothing. Any question about a watchlist ('what did my watchlist say…', 'summarize it', 'did it find anything') is query_watchlist and is the first call — it starts a run; gen_discover watchlist.list only enumerates saved watchlist records. Listing and fetching watchlists are gen_discover domain=watchlist (list | detail); this family's branch fields are gen_discover domain=watchlist view=actions (target=<branch action>). The legacy watchlist tool names are retired; use this dispatcher.
| Argument | Type | Description |
|---|---|---|
| actions* | array | One or more typed watchlist actions: create_watchlist (name, optional sources/project_id/conversation_id/created_by_run_id) | update_watchlist (watchlist_id or watchlist_name, optional name/project_id/rails_project_error) | pause_watchlist (watchlist_id or watchlist_name) | resume_watchlist (watchlist_id or watchlist_name) | delete_watchlist (watchlist_id or watchlist_name; two-phase, resend with confirm_token) | add_watchlist_source (platform, target_type, target_value, watchlist_id or watchlist_name, optional original_display_value) | remove_watchlist_source (watchlist_id or watchlist_name, source_id or platform+target_type+target_value; two-phase, resend with confirm_token) | query_watchlist (question, watchlist_id or watchlist_name, optional days/limit/sort_by/min_engagement_rate/return_all). watchlist_name (a display name or its @list mention slug) resolves case-insensitively: an exact name or an equal slug as one candidate set, then a unique prefix; an ambiguous name returns the candidates and changes nothing. 'what did my watchlist say/find about X' = query_watchlist (it starts a run); gen_discover watchlist list/detail only enumerate saved watchlist records. |
| Argument | Type | Description |
|---|---|---|
| actions* | array | One or more typed analysis actions: collect (the typed collection seam — targets [{platform, scope, target}] over scope user|hashtag|keyword|search|url|id|asset|account|creators|comments|sounds|ads and platform tiktok|instagram|youtube|pinterest|twitter|kick|twitch|meta_ads|tiktok_ads (x is an accepted alias for twitter; omit platform for scope asset; it defaults to asset; for scope url, omit it or pass "auto" — the DW resolves the pasted URL's platform itself), optional platform (the default for any target that names none), count (a positive integer, or "all" for every stored row), window {days}, filters GEN-3096 object, sort recent|views|likes|engagement, freshness live (the default) or cache_then_live_deficit (cache_then_live_deficit serves stored rows free and fetches only the missing count live; cache_only is refused), rollups, options {scrape_type}, deadline_ms (the caller's remaining budget; the admitted deadline_ms is computed per caller class), run_id (forwarded as the DW billing run id), enrich "full" (wait for the DW to fully process every row — transcript, hooks, visual analysis — then answer GEN's written analysis plus one display card per row; never caption-only rows), include [transcript|hooks|visual_description|description|stats|hashtags|media_type|video_url] (the per-row fields each row may carry — transcript/hooks/visual_description/description/stats are the enriched per-video fields, hashtags adds the provider's raw hashtag array as provider_hashtags_raw, media_type rides every collected row anyway, and video_url exposes the row's observed canonical first-party hosted media URL (assets.video_url) as a playable link, null when the DW mirrored none; by default the enriched fields stay server-side and only the display cards + written analysis reach the caller)); ONE synchronous DW call answered as model-visible evidence + a per-target coverage summary + result cards (video/post → video_grid, creator/account → creator_grid, sound → song_list, comment → comment_cluster, asset → table) — normally no job id and no PENDING, except a walk that reaches the admitted deadline: that answers a typed PENDING receipt naming its durable job id and idempotency_key (poll it with gen_discover domain=social view=job job_id=..., or retry the same collect with that idempotency_key — the retry resolves to the same job and never charges twice), and enrich "full" which waits and answers a PENDING receipt (collect_enrichment_status {job_id} polls it) when its budget expires; it replaces the older social-data branches below and is the first pick for any social data pull) | collect_enrichment_status (job_id required, include optional — poll one full-enrichment collect job by the job_id its PENDING receipt named, in the same shape as enrich "full"; while the job runs the receipt relays the rows already enriched as partial_rows and says how many are enriched so far) | trends | hooks (query required, mode hashtag|keyword|niche|handle, target, platform tiktok|instagram|youtube|kick, filters CommonFilters bundle, relevance_query, raw, idempotency_key (<=255; reuse it on a retry to replay the same job)) | creators (same shape, mode keyword|handle only) | comments (one of query/video_ids/creator/hashtag, optional sentiment positive|neutral|negative, days, limit, platform tiktok) | report (window 1|7|30, optional limit) | research_web (query required, optional mode news|social|web|all and research-source platforms x|news|web|reddit, reddit_subreddits, days, limit, save, idempotency_key (<=255, save:false only; reuse it on a retry to replay the same job); save:true persists the run as a Research Warehouse brief, save:false/omitted is one-shot; mode social is the community sources, X and Reddit; Reddit research carries its subreddit scope through the same one-shot analysis job as X/news/web, and a reddit.com URL or Reddit collect target is answered as research rather than a DW collection) | video_analysis (video_url: a social link or public HTTPS .mp4/.mov/.webm/.m4v/.mkv file; include_video_analysis=true watches framing, shots and timing without creating clips or drafts; false requests social metadata only) | clip_moments (only when clips are requested; sources: 1–10 social links, public HTTPS video files, GEN asset URLs, or numeric GEN video IDs; optional clip_count 1–10 (omit it and the engine makes one clip per 3 minutes of source, capped at 10 with the cap disclosed; an explicit count wins), positive min_duration_s/max_duration_s/target_final_max_duration_s/playback_speed, mode viral_moments|summarize, presentation source_clip|floating_head|split_screen, output_aspect_ratio 9:16|16:9|1:1, smart_reframe, enrich; each clip returns its persisted idea_id; one paid POST returns per-source clips and is never automatically retried) | layer_analysis (one vidsheet video layer or audio/ingredient media cell: vidsheet_id + cell_id, plus layer_id for a layer; video and audio only, images refused; the layer's own media URL goes to the attributed GENGEMINI boundary as ONE synchronous generateContent call running the approved DW prompt for that media kind, and the answer is projected at 30 fps: scene cuts, dead head/tail spans, suggested trim in/out and a description per segment — no job to poll. Analysis runs and bills on the first call; a valid legacy confirm_token remains accepted) | research_scrape (source: platform tiktok|instagram|youtube|x/twitter|pinterest|kick|web or any public URL, input naming the scrape target — keyword | hashtag | username | user URL on pinterest (x serves user targets only; pinterest user walks take cursor), keyword/hashtag/userPageURL/video_url on tiktok/instagram/youtube/kick, page url/asset_types/limit/query on web — plus max_items (a stray confirm_token is accepted and ignored); success returns the scraped rows and billing) | web_asset_scrape (public-page url, asset_types, limit, query, optional import_assets through gen_asset_action; runs and bills on the first call, optional legacy confirm_token) | import_urls (paid first-call URL-to-S3 import: platform tiktok|instagram|youtube + videos_urls public URLs, capped at 50 per call, writes S3 and bills on the first call; from_db=true/from_db_only=true refuse as stored-only-unavailable) | apify_scrape (billed first-call external-records run: actor_id names one approved provider actor and input is that actor's own run input, capped by max_items; returns the dataset rows and billing) | analyze_socials (DEPRECATED — superseded by collect; still served: paid social write: a social target platform/mode/target for a live social.posts scrape, or a wide scope platform plus one of keyword/hashtag/userPageURL/video_url for the DW general scrape; Twitch and Kick channel/VOD URLs are served, a Kick or Twitch mode + target resolves to that scope, and Kick/Twitch keyword/hashtag scopes forward to the DW, whose own provider path answers the scopes it does not serve; videoMonitoring forwards unchanged) | search_posts (DEPRECATED — superseded by collect; still served: keyword required; optional platforms [] and the Common GEN-3096 filters — days, posted_after, posted_before, min_/max_ engagement and save counts and rates, min_/max_followers, content filters (min_/max_duration, language, country, location_query, is_paid_partnership, media_type, has_music, is_faceless_video, category), transcript_search, visual_search, hook_search, comment_search, sort_by, sort_direction, cursor, limit, sample_limit, from_db) | analyze_account (DEPRECATED — superseded by collect; still served: username required, platform tiktok|instagram|youtube|twitter|x|linkedin; url is the non-TikTok followers lookup target) | transcribe (DEPRECATED — superseded by collect url/id; still served: platform tiktok|instagram|youtube with video_ids — TikTok ids, Instagram post ids, YouTube URLs — and/or hashtags, optional num_posts, from_db, force, mode online|batch defaulting to batch above 20 ids) | transcribe_status (DEPRECATED — superseded by collect url/id; still served: video_ids) | upload_by_ids (video_ids, optional force) | comments_online (DEPRECATED — superseded by collect comments; still served: video_ids, optional count — the live fetch beside the cached social.comments read) | monitor_status (platform + exactly one of username/hashtag) | aura_user_stats (emails + environment) | sounds (DEPRECATED — superseded by collect sounds; still served: view option: sounds_by_niche | sounds_by_creator | rising_sounds | sound_performance | sound_arbitrage | music | trending_sounds | sound_info; each view takes its own endpoint fields — min_videos, creator/username, recent_days/baseline_days/min_recent_videos/min_baseline_videos, platform/audio_id/days/group_by/limit_top_videos, min_niche_videos/min_global_videos/min_lift/metric, genre/mood/theme/tags/limit/offset, periods/Top_k/country, audio_id — plus the common GEN-3096 filters object) | chart (FREE; exactly one of data {labels, series [{name, values}]} charted as given, or source {job_id, group_by, metric, agg count|sum|avg|max} aggregated from a finished analysis job's rows — group_by "day"|"week"|"month" buckets the row's timestamp by UTC date (week = its Monday); optional type bar|line, title; a running job answers PENDING, never an empty chart) | analytics (view option: aggregate | sleepers | posting_times — by_demographics is owner-removed; group_by/metrics/histograms, ratio/min_ratio, timezone/metric/group_by plus the same filters object). Paid DW writes and research_scrape execute on the first call — confirmation happens in the FE and a stray confirmed/confirm_token argument is accepted and ignored; web_asset_scrape runs and bills on the first call; a valid legacy confirm_token remains accepted. Demographic filters are rejected. wait is optional per entry. meta_ads and tiktok_ads are paid advertising platforms served by the DW's one ads lane over scope ads|keyword|user|id (scope ads takes a target object with exactly one of query/advertiser_id/ad_id plus optional country and status, and is forwarded verbatim; the alias scopes take a plain string: keyword->query, user->advertiser page id, id->ad id). That lane is what keeps an ad id from ever dispatching organic TikTok/Instagram retrieval. meta_ads serves live and cached ads; tiktok_ads is cache-only, so a live freshness reaches an unsupported coverage entry and never falls back to Meta or organic retrieval. enrich "full" is refused for every ads target: DW full enrichment selects video entities only and can never enrich an ad, so opt in to one creative's analysis with gen_asset_action analyze instead. |
| agent_id* | string | The agent ID that owns the workspace (envelope; the billing subject — the analysis run is billed to this agent, no anonymous path) |
{
"type": "object",
"required": [
"agent_id",
"actions"
],
"properties": {
"actions": {
"type": "array",
"items": {
"oneOf": [
{
"type": "object",
"required": [
"action",
"view"
],
"properties": {
"view": {
"enum": [
"aggregate",
"sleepers",
"posting_times"
],
"type": "string"
},
"wait": {
"type": "boolean",
"default": null
},
"ratio": {
"enum": [
"engagement_rate_1d_vs_7d",
"views_1d_vs_7d",
"avg_daily_engagement_rate_vs_category"
],
"type": "string",
"default": null
},
"action": {
"const": "analytics"
},
"metric": {
"enum": [
"post_count",
"views",
"likes",
"comments",
"engagement_rate",
"save_rate"
],
"type": "string",
"default": null
},
"filters": {
"type": "object",
"default": null,
"additionalProperties": true
},
"metrics": {
"type": "array",
"items": {},
"default": null
},
"group_by": {
"anyOf": [
{
"enum": [
"hour_of_day",
"day_of_week",
"hour_of_week"
],
"type": "string"
},
{
"type": "array",
"items": {
"enum": [
"hour_of_day",
"day_of_week",
"hour_of_week",
"platform",
"category",
"creator"
],
"type": "string"
}
}
],
"description": "The dimension to group by. posting_times: one of hour_of_day | day_of_week | hour_of_week (a string or a single-item list). aggregate: a list of platform | category | creator. sleepers takes no group_by."
},
"timezone": {
"type": "string",
"default": null
},
"min_ratio": {
"type": "number",
"default": null
},
"histograms": {
"type": "array",
"items": {},
"default": null
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"username"
],
"properties": {
"url": {
"type": "string",
"default": null
},
"action": {
"const": "analyze_account"
},
"platform": {
"enum": [
"tiktok",
"instagram",
"youtube",
"twitter",
"linkedin"
],
"type": "string",
"default": null
},
"username": {
"type": "string"
}
},
"additionalProperties": false
},
{
"type": "object",
"anyOf": [
{
"required": [
"keyword"
]
},
{
"required": [
"hashtag"
]
},
{
"required": [
"userPageURL"
]
},
{
"required": [
"video_url"
]
},
{
"required": [
"mode",
"target"
]
}
],
"required": [
"action"
],
"properties": {
"days": {
"type": "integer",
"default": null
},
"mode": {
"type": "string",
"default": null
},
"wait": {
"type": "boolean",
"default": null
},
"limit": {
"type": "integer",
"default": null
},
"action": {
"const": "analyze_socials"
},
"cursor": {
"type": "integer",
"default": null
},
"target": {
"type": "string",
"default": null
},
"from_db": {
"type": "boolean",
"default": null
},
"hashtag": {
"type": "string",
"default": null
},
"keyword": {
"type": "string",
"default": null
},
"platform": {
"type": "string",
"default": null
},
"confirmed": {
"type": "boolean",
"default": null,
"description": "Accepted and ignored: this branch executes on the first call — confirmation happens in the FE. Sent only by old callers."
},
"min_count": {
"type": "integer",
"default": null
},
"video_url": {
"type": "string",
"default": null
},
"scrape_type": {
"type": "string",
"default": null
},
"userPageURL": {
"type": "string",
"default": null
},
"last_num_videos": {
"type": "integer",
"default": null
},
"videoMonitoring": {
"type": "boolean",
"default": null
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"actor_id",
"input"
],
"properties": {
"wait": {
"type": "boolean",
"default": null
},
"input": {
"type": "object",
"additionalProperties": true
},
"action": {
"const": "apify_scrape"
},
"actor_id": {
"type": "string"
},
"max_items": {
"type": "integer",
"default": null,
"maximum": 200,
"minimum": 1
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"emails",
"environment"
],
"properties": {
"action": {
"const": "aura_user_stats"
},
"emails": {
"type": "array",
"items": {}
},
"environment": {
"type": "string"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action"
],
"properties": {
"data": {
"type": "object",
"default": null,
"additionalProperties": true
},
"type": {
"enum": [
"bar",
"line"
],
"type": "string",
"default": null
},
"title": {
"type": "string",
"default": null
},
"action": {
"const": "chart"
},
"source": {
"type": "object",
"default": null,
"additionalProperties": true
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"sources"
],
"properties": {
"mode": {
"anyOf": [
{
"enum": [
"viral_moments",
"summarize"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"action": {
"const": "clip_moments"
},
"enrich": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null
},
"sources": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 10,
"minItems": 1
},
"clip_count": {
"type": "integer",
"default": null,
"maximum": 10,
"minimum": 1
},
"presentation": {
"anyOf": [
{
"enum": [
"source_clip",
"floating_head",
"split_screen"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"smart_reframe": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null
},
"max_duration_s": {
"anyOf": [
{
"type": "number",
"exclusiveMinimum": 0
},
{
"type": "null"
}
],
"default": null
},
"min_duration_s": {
"anyOf": [
{
"type": "number",
"exclusiveMinimum": 0
},
{
"type": "null"
}
],
"default": null
},
"playback_speed": {
"anyOf": [
{
"type": "number",
"exclusiveMinimum": 0
},
{
"type": "null"
}
],
"default": null
},
"idempotency_key": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"source_end_seconds": {
"anyOf": [
{
"type": "number",
"exclusiveMinimum": 0
},
{
"type": "null"
}
],
"default": null
},
"output_aspect_ratio": {
"anyOf": [
{
"enum": [
"9:16",
"16:9",
"1:1"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"source_start_seconds": {
"anyOf": [
{
"type": "number",
"minimum": 0
},
{
"type": "null"
}
],
"default": null
},
"target_final_max_duration_s": {
"anyOf": [
{
"type": "number",
"exclusiveMinimum": 0
},
{
"type": "null"
}
],
"default": null
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"targets"
],
"properties": {
"sort": {
"enum": [
"recent",
"views",
"likes",
"engagement"
],
"type": "string",
"default": null
},
"count": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string",
"const": "all"
}
],
"default": null
},
"action": {
"const": "collect"
},
"enrich": {
"type": "string",
"const": "full",
"default": null
},
"run_id": {
"type": "string",
"default": null
},
"window": {
"type": "object",
"default": null,
"additionalProperties": true
},
"filters": {
"type": "object",
"default": null,
"additionalProperties": true
},
"include": {
"type": "array",
"items": {
"enum": [
"transcript",
"hooks",
"visual_description",
"description",
"stats",
"hashtags",
"media_type",
"video_url"
],
"type": "string"
},
"default": null
},
"options": {
"type": "object",
"default": null,
"additionalProperties": true
},
"rollups": {
"type": "array",
"items": {},
"default": null
},
"targets": {
"type": "array",
"items": {
"type": "object",
"required": [
"scope",
"target"
],
"properties": {
"scope": {
"enum": [
"user",
"hashtag",
"keyword",
"search",
"url",
"id",
"asset",
"account",
"creators",
"comments",
"sounds",
"ads"
],
"type": "string"
},
"target": {
"anyOf": [
{
"type": "string"
},
{
"type": "object"
}
]
},
"platform": {
"enum": [
"tiktok",
"instagram",
"youtube",
"pinterest",
"twitter",
"kick",
"twitch",
"meta_ads",
"tiktok_ads",
"x",
"asset",
"auto"
],
"type": "string"
}
}
},
"description": "Typed collection targets, each an object with platform, scope and target. scope: user|hashtag|keyword|search|url|id|asset|account|creators|comments|sounds|ads. platform: tiktok|instagram|youtube|pinterest|twitter|kick|twitch|meta_ads|tiktok_ads (x is accepted for twitter; scope asset defaults the platform to asset, and scope url to auto). meta_ads and tiktok_ads are paid advertising platforms served by the DW's one ads lane over scope ads|keyword|user|id (scope ads takes a target object with exactly one of query/advertiser_id/ad_id plus optional country and status, and is forwarded verbatim; the alias scopes take a plain string: keyword->query, user->advertiser page id, id->ad id). That lane is what keeps an ad id from ever dispatching organic TikTok/Instagram retrieval. meta_ads serves live and cached ads; tiktok_ads is cache-only, so a live freshness reaches an unsupported coverage entry and never falls back to Meta or organic retrieval. enrich \"full\" is refused for every ads target: DW full enrichment selects video entities only and can never enrich an ad, so opt in to one creative's analysis with gen_asset_action analyze instead."
},
"platform": {
"type": "string",
"default": null
},
"freshness": {
"enum": [
"live",
"cache_then_live_deficit"
],
"type": "string",
"default": null
},
"deadline_ms": {
"type": "integer",
"default": null
},
"idempotency_key": {
"type": "string",
"default": null
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"job_id"
],
"properties": {
"action": {
"const": "collect_enrichment_status"
},
"job_id": {
"type": "string"
},
"include": {
"type": "array",
"items": {
"enum": [
"transcript",
"hooks",
"visual_description",
"description",
"stats",
"hashtags",
"media_type",
"video_url"
],
"type": "string"
},
"default": null
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"target"
],
"properties": {
"days": {
"type": "integer",
"default": null
},
"wait": {
"type": "boolean",
"default": null
},
"limit": {
"type": "integer",
"default": null
},
"query": {
"type": "string",
"default": null
},
"action": {
"const": "comment_mining"
},
"target": {
"type": "string"
},
"platform": {
"enum": [
"tiktok",
"instagram",
"youtube"
],
"type": "string",
"default": null
},
"idempotency_key": {
"type": "string",
"default": null
}
},
"additionalProperties": false
},
{
"type": "object",
"anyOf": [
{
"required": [
"query"
]
},
{
"required": [
"video_ids"
]
},
{
"required": [
"creator"
]
},
{
"required": [
"hashtag"
]
}
],
"required": [
"action"
],
"properties": {
"days": {
"type": "integer",
"default": null
},
"wait": {
"type": "boolean",
"default": null
},
"limit": {
"type": "integer",
"default": null
},
"query": {
"type": "string",
"default": null
},
"action": {
"const": "comments"
},
"creator": {
"type": "string",
"default": null
},
"from_db": {
"type": "boolean",
"default": null
},
"hashtag": {
"type": "string",
"default": null
},
"platform": {
"type": "string",
"const": "tiktok",
"default": null
},
"sentiment": {
"enum": [
"positive",
"neutral",
"negative"
],
"type": "string",
"default": null
},
"video_ids": {
"type": "array",
"items": {},
"default": null
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"video_ids"
],
"properties": {
"wait": {
"type": "boolean",
"default": null
},
"count": {
"type": "integer",
"default": null
},
"action": {
"const": "comments_online"
},
"video_ids": {
"type": "array",
"items": {}
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"query"
],
"properties": {
"raw": {
"type": "boolean",
"default": null
},
"mode": {
"enum": [
"keyword",
"handle"
],
"type": "string",
"default": null
},
"wait": {
"type": "boolean",
"default": null
},
"query": {
"type": "string"
},
"action": {
"const": "creators"
},
"target": {
"anyOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"type": "string"
}
}
],
"default": null
},
"creator": {
"type": "string",
"default": null
},
"filters": {
"type": "object",
"default": null,
"additionalProperties": true
},
"platform": {
"enum": [
"tiktok",
"instagram",
"youtube",
"kick"
],
"type": "string",
"default": null
},
"idempotency_key": {
"type": "string",
"default": null
},
"relevance_query": {
"type": "string",
"default": null
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"query"
],
"properties": {
"raw": {
"type": "boolean",
"default": null
},
"mode": {
"enum": [
"hashtag",
"keyword",
"niche",
"handle"
],
"type": "string",
"default": null
},
"wait": {
"type": "boolean",
"default": null
},
"query": {
"type": "string"
},
"action": {
"const": "hooks"
},
"target": {
"anyOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"type": "string"
}
}
],
"default": null
},
"creator": {
"type": "string",
"default": null
},
"filters": {
"type": "object",
"default": null,
"additionalProperties": true
},
"platform": {
"enum": [
"tiktok",
"instagram",
"youtube",
"kick"
],
"type": "string",
"default": null
},
"idempotency_key": {
"type": "string",
"default": null
},
"relevance_query": {
"type": "string",
"default": null
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"platform",
"videos_urls"
],
"properties": {
"wait": {
"type": "boolean",
"default": null
},
"action": {
"const": "import_urls"
},
"from_db": {
"type": "boolean",
"default": null
},
"platform": {
"enum": [
"tiktok",
"instagram",
"youtube"
],
"type": "string"
},
"confirmed": {
"type": "boolean",
"default": null,
"description": "Accepted and ignored: this branch executes on the first call — confirmation happens in the FE. Sent only by old callers."
},
"videos_urls": {
"type": "array",
"items": {}
},
"from_db_only": {
"type": "boolean",
"default": null
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"vidsheet_id",
"cell_id"
],
"properties": {
"action": {
"const": "layer_analysis"
},
"cell_id": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
]
},
"layer_id": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"default": null
},
"vidsheet_id": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
]
},
"confirm_token": {
"type": "string",
"default": null
}
},
"additionalProperties": false
},
{
"type": "object",
"anyOf": [
{
"required": [
"username"
]
},
{
"required": [
"hashtag"
]
}
],
"required": [
"action"
],
"properties": {
"action": {
"const": "monitor_status"
},
"hashtag": {
"type": "string",
"default": null
},
"platform": {
"enum": [
"tiktok",
"instagram",
"youtube"
],
"type": "string",
"default": null
},
"username": {
"type": "string",
"default": null
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"window"
],
"properties": {
"wait": {
"type": "boolean",
"default": null
},
"limit": {
"type": "integer",
"default": null
},
"action": {
"const": "report"
},
"window": {
"enum": [
1,
7,
30
],
"type": "integer"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"source",
"input"
],
"properties": {
"input": {
"type": "object",
"additionalProperties": true
},
"action": {
"const": "research_scrape"
},
"source": {
"type": "string"
},
"max_items": {
"type": "integer",
"default": null,
"maximum": 200,
"minimum": 1
},
"confirm_token": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"query"
],
"properties": {
"days": {
"type": "integer",
"default": null
},
"mode": {
"enum": [
"news",
"social",
"web",
"all"
],
"type": "string",
"default": null
},
"save": {
"type": "boolean",
"default": null
},
"wait": {
"type": "boolean",
"default": null
},
"limit": {
"type": "integer",
"default": null
},
"query": {
"type": "string"
},
"action": {
"const": "research_web"
},
"platforms": {
"type": "array",
"items": {
"enum": [
"x",
"news",
"web",
"reddit"
],
"type": "string"
},
"default": null
},
"asset_urls": {
"type": "array",
"items": {
"type": "string"
},
"default": null
},
"import_assets": {
"type": "boolean",
"default": null
},
"extract_assets": {
"type": "boolean",
"default": null
},
"idempotency_key": {
"type": "string",
"default": null
},
"reddit_subreddits": {
"type": "array",
"items": {
"type": "string"
},
"default": null
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"keyword"
],
"properties": {
"days": {
"type": "integer",
"default": null
},
"wait": {
"type": "boolean",
"default": null
},
"limit": {
"type": "integer",
"default": null
},
"action": {
"const": "search_posts"
},
"cursor": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
],
"default": null
},
"country": {
"type": "string",
"default": null
},
"from_db": {
"type": "boolean",
"default": null
},
"keyword": {
"type": "string"
},
"sort_by": {
"type": "string",
"default": null
},
"category": {
"type": "string",
"default": null
},
"language": {
"type": "string",
"default": null
},
"has_music": {
"type": "boolean",
"default": null
},
"min_likes": {
"type": "integer",
"default": null
},
"min_saves": {
"type": "integer",
"default": null
},
"min_views": {
"type": "integer",
"default": null
},
"platforms": {
"type": "array",
"items": {},
"default": null
},
"media_type": {
"type": "string",
"default": null
},
"min_shares": {
"type": "integer",
"default": null
},
"hook_search": {
"type": "string",
"default": null
},
"max_duration": {
"type": "integer",
"default": null
},
"min_comments": {
"type": "integer",
"default": null
},
"min_duration": {
"type": "integer",
"default": null
},
"posted_after": {
"type": "string",
"default": null
},
"sample_limit": {
"type": "integer",
"default": null
},
"max_followers": {
"type": "integer",
"default": null
},
"max_save_rate": {
"type": "number",
"default": null
},
"min_followers": {
"type": "integer",
"default": null
},
"min_save_rate": {
"type": "number",
"default": null
},
"posted_before": {
"type": "string",
"default": null
},
"visual_search": {
"type": "string",
"default": null
},
"comment_search": {
"type": "string",
"default": null
},
"location_query": {
"type": "string",
"default": null
},
"sort_direction": {
"type": "string",
"default": null
},
"is_faceless_video": {
"type": "boolean",
"default": null
},
"transcript_search": {
"type": "string",
"default": null
},
"is_paid_partnership": {
"type": "boolean",
"default": null
},
"max_engagement_rate": {
"type": "number",
"default": null
},
"min_engagement_rate": {
"type": "number",
"default": null
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"view"
],
"properties": {
"days": {
"type": "integer",
"default": null
},
"mood": {
"type": "string",
"default": null
},
"tags": {
"type": "string",
"default": null
},
"view": {
"enum": [
"sounds_by_niche",
"sounds_by_creator",
"rising_sounds",
"sound_performance",
"sound_arbitrage",
"music",
"trending_sounds",
"sound_info"
],
"type": "string"
},
"wait": {
"type": "boolean",
"default": null
},
"Top_k": {
"type": "integer",
"default": null
},
"genre": {
"type": "string",
"default": null
},
"limit": {
"type": "integer",
"default": null
},
"theme": {
"type": "string",
"default": null
},
"action": {
"const": "sounds"
},
"metric": {
"enum": [
"avg_engagement_rate",
"median_views",
"p95_views",
"save_rate",
"avg_daily_engagement_rate"
],
"type": "string",
"default": null
},
"offset": {
"type": "integer",
"default": null
},
"country": {
"type": "string",
"default": null
},
"creator": {
"type": "string",
"default": null
},
"filters": {
"type": "object",
"default": null,
"additionalProperties": true
},
"periods": {
"enum": [
7,
30
],
"type": "integer",
"default": null
},
"audio_id": {
"type": "string",
"default": null
},
"group_by": {
"anyOf": [
{
"type": "string"
},
{
"type": "array",
"items": {}
}
],
"default": null
},
"min_lift": {
"type": "number",
"default": null
},
"platform": {
"type": "string",
"default": null
},
"username": {
"type": "string",
"default": null
},
"min_videos": {
"type": "integer",
"default": null
},
"recent_days": {
"type": "integer",
"default": null
},
"baseline_days": {
"type": "integer",
"default": null
},
"limit_top_videos": {
"type": "integer",
"default": null
},
"min_niche_videos": {
"type": "integer",
"default": null
},
"min_global_videos": {
"type": "integer",
"default": null
},
"min_recent_videos": {
"type": "integer",
"default": null
},
"min_baseline_videos": {
"type": "integer",
"default": null
}
},
"additionalProperties": false
},
{
"type": "object",
"anyOf": [
{
"required": [
"video_ids"
]
},
{
"required": [
"hashtags"
]
}
],
"required": [
"action"
],
"properties": {
"mode": {
"enum": [
"online",
"batch"
],
"type": "string",
"default": null
},
"wait": {
"type": "boolean",
"default": null
},
"force": {
"type": "boolean",
"default": null
},
"action": {
"const": "transcribe"
},
"from_db": {
"type": "boolean",
"default": null
},
"hashtags": {
"type": "array",
"items": {},
"default": null
},
"platform": {
"enum": [
"tiktok",
"instagram",
"youtube"
],
"type": "string",
"default": null
},
"num_posts": {
"type": "integer",
"default": null
},
"video_ids": {
"type": "array",
"items": {},
"default": null
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"video_ids"
],
"properties": {
"action": {
"const": "transcribe_status"
},
"video_ids": {
"type": "array",
"items": {}
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"query"
],
"properties": {
"raw": {
"type": "boolean",
"default": null
},
"mode": {
"enum": [
"hashtag",
"keyword",
"niche",
"handle"
],
"type": "string",
"default": null
},
"wait": {
"type": "boolean",
"default": null
},
"query": {
"type": "string"
},
"action": {
"const": "trends"
},
"target": {
"anyOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"type": "string"
}
}
],
"default": null
},
"creator": {
"type": "string",
"default": null
},
"filters": {
"type": "object",
"default": null,
"additionalProperties": true
},
"platform": {
"enum": [
"tiktok",
"instagram",
"youtube",
"kick"
],
"type": "string",
"default": null
},
"idempotency_key": {
"type": "string",
"default": null
},
"relevance_query": {
"type": "string",
"default": null
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"video_ids"
],
"properties": {
"wait": {
"type": "boolean",
"default": null
},
"force": {
"type": "boolean",
"default": null
},
"action": {
"const": "upload_by_ids"
},
"video_ids": {
"type": "array",
"items": {}
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"video_url"
],
"properties": {
"wait": {
"type": "boolean",
"default": null
},
"action": {
"const": "video_analysis"
},
"video_url": {
"type": "string"
},
"idempotency_key": {
"type": "string",
"default": null
},
"include_video_analysis": {
"type": "boolean",
"default": null
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"url"
],
"properties": {
"url": {
"type": "string"
},
"limit": {
"type": "integer",
"default": null,
"maximum": 50,
"minimum": 1
},
"query": {
"type": "string",
"default": null
},
"action": {
"const": "web_asset_scrape"
},
"asset_types": {
"type": "array",
"items": {
"enum": [
"video",
"image"
],
"type": "string"
},
"default": null
},
"confirm_token": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"import_assets": {
"type": "boolean",
"default": null
},
"idempotency_key": {
"type": "string",
"default": null,
"maxLength": 255,
"minLength": 1
}
},
"additionalProperties": false
}
]
},
"minItems": 1,
"description": "One or more typed analysis actions: collect (the typed collection seam — targets [{platform, scope, target}] over scope user|hashtag|keyword|search|url|id|asset|account|creators|comments|sounds|ads and platform tiktok|instagram|youtube|pinterest|twitter|kick|twitch|meta_ads|tiktok_ads (x is an accepted alias for twitter; omit platform for scope asset; it defaults to asset; for scope url, omit it or pass \"auto\" — the DW resolves the pasted URL's platform itself), optional platform (the default for any target that names none), count (a positive integer, or \"all\" for every stored row), window {days}, filters GEN-3096 object, sort recent|views|likes|engagement, freshness live (the default) or cache_then_live_deficit (cache_then_live_deficit serves stored rows free and fetches only the missing count live; cache_only is refused), rollups, options {scrape_type}, deadline_ms (the caller's remaining budget; the admitted deadline_ms is computed per caller class), run_id (forwarded as the DW billing run id), enrich \"full\" (wait for the DW to fully process every row — transcript, hooks, visual analysis — then answer GEN's written analysis plus one display card per row; never caption-only rows), include [transcript|hooks|visual_description|description|stats|hashtags|media_type|video_url] (the per-row fields each row may carry — transcript/hooks/visual_description/description/stats are the enriched per-video fields, hashtags adds the provider's raw hashtag array as provider_hashtags_raw, media_type rides every collected row anyway, and video_url exposes the row's observed canonical first-party hosted media URL (assets.video_url) as a playable link, null when the DW mirrored none; by default the enriched fields stay server-side and only the display cards + written analysis reach the caller)); ONE synchronous DW call answered as model-visible evidence + a per-target coverage summary + result cards (video/post → video_grid, creator/account → creator_grid, sound → song_list, comment → comment_cluster, asset → table) — normally no job id and no PENDING, except a walk that reaches the admitted deadline: that answers a typed PENDING receipt naming its durable job id and idempotency_key (poll it with gen_discover domain=social view=job job_id=..., or retry the same collect with that idempotency_key — the retry resolves to the same job and never charges twice), and enrich \"full\" which waits and answers a PENDING receipt (collect_enrichment_status {job_id} polls it) when its budget expires; it replaces the older social-data branches below and is the first pick for any social data pull) | collect_enrichment_status (job_id required, include optional — poll one full-enrichment collect job by the job_id its PENDING receipt named, in the same shape as enrich \"full\"; while the job runs the receipt relays the rows already enriched as partial_rows and says how many are enriched so far) | trends | hooks (query required, mode hashtag|keyword|niche|handle, target, platform tiktok|instagram|youtube|kick, filters CommonFilters bundle, relevance_query, raw, idempotency_key (<=255; reuse it on a retry to replay the same job)) | creators (same shape, mode keyword|handle only) | comments (one of query/video_ids/creator/hashtag, optional sentiment positive|neutral|negative, days, limit, platform tiktok) | report (window 1|7|30, optional limit) | research_web (query required, optional mode news|social|web|all and research-source platforms x|news|web|reddit, reddit_subreddits, days, limit, save, idempotency_key (<=255, save:false only; reuse it on a retry to replay the same job); save:true persists the run as a Research Warehouse brief, save:false/omitted is one-shot; mode social is the community sources, X and Reddit; Reddit research carries its subreddit scope through the same one-shot analysis job as X/news/web, and a reddit.com URL or Reddit collect target is answered as research rather than a DW collection) | video_analysis (video_url: a social link or public HTTPS .mp4/.mov/.webm/.m4v/.mkv file; include_video_analysis=true watches framing, shots and timing without creating clips or drafts; false requests social metadata only) | clip_moments (only when clips are requested; sources: 1–10 social links, public HTTPS video files, GEN asset URLs, or numeric GEN video IDs; optional clip_count 1–10 (omit it and the engine makes one clip per 3 minutes of source, capped at 10 with the cap disclosed; an explicit count wins), positive min_duration_s/max_duration_s/target_final_max_duration_s/playback_speed, mode viral_moments|summarize, presentation source_clip|floating_head|split_screen, output_aspect_ratio 9:16|16:9|1:1, smart_reframe, enrich; each clip returns its persisted idea_id; one paid POST returns per-source clips and is never automatically retried) | layer_analysis (one vidsheet video layer or audio/ingredient media cell: vidsheet_id + cell_id, plus layer_id for a layer; video and audio only, images refused; the layer's own media URL goes to the attributed GENGEMINI boundary as ONE synchronous generateContent call running the approved DW prompt for that media kind, and the answer is projected at 30 fps: scene cuts, dead head/tail spans, suggested trim in/out and a description per segment — no job to poll. Analysis runs and bills on the first call; a valid legacy confirm_token remains accepted) | research_scrape (source: platform tiktok|instagram|youtube|x/twitter|pinterest|kick|web or any public URL, input naming the scrape target — keyword | hashtag | username | user URL on pinterest (x serves user targets only; pinterest user walks take cursor), keyword/hashtag/userPageURL/video_url on tiktok/instagram/youtube/kick, page url/asset_types/limit/query on web — plus max_items (a stray confirm_token is accepted and ignored); success returns the scraped rows and billing) | web_asset_scrape (public-page url, asset_types, limit, query, optional import_assets through gen_asset_action; runs and bills on the first call, optional legacy confirm_token) | import_urls (paid first-call URL-to-S3 import: platform tiktok|instagram|youtube + videos_urls public URLs, capped at 50 per call, writes S3 and bills on the first call; from_db=true/from_db_only=true refuse as stored-only-unavailable) | apify_scrape (billed first-call external-records run: actor_id names one approved provider actor and input is that actor's own run input, capped by max_items; returns the dataset rows and billing) | analyze_socials (DEPRECATED — superseded by collect; still served: paid social write: a social target platform/mode/target for a live social.posts scrape, or a wide scope platform plus one of keyword/hashtag/userPageURL/video_url for the DW general scrape; Twitch and Kick channel/VOD URLs are served, a Kick or Twitch mode + target resolves to that scope, and Kick/Twitch keyword/hashtag scopes forward to the DW, whose own provider path answers the scopes it does not serve; videoMonitoring forwards unchanged) | search_posts (DEPRECATED — superseded by collect; still served: keyword required; optional platforms [] and the Common GEN-3096 filters — days, posted_after, posted_before, min_/max_ engagement and save counts and rates, min_/max_followers, content filters (min_/max_duration, language, country, location_query, is_paid_partnership, media_type, has_music, is_faceless_video, category), transcript_search, visual_search, hook_search, comment_search, sort_by, sort_direction, cursor, limit, sample_limit, from_db) | analyze_account (DEPRECATED — superseded by collect; still served: username required, platform tiktok|instagram|youtube|twitter|x|linkedin; url is the non-TikTok followers lookup target) | transcribe (DEPRECATED — superseded by collect url/id; still served: platform tiktok|instagram|youtube with video_ids — TikTok ids, Instagram post ids, YouTube URLs — and/or hashtags, optional num_posts, from_db, force, mode online|batch defaulting to batch above 20 ids) | transcribe_status (DEPRECATED — superseded by collect url/id; still served: video_ids) | upload_by_ids (video_ids, optional force) | comments_online (DEPRECATED — superseded by collect comments; still served: video_ids, optional count — the live fetch beside the cached social.comments read) | monitor_status (platform + exactly one of username/hashtag) | aura_user_stats (emails + environment) | sounds (DEPRECATED — superseded by collect sounds; still served: view option: sounds_by_niche | sounds_by_creator | rising_sounds | sound_performance | sound_arbitrage | music | trending_sounds | sound_info; each view takes its own endpoint fields — min_videos, creator/username, recent_days/baseline_days/min_recent_videos/min_baseline_videos, platform/audio_id/days/group_by/limit_top_videos, min_niche_videos/min_global_videos/min_lift/metric, genre/mood/theme/tags/limit/offset, periods/Top_k/country, audio_id — plus the common GEN-3096 filters object) | chart (FREE; exactly one of data {labels, series [{name, values}]} charted as given, or source {job_id, group_by, metric, agg count|sum|avg|max} aggregated from a finished analysis job's rows — group_by \"day\"|\"week\"|\"month\" buckets the row's timestamp by UTC date (week = its Monday); optional type bar|line, title; a running job answers PENDING, never an empty chart) | analytics (view option: aggregate | sleepers | posting_times — by_demographics is owner-removed; group_by/metrics/histograms, ratio/min_ratio, timezone/metric/group_by plus the same filters object). Paid DW writes and research_scrape execute on the first call — confirmation happens in the FE and a stray confirmed/confirm_token argument is accepted and ignored; web_asset_scrape runs and bills on the first call; a valid legacy confirm_token remains accepted. Demographic filters are rejected. wait is optional per entry. meta_ads and tiktok_ads are paid advertising platforms served by the DW's one ads lane over scope ads|keyword|user|id (scope ads takes a target object with exactly one of query/advertiser_id/ad_id plus optional country and status, and is forwarded verbatim; the alias scopes take a plain string: keyword->query, user->advertiser page id, id->ad id). That lane is what keeps an ad id from ever dispatching organic TikTok/Instagram retrieval. meta_ads serves live and cached ads; tiktok_ads is cache-only, so a live freshness reaches an unsupported coverage entry and never falls back to Meta or organic retrieval. enrich \"full\" is refused for every ads target: DW full enrichment selects video entities only and can never enrich an ad, so opt in to one creative's analysis with gen_asset_action analyze instead."
},
"agent_id": {
"type": "string",
"description": "The agent ID that owns the workspace (envelope; the billing subject — the analysis run is billed to this agent, no anonymous path)"
}
},
"x-gen-delegation": {
"actions": [
"clip_moments",
"collect",
"comment_mining",
"comments",
"creators",
"hooks",
"research_web",
"sounds",
"trends",
"video_analysis",
"web_asset_scrape"
],
"excluded_actions": []
},
"additionalProperties": false
}| agent_id | any | The agent ID the conversation, ideas and research belong to (envelope; routed per branch) |
| confirm_token | any | Single-use token from a CONFIRMATION_REQUIRED error; repeat the same call with it to complete the destructive action it was issued for. Omit on the first call. |
{
"type": "object",
"required": [
"actions"
],
"properties": {
"actions": {
"type": "array",
"items": {
"oneOf": [
{
"type": "object",
"required": [
"action",
"question",
"client_message_id"
],
"properties": {
"mode": {
"anyOf": [
{
"enum": [
"queue",
"steer"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "How to send when a run is already in flight: queue (the default on a conversation continuation) or steer into the live run. Omitted on a first message, which starts a run as before."
},
"wait": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "Poll to completion (default true). Set false to return the run_id immediately."
},
"action": {
"const": "ask"
},
"row_id": {
"anyOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "null"
}
],
"default": null,
"description": "Selected database row ID; resolved on the owned Vidsheet instead of trusting row_position"
},
"run_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The caller's run that asked this question; a pushed result binds to that run so a late answer never lands on a later turn."
},
"cell_id": {
"anyOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "null"
}
],
"default": null,
"description": "Selected database cell ID; resolved to its row on the owned Vidsheet"
},
"question": {
"type": "string",
"description": "The question to ask (paste video/social links inline)"
},
"attachments": {
"anyOf": [
{
"type": "array",
"items": {}
},
{
"type": "null"
}
],
"default": null,
"description": "File attachments to analyze (image, video, audio, document or spreadsheet): one object per file, either {signed_id, filename, content_type} from gen_asset_action create_direct_upload (the URL is resolved from the blob) or {content_resource_id, filename, content_type} with the id complete_asset_upload returned, whose URL is read from that resource. Optional url/byte_size/thumbnail_url ride along. A YouTube watch/shorts link goes in the message."
},
"vidsheet_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The open Vidsheet ID for this question"
},
"row_position": {
"anyOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "null"
}
],
"default": null,
"description": "The selected one-based row; null means the whole sheet"
},
"conversation_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Continue an existing conversation (from a prior run)"
},
"client_message_id": {
"type": "string",
"maxLength": 64,
"description": "A fresh UUID per new user message, reused only on retry (max 64 chars)."
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"conversation_id",
"pending_id"
],
"properties": {
"action": {
"const": "cancel_pending"
},
"pending_id": {
"type": "string",
"description": "The queued message to take back (its pending_id)"
},
"conversation_id": {
"type": "string",
"description": "The conversation that owns the queued message"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"message",
"client_message_id"
],
"properties": {
"mode": {
"anyOf": [
{
"enum": [
"queue",
"steer"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "How to send when a run is already in flight: queue (the default on a conversation continuation) or steer into the live run. Omitted on a first message, which starts a run as before."
},
"wait": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "Poll to completion (default true). Set false to return run_id immediately."
},
"action": {
"const": "chat"
},
"row_id": {
"anyOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "null"
}
],
"default": null,
"description": "Selected database row ID; resolved on the owned Vidsheet instead of trusting row_position"
},
"run_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The caller's run that asked this question; a pushed result binds to that run so a late answer never lands on a later turn."
},
"cell_id": {
"anyOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "null"
}
],
"default": null,
"description": "Selected database cell ID; resolved to its row on the owned Vidsheet"
},
"message": {
"type": "string",
"description": "The build goal or instruction for the GEN composer"
},
"metadata": {
"anyOf": [
{
"type": "object",
"additionalProperties": true
},
{
"type": "null"
}
],
"default": null,
"description": "Structured card action context, including saved idea_id, action and creation_mode. Forwarded to the composer, which enforces ownership and reserves privileged fields."
},
"attachments": {
"anyOf": [
{
"type": "array",
"items": {}
},
{
"type": "null"
}
],
"default": null,
"description": "File attachments to analyze (image, video, audio, document or spreadsheet): one object per file, either {signed_id, filename, content_type} from gen_asset_action create_direct_upload (the URL is resolved from the blob) or {content_resource_id, filename, content_type} with the id complete_asset_upload returned, whose URL is read from that resource. Optional url/byte_size/thumbnail_url ride along. A YouTube watch/shorts link goes in the message."
},
"vidsheet_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The open Vidsheet ID for this question"
},
"row_position": {
"anyOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "null"
}
],
"default": null,
"description": "The selected one-based row; null means the whole sheet"
},
"conversation_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Continue an existing conversation (from a prior run)"
},
"client_message_id": {
"type": "string",
"maxLength": 64,
"description": "A fresh UUID per new user message, reused only on retry (max 64 chars)."
}
},
"additionalProperties": false
},
{
"type": "object",
"anyOf": [
{
"required": [
"message"
]
},
{
"required": [
"pending_id"
]
}
],
"required": [
"action",
"conversation_id"
],
"properties": {
"action": {
"const": "steer"
},
"message": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Text to add to the live run as a steering user message"
},
"pending_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "A queued message (pending_id) to promote to steering now"
},
"conversation_id": {
"type": "string",
"description": "The conversation whose live run to steer (or whose queued message to promote)"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"run_id"
],
"properties": {
"action": {
"const": "stop"
},
"run_id": {
"type": "string",
"description": "The run to stop; the messages it returns ride the reply's returned list"
}
},
"additionalProperties": false
}
]
},
"minItems": 1,
"description": "One or more typed ask actions: ask (question, required client_message_id, optional conversation_id/wait/attachments) | chat (message, required client_message_id, optional conversation_id/wait/attachments/metadata) | steer (conversation_id + message, or conversation_id + pending_id) | cancel_pending (conversation_id + pending_id) | stop (run_id). Workflow-routed ask/chat mode is refused with WORKFLOW_INPUT_UNSUPPORTED and a new message during active work is refused with REQUEST_ACTIVE; legacy steer calls keep their existing owner. Reading the queue or the thread is a gen_discover view (platform.conversations / platform.conversation / platform.conversation_pending), not a branch here. Content ideas are gen_content_action (generate_ideas | expand_idea | set_idea_status) and research is gen_analyze (research_web | report) — neither is served here."
},
"agent_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The agent ID the conversation, ideas and research belong to (envelope; routed per branch)"
},
"confirm_token": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Single-use token from a CONFIRMATION_REQUIRED error; repeat the same call with it to complete the destructive action it was issued for. Omit on the first call."
}
},
"x-gen-delegation": {
"actions": [],
"excluded_actions": []
},
"additionalProperties": false
}| confirm_token | any | Single-use token from a CONFIRMATION_REQUIRED error; repeat the same call with it to complete the destructive action it was issued for. Omit on the first call. |
{
"type": "object",
"required": [
"actions"
],
"properties": {
"actions": {
"type": "array",
"items": {
"oneOf": [
{
"type": "object",
"oneOf": [
{
"not": {
"required": [
"url"
]
},
"required": [
"asset_id"
],
"properties": {
"asset_id": {
"type": "string"
}
}
},
{
"not": {
"required": [
"asset_id"
]
},
"required": [
"url"
],
"properties": {
"url": {
"type": "string"
}
}
}
],
"required": [
"action",
"kind"
],
"properties": {
"url": {
"anyOf": [
{
"type": "string",
"minLength": 1
},
{
"type": "null"
}
],
"default": null
},
"kind": {
"enum": [
"video",
"image",
"audio",
"document"
],
"type": "string"
},
"action": {
"const": "analyze"
},
"asset_id": {
"anyOf": [
{
"type": "string",
"pattern": "\\S",
"minLength": 1
},
{
"type": "null"
}
],
"default": null
},
"idempotency_key": {
"anyOf": [
{
"type": "string",
"maxLength": 255
},
{
"type": "null"
}
],
"default": null
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"signed_id"
],
"properties": {
"action": {
"const": "complete_asset_upload"
},
"folder_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Place the asset inside this folder"
},
"signed_id": {
"type": "string",
"description": "The signed_id returned from the gen_asset_action create_direct_upload branch"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"filename",
"byte_size",
"checksum",
"content_type"
],
"properties": {
"action": {
"const": "create_direct_upload"
},
"checksum": {
"type": "string",
"pattern": "^[A-Za-z0-9+/]{22}==$",
"description": "Base64-encoded MD5 checksum of the exact file bytes"
},
"filename": {
"type": "string",
"pattern": "\\S",
"minLength": 1,
"description": "Original filename including extension"
},
"byte_size": {
"type": "integer",
"maximum": 4294967296,
"minimum": 1,
"description": "File size in bytes (max 4 GiB; workbook imports max 2 MiB)"
},
"content_type": {
"type": "string",
"pattern": "\\S",
"minLength": 1,
"description": "MIME type (e.g. image/png, video/mp4)"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"resource_id"
],
"properties": {
"action": {
"const": "delete_asset"
},
"resource_id": {
"type": "string",
"description": "The content resource ID to delete"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"url"
],
"properties": {
"url": {
"type": "string",
"description": "Public HTTPS video URL on YouTube, TikTok, Instagram, or Kick; not an arbitrary CDN/direct-file URL"
},
"action": {
"const": "import_asset_from_url"
},
"folder_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Place the imported asset inside this folder"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"command"
],
"properties": {
"action": {
"const": "run_computer"
},
"run_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Originating run id, for attribution (optional)"
},
"command": {
"type": "string",
"description": "The shell command to run: ffmpeg/ffprobe, Python with Pillow, or a shell script"
},
"profile": {
"anyOf": [
{
"enum": [
"default",
"media"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Sandbox profile: 'media' for ffmpeg/transcode work (allows a 900 s run), 'default' otherwise"
},
"secrets": {
"anyOf": [
{
"type": "object",
"additionalProperties": {
"type": "string"
}
},
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"default": null,
"description": "Environment secrets the command may read, as {name: value} or a list of names to forward"
},
"confirm_token": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Single-use token from the CONFIRMATION_REQUIRED preview; resend the exact same action with it to approve egress to non-GEN hosts"
},
"egress_allowlist": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Hosts the command may reach. GEN's asset hosts (assets.gen.pro, cdn.gen.pro, s3.us-east-005.backblazeb2.com) need no confirmation; any other host needs a confirm_token round"
}
},
"additionalProperties": false
}
]
},
"minItems": 1,
"description": "One or more typed asset actions: analyze (kind, exactly one asset_id or url) | create_direct_upload (filename, byte_size, checksum, content_type) | complete_asset_upload (signed_id, optional folder_id) | import_asset_from_url (url, optional folder_id) | delete_asset (resource_id) | run_computer (command, optional profile, secrets, egress_allowlist, run_id)"
},
"agent_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The agent ID that owns the asset library (envelope; routed per branch)"
},
"confirm_token": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Single-use token from a CONFIRMATION_REQUIRED error; repeat the same call with it to complete the destructive action it was issued for. Omit on the first call."
}
},
"x-gen-delegation": {
"actions": [
"analyze",
"run_computer"
],
"excluded_actions": []
},
"additionalProperties": false
}| confirm_token | any | Single-use token from a CONFIRMATION_REQUIRED error; repeat the same call with it to complete the destructive action it was issued for. Omit on the first call. |
{
"type": "object",
"required": [
"actions"
],
"properties": {
"actions": {
"type": "array",
"items": {
"oneOf": [
{
"type": "object",
"required": [
"action",
"organization_id",
"credit_plan_id"
],
"properties": {
"action": {
"const": "buy_credits"
},
"cancel_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Redirect URL on cancel (default: gen.pro/home)"
},
"success_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Redirect URL after successful payment (default: gen.pro/api-keys)"
},
"credit_plan_id": {
"type": "string",
"description": "The credit plan ID from the gen_discover billing.plans view"
},
"organization_id": {
"type": "string",
"description": "The organization/workspace ID to fund"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"workspace_id"
],
"properties": {
"action": {
"const": "create_x402_credit_purchase"
},
"credits": {
"anyOf": [
{
"type": "number",
"exclusiveMinimum": 0
},
{
"type": "null"
}
],
"default": null,
"description": "GEN credits to buy; provide exactly one of credits or amount_usd"
},
"network": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Payment network. Omit to receive every method the backend supports in the quote, then pass one exact network from that quote's payment_required.accepts (a friendly alias such as base, or a CAIP-2 id the backend supports). The backend validates the value; never invent a network the quote did not offer."
},
"amount_usd": {
"anyOf": [
{
"type": "number",
"exclusiveMinimum": 0
},
{
"type": "null"
}
],
"default": null,
"description": "USD value to buy; provide exactly one of amount_usd or credits"
},
"workspace_id": {
"type": "string",
"description": "Workspace/organization ID to fund: the numeric id or the workspace UUID (gen_discover platform.organizations / platform.workspaces reports both; a UUID resolves to the numeric id)"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"organization_id"
],
"properties": {
"action": {
"const": "list_owned_invoices"
},
"starting_after": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Last invoice ID from the previous page"
},
"organization_id": {
"type": "string",
"description": "ID of a workspace the caller owns"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action"
],
"properties": {
"action": {
"const": "list_owned_subscriptions"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"organization_id",
"credit_plan_id"
],
"properties": {
"action": {
"const": "open_checkout"
},
"cancel_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Redirect on cancel; defaults to the GEN plans page"
},
"success_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Redirect after payment; defaults to the GEN plans page"
},
"credit_plan_id": {
"type": "string",
"description": "Plan or credit pack ID from gen_discover billing.plans"
},
"organization_id": {
"type": "string",
"description": "ID of the workspace the caller owns"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action"
],
"properties": {
"action": {
"const": "prepare_funding_recovery"
},
"funding_error_kind": {
"type": "string",
"default": "out_of_credits",
"description": "Rails funding error kind of the refusal"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"workspace_id",
"checkout_session_id",
"payment_signature"
],
"properties": {
"action": {
"const": "settle_x402_credit_purchase"
},
"network": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Network selected from the quote's payment_required.accepts (a friendly alias or a CAIP-2 id the backend supports). Omit when the quote offers a single method. The backend validates the value; never invent a network the quote did not offer."
},
"workspace_id": {
"type": "string",
"description": "Workspace/organization ID from the quote: the numeric id or the workspace UUID (a UUID resolves to its numeric id)"
},
"payment_signature": {
"type": "string",
"description": "Signed x402 payment payload from the user's wallet"
},
"checkout_session_id": {
"type": "string",
"description": "checkout_session_id from the gen_billing_action create_x402_credit_purchase branch"
}
},
"additionalProperties": false
}
]
},
"minItems": 1,
"description": "Typed billing actions: open_checkout (organization_id, credit_plan_id, optional success_url/cancel_url; creates a Stripe payment page without charging), list_owned_subscriptions (no fields) | list_owned_invoices (organization_id, optional starting_after), both read-only for owned workspaces; or buy_credits, create_x402_credit_purchase, settle_x402_credit_purchase (purchase actions requiring user confirmation)"
},
"agent_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The agent ID that owns the workspace (envelope; routed per branch)"
},
"confirm_token": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Single-use token from a CONFIRMATION_REQUIRED error; repeat the same call with it to complete the destructive action it was issued for. Omit on the first call."
}
},
"x-gen-delegation": {
"actions": [],
"excluded_actions": []
},
"additionalProperties": false
}| Argument | Type | Description |
|---|---|---|
| op | any | The character op (list is the default only when no op-specific argument is given) |
| name | any | Name (rename: required; create: optional, default the file name; upload_look, upload_talking_character, create_talking_character, edit_talking_character: optional, Rails picks a default) |
| clips | any | 3 to 10 clips in order (create_talking_character, edit_talking_character): each {prompt, duration} with duration 5 or 10 seconds (default 10); on edit, {from_position} keeps that clip of the source talking character, reused free unless its prompt or duration is changed |
| query | any | Text to search character names for (list) |
| voice | any | set_primary_voice, and the voice create_talking_character / edit_talking_character speak with (default: the character's primary voice): {voice_id, provider} from gen_discover voice.mine or voice.list; name, ownership and billing_source from gen_discover voice.resource are kept when sent |
| script | any | What the talking character says (create_talking_character, edit_talking_character). Optional: a default line is used when blank |
| source | string | Character pool (list): the agent's own characters (my), the shared character library (library), or both (all) |
| look_id | any | Look ID from op=get (create_talking_character, delete_look; with rename, renames that look) |
| agent_id* | string | The selected agent ID |
| ready_for | any | list/get only: visual requires attached look or talking media; speaking also requires the saved primary voice. list excludes incomplete identities; get returns an actionable INPUT_NOT_READY refusal. Omit when managing or repairing identities. |
| clone_voice | any | create with a video, upload_talking_character: clone the person's voice from the video's audio into the character's primary voice (a paid job). create: default true, false skips it, true refuses a video without audio or under 30 seconds instead of creating it without a voice; upload_talking_character: default false, true clones with the same refusals. Ignored for images |
| aspect_ratio | any | Talking character shape (create_talking_character: default 9:16; edit_talking_character: default the source's) |
| build_inputs | any | validate_cast only: persisted idea inputs, including cast/resolved_input/confirmed. Checks selected character media and voice requirements without starting or billing a build. |
| character_id | any | Character ID (or its public id) from op=list (every op except list and create) |
| voice_gender | any | create with a video, upload_talking_character with clone_voice: the cloned voice's gender label (default female) |
| confirm_token | any | Single-use token from a CONFIRMATION_REQUIRED error; repeat the same call with it to complete the destructive action it was issued for. Omit on the first call. |
| voice_language | any | create with a video, upload_talking_character with clone_voice: the cloned voice's language (default english) |
| idempotency_key | any | Stable retry key (sent as the Idempotency-Key header, max 255 chars). Reuse the same key when retrying this exact create so Rails replays the originally created resource (same id) instead of creating a duplicate. Omit to create unconditionally. |
| content_resource_id | any | Image or video content resource ID, or a completed image generation's receipt (generation:<job>:succeeded:<resource>) (create: an image becomes the original look; a video an uploaded talking character, its first frame a look and its audio a cloned voice; upload_look: an image; upload_talking_character: a video) |
| talking_character_id | any | Talking character ID from op=get (get_talking_character, edit_talking_character, delete_talking_character; with rename, renames that talking character) |
{
"type": "object",
"required": [
"agent_id"
],
"properties": {
"op": {
"anyOf": [
{
"enum": [
"list",
"get",
"validate_cast",
"get_talking_character",
"create",
"upload_look",
"upload_talking_character",
"create_talking_character",
"edit_talking_character",
"copy_to_mine",
"rename",
"set_primary_voice",
"delete_character",
"delete_look",
"delete_talking_character"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The character op (list is the default only when no op-specific argument is given)"
},
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Name (rename: required; create: optional, default the file name; upload_look, upload_talking_character, create_talking_character, edit_talking_character: optional, Rails picks a default)"
},
"clips": {
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
}
},
{
"type": "null"
}
],
"default": null,
"description": "3 to 10 clips in order (create_talking_character, edit_talking_character): each {prompt, duration} with duration 5 or 10 seconds (default 10); on edit, {from_position} keeps that clip of the source talking character, reused free unless its prompt or duration is changed"
},
"query": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Text to search character names for (list)"
},
"voice": {
"anyOf": [
{
"type": "object",
"additionalProperties": true
},
{
"type": "null"
}
],
"default": null,
"description": "set_primary_voice, and the voice create_talking_character / edit_talking_character speak with (default: the character's primary voice): {voice_id, provider} from gen_discover voice.mine or voice.list; name, ownership and billing_source from gen_discover voice.resource are kept when sent"
},
"script": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "What the talking character says (create_talking_character, edit_talking_character). Optional: a default line is used when blank"
},
"source": {
"enum": [
"my",
"library",
"all"
],
"type": "string",
"default": "my",
"description": "Character pool (list): the agent's own characters (my), the shared character library (library), or both (all)"
},
"look_id": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Look ID from op=get (create_talking_character, delete_look; with rename, renames that look)"
},
"agent_id": {
"type": "string",
"pattern": "^\\S+$",
"minLength": 1,
"description": "The selected agent ID"
},
"ready_for": {
"anyOf": [
{
"enum": [
"visual",
"speaking"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "list/get only: visual requires attached look or talking media; speaking also requires the saved primary voice. list excludes incomplete identities; get returns an actionable INPUT_NOT_READY refusal. Omit when managing or repairing identities."
},
"clone_voice": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "create with a video, upload_talking_character: clone the person's voice from the video's audio into the character's primary voice (a paid job). create: default true, false skips it, true refuses a video without audio or under 30 seconds instead of creating it without a voice; upload_talking_character: default false, true clones with the same refusals. Ignored for images"
},
"aspect_ratio": {
"anyOf": [
{
"enum": [
"9:16",
"16:9",
"1:1"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Talking character shape (create_talking_character: default 9:16; edit_talking_character: default the source's)"
},
"build_inputs": {
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
},
"maxItems": 10,
"minItems": 1
},
{
"type": "null"
}
],
"default": null,
"description": "validate_cast only: persisted idea inputs, including cast/resolved_input/confirmed. Checks selected character media and voice requirements without starting or billing a build."
},
"character_id": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Character ID (or its public id) from op=list (every op except list and create)"
},
"voice_gender": {
"anyOf": [
{
"enum": [
"male",
"female"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "create with a video, upload_talking_character with clone_voice: the cloned voice's gender label (default female)"
},
"confirm_token": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Single-use token from a CONFIRMATION_REQUIRED error; repeat the same call with it to complete the destructive action it was issued for. Omit on the first call."
},
"voice_language": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "create with a video, upload_talking_character with clone_voice: the cloned voice's language (default english)"
},
"idempotency_key": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Stable retry key (sent as the Idempotency-Key header, max 255 chars). Reuse the same key when retrying this exact create so Rails replays the originally created resource (same id) instead of creating a duplicate. Omit to create unconditionally."
},
"content_resource_id": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Image or video content resource ID, or a completed image generation's receipt (generation:<job>:succeeded:<resource>) (create: an image becomes the original look; a video an uploaded talking character, its first frame a look and its audio a cloned voice; upload_look: an image; upload_talking_character: a video)",
"x-gen-input-kinds": [
"content_resource"
],
"x-gen-receipt-field": "result.results.0.result.id",
"x-gen-required-when": {
"op": [
"create",
"upload_look",
"upload_talking_character"
]
}
},
"talking_character_id": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Talking character ID from op=get (get_talking_character, edit_talking_character, delete_talking_character; with rename, renames that talking character)"
}
},
"x-gen-delegation": {
"actions": [
"create",
"get",
"list"
],
"excluded_actions": []
},
"additionalProperties": false
}| Argument | Type | Description |
|---|---|---|
| actions* | array | One or more typed content actions: create_content_resource (signed_id, optional asset_folder_id) | update_content_resource (resource_id, filename) | delete_content_resource (resource_id) |
| no_paid | boolean | Refuse paid media generation for this run. Text and LLM work still bills normally. |
| agent_id | any | The agent ID that owns the content resources (envelope; routed per branch) |
| confirm_token | any | Single-use token from a CONFIRMATION_REQUIRED error; repeat the same call with it to complete the destructive action it was issued for. Omit on the first call. |
| spending_run_id | string | Stable run or conversation identity required with spending controls. The authenticated run owner shares one policy across workspaces. |
| max_paid_operations | integer | Maximum paid media reservations across all workspaces in this authenticated user/run, enforced atomically. Retries reuse their reservation. |
{
"type": "object",
"required": [
"actions"
],
"properties": {
"actions": {
"type": "array",
"items": {
"oneOf": [
{
"type": "object",
"required": [
"action",
"signed_id"
],
"properties": {
"action": {
"const": "create_content_resource"
},
"signed_id": {
"type": "string",
"description": "The signed_id returned from the gen_asset_action create_direct_upload branch"
},
"asset_folder_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Place the resource inside this asset folder"
},
"idempotency_key": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Stable retry key (sent as the Idempotency-Key header, max 255 chars). Reuse the same key when retrying this exact create so Rails replays the originally created resource (same id) instead of creating a duplicate. Omit to create unconditionally."
}
},
"additionalProperties": false
},
{
"type": "object",
"anyOf": [
{
"required": [
"idea_id"
]
},
{
"required": [
"idea_ids"
]
},
{
"required": [
"idea_title"
]
}
],
"required": [
"action"
],
"properties": {
"action": {
"const": "create_video_from_idea"
},
"row_id": {
"anyOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "null"
}
],
"default": null,
"description": "An existing row of vidsheet_id to build the video into instead of adding a new row; requires vidsheet_id"
},
"idea_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The content idea to build the video from. Omit it when idea_ids names the clip run: the path idea is then idea_ids[0]."
},
"recover": {
"type": "boolean",
"default": false,
"description": "Read an accepted build by its original caller key instead of submitting again"
},
"idea_ids": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
},
"maxItems": 10,
"minItems": 1
},
{
"type": "null"
}
],
"default": null,
"description": "Clip ideas from one clip or viral-moments request: pass all of their ids in idea_ids (in order) in ONE call; GEN builds one Vidsheet with one row per clip. Do not make one call per clip."
},
"idea_title": {
"anyOf": [
{
"type": "string",
"minLength": 1
},
{
"type": "null"
}
],
"default": null,
"description": "Saved idea title or unique title fragment instead of idea_id/idea_ids. MCP resolves it on the envelope agent_id; several matches ask one question and do not build."
},
"vidsheet_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "An existing Vidsheet to add the idea to as a new row; omit to create a new Vidsheet"
},
"creation_mode": {
"enum": [
"draft",
"full"
],
"type": "string",
"default": "full",
"description": "draft = a Vidsheet plan that requires credits for LLM cost plus markup; no paid subscription is required. Media generation is billed separately; full bills credits for generated media. Omitting creation_mode defaults to full and bills credits."
},
"enhance_prompt": {
"type": "boolean",
"default": true,
"description": "enhance_prompt (default true) rewrites each generation prompt for the model that will render it using GEN's prompt and style skills; set false to keep the writer's prompts unchanged."
},
"idempotency_key": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Stable key so a retried submission is not run twice"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"resource_id"
],
"properties": {
"action": {
"const": "delete_content_resource"
},
"resource_id": {
"type": "string",
"description": "The content resource ID to delete"
}
},
"additionalProperties": false
},
{
"type": "object",
"anyOf": [
{
"required": [
"idea_id"
]
},
{
"required": [
"idea_title"
]
}
],
"required": [
"action"
],
"properties": {
"action": {
"const": "expand_idea"
},
"idea_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The idea ID to expand; takes precedence over idea_title"
},
"idea_title": {
"anyOf": [
{
"type": "string",
"minLength": 1
},
{
"type": "null"
}
],
"default": null,
"description": "Saved idea title or unique title fragment instead of idea_id. MCP resolves it on the envelope agent_id; several matches ask one question and do not expand."
},
"enhance_prompt": {
"type": "boolean",
"default": true,
"description": "enhance_prompt (default true) rewrites each generation prompt for the model that will render it using GEN's prompt and style skills; set false to keep the writer's prompts unchanged."
},
"idempotency_key": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Stable key so a retried submission is not run twice"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action"
],
"properties": {
"cast": {
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"title": "_IdeaCastRole",
"required": [
"role"
],
"properties": {
"look": {
"anyOf": [
{
"type": "object",
"title": "_IdeaLook",
"required": [
"source"
],
"properties": {
"source": {
"enum": [
"agent_look",
"avatar",
"attachment",
"description",
"none"
],
"type": "string",
"title": "Source"
},
"avatar_id": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Avatar Id",
"default": null,
"description": "Own or shared character ID (character_id) from gen_characters source=my or library; never a Vidsheet variable ID"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Description",
"default": null
},
"attachment_ref": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Attachment Ref",
"default": null
}
},
"additionalProperties": false
},
{
"type": "null"
}
],
"default": null
},
"role": {
"type": "string",
"title": "Role"
},
"needs": {
"anyOf": [
{
"type": "array",
"items": {
"enum": [
"character_sheet",
"look",
"voice"
],
"type": "string"
}
},
{
"type": "null"
}
],
"title": "Needs",
"default": null
},
"voice": {
"anyOf": [
{
"type": "object",
"title": "_IdeaVoice",
"required": [
"source"
],
"properties": {
"source": {
"enum": [
"voice_file",
"shared",
"mine",
"primary",
"description",
"avatar_default"
],
"type": "string",
"title": "Source"
},
"provider": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Provider",
"default": null
},
"voice_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Voice Id",
"default": null,
"description": "Voice ID from gen_discover voice.mine or voice.list; agent.core supplies the primary voice"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Description",
"default": null
},
"attachment_ref": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Attachment Ref",
"default": null
}
},
"additionalProperties": false
},
{
"type": "null"
}
],
"default": null
},
"speaks": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Speaks",
"default": null
},
"on_screen": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "On Screen",
"default": null
},
"is_new_character": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Is New Character",
"default": null
}
},
"additionalProperties": false
}
},
{
"type": "null"
}
],
"default": null,
"description": "Zero or more characters and speakers, each with its own look and voice. Character IDs: gen_characters my/library. Voice IDs: gen_discover voice.mine/voice.list. Agent reference images and primary voice: gen_discover agent.core. New looks/voices are created at build time, not idea time."
},
"brief": {
"anyOf": [
{
"type": "string"
},
{
"type": "object",
"title": "IdeaBriefV1",
"required": [
"agent_id",
"subject",
"video_type",
"mode",
"format",
"visual_style",
"attachments",
"characters",
"understanding"
],
"properties": {
"mode": {
"enum": [
"new",
"edit_existing"
],
"type": "string",
"title": "Mode"
},
"count": {
"type": "integer",
"title": "Count",
"default": 5,
"minimum": 1
},
"format": {
"type": "object",
"title": "IdeaFormat",
"required": [
"aspect_ratio",
"duration_s"
],
"properties": {
"duration_s": {
"type": "number",
"title": "Duration S",
"exclusiveMinimum": 0
},
"aspect_ratio": {
"type": "string",
"title": "Aspect Ratio",
"pattern": "\\S",
"minLength": 1
}
},
"additionalProperties": false
},
"subject": {
"type": "string",
"title": "Subject",
"pattern": "\\S",
"minLength": 1
},
"agent_id": {
"type": "string",
"title": "Agent Id",
"format": "uuid"
},
"characters": {
"type": "array",
"items": {
"type": "object",
"title": "IdeaCharacter",
"required": [
"character_id",
"name",
"role",
"origin",
"look",
"voice",
"speaks",
"on_screen"
],
"properties": {
"look": {
"type": "object",
"title": "IdeaLook",
"required": [
"avatar_id",
"attachment_id",
"description"
],
"properties": {
"look_id": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Look Id",
"default": null
},
"avatar_id": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Avatar Id"
},
"description": {
"type": "string",
"title": "Description",
"pattern": "\\S",
"minLength": 1
},
"attachment_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Attachment Id"
},
"thumbnail_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Thumbnail Url",
"default": null
}
},
"additionalProperties": false
},
"name": {
"type": "string",
"title": "Name",
"pattern": "\\S",
"minLength": 1
},
"role": {
"type": "string",
"title": "Role",
"pattern": "\\S",
"minLength": 1
},
"voice": {
"type": "object",
"title": "IdeaVoice",
"required": [
"source",
"voice_id",
"attachment_id"
],
"properties": {
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name",
"default": null
},
"source": {
"enum": [
"avatar_default",
"user_upload",
"library",
"generate",
"none"
],
"type": "string",
"title": "Source"
},
"voice_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Voice Id"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Description",
"default": null
},
"preview_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Preview Url",
"default": null
},
"attachment_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Attachment Id"
}
},
"additionalProperties": false
},
"origin": {
"enum": [
"existing_avatar",
"existing_character",
"new",
"user_upload"
],
"type": "string",
"title": "Origin"
},
"speaks": {
"type": "boolean",
"title": "Speaks"
},
"on_screen": {
"type": "boolean",
"title": "On Screen"
},
"character_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Character Id"
}
},
"additionalProperties": false
},
"title": "Characters"
},
"video_type": {
"type": "object",
"title": "IdeaVideoType",
"required": [
"id",
"name"
],
"properties": {
"id": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Id"
},
"name": {
"type": "string",
"title": "Name",
"pattern": "\\S",
"minLength": 1
}
},
"additionalProperties": false
},
"attachments": {
"type": "array",
"items": {
"type": "object",
"title": "IdeaAttachment",
"required": [
"attachment_id",
"kind",
"name",
"url",
"thumbnail_url",
"given_in_turn",
"used_as",
"analysis"
],
"properties": {
"url": {
"type": "string",
"title": "Url",
"pattern": "\\S",
"minLength": 1
},
"kind": {
"enum": [
"image",
"video",
"audio",
"document"
],
"type": "string",
"title": "Kind"
},
"name": {
"type": "string",
"title": "Name",
"pattern": "\\S",
"minLength": 1
},
"used_as": {
"type": "string",
"title": "Used As",
"pattern": "\\S",
"minLength": 1
},
"analysis": {
"type": "object",
"title": "IdeaAnalysis",
"required": [
"status",
"summary"
],
"properties": {
"status": {
"type": "string",
"const": "done",
"title": "Status"
},
"summary": {
"type": "string",
"title": "Summary",
"pattern": "\\S",
"minLength": 1
}
},
"additionalProperties": false
},
"attachment_id": {
"type": "string",
"title": "Attachment Id",
"pattern": "\\S",
"minLength": 1
},
"given_in_turn": {
"type": "integer",
"title": "Given In Turn",
"minimum": 1
},
"thumbnail_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Thumbnail Url"
}
},
"additionalProperties": false
},
"title": "Attachments"
},
"visual_style": {
"type": "object",
"title": "IdeaVisualStyle",
"required": [
"name",
"notes"
],
"properties": {
"name": {
"type": "string",
"title": "Name",
"pattern": "\\S",
"minLength": 1
},
"notes": {
"type": "string",
"title": "Notes"
}
},
"additionalProperties": false
},
"understanding": {
"type": "object",
"title": "IdeaUnderstanding",
"required": [
"summary",
"assumptions"
],
"properties": {
"summary": {
"type": "string",
"title": "Summary",
"pattern": "\\S",
"minLength": 1
},
"assumptions": {
"type": "array",
"items": {
"type": "object",
"title": "IdeaAssumption",
"required": [
"field",
"value",
"source"
],
"properties": {
"field": {
"type": "string",
"title": "Field",
"pattern": "\\S",
"minLength": 1
},
"value": {
"title": "Value"
},
"source": {
"enum": [
"message",
"attachment",
"analysis",
"conversation",
"agent_settings",
"saved_preference",
"default"
],
"type": "string",
"title": "Source"
}
},
"additionalProperties": false
},
"title": "Assumptions"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
},
{
"type": "null"
}
],
"default": null,
"description": "What the ideas should be about, in plain words, or the complete IdeaBriefV1. Structured briefs use the same validated assumptions path as idea_brief."
},
"count": {
"anyOf": [
{
"type": "integer",
"maximum": 50,
"minimum": 1
},
{
"type": "null"
}
],
"default": 5,
"description": "How many ideas to propose; omit when continuing an existing count, otherwise use the user's final count."
},
"style": {
"anyOf": [
{
"type": "object",
"title": "_IdeaStyle",
"properties": {
"tone": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Tone",
"default": null
},
"music": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Music",
"default": null
},
"pacing": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Pacing",
"default": null
},
"references": {
"anyOf": [
{
"type": "array",
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
},
{
"type": "object",
"additionalProperties": true
}
]
}
},
{
"type": "null"
}
],
"title": "References",
"default": null
},
"preferences": {
"anyOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"title": "Preferences",
"default": null
},
"visual_style": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Visual Style",
"default": null
}
},
"additionalProperties": false
},
{
"type": "null"
}
],
"default": null,
"description": "Style preferences, tone, pacing, visual style, music, and references"
},
"action": {
"const": "generate_ideas"
},
"format": {
"anyOf": [
{
"type": "object",
"title": "_IdeaFormat",
"properties": {
"count": {
"anyOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "null"
}
],
"title": "Count",
"default": null
},
"platform": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Platform",
"default": null
},
"aspect_ratio": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Aspect Ratio",
"default": null
},
"duration_seconds": {
"anyOf": [
{
"type": "integer",
"exclusiveMinimum": 0
},
{
"type": "null"
}
],
"title": "Duration Seconds",
"default": null
}
},
"additionalProperties": false
},
{
"type": "null"
}
],
"default": null,
"description": "Duration, aspect ratio, platform, and count"
},
"prompt": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The user's words verbatim"
},
"confirm": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "true with proposal_id accepts that plan and starts the idea job; confirm=true without proposal_id is a fresh request, with the same needs_input/proposal/running behavior as omitting confirm"
},
"content": {
"anyOf": [
{
"type": "object",
"title": "_IdeaContent",
"properties": {
"cta": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Cta",
"default": null
},
"avoid": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"title": "Avoid",
"default": null
},
"topic": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Topic",
"default": null
},
"claims": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"title": "Claims",
"default": null
},
"script": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Script",
"default": null
},
"key_points": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"title": "Key Points",
"default": null
},
"must_include": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"title": "Must Include",
"default": null
}
},
"additionalProperties": false
},
{
"type": "null"
}
],
"default": null,
"description": "Topic, key points, script, must_include, avoid, claims, and CTA"
},
"feedback": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Refinement feedback for from_ideas, or for the proposal_id you are replying to"
},
"from_ideas": {
"anyOf": [
{
"type": "string"
},
{
"type": "array",
"items": {}
},
{
"type": "null"
}
],
"default": null,
"description": "Ideas to refine: an idea id, a list of idea ids, or the conversation id of an earlier batch; send feedback alongside"
},
"idea_brief": {
"anyOf": [
{
"type": "object",
"title": "IdeaBriefV1",
"required": [
"agent_id",
"subject",
"video_type",
"mode",
"format",
"visual_style",
"attachments",
"characters",
"understanding"
],
"properties": {
"mode": {
"enum": [
"new",
"edit_existing"
],
"type": "string",
"title": "Mode"
},
"count": {
"type": "integer",
"title": "Count",
"default": 5,
"minimum": 1
},
"format": {
"type": "object",
"title": "IdeaFormat",
"required": [
"aspect_ratio",
"duration_s"
],
"properties": {
"duration_s": {
"type": "number",
"title": "Duration S",
"exclusiveMinimum": 0
},
"aspect_ratio": {
"type": "string",
"title": "Aspect Ratio",
"pattern": "\\S",
"minLength": 1
}
},
"additionalProperties": false
},
"subject": {
"type": "string",
"title": "Subject",
"pattern": "\\S",
"minLength": 1
},
"agent_id": {
"type": "string",
"title": "Agent Id",
"format": "uuid"
},
"characters": {
"type": "array",
"items": {
"type": "object",
"title": "IdeaCharacter",
"required": [
"character_id",
"name",
"role",
"origin",
"look",
"voice",
"speaks",
"on_screen"
],
"properties": {
"look": {
"type": "object",
"title": "IdeaLook",
"required": [
"avatar_id",
"attachment_id",
"description"
],
"properties": {
"look_id": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Look Id",
"default": null
},
"avatar_id": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Avatar Id"
},
"description": {
"type": "string",
"title": "Description",
"pattern": "\\S",
"minLength": 1
},
"attachment_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Attachment Id"
},
"thumbnail_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Thumbnail Url",
"default": null
}
},
"additionalProperties": false
},
"name": {
"type": "string",
"title": "Name",
"pattern": "\\S",
"minLength": 1
},
"role": {
"type": "string",
"title": "Role",
"pattern": "\\S",
"minLength": 1
},
"voice": {
"type": "object",
"title": "IdeaVoice",
"required": [
"source",
"voice_id",
"attachment_id"
],
"properties": {
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name",
"default": null
},
"source": {
"enum": [
"avatar_default",
"user_upload",
"library",
"generate",
"none"
],
"type": "string",
"title": "Source"
},
"voice_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Voice Id"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Description",
"default": null
},
"preview_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Preview Url",
"default": null
},
"attachment_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Attachment Id"
}
},
"additionalProperties": false
},
"origin": {
"enum": [
"existing_avatar",
"existing_character",
"new",
"user_upload"
],
"type": "string",
"title": "Origin"
},
"speaks": {
"type": "boolean",
"title": "Speaks"
},
"on_screen": {
"type": "boolean",
"title": "On Screen"
},
"character_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Character Id"
}
},
"additionalProperties": false
},
"title": "Characters"
},
"video_type": {
"type": "object",
"title": "IdeaVideoType",
"required": [
"id",
"name"
],
"properties": {
"id": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Id"
},
"name": {
"type": "string",
"title": "Name",
"pattern": "\\S",
"minLength": 1
}
},
"additionalProperties": false
},
"attachments": {
"type": "array",
"items": {
"type": "object",
"title": "IdeaAttachment",
"required": [
"attachment_id",
"kind",
"name",
"url",
"thumbnail_url",
"given_in_turn",
"used_as",
"analysis"
],
"properties": {
"url": {
"type": "string",
"title": "Url",
"pattern": "\\S",
"minLength": 1
},
"kind": {
"enum": [
"image",
"video",
"audio",
"document"
],
"type": "string",
"title": "Kind"
},
"name": {
"type": "string",
"title": "Name",
"pattern": "\\S",
"minLength": 1
},
"used_as": {
"type": "string",
"title": "Used As",
"pattern": "\\S",
"minLength": 1
},
"analysis": {
"type": "object",
"title": "IdeaAnalysis",
"required": [
"status",
"summary"
],
"properties": {
"status": {
"type": "string",
"const": "done",
"title": "Status"
},
"summary": {
"type": "string",
"title": "Summary",
"pattern": "\\S",
"minLength": 1
}
},
"additionalProperties": false
},
"attachment_id": {
"type": "string",
"title": "Attachment Id",
"pattern": "\\S",
"minLength": 1
},
"given_in_turn": {
"type": "integer",
"title": "Given In Turn",
"minimum": 1
},
"thumbnail_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Thumbnail Url"
}
},
"additionalProperties": false
},
"title": "Attachments"
},
"visual_style": {
"type": "object",
"title": "IdeaVisualStyle",
"required": [
"name",
"notes"
],
"properties": {
"name": {
"type": "string",
"title": "Name",
"pattern": "\\S",
"minLength": 1
},
"notes": {
"type": "string",
"title": "Notes"
}
},
"additionalProperties": false
},
"understanding": {
"type": "object",
"title": "IdeaUnderstanding",
"required": [
"summary",
"assumptions"
],
"properties": {
"summary": {
"type": "string",
"title": "Summary",
"pattern": "\\S",
"minLength": 1
},
"assumptions": {
"type": "array",
"items": {
"type": "object",
"title": "IdeaAssumption",
"required": [
"field",
"value",
"source"
],
"properties": {
"field": {
"type": "string",
"title": "Field",
"pattern": "\\S",
"minLength": 1
},
"value": {
"title": "Value"
},
"source": {
"enum": [
"message",
"attachment",
"analysis",
"conversation",
"agent_settings",
"saved_preference",
"default"
],
"type": "string",
"title": "Source"
}
},
"additionalProperties": false
},
"title": "Assumptions"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
},
{
"type": "null"
}
],
"default": null,
"description": "Complete model-authored assumptions from the workflow intake. Resolve request over agent settings over type defaults; include every assumption and its source. Repeat this same brief when confirming its proposal."
},
"sheet_rows": {
"anyOf": [
{
"type": "array",
"items": {}
},
{
"type": "null"
}
],
"default": null,
"description": "Existing Vidsheet rows to ground this batch; the backend reports its bounded rows used and truncation"
},
"video_type": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "VIDEO_TYPES ID or name; active types: 0 Any | 1 Talking Avatar | 2 Floating Head | 3 Montage | 6 Narrated/Voiceover | 8 Split Screen | 9 Skit; omit to let the understanding step choose"
},
"attachments": {
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"title": "_IdeaAttachment",
"required": [
"kind",
"role"
],
"properties": {
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Url",
"default": null
},
"kind": {
"enum": [
"image",
"video",
"audio",
"document"
],
"type": "string",
"title": "Kind"
},
"note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Note",
"default": null
},
"role": {
"enum": [
"reference_video",
"look",
"voice_sample",
"content",
"style",
"brand"
],
"type": "string",
"title": "Role"
},
"signed_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Signed Id",
"default": null
},
"resource_id": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Resource Id",
"default": null
}
},
"additionalProperties": false
}
},
{
"type": "null"
}
],
"default": null,
"description": "Every file the user supplied: resource_id from gen_discover asset.detail/list, signed_id from an upload, or url. Set kind and role to explain its use; new feedback files also go here."
},
"proposal_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Reply to a proposal from a previous call: with feedback for a new proposal, or with confirm=true to start the job"
},
"content_idea": {
"anyOf": [
{
"type": "object",
"title": "_IdeaConcept",
"properties": {
"hook": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Hook",
"default": null
},
"title": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Title",
"default": null
},
"script": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Script",
"default": null
}
},
"additionalProperties": false
},
{
"type": "null"
}
],
"default": null,
"description": "A specific title, hook, or script the user already has"
},
"requirements": {
"anyOf": [
{
"type": "array",
"items": {}
},
{
"type": "null"
}
],
"default": null,
"description": "Per-batch constraints, e.g. ['focus on before/after', 'under 12 seconds']"
},
"conversation_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Owner-scoped GEN conversation whose bounded history is used for this new batch"
},
"idempotency_key": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Stable key so a retried submission is not run twice"
},
"reference_video": {
"anyOf": [
{
"type": "object",
"title": "_IdeaReferenceVideo",
"properties": {
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Url",
"default": null
},
"resource_id": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Resource Id",
"default": null
},
"what_to_copy": {
"anyOf": [
{
"enum": [
"structure",
"pacing",
"look",
"all"
],
"type": "string"
},
{
"type": "null"
}
],
"title": "What To Copy",
"default": null
}
},
"additionalProperties": false
},
{
"type": "null"
}
],
"default": null,
"description": "Reference video resource_id or url and what_to_copy"
},
"conversation_context": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Relevant recent messages or summary from an external host whose chat GEN cannot read. Include the user's own words, not only a paraphrase; send files in attachments."
},
"source_analysis_job_id": {
"anyOf": [
{
"type": "string",
"maxLength": 200
},
{
"type": "null"
}
],
"default": null,
"description": "A completed analysis job id whose saved result grounds this batch: a gen_analyze trends/hooks/creators/research_web job id, read with gen_discover domain=analyze view=job. Pass it on the confirm call as well, so the job that starts stays grounded in that analysis. Only the caller's own completed job is accepted; another caller's id is refused JOB_NOT_FOUND."
},
"target_duration_seconds": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Target duration for the ideas' videos, in seconds"
},
"source_content_resource_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Content resource to ground the ideas in (content resource id)"
}
},
"additionalProperties": false
},
{
"type": "object",
"anyOf": [
{
"required": [
"content_resource_id"
]
},
{
"required": [
"video_url"
]
},
{
"required": [
"row_id"
]
},
{
"required": [
"row_number"
]
}
],
"required": [
"action"
],
"properties": {
"action": {
"const": "recreate_video"
},
"row_id": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The Vidsheet row's database id, only when you read it (e.g. from the rows view); use row_number for \"row N\" as the sheet shows it. With vidsheet_id."
},
"video_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Source video as a public https URL"
},
"row_number": {
"anyOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "null"
}
],
"default": null,
"description": "The row's 1-based position in the sheet's row order as the rows view returns it — pass this for \"row N\" (\"row 1\" is row_number 1). Resolved to that row's rendered final video. With vidsheet_id; exactly one of row_number and row_id."
},
"vidsheet_id": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "With row_number (or row_id): the video in that Vidsheet row — the row's rendered final video, resolved to its URL and sent as video_url. A row with no final video is refused (no_final_video_cell); no other row's video is used."
},
"idempotency_key": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Stable key so a retried submission is not run twice"
},
"content_resource_id": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Source video as an owned content resource (its content resource id)"
}
},
"additionalProperties": false
},
{
"type": "object",
"anyOf": [
{
"required": [
"idea_id"
]
},
{
"required": [
"content_resource_id"
]
},
{
"required": [
"video_url"
]
},
{
"required": [
"row_id"
]
},
{
"required": [
"row_number"
]
}
],
"required": [
"action",
"direction"
],
"properties": {
"count": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "How many new ideas to make (1-5, default 3)"
},
"action": {
"const": "reimagine_video"
},
"row_id": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The Vidsheet row's database id, only when you read it (e.g. from the rows view); use row_number for \"row N\" as the sheet shows it. With vidsheet_id."
},
"idea_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The idea ID of an earlier recreate_video idea; its manifest is reused and the video is not watched again"
},
"direction": {
"type": "string",
"description": "The new subject or brief for the new ideas — what changes while the source's pacing, scene structure and caption timing stay. Send the user's requested subject here (not as brief/prompt)."
},
"video_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Source video as a public https URL, when no idea_id names a recreate"
},
"row_number": {
"anyOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "null"
}
],
"default": null,
"description": "The row's 1-based position in the sheet's row order as the rows view returns it — pass this for \"row N\". Reads that row's existing media/layers without rendering or changing it. With vidsheet_id; exactly one of row_number and row_id."
},
"vidsheet_id": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "With row_number (or row_id): read that Vidsheet row's existing media and authored layers. No final render is required or started, and the source row is never changed."
},
"idempotency_key": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Stable key so a retried submission is not run twice"
},
"content_resource_id": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Source video as an owned content resource (its content resource id), when no idea_id names a recreate"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"preference"
],
"properties": {
"scope": {
"enum": [
"long_term",
"session"
],
"type": "string",
"default": "long_term",
"description": "The scope of the saved rule to remove"
},
"action": {
"const": "remove_content_preference"
},
"preference": {
"type": "string",
"description": "The saved rule to remove, as reported by preference_updates or platform.preferences"
},
"conversation_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "GEN conversation containing a session preference"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"title",
"brief",
"video_type_id"
],
"properties": {
"brief": {
"type": "string",
"maxLength": 20000,
"minLength": 1,
"description": "The user's authored request verbatim, including scene times, captions, source ingredients and exclusions. Saves one idea without generating alternatives or preferences."
},
"title": {
"type": "string",
"maxLength": 200,
"minLength": 1
},
"action": {
"const": "save_idea"
},
"scenes": {
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
}
},
{
"type": "null"
}
],
"default": null,
"description": "The user's authored scenes, preserving scene_number, time_range, duration, action, dialogue and text_overlays verbatim. Caption lines belong in text_overlays, a list of plain strings (one line each, never objects). Supply these when the user already wrote the scenes so Draft uses them without a script rewrite."
},
"full_script": {
"anyOf": [
{
"type": "string",
"maxLength": 20000
},
{
"type": "null"
}
],
"default": null,
"description": "The user's spoken script verbatim, when supplied; never invent speech for captions."
},
"aspect_ratio": {
"type": "string",
"default": "9:16"
},
"visual_style": {
"anyOf": [
{
"type": "object",
"additionalProperties": true
},
{
"type": "null"
}
],
"default": null,
"description": "The authored visual direction as {name, direction}; direction is a nonblank sentence."
},
"video_type_id": {
"type": "integer",
"minimum": 0,
"description": "VIDEO_TYPES ID; read the video_type field via gen_discover domain=content view=actions target=generate_ideas"
},
"conversation_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The conversation this authored idea belongs to"
},
"estimated_duration": {
"type": "integer",
"default": 15,
"maximum": 180,
"minimum": 3
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"preference"
],
"properties": {
"scope": {
"enum": [
"long_term",
"session"
],
"type": "string",
"default": "long_term",
"description": "long_term applies to future ideas; session lasts 24 hours on the GEN conversation"
},
"action": {
"const": "set_content_preference"
},
"preference": {
"type": "string",
"description": "Rule to save, e.g. 'always use statement hooks' or 'target women 25-34'"
},
"conversation_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Optional conversation context"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"idea_id",
"status"
],
"properties": {
"action": {
"const": "set_idea_status"
},
"status": {
"enum": [
"generated",
"approve_to_create",
"ready_for_review",
"change_idea",
"change_video",
"rejected",
"approved_to_post",
"posted"
],
"type": "string",
"description": "New status value: generated | approve_to_create | ready_for_review | change_idea | change_video | rejected | approved_to_post | posted"
},
"idea_id": {
"type": "string",
"description": "The idea ID"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"resource_id",
"filename"
],
"properties": {
"action": {
"const": "update_content_resource"
},
"filename": {
"type": "string",
"description": "The new filename for the resource"
},
"resource_id": {
"type": "string",
"description": "The content resource ID"
}
},
"additionalProperties": false
}
]
},
"minItems": 1,
"description": "One or more typed content actions: create_content_resource (signed_id, optional asset_folder_id) | update_content_resource (resource_id, filename) | delete_content_resource (resource_id)"
},
"no_paid": {
"type": "boolean",
"default": false,
"description": "Refuse paid media generation for this run. Text and LLM work still bills normally."
},
"agent_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The agent ID that owns the content resources (envelope; routed per branch)"
},
"confirm_token": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Single-use token from a CONFIRMATION_REQUIRED error; repeat the same call with it to complete the destructive action it was issued for. Omit on the first call."
},
"spending_run_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,128}$",
"maxLength": 128,
"minLength": 1,
"description": "Stable run or conversation identity required with spending controls. The authenticated run owner shares one policy across workspaces."
},
"max_paid_operations": {
"type": "integer",
"maximum": 2147483647,
"minimum": 0,
"description": "Maximum paid media reservations across all workspaces in this authenticated user/run, enforced atomically. Retries reuse their reservation."
}
},
"x-gen-delegation": {
"actions": [
"create_content_resource",
"expand_idea",
"generate_ideas",
"remove_content_preference",
"save_idea",
"set_content_preference"
],
"excluded_actions": []
},
"additionalProperties": false
}| Argument | Type | Description |
|---|---|---|
| data | any | Completed job data used to construct the card (card_from_job view), or the character review's typed facts {characters: [{name, image_url, look_source, look_id, look_name, voice}]} (characters.review view) |
| jobs | any | Job specs to price (generation_estimate view): one entry per job, {user_job_type, data} — the same user_job_type and data the run would create (data may be a JSON object string). The served item schema lists the accepted user_job_type values; an entry missing either key is refused by field path, never silently dropped. |
| mode | any | Social listing scope (social.posts view): user | keyword | hashtag (platform-dependent) |
| mood | any | Mood filter (media sound_library and recommended_sounds views) |
| page | any | Page number (templates, sound_library, billing.usage and analyze.job rows views); an integer or a string of digits |
| tags | any | Tag filter (media sound_library view) |
| type | any | Resource type filter (asset.list, content.list views) |
| view | string | Pick by the user's question: 'what did my watchlist say/find/summarize' = gen_watchlist_action query_watchlist, never a watchlist view here; 'who can see/access X' (even about a sheet) = platform organization (the workspace's members and visibility), never organizations; 'what did I ask/say before' = platform conversations (chat history), never a new gen_ask; 'what happened in this conversation / what did it start' = platform request_tree (the conversation's turns, ideas, builds, DW jobs, Rails jobs and delivery receipts in one tree, every node keeping its owner's own status); 'am I out of X this month' / 'how much have I used' = billing usage; 'is X allowed at all' = billing generation_access; 'what did run X cost / the charges for this run' = billing receipt (run_id); 'is my video/song/generation ready yet?' = media last_operation (vidsheet last_operation = sheet edit history); 'my assets / find my X' = asset list (the user's own files), ALWAYS — never asset libraries (asset libraries is only the folder tree browser, folder_id); 'trending/recommended sounds' = media recommended_sounds (what GEN recommends for this agent), while sound_library searches the shared catalog by text; 'what is being monitored for me / is anything paused for credits' = agent monitoring; 'ideas from run X' / 'saved ideas from run X' = content ideas with run_id — never task run_status (that view polls one agent run's own status) and never content.idea_job (only for a job_id generate_ideas returned); a video build job id (video-create-…) is never content.idea_job, read it with content.video_job; on a family domain (agent, content, generate, ...), actions lists that family's branches and target=<branch action> reads one branch's fields. The full per-domain view lists are in the tool description. |
| after | any | Conversation cursor from a previous platform.conversations page's next_cursor |
| cycle | any | Billing cycle filter (billing.plans view) |
| genre | any | Genre filter (media recommended_sounds view) |
| limit | any | Max rows in the selected view: change sets (operations, 1-100), conversations/messages (platform), or recommended sounds (media.recommended_sounds, 1-20, default 10) |
| model | any | Resolve a model name to its creation card (card_types view) |
| order | any | Sort order (asset.libraries view) |
| query | any | Search text (templates, sound_library, platform.conversations views; omit on sound_library to browse; conversations matches titles, max 200 characters) |
| before | any | Message cursor for platform.conversation: read the page before it |
| cursor | any | Pagination cursor (agent.profile_photos view) |
| domain | string | Discovery domain: contracts | vidsheet | agent | asset | billing | content | generate | location | media | platform | publish | task | voice | watchlist | social | analyze | ask (views per domain in the tool description); every family and flat op domain also serves view=actions, its branch schemas (including characters); characters also serves view=review, the character review card worded here from the engine's typed facts; a watchlist question ('what did my watchlist find') is gen_watchlist_action query_watchlist, never a read here |
| job_id | any | user_job_id from generate sound_matching (vidsheet audio_matches view), recurring job ID (task.job view), TTS preview user_job_id (voice.preview_status view), a DW asset-enrichment job id (asset.analysis view), a DW job id (social.job view, the poll for a PENDING DW run), a gen-agentic analysis job id (analyze.job view, the poll for a PENDING gen_analyze trends/hooks/creators/research_web job), the job_id generate_ideas returned for a confirmed idea batch (content.idea_job view) or the video build job id create_video returned (content.video_job view, the video-create-… poll: its status, sheet link, QA result and error), the opaque native taskId from an accepted MCP Task handle (task.job_locator view). A run reference is not a job id: 'ideas from run X' is content.ideas with run_id, never content.idea_job. |
| row_id | any | Row ID (row, video, final_video_probe views) |
| run_id | any | content.ideas run reference — 'ideas from run X' / 'saved ideas from run X', the ideas from a run: a run id or its prefix of at least 8 characters. Reads that run's saved ideas; omit it to list the agent's newest ideas. For one saved idea use content.idea with idea_id, never this run_id field. On task.run_status it is only an agent run's own id, to poll that run's status — never a saved run's ideas. On billing.receipt it is the exact run whose billed charges to read. |
| search | any | Search text (asset.libraries view) |
| source | any | Voice source filter: public | user_* (voice.list view) |
| status | any | Status filter (content.ideas view) |
| target | any | Social handle, keyword or hashtag (social.user_info, social.posts views); on vidsheet.actions, one action+target pair to focus as "<action>:<kind>" (e.g. "update:column"); on a family domain's actions view, the branch action to read (e.g. reimagine_video under domain=content); on task.job_locator, the original caller idempotency key when the admission reply was lost (omit job_id) |
| cell_id | any | Cell ID (cell, layers, layer, layer_analysis views; optional on layer — the owning cell is resolved from the layer id; on layer_analysis a cell_id without a layer_id addresses an ingredient media cell) |
| from_db | any | Legacy social.posts flag; the read-only view is unavailable because it cannot guarantee zero provider calls. Use gen_analyze collect for live collection. |
| idea_id | any | Saved idea ID: read its title and script with domain=content view=idea idea_id=<the saved idea id>. An idea id is never a run_id or job_id. |
| include | any | Extra sections; ["full"] dumps the whole sheet on the sheet view |
| max_bpm | any | Maximum tempo in BPM (media recommended_sounds view) |
| min_bpm | any | Minimum tempo in BPM (media recommended_sounds view) |
| post_id | any | Scheduled/published post ID (publish.post_status view) |
| agent_id | any | The agent ID (envelope; forwarded to every view that scopes by agent). Optional: only the agent-scoped views require it — the vidsheet/media engine views resolve the owning agent from the sheet's engine read (GEN-7151). An agent-scoped view with no agent_id refuses with the caller's agents listed (agent_required): when the user has not already named an agent, read agent.list and ask them which to use — never guess. |
| end_date | any | Range end, ISO date (publish.scheduled view; required there, within a 60-day window with start_date) |
| layer_id | any | Layer ID (layer, layer_analysis views; a layer id is unique on the sheet, so it is enough — pass cell_id to pin the read to one cell) |
| per_page | any | Results per page (sound_library view, default 10) |
| platform | any | Social platform (publish.connect_url view, default youtube) |
| produces | any | Creation card output filter: text | image | video | audio | caption (card_types view) |
| provider | any | Voice provider (voice.resource view): user_voice_resource for the agent's own voices (voice.mine), else the voice library; default platform_eleven_labs |
| template | any | Template slug/UUID/ID (template view) |
| voice_id | any | Voice resource ID (voice.resource view) |
| container | any | Creation card attach filter: SpreadsheetCell | VideoLayer (card_types view) |
| folder_id | any | Folder filter (asset.libraries view) |
| min_count | any | Minimum engagement count (Pinterest keyword/hashtag posts) |
| page_size | any | Page size (asset.libraries view) |
| placement | any | The card's layer as authored (input_bindings view): {source_asset_ref, source_clip, content_type}. When the layer places supplied footage, a reference to that same media through a field the card does not serve is satisfied by the placement. Without card_schema, returns placed_inputs: the referenced input ids this card-less layer consumes as its own footage. |
| video_ids | any | Video/post ids (social.video_info, social.comments views; TikTok/Instagram/YouTube/Kick ids or URLs) |
| asset_type | any | Asset type filter (asset.libraries view) |
| audio_lens | any | Audio ranking lens for the vidsheet.actions live discovery, from Rails' own lens set (e.g. scrape ranks creator-scraped audio) |
| audio_mood | any | Filter recommended audio by mood (vidsheet.actions live discovery with audio_library=recommended) |
| commercial | any | Only sounds cleared for commercial use (sound_library and recommended_sounds views) |
| layer_type | any | Layer type to focus the vidsheet.actions view's LIVE discovery on (GEN-8203): caption, text, clip, sound and the other Rails layer types; layer_type=caption returns that layer's settings schema, whose styles.fontFamily enum lists the offered fonts. Omit for the static action guide. |
| project_id | any | Project filter (content.list view) |
| start_date | any | Range start, ISO date (publish.scheduled view; required there, within a 60-day window with end_date) |
| audio_genre | any | Filter recommended audio by genre (vidsheet.actions live discovery with audio_library=recommended) |
| audio_limit | any | Maximum ranked audio results, Rails default 10 (vidsheet.actions live discovery) |
| audio_query | any | Scope recommended audio to an @creator, #hashtag or keyword (vidsheet.actions live discovery with audio_library=recommended) |
| card_inputs | any | The card's current inputs to bind into (input_bindings view); the MCP returns them with every source reference applied. |
| card_schema | any | Creation card to describe (card_schema view): an FE card type such as video-from-talking-avatar, lip-sync or video-from-text, final-video (the final render card — its creation_card_inputs is optional and built from the row's video layers), or its backend job_type; omit to list card types |
| resource_id | any | Asset or content resource ID (asset.detail, content.resource views) |
| vidsheet_id | any | Vidsheet ID |
| country_code | any | Two-letter country code (location.cities view) |
| from_db_only | any | Legacy social.video_info flag; the read-only view is unavailable because no provider-free DW contract is served. Use gen_analyze collect for live collection. |
| watchlist_id | any | Watchlist ID (watchlist.detail view) |
| workspace_id | any | Filter agents by workspace (agent.list view) |
| audio_library | any | Scoped audio library for the vidsheet.actions view's LIVE discovery (GEN-8203): recommended (ranked music for this agent; each media entry carries the signed library_reference a sound layer saves) or trending. Rails validates the value and a bad one passes its 422 through. Omit for the static action guide. |
| audio_max_bpm | any | Maximum tempo in BPM for recommended audio (vidsheet.actions live discovery with audio_library=recommended) |
| audio_min_bpm | any | Minimum tempo in BPM for recommended audio (vidsheet.actions live discovery with audio_library=recommended) |
| generation_id | any | Generation ID to poll (vidsheet generation view) or voice-design sample generation ID (voice.sample_status view) |
| source_inputs | any | Form view: confirmed cast context only; assets are read live. The resolved saved input media the references name (input_bindings view): {attachments: [{ref, url, kind, content_resource_id, resource...}]}, the same set gen_content_action built inputs from. The MCP is the only binding owner (GEN-9391). |
| user_job_type | any | Completed job type to map to a Vidsheet creation card (card_from_job view) |
| audio_platform | any | Social platform whose audio usage is ranked (vidsheet.actions live discovery; Rails defaults it to tiktok) |
| include_undone | any | Include undone change sets (operations view) |
| watchlist_name | any | Watchlist display name or its @list mention slug (watchlist.detail view), resolved case-insensitively: an exact name or an equal slug as one candidate set, then a unique prefix; an ambiguous name answers the candidates. Pass this or watchlist_id. |
| conversation_id | any | Conversation ID (platform.conversation, platform.conversation_pending, platform.request_tree, platform.preferences views) |
| idempotency_key | any | Original create-call key with idea_id for content.video_job transport readback |
| include_removed | any | Include removed backups (platform.backups view) |
| organization_id | any | Organization ID (platform.organization view) |
| selecting_model | any | Skip the selected model's acceptance check because the model is not chosen yet (input_bindings view). |
| audio_search_type | any | How to read audio_query: creator | hashtag | keyword (vidsheet.actions live discovery); an @ or # prefix infers it |
| audio_video_count | any | Maximum cached source videos scanned for creator/scrape ranking, Rails default 50 (vidsheet.actions live discovery) |
| audio_window_days | any | Audio lookback window in days, Rails default 30 (vidsheet.actions live discovery) |
| source_references | any | Saved-input references to bind (input_bindings view): one {input_id, card_type?, field?} per named upload or saved media. Omit to only resolve picker labels. |
| audio_commercial_only | any | Only commercially licensed recommended audio (vidsheet.actions live discovery with audio_library=recommended) |
| with_organization_uuid | any | For agent.detail, 'true'/'false' controls whether the response includes the organization UUID; an organization UUID scopes the read |
{
"type": "object",
"allOf": [
{
"if": {
"required": [
"domain",
"view"
],
"properties": {
"view": {
"const": "scheduled"
},
"domain": {
"const": "publish"
}
}
},
"then": {
"required": [
"start_date",
"end_date"
]
}
}
],
"properties": {
"data": {
"anyOf": [
{
"type": "object",
"additionalProperties": true
},
{
"type": "null"
}
],
"default": null,
"description": "Completed job data used to construct the card (card_from_job view), or the character review's typed facts {characters: [{name, image_url, look_source, look_id, look_name, voice}]} (characters.review view)"
},
"jobs": {
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"required": [
"user_job_type"
],
"properties": {
"data": {
"anyOf": [
{
"type": "object"
},
{
"type": "string"
}
],
"description": "The job's data object: the fields that job prices from (prompt, model, duration, ...). A JSON object string is accepted, as Rails accepts it. Omit it to price the job type's own defaults."
},
"label": {
"type": "string",
"description": "Optional label echoed back on the quote item."
},
"user_job_type": {
"enum": [
"analyze_viral_moment",
"assemblyai_audio_caption_generation",
"audio_matching",
"clone_spreadsheet",
"clone_voice",
"create_talking_avatar_and_lip_sync",
"design_voice",
"gemini_caption_generation",
"gemini_image_generation",
"gemini_omni_video_generation",
"gemini_video_generation",
"grok_image_generation",
"grok_video_generation",
"image_caption_generation",
"infinite_voice_lip_sync",
"kling",
"kling_img2video",
"midjourney",
"minimax_h3_max_video_generation",
"openai_image_generation",
"openai_image_generation_2",
"publish_content",
"remotion",
"remotion_publish",
"remove_background",
"replace_master_kling",
"seedance_2_0_video_generation",
"seedance_2_5_video_generation",
"seedream_image_generation",
"song_generation",
"spreadsheet_audio_matching",
"talking_avatar",
"talking_avatar_combine",
"text_generation",
"train_social",
"transcription",
"video_from_image_and_image_from_text",
"voice_design_runpod",
"voice_generation",
"voice_replace"
],
"type": "string",
"description": "The Rails job type to price — the same user_job_type the run will create (e.g. the job_type gen_discover card_schema reports for the card you are about to generate)."
}
},
"description": "One job to price: the user_job_type and data the run would create, plus an optional label. A priceable field sent beside user_job_type (a flat duration, model, prompt) is folded into data so it reaches the estimator; a value already in data wins.",
"additionalProperties": true
}
},
{
"type": "null"
}
],
"default": null,
"description": "Job specs to price (generation_estimate view): one entry per job, {user_job_type, data} — the same user_job_type and data the run would create (data may be a JSON object string). The served item schema lists the accepted user_job_type values; an entry missing either key is refused by field path, never silently dropped."
},
"mode": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Social listing scope (social.posts view): user | keyword | hashtag (platform-dependent)"
},
"mood": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Mood filter (media sound_library and recommended_sounds views)"
},
"page": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Page number (templates, sound_library, billing.usage and analyze.job rows views); an integer or a string of digits"
},
"tags": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Tag filter (media sound_library view)"
},
"type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Resource type filter (asset.list, content.list views)"
},
"view": {
"enum": [
"sheet",
"rows",
"row",
"columns",
"cell",
"video",
"layers",
"layer",
"layer_analysis",
"variables",
"available_variables",
"operations",
"last_operation",
"engine",
"template",
"templates",
"layout_validation",
"recipe",
"card_types",
"card_schema",
"card_matrix",
"actions",
"card_from_job",
"input_bindings",
"final_video_probe",
"generation",
"generation_estimate",
"audio_matches",
"running_generations",
"detail",
"capabilities",
"settings",
"core",
"profile",
"profile_photos",
"list",
"shares",
"monitoring",
"execution_access",
"analysis",
"libraries",
"balance",
"generation_access",
"usage",
"receipt",
"plans",
"resource",
"ideas",
"idea",
"idea_job",
"video_job",
"directions",
"countries",
"cities",
"recommended_sounds",
"sound_library",
"conversation",
"conversation_pending",
"request_tree",
"me",
"organization",
"preferences",
"api_keys",
"conversations",
"organizations",
"backups",
"workspaces",
"members",
"post_status",
"rules",
"connect_url",
"connections",
"scheduled",
"stats",
"job",
"job_locator",
"run_status",
"preview_status",
"sample_status",
"mine",
"user_info",
"video_info",
"comments",
"posts",
"collect_enrichment",
"web_asset_job",
"schemas",
"form",
"review"
],
"type": "string",
"default": "sheet",
"description": "Pick by the user's question: 'what did my watchlist say/find/summarize' = gen_watchlist_action query_watchlist, never a watchlist view here; 'who can see/access X' (even about a sheet) = platform organization (the workspace's members and visibility), never organizations; 'what did I ask/say before' = platform conversations (chat history), never a new gen_ask; 'what happened in this conversation / what did it start' = platform request_tree (the conversation's turns, ideas, builds, DW jobs, Rails jobs and delivery receipts in one tree, every node keeping its owner's own status); 'am I out of X this month' / 'how much have I used' = billing usage; 'is X allowed at all' = billing generation_access; 'what did run X cost / the charges for this run' = billing receipt (run_id); 'is my video/song/generation ready yet?' = media last_operation (vidsheet last_operation = sheet edit history); 'my assets / find my X' = asset list (the user's own files), ALWAYS — never asset libraries (asset libraries is only the folder tree browser, folder_id); 'trending/recommended sounds' = media recommended_sounds (what GEN recommends for this agent), while sound_library searches the shared catalog by text; 'what is being monitored for me / is anything paused for credits' = agent monitoring; 'ideas from run X' / 'saved ideas from run X' = content ideas with run_id — never task run_status (that view polls one agent run's own status) and never content.idea_job (only for a job_id generate_ideas returned); a video build job id (video-create-…) is never content.idea_job, read it with content.video_job; on a family domain (agent, content, generate, ...), actions lists that family's branches and target=<branch action> reads one branch's fields. The full per-domain view lists are in the tool description.",
"x-gen-research-collection": {
"vidsheet.row": {
"produces": [
"vidsheet_row"
],
"source_kinds": {
"vidsheet_row": {
"bindings": {
"row_id": "row_id",
"vidsheet_id": "vidsheet_id"
}
}
},
"output_schema": "JobStatusV1"
},
"vidsheet.sheet": {
"produces": [
"vidsheet"
],
"source_kinds": {
"vidsheet": {
"bindings": {
"vidsheet_id": "vidsheet_id"
},
"defaults": {
"include": [
"full"
]
}
}
},
"output_schema": "JobStatusV1"
}
}
},
"after": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Conversation cursor from a previous platform.conversations page's next_cursor"
},
"cycle": {
"anyOf": [
{
"enum": [
"monthly",
"yearly",
"one_time"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Billing cycle filter (billing.plans view)"
},
"genre": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Genre filter (media recommended_sounds view)"
},
"limit": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Max rows in the selected view: change sets (operations, 1-100), conversations/messages (platform), or recommended sounds (media.recommended_sounds, 1-20, default 10)"
},
"model": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Resolve a model name to its creation card (card_types view)"
},
"order": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Sort order (asset.libraries view)"
},
"query": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Search text (templates, sound_library, platform.conversations views; omit on sound_library to browse; conversations matches titles, max 200 characters)"
},
"before": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Message cursor for platform.conversation: read the page before it"
},
"cursor": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Pagination cursor (agent.profile_photos view)"
},
"domain": {
"enum": [
"vidsheet",
"agent",
"asset",
"billing",
"content",
"location",
"media",
"platform",
"publish",
"task",
"voice",
"watchlist",
"social",
"analyze",
"contracts",
"characters",
"generate",
"ask"
],
"type": "string",
"default": "vidsheet",
"description": "Discovery domain: contracts | vidsheet | agent | asset | billing | content | generate | location | media | platform | publish | task | voice | watchlist | social | analyze | ask (views per domain in the tool description); every family and flat op domain also serves view=actions, its branch schemas (including characters); characters also serves view=review, the character review card worded here from the engine's typed facts; a watchlist question ('what did my watchlist find') is gen_watchlist_action query_watchlist, never a read here"
},
"job_id": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "user_job_id from generate sound_matching (vidsheet audio_matches view), recurring job ID (task.job view), TTS preview user_job_id (voice.preview_status view), a DW asset-enrichment job id (asset.analysis view), a DW job id (social.job view, the poll for a PENDING DW run), a gen-agentic analysis job id (analyze.job view, the poll for a PENDING gen_analyze trends/hooks/creators/research_web job), the job_id generate_ideas returned for a confirmed idea batch (content.idea_job view) or the video build job id create_video returned (content.video_job view, the video-create-… poll: its status, sheet link, QA result and error), the opaque native taskId from an accepted MCP Task handle (task.job_locator view). A run reference is not a job id: 'ideas from run X' is content.ideas with run_id, never content.idea_job."
},
"row_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Row ID (row, video, final_video_probe views)"
},
"run_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "content.ideas run reference — 'ideas from run X' / 'saved ideas from run X', the ideas from a run: a run id or its prefix of at least 8 characters. Reads that run's saved ideas; omit it to list the agent's newest ideas. For one saved idea use content.idea with idea_id, never this run_id field. On task.run_status it is only an agent run's own id, to poll that run's status — never a saved run's ideas. On billing.receipt it is the exact run whose billed charges to read."
},
"search": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Search text (asset.libraries view)"
},
"source": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Voice source filter: public | user_* (voice.list view)"
},
"status": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Status filter (content.ideas view)"
},
"target": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Social handle, keyword or hashtag (social.user_info, social.posts views); on vidsheet.actions, one action+target pair to focus as \"<action>:<kind>\" (e.g. \"update:column\"); on a family domain's actions view, the branch action to read (e.g. reimagine_video under domain=content); on task.job_locator, the original caller idempotency key when the admission reply was lost (omit job_id)"
},
"cell_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Cell ID (cell, layers, layer, layer_analysis views; optional on layer — the owning cell is resolved from the layer id; on layer_analysis a cell_id without a layer_id addresses an ingredient media cell)"
},
"from_db": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "Legacy social.posts flag; the read-only view is unavailable because it cannot guarantee zero provider calls. Use gen_analyze collect for live collection."
},
"idea_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Saved idea ID: read its title and script with domain=content view=idea idea_id=<the saved idea id>. An idea id is never a run_id or job_id."
},
"include": {
"anyOf": [
{
"type": "array",
"items": {}
},
{
"type": "null"
}
],
"default": null,
"description": "Extra sections; [\"full\"] dumps the whole sheet on the sheet view"
},
"max_bpm": {
"anyOf": [
{
"type": "integer",
"minimum": 0
},
{
"type": "null"
}
],
"default": null,
"description": "Maximum tempo in BPM (media recommended_sounds view)"
},
"min_bpm": {
"anyOf": [
{
"type": "integer",
"minimum": 0
},
{
"type": "null"
}
],
"default": null,
"description": "Minimum tempo in BPM (media recommended_sounds view)"
},
"post_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Scheduled/published post ID (publish.post_status view)"
},
"agent_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The agent ID (envelope; forwarded to every view that scopes by agent). Optional: only the agent-scoped views require it — the vidsheet/media engine views resolve the owning agent from the sheet's engine read (GEN-7151). An agent-scoped view with no agent_id refuses with the caller's agents listed (agent_required): when the user has not already named an agent, read agent.list and ask them which to use — never guess."
},
"end_date": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Range end, ISO date (publish.scheduled view; required there, within a 60-day window with start_date)"
},
"layer_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Layer ID (layer, layer_analysis views; a layer id is unique on the sheet, so it is enough — pass cell_id to pin the read to one cell)"
},
"per_page": {
"anyOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "null"
}
],
"default": null,
"description": "Results per page (sound_library view, default 10)"
},
"platform": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Social platform (publish.connect_url view, default youtube)"
},
"produces": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Creation card output filter: text | image | video | audio | caption (card_types view)"
},
"provider": {
"anyOf": [
{
"enum": [
"platform_eleven_labs",
"eleven_labs",
"user_voice_resource"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Voice provider (voice.resource view): user_voice_resource for the agent's own voices (voice.mine), else the voice library; default platform_eleven_labs"
},
"template": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Template slug/UUID/ID (template view)"
},
"voice_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Voice resource ID (voice.resource view)"
},
"container": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Creation card attach filter: SpreadsheetCell | VideoLayer (card_types view)"
},
"folder_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Folder filter (asset.libraries view)"
},
"min_count": {
"anyOf": [
{
"type": "integer",
"minimum": 0
},
{
"type": "null"
}
],
"default": null,
"description": "Minimum engagement count (Pinterest keyword/hashtag posts)"
},
"page_size": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Page size (asset.libraries view)"
},
"placement": {
"anyOf": [
{
"type": "object",
"additionalProperties": true
},
{
"type": "null"
}
],
"default": null,
"description": "The card's layer as authored (input_bindings view): {source_asset_ref, source_clip, content_type}. When the layer places supplied footage, a reference to that same media through a field the card does not serve is satisfied by the placement. Without card_schema, returns placed_inputs: the referenced input ids this card-less layer consumes as its own footage."
},
"video_ids": {
"anyOf": [
{
"type": "array",
"items": {}
},
{
"type": "null"
}
],
"default": null,
"description": "Video/post ids (social.video_info, social.comments views; TikTok/Instagram/YouTube/Kick ids or URLs)"
},
"asset_type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Asset type filter (asset.libraries view)"
},
"audio_lens": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Audio ranking lens for the vidsheet.actions live discovery, from Rails' own lens set (e.g. scrape ranks creator-scraped audio)"
},
"audio_mood": {
"anyOf": [
{
"type": "string",
"maxLength": 100
},
{
"type": "null"
}
],
"default": null,
"description": "Filter recommended audio by mood (vidsheet.actions live discovery with audio_library=recommended)"
},
"commercial": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "Only sounds cleared for commercial use (sound_library and recommended_sounds views)"
},
"layer_type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Layer type to focus the vidsheet.actions view's LIVE discovery on (GEN-8203): caption, text, clip, sound and the other Rails layer types; layer_type=caption returns that layer's settings schema, whose styles.fontFamily enum lists the offered fonts. Omit for the static action guide."
},
"project_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Project filter (content.list view)"
},
"start_date": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Range start, ISO date (publish.scheduled view; required there, within a 60-day window with end_date)"
},
"audio_genre": {
"anyOf": [
{
"type": "string",
"maxLength": 100
},
{
"type": "null"
}
],
"default": null,
"description": "Filter recommended audio by genre (vidsheet.actions live discovery with audio_library=recommended)"
},
"audio_limit": {
"anyOf": [
{
"type": "integer",
"maximum": 20,
"minimum": 1
},
{
"type": "null"
}
],
"default": null,
"description": "Maximum ranked audio results, Rails default 10 (vidsheet.actions live discovery)"
},
"audio_query": {
"anyOf": [
{
"type": "string",
"maxLength": 200
},
{
"type": "null"
}
],
"default": null,
"description": "Scope recommended audio to an @creator, #hashtag or keyword (vidsheet.actions live discovery with audio_library=recommended)"
},
"card_inputs": {
"anyOf": [
{
"type": "object",
"additionalProperties": true
},
{
"type": "null"
}
],
"default": null,
"description": "The card's current inputs to bind into (input_bindings view); the MCP returns them with every source reference applied."
},
"card_schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Creation card to describe (card_schema view): an FE card type such as video-from-talking-avatar, lip-sync or video-from-text, final-video (the final render card — its creation_card_inputs is optional and built from the row's video layers), or its backend job_type; omit to list card types"
},
"resource_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Asset or content resource ID (asset.detail, content.resource views)"
},
"vidsheet_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Vidsheet ID"
},
"country_code": {
"anyOf": [
{
"type": "string",
"maxLength": 2,
"minLength": 2
},
{
"type": "null"
}
],
"default": null,
"description": "Two-letter country code (location.cities view)"
},
"from_db_only": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "Legacy social.video_info flag; the read-only view is unavailable because no provider-free DW contract is served. Use gen_analyze collect for live collection."
},
"watchlist_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Watchlist ID (watchlist.detail view)"
},
"workspace_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Filter agents by workspace (agent.list view)"
},
"audio_library": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Scoped audio library for the vidsheet.actions view's LIVE discovery (GEN-8203): recommended (ranked music for this agent; each media entry carries the signed library_reference a sound layer saves) or trending. Rails validates the value and a bad one passes its 422 through. Omit for the static action guide."
},
"audio_max_bpm": {
"anyOf": [
{
"type": "integer",
"maximum": 300,
"minimum": 1
},
{
"type": "null"
}
],
"default": null,
"description": "Maximum tempo in BPM for recommended audio (vidsheet.actions live discovery with audio_library=recommended)"
},
"audio_min_bpm": {
"anyOf": [
{
"type": "integer",
"maximum": 300,
"minimum": 1
},
{
"type": "null"
}
],
"default": null,
"description": "Minimum tempo in BPM for recommended audio (vidsheet.actions live discovery with audio_library=recommended)"
},
"generation_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Generation ID to poll (vidsheet generation view) or voice-design sample generation ID (voice.sample_status view)"
},
"source_inputs": {
"anyOf": [
{
"type": "object",
"additionalProperties": true
},
{
"type": "null"
}
],
"default": null,
"description": "Form view: confirmed cast context only; assets are read live. The resolved saved input media the references name (input_bindings view): {attachments: [{ref, url, kind, content_resource_id, resource...}]}, the same set gen_content_action built inputs from. The MCP is the only binding owner (GEN-9391)."
},
"user_job_type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Completed job type to map to a Vidsheet creation card (card_from_job view)"
},
"audio_platform": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Social platform whose audio usage is ranked (vidsheet.actions live discovery; Rails defaults it to tiktok)"
},
"include_undone": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "Include undone change sets (operations view)"
},
"watchlist_name": {
"anyOf": [
{
"type": "string",
"maxLength": 200,
"minLength": 1
},
{
"type": "null"
}
],
"default": null,
"description": "Watchlist display name or its @list mention slug (watchlist.detail view), resolved case-insensitively: an exact name or an equal slug as one candidate set, then a unique prefix; an ambiguous name answers the candidates. Pass this or watchlist_id."
},
"conversation_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Conversation ID (platform.conversation, platform.conversation_pending, platform.request_tree, platform.preferences views)"
},
"idempotency_key": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Original create-call key with idea_id for content.video_job transport readback"
},
"include_removed": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "Include removed backups (platform.backups view)"
},
"organization_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Organization ID (platform.organization view)"
},
"selecting_model": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "Skip the selected model's acceptance check because the model is not chosen yet (input_bindings view)."
},
"audio_search_type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "How to read audio_query: creator | hashtag | keyword (vidsheet.actions live discovery); an @ or # prefix infers it"
},
"audio_video_count": {
"anyOf": [
{
"type": "integer",
"maximum": 500,
"minimum": 1
},
{
"type": "null"
}
],
"default": null,
"description": "Maximum cached source videos scanned for creator/scrape ranking, Rails default 50 (vidsheet.actions live discovery)"
},
"audio_window_days": {
"anyOf": [
{
"type": "integer",
"maximum": 180,
"minimum": 1
},
{
"type": "null"
}
],
"default": null,
"description": "Audio lookback window in days, Rails default 30 (vidsheet.actions live discovery)"
},
"source_references": {
"anyOf": [
{
"type": "array",
"items": {}
},
{
"type": "null"
}
],
"default": null,
"description": "Saved-input references to bind (input_bindings view): one {input_id, card_type?, field?} per named upload or saved media. Omit to only resolve picker labels."
},
"audio_commercial_only": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "Only commercially licensed recommended audio (vidsheet.actions live discovery with audio_library=recommended)"
},
"with_organization_uuid": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "For agent.detail, 'true'/'false' controls whether the response includes the organization UUID; an organization UUID scopes the read"
}
},
"x-gen-delegation": {
"actions": null,
"excluded_actions": [
"agent.capabilities",
"agent.list",
"agent.monitoring",
"agent.profile_photos",
"agent.shares",
"billing.plans",
"billing.usage",
"content.directions",
"content.ideas",
"location.cities",
"location.countries",
"media.recommended_sounds",
"media.sound_library",
"platform.api_keys",
"platform.backups",
"platform.conversation",
"platform.conversation_pending",
"platform.conversations",
"platform.members",
"platform.organization",
"platform.organizations",
"platform.preferences",
"platform.workspaces",
"publish.connect_url",
"publish.connections",
"publish.post_status",
"publish.scheduled",
"task.job",
"task.list",
"voice.sample_status",
"watchlist.detail"
]
},
"additionalProperties": false
}| agent_id | any | The agent ID that owns the workspace (envelope; routed per branch) |
| confirm_token | any | Single-use token from a CONFIRMATION_REQUIRED error; repeat the same call with it to complete the destructive action it was issued for. Omit on the first call. |
| spending_run_id | string | Stable run or conversation identity required with spending controls. The authenticated run owner shares one policy across workspaces. |
| max_paid_operations | integer | Maximum paid media reservations across all workspaces in this authenticated user/run, enforced atomically. Retries reuse their reservation. |
{
"type": "object",
"required": [
"actions"
],
"properties": {
"actions": {
"type": "array",
"items": {
"oneOf": [
{
"type": "object",
"required": [
"action",
"prompt"
],
"properties": {
"action": {
"const": "create_image"
},
"prompt": {
"type": "string",
"description": "Image generation prompt"
},
"version": {
"anyOf": [
{
"enum": [
"gemini_2",
"gemini_2_lite",
"gemini_pro",
"gpt-image-2",
"gpt-image-2.5-flare",
"gpt-image-2.5-sunburst",
"grok",
"midjourney",
"seedream-4.0",
"seedream-4.5"
],
"type": "string"
},
{
"type": "null"
}
],
"default": "seedream-4.0",
"description": "Image model: gemini_2 (Nano Banana 2) | gemini_2_lite (Nano Banana 2 Lite) | gemini_pro (Nano Banana Pro) | gpt-image-2 (GPT Image 2) | gpt-image-2.5-flare (GPT Image 2.5 Flare) | gpt-image-2.5-sunburst (GPT Image 2.5 Sunburst) | grok (Grok) | midjourney (Midjourney 8.2) | seedream-4.0 (Seedream 4.0) | seedream-4.5 (Seedream 4.5) (default seedream-4.0)"
},
"aspect_ratio": {
"anyOf": [
{
"enum": [
"1:1",
"9:16",
"16:9",
"4:3",
"3:4",
"3:2",
"2:3"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"idempotency_key": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Stable retry key (sent as the Idempotency-Key header, max 255 chars). Reuse the same key when retrying this exact create so Rails replays the originally created resource (same id) instead of creating a duplicate. Omit to create unconditionally."
},
"number_of_images": {
"anyOf": [
{
"type": "integer",
"maximum": 10,
"minimum": 1
},
{
"type": "null"
}
],
"default": null,
"description": "Number of images to generate (1-10, default 1)"
},
"reference_images": {
"anyOf": [
{
"type": "array",
"items": {}
},
{
"type": "null"
}
],
"default": null,
"description": "List of public image URLs for image-to-image reference (up to 10)"
},
"content_resource_ids": {
"anyOf": [
{
"type": "array",
"items": {}
},
{
"type": "null"
}
],
"default": null,
"description": "GEN content resource IDs to use as reference images (preferred over reference_images; supported by the gemini, seedream and gpt-image models)"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"prompt"
],
"properties": {
"model": {
"anyOf": [
{
"enum": [
"suno-v4.5plus-beta",
"suno-v5-beta",
"suno-v5.5-beta"
],
"type": "string"
},
{
"type": "null"
}
],
"default": "suno-v5-beta",
"description": "Model: suno-v4.5plus-beta | suno-v5-beta | suno-v5.5-beta (default suno-v5-beta)"
},
"style": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Musical style/genre/mood (max 1000 chars)"
},
"title": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Song title (max 80 chars)"
},
"action": {
"const": "create_song"
},
"prompt": {
"type": "string",
"description": "Song description / lyrics prompt"
},
"duration": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Duration in seconds; Rails owns the model-specific validation"
},
"audio_weight": {
"anyOf": [
{
"type": "number",
"maximum": 1,
"minimum": 0
},
{
"type": "null"
}
],
"default": null,
"description": "Audio conditioning fidelity 0.0-1.0"
},
"instrumental": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "True to generate without vocals"
},
"vocal_gender": {
"anyOf": [
{
"enum": [
"m",
"f"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"negative_tags": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Styles/instruments to avoid (max 500 chars)"
},
"idempotency_key": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Stable retry key (sent as the Idempotency-Key header, max 255 chars). Reuse the same key when retrying this exact create so Rails replays the originally created resource (same id) instead of creating a duplicate. Omit to create unconditionally."
},
"source_audio_url": {
"anyOf": [
{
"type": "string",
"pattern": "^https://"
},
{
"type": "null"
}
],
"default": null,
"description": "Direct HTTPS audio URL for audio-to-audio conditioning"
},
"source_audio_resource_id": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "GEN content resource ID for audio-to-audio conditioning"
}
},
"additionalProperties": false
},
{
"type": "object",
"anyOf": [
{
"required": [
"tracks"
],
"properties": {
"tracks": {
"minItems": 2
}
}
}
],
"required": [
"action",
"tracks"
],
"properties": {
"action": {
"const": "create_song_mix"
},
"prompt": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Custom DJ mix prompt. Omit to use the default optimal-order BPM/key/mood prompt."
},
"tracks": {
"type": "array",
"items": {},
"description": "REQUIRED — at least two track objects to mix, each carrying at least one of title | url | asset_id, e.g. [{'url': 'https://cdn.example/a.mp3'}, {'title': 'Song name'}]. The endpoint mixes only the tracks you send; it does not auto-generate songs."
},
"auto_order": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "Whether GEN should choose optimal order by BPM/key/mood. Defaults true."
},
"confirm_token": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Single-use token from a CONFIRMATION_REQUIRED reply, which states the credit price; resend the identical call with it to render the mix. Omit on the first call."
},
"output_format": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Final audio format. Defaults to mp3."
},
"transition_style": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Transition style, e.g. professional, smooth, high-energy."
},
"generate_missing_count": {
"anyOf": [
{
"type": "number",
"minimum": 1
},
{
"type": "null"
}
],
"default": null,
"description": "Planning hint: the song count the default mix prompt assumes. It never generates songs — the endpoint only mixes the tracks sent above."
},
"desired_duration_seconds": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Desired final mix duration in seconds."
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"prompt"
],
"properties": {
"model": {
"anyOf": [
{
"enum": [
"gemini-omni-1.1-flash",
"grok",
"kling-v3",
"seedance-2.0",
"seedance-2.0-fast",
"seedance-2.0-less-restriction",
"seedance-2.5",
"seedance-2.5-less-restriction",
"kling-v2-6",
"minimax-h3-max"
],
"type": "string"
},
{
"type": "null"
}
],
"default": "seedance-2.0-fast",
"description": "Model: gemini-omni-1.1-flash | grok | kling-v3 | seedance-2.0 | seedance-2.0-fast | seedance-2.0-less-restriction | seedance-2.5 | seedance-2.5-less-restriction | kling-v2-6 | minimax-h3-max (default seedance-2.0-fast)"
},
"action": {
"const": "create_video"
},
"prompt": {
"type": "string",
"description": "Video generation prompt"
},
"duration": {
"anyOf": [
{
"ge": 1,
"le": 30,
"enum": [
1,
2,
3,
4,
5,
6,
7,
8,
9,
10,
11,
12,
13,
14,
15,
16,
17,
18,
19,
20,
21,
22,
23,
24,
25,
26,
27,
28,
29,
30
],
"type": "integer",
"maximum": 30,
"minimum": 1
},
{
"type": "null"
}
],
"default": null
},
"resolution": {
"anyOf": [
{
"enum": [
"480p",
"720p",
"1080p",
"768p"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"aspect_ratio": {
"anyOf": [
{
"enum": [
"1:1",
"9:16",
"16:9",
"4:3",
"3:4",
"3:2",
"2:3"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"native_audio": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "Request model-native audio where supported (default false)"
},
"idempotency_key": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Stable retry key (sent as the Idempotency-Key header, max 255 chars). Reuse the same key when retrying this exact create so Rails replays the originally created resource (same id) instead of creating a duplicate. Omit to create unconditionally."
},
"reference_images": {
"anyOf": [
{
"type": "array",
"items": {}
},
{
"type": "null"
}
],
"default": null,
"description": "Public image URLs for image-to-video (up to 10)."
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action"
],
"properties": {
"action": {
"const": "transcribe"
},
"audio_url": {
"anyOf": [
{
"type": "string",
"pattern": "^https://"
},
{
"type": "null"
}
],
"default": null,
"description": "Public HTTPS URL to an audio file to transcribe"
},
"video_url": {
"anyOf": [
{
"type": "string",
"pattern": "^https://"
},
{
"type": "null"
}
],
"default": null,
"description": "Public HTTPS URL to a video; its audio track is extracted and transcribed"
},
"idempotency_key": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Stable retry key (sent as the Idempotency-Key header, max 255 chars). Reuse the same key when retrying this exact create so Rails replays the originally created resource (same id) instead of creating a duplicate. Omit to create unconditionally."
},
"trim_start_seconds": {
"anyOf": [
{
"type": "number",
"minimum": 0
},
{
"type": "null"
}
],
"default": null,
"description": "Start of the window to transcribe (seconds); requires trim_duration_seconds"
},
"content_resource_id": {
"anyOf": [
{
"type": "string",
"pattern": "^[0-9]+$"
},
{
"type": "null"
}
],
"default": null,
"description": "ID of an existing GEN content resource to transcribe"
},
"trim_duration_seconds": {
"anyOf": [
{
"type": "number",
"exclusiveMinimum": 0
},
{
"type": "null"
}
],
"default": null,
"description": "Length of the window to transcribe (seconds); requires trim_start_seconds"
}
},
"additionalProperties": false
}
]
},
"minItems": 1,
"description": "One or more typed media actions: create_image (prompt, optional version/aspect_ratio/number_of_images/reference_images/content_resource_ids) | create_video (prompt, optional model/aspect_ratio/resolution/duration/native_audio/reference_images) | create_song (prompt, optional model/duration/style/title/negative_tags/vocal_gender/instrumental/source_audio) | create_song_mix (tracks REQUIRED: at least two of {title|url|asset_id}; optional prompt/transition_style/output_format/auto_order/desired_duration_seconds/generate_missing_count) | transcribe (exactly one of audio_url/video_url/content_resource_id, optional trim window)"
},
"no_paid": {
"type": "boolean",
"default": false,
"description": "Refuse paid media generation for this run. Text and LLM work still bills normally."
},
"agent_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The agent ID that owns the workspace (envelope; routed per branch)"
},
"confirm_token": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Single-use token from a CONFIRMATION_REQUIRED error; repeat the same call with it to complete the destructive action it was issued for. Omit on the first call."
},
"spending_run_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,128}$",
"maxLength": 128,
"minLength": 1,
"description": "Stable run or conversation identity required with spending controls. The authenticated run owner shares one policy across workspaces."
},
"max_paid_operations": {
"type": "integer",
"maximum": 2147483647,
"minimum": 0,
"description": "Maximum paid media reservations across all workspaces in this authenticated user/run, enforced atomically. Retries reuse their reservation."
}
},
"x-gen-delegation": {
"actions": [
"create_image",
"transcribe"
],
"excluded_actions": []
},
"additionalProperties": false
}| references* |
| array |
| Verified first-party We Believe references (official site or @webelieveinedu) with explicit observed_at; each declares the playbook principles it supports |
| report_key* | string | Stable report run key; one idempotency key per source is derived from it so a retry cannot start a second billed run |
| excluded_keys | any | Source keys/aliases already used in earlier reports |
| peer_evidence | any | Verified peer posts with exact metrics; passed to the generator as evidence and attached verbatim, never inferred or topped up |
| playbook_text* | string | The current master playbook's own mission/voice text; every playbook principle must appear in it, and it grounds the idea generator as We Believe |
| playbook_principles* | array | The current master playbook's closed principle names |
{
"type": "object",
"required": [
"agent_id",
"sources",
"references",
"playbook_principles",
"playbook_text",
"count",
"report_key"
],
"properties": {
"count": {
"type": "integer",
"maximum": 25,
"minimum": 1,
"description": "How many report ideas to compose (at most one per selected comment)"
},
"sources": {
"type": "array",
"items": {
"type": "object",
"required": [
"source_key",
"platform",
"url",
"text",
"likes",
"published_at"
],
"properties": {
"url": {
"type": "string",
"minLength": 1,
"description": "Canonical post URL the comment was made on"
},
"text": {
"type": "string",
"minLength": 1,
"description": "The measured comment text"
},
"likes": {
"type": "integer",
"minimum": 0,
"description": "Measured likes (never a guess)"
},
"aliases": {
"type": "array",
"items": {
"type": "string"
},
"description": "Earlier ids this comment is known by"
},
"platform": {
"type": "string",
"description": "instagram | tiktok"
},
"principle": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The master-playbook principle this comment serves"
},
"source_key": {
"type": "string",
"minLength": 1,
"description": "Caller-stable identity for this measured comment"
},
"published_at": {
"type": "string",
"description": "Comment instant, ISO 8601 UTC"
}
},
"description": "One measured comment the report may build an idea from.\n\n``source_key`` is the caller's stable identity for the comment; the MCP\nbinds the returned idea to exactly this key and never trusts a key echoed\nback by the model (GEN-9371).",
"additionalProperties": false
},
"description": "Measured Instagram/TikTok comments; each carries its stable source_key, platform, url, text, likes, published_at, aliases and the master-playbook principle it serves"
},
"agent_id": {
"type": "string",
"description": "The agent ID the report ideas belong to (envelope; the generation is billed to it)"
},
"period_end": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Window end instant (ISO 8601 UTC); defaults to now"
},
"references": {
"type": "array",
"items": {
"type": "object",
"required": [
"ref_key",
"url",
"title",
"source",
"principles",
"observed_at"
],
"properties": {
"url": {
"type": "string",
"minLength": 1
},
"title": {
"type": "string",
"minLength": 1
},
"source": {
"type": "string",
"description": "official_site | webelieveinedu"
},
"ref_key": {
"type": "string",
"minLength": 1
},
"principles": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"description": "Playbook principles this reference supports"
},
"observed_at": {
"type": "string",
"description": "When this reference was verified, ISO 8601 UTC"
},
"owner_username": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Typed verified owner of an Instagram reference. A post/Reel permalink is accepted only when this names the campaign account."
},
"owner_profile_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Typed verified owner profile URL; when supplied for an Instagram reference it must be the official webelieveinedu profile."
}
},
"description": "One verified first-party We Believe reference.\n\n``source`` must be an owned owner; anything else is refused rather than\nsilently cited. Freshness is explicit in ``observed_at``.",
"additionalProperties": false
},
"description": "Verified first-party We Believe references (official site or @webelieveinedu) with explicit observed_at; each declares the playbook principles it supports"
},
"report_key": {
"type": "string",
"minLength": 1,
"description": "Stable report run key; one idempotency key per source is derived from it so a retry cannot start a second billed run"
},
"excluded_keys": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"default": null,
"description": "Source keys/aliases already used in earlier reports"
},
"peer_evidence": {
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"required": [
"url",
"title"
],
"properties": {
"url": {
"type": "string",
"minLength": 1
},
"title": {
"type": "string",
"minLength": 1
},
"metrics": {
"type": "object",
"description": "Exact verified metrics, e.g. {likes: 12000}",
"additionalProperties": {
"type": "integer"
}
}
},
"description": "One verified peer post with its exact metrics, attached verbatim.",
"additionalProperties": false
}
},
{
"type": "null"
}
],
"default": null,
"description": "Verified peer posts with exact metrics; passed to the generator as evidence and attached verbatim, never inferred or topped up"
},
"playbook_text": {
"type": "string",
"minLength": 1,
"description": "The current master playbook's own mission/voice text; every playbook principle must appear in it, and it grounds the idea generator as We Believe"
},
"playbook_principles": {
"type": "array",
"items": {
"type": "string"
},
"description": "The current master playbook's closed principle names"
}
},
"x-gen-delegation": {
"actions": [],
"excluded_actions": []
},
"additionalProperties": false
}| actions* |
| array |
| One or more typed platform actions: create_api_key (optional name/expires_in) | create_organization (name) | create_proof_of_genesis_backup (asset_url, optional asset_type/visibility/encrypted/encryption_scheme/encryption_key_id/owner_sui_address/source_event/content_type/idempotency_key/metadata) | delete_organization (organization_id) | invite_member (organization_id, username_or_email, optional role viewer|editor|manager) | leave_workspace (organization_id) | remove_member (organization_id, user_id) | remove_proof_of_genesis_backup (backup_id) | revoke_all_api_keys (no fields) | revoke_api_key (token_id) | set_member_role (organization_id, username_or_email, role viewer|editor|manager) | start_seat_checkout (organization_id, return_url) | transfer_workspace_ownership (organization_id, username_or_email) | update_api_key (token_id, name) | update_organization (organization_id, name) | update_session_preferences (conversation_id, preferences) | upgrade_workspace (organization_id, credit_plan_id, return_url) | request_email_link_code (email) | resend_email_link_code (request_id) | verify_email_link_code (request_id, code as TEXT preserving leading zeros) |
| agent_id | any | The agent ID that owns the workspace (envelope; routed into the backup branches) |
| confirm_token | any | Single-use token from a CONFIRMATION_REQUIRED error; repeat the same call with it to complete the destructive action it was issued for. Omit on the first call. |
{
"type": "object",
"required": [
"actions"
],
"properties": {
"actions": {
"type": "array",
"items": {
"oneOf": [
{
"type": "object",
"required": [
"action"
],
"properties": {
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Descriptive name for the API key"
},
"action": {
"const": "create_api_key"
},
"expires_in": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Seconds until the key expires. Omit for a non-expiring key."
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"name"
],
"properties": {
"name": {
"type": "string",
"description": "Display name for the organization"
},
"action": {
"const": "create_organization"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"asset_url"
],
"properties": {
"action": {
"const": "create_proof_of_genesis_backup"
},
"metadata": {
"anyOf": [
{
"type": "object",
"additionalProperties": true
},
{
"type": "null"
}
],
"default": null,
"description": "Caller metadata such as content_resource_id, vidsheet_id, row_id, project_id, or publish id."
},
"asset_url": {
"type": "string",
"description": "GEN asset URL to back up. Use assets.gen.pro URLs when available."
},
"encrypted": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "Whether the bytes at asset_url are already encrypted before Walrus upload. Required for private backups. Defaults to false."
},
"asset_type": {
"anyOf": [
{
"enum": [
"video",
"image",
"json"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Asset type: video, image, or json. When omitted, inferred from the asset URL extension or content_type (json for .json/application/json), falling back to the backend default when neither names it."
},
"visibility": {
"anyOf": [
{
"enum": [
"private",
"public"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Asset visibility. Private assets must send encrypted=true and encryption_scheme; raw private requests are rejected before billing or Walrus work. Defaults to the backend's private."
},
"content_type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "MIME type if known, e.g. video/mp4 or image/png. Used to infer asset_type when it is omitted."
},
"source_event": {
"anyOf": [
{
"enum": [
"generated",
"uploaded",
"downloaded",
"published",
"manual"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Why this backup is being created. Defaults to the backend's manual."
},
"idempotency_key": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Stable retry key, e.g. content-resource id plus version, to avoid duplicate upload/billing."
},
"encryption_key_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Optional key policy/version identifier for private proof metadata."
},
"encryption_scheme": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Encryption scheme for private backups, e.g. seal/v1."
},
"owner_sui_address": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Optional customer Sui wallet address that should own the Walrus object. Omit for server-triggered auto-backup when Agent Core resolves the user's Dynamic Sui wallet."
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"organization_id"
],
"properties": {
"action": {
"const": "delete_organization"
},
"organization_id": {
"type": "string",
"description": "The organization ID to delete"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"organization_id",
"username_or_email"
],
"properties": {
"role": {
"enum": [
"viewer",
"editor",
"manager"
],
"type": "string",
"default": "editor",
"description": "Workspace role to grant: viewer | editor | manager"
},
"action": {
"const": "invite_member"
},
"organization_id": {
"type": "string",
"description": "The workspace/organization ID"
},
"username_or_email": {
"type": "string",
"description": "Email (or username) of the person to add"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"organization_id"
],
"properties": {
"action": {
"const": "leave_workspace"
},
"organization_id": {
"type": "string",
"description": "The workspace/organization ID to leave"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"organization_id",
"user_id"
],
"properties": {
"action": {
"const": "remove_member"
},
"user_id": {
"type": "integer",
"description": "The member's user ID from the platform.members view"
},
"organization_id": {
"type": "string",
"description": "The workspace/organization ID"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"backup_id"
],
"properties": {
"action": {
"const": "remove_proof_of_genesis_backup"
},
"backup_id": {
"type": "number",
"description": "The Proof of Genesis backup id"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"email"
],
"properties": {
"email": {
"type": "string",
"description": "Email address to verify and attach as this account's FIRST sign-in email. GEN emails a six-digit code to it; ask the user to read the code from that inbox and call verify_email_link_code with the request_id this returns. GEN never reads the inbox and never returns the code. Only an account with no email and no linked identity can link one; an account that already has an email or Google sign-in is refused with reauthentication_required, and the change happens in the browser profile instead."
},
"action": {
"const": "request_email_link_code"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"request_id"
],
"properties": {
"action": {
"const": "resend_email_link_code"
},
"request_id": {
"type": "string",
"description": "The request_id returned by request_email_link_code. Identifies the verification challenge to email again; use it after the resend_after instant, and only while the account is still unclaimed."
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action"
],
"properties": {
"action": {
"const": "revoke_all_api_keys"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"token_id"
],
"properties": {
"action": {
"const": "revoke_api_key"
},
"token_id": {
"type": "string",
"description": "The token ID to revoke"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"organization_id",
"username_or_email",
"role"
],
"properties": {
"role": {
"enum": [
"viewer",
"editor",
"manager"
],
"type": "string",
"description": "New workspace role: viewer | editor | manager"
},
"action": {
"const": "set_member_role"
},
"organization_id": {
"type": "string",
"description": "The workspace/organization ID"
},
"username_or_email": {
"type": "string",
"description": "Email (or username) of the existing member"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"organization_id",
"return_url"
],
"properties": {
"action": {
"const": "start_seat_checkout"
},
"return_url": {
"type": "string",
"description": "HTTPS URL to return the payer to after checkout"
},
"organization_id": {
"type": "string",
"description": "The workspace/organization ID buying the seat"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"organization_id",
"username_or_email"
],
"properties": {
"action": {
"const": "transfer_workspace_ownership"
},
"organization_id": {
"type": "string",
"description": "The workspace/organization ID"
},
"username_or_email": {
"type": "string",
"description": "Email (or username) of the new owner"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"token_id",
"name"
],
"properties": {
"name": {
"type": "string",
"description": "New display name for the API key"
},
"action": {
"const": "update_api_key"
},
"token_id": {
"type": "string",
"description": "The token ID to rename"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"organization_id",
"name"
],
"properties": {
"name": {
"type": "string",
"description": "New display name for the organization"
},
"action": {
"const": "update_organization"
},
"organization_id": {
"type": "string",
"description": "The organization ID to update"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"conversation_id",
"preferences"
],
"properties": {
"action": {
"const": "update_session_preferences"
},
"preferences": {
"type": "string",
"description": "The session preferences text to apply to this conversation"
},
"conversation_id": {
"type": "string",
"description": "The conversation ID"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"organization_id",
"credit_plan_id",
"return_url"
],
"properties": {
"action": {
"const": "upgrade_workspace"
},
"return_url": {
"type": "string",
"description": "URL to redirect to after the checkout completes"
},
"confirm_token": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Single-use token from a CONFIRMATION_REQUIRED preview; repeat the same call with it to run the upgrade it previewed"
},
"credit_plan_id": {
"type": "string",
"description": "The target plan ID from the gen_discover billing.plans view"
},
"organization_id": {
"type": "string",
"description": "The organization/workspace ID to upgrade"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"request_id",
"code"
],
"properties": {
"code": {
"type": "string",
"pattern": "^[0-9]{6}$",
"maxLength": 6,
"minLength": 6,
"description": "The six-digit verification code the user read out of their email, as TEXT. Preserve leading zeros (send \"012345\", never the number 12345): a numeric value loses them and is refused. Never invent or guess a code."
},
"action": {
"const": "verify_email_link_code"
},
"request_id": {
"type": "string",
"description": "The request_id returned by request_email_link_code or resend_email_link_code."
}
},
"additionalProperties": false
}
]
},
"minItems": 1,
"description": "One or more typed platform actions: create_api_key (optional name/expires_in) | create_organization (name) | create_proof_of_genesis_backup (asset_url, optional asset_type/visibility/encrypted/encryption_scheme/encryption_key_id/owner_sui_address/source_event/content_type/idempotency_key/metadata) | delete_organization (organization_id) | invite_member (organization_id, username_or_email, optional role viewer|editor|manager) | leave_workspace (organization_id) | remove_member (organization_id, user_id) | remove_proof_of_genesis_backup (backup_id) | revoke_all_api_keys (no fields) | revoke_api_key (token_id) | set_member_role (organization_id, username_or_email, role viewer|editor|manager) | start_seat_checkout (organization_id, return_url) | transfer_workspace_ownership (organization_id, username_or_email) | update_api_key (token_id, name) | update_organization (organization_id, name) | update_session_preferences (conversation_id, preferences) | upgrade_workspace (organization_id, credit_plan_id, return_url) | request_email_link_code (email) | resend_email_link_code (request_id) | verify_email_link_code (request_id, code as TEXT preserving leading zeros)"
},
"agent_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The agent ID that owns the workspace (envelope; routed into the backup branches)"
},
"confirm_token": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Single-use token from a CONFIRMATION_REQUIRED error; repeat the same call with it to complete the destructive action it was issued for. Omit on the first call."
}
},
"x-gen-delegation": {
"actions": [],
"excluded_actions": []
},
"additionalProperties": false
}| Argument | Type | Description |
|---|---|---|
| actions* | array | One or more typed publish actions: schedule_post_tiktok (media_url, tiktok_privacy_level, tiktok_disable_comment, tiktok_disable_duet, tiktok_disable_stitch, optional description/thumbnail_url/tiktok_disclose_commercial_content/tiktok_your_brand/tiktok_branded_content) | schedule_post_instagram (media_url, optional description/thumbnail_url/media_urls (2-10 = carousel)/instagram_music) | schedule_post_facebook (media_url, optional description/title/thumbnail_url) | schedule_post_youtube (media_url, title, optional description/thumbnail_url/youtube_options) | schedule_post_x (optional description/media_url/media_urls (up to 4 images)/media_type/thread/reply_to_tweet_id) | schedule_post_linkedin (optional description/media_url/media_urls (up to 9 images)/title/thumbnail_url/linkedin_options); every schedule_post_* branch also takes schedule_type ('now' | 'specific_time'; omitted it defaults to 'now' and publishes immediately), scheduled_time (ISO 8601 UTC), timezone_offset (hours), strict | publish_content (platform, media_url, description, schedule_type, optional title/media_type/scheduled_time/thumbnail_url/timezone_offset) | update_scheduled_post (post_id, fields) | delete_scheduled_post (post_id) | update_published_post (post_id, optional title/description/tags/category_id) | delete_published_post (post_id, two-phase — resend with confirm_token) | disconnect_social (platform, two-phase — resend with confirm_token). Reconnecting or refreshing an account is gen_discover publish.connect_url only — never disconnect_social first; connecting again replaces the old token. |
| agent_id | any | The agent ID that owns the connected accounts (envelope; routed per branch) |
| confirm_token | any | Single-use token from a CONFIRMATION_REQUIRED error; repeat the same call with it to complete the destructive action it was issued for. Omit on the first call. |
{
"type": "object",
"required": [
"actions"
],
"properties": {
"actions": {
"type": "array",
"items": {
"oneOf": [
{
"type": "object",
"required": [
"action",
"post_id"
],
"properties": {
"action": {
"const": "delete_published_post"
},
"post_id": {
"type": "string",
"description": "The post ID returned by the schedule_post_<platform> branch (the post must already be published)"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"post_id"
],
"properties": {
"action": {
"const": "delete_scheduled_post"
},
"post_id": {
"type": "string",
"description": "The post ID to delete"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"platform"
],
"properties": {
"action": {
"const": "disconnect_social"
},
"platform": {
"type": "string",
"description": "Platform to disconnect: tiktok | instagram | facebook | youtube | x | linkedin"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"platform",
"description",
"schedule_type"
],
"properties": {
"title": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Post title"
},
"action": {
"const": "publish_content"
},
"row_id": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The vidsheet row whose final video is posted (with vidsheet_id)."
},
"platform": {
"type": "string",
"description": "Target platform (currently only tiktok)"
},
"media_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Public URL to the media file (must be accessible at post time). Required unless vidsheet_id + row_id name the row whose final video is posted."
},
"media_type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Media type (default VIDEO)"
},
"description": {
"type": "string",
"description": "Post caption/description. Max ~2200 chars for TikTok. Include hashtags inline."
},
"user_job_id": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The generation being posted. The same user_job_id is posted once per platform; a repeat answers already_published with the first post id."
},
"vidsheet_id": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "With row_id: post that row's rendered final video. A row with no final video is refused (no_final_video_cell); another row's video is never used."
},
"schedule_type": {
"type": "string",
"description": "'now' publishes immediately; 'scheduled' posts at scheduled_time"
},
"thumbnail_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Custom thumbnail URL"
},
"scheduled_time": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "ISO 8601 UTC datetime. Required when schedule_type is 'scheduled'."
},
"timezone_offset": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Timezone offset in minutes from UTC (default 0)"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"media_url"
],
"properties": {
"title": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"action": {
"const": "schedule_post_facebook"
},
"strict": {
"type": "boolean",
"default": null
},
"media_url": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"schedule_type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"thumbnail_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"scheduled_time": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"timezone_offset": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"media_url"
],
"properties": {
"action": {
"const": "schedule_post_instagram"
},
"strict": {
"type": "boolean",
"default": null
},
"media_url": {
"type": "string"
},
"media_urls": {
"anyOf": [
{
"type": "array",
"items": {}
},
{
"type": "null"
}
],
"default": null
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"schedule_type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"thumbnail_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"scheduled_time": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"instagram_music": {
"anyOf": [
{
"type": "object",
"additionalProperties": true
},
{
"type": "null"
}
],
"default": null
},
"timezone_offset": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action"
],
"properties": {
"title": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"action": {
"const": "schedule_post_linkedin"
},
"strict": {
"type": "boolean",
"default": null
},
"media_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"media_urls": {
"anyOf": [
{
"type": "array",
"items": {}
},
{
"type": "null"
}
],
"default": null
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"schedule_type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"thumbnail_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"scheduled_time": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"timezone_offset": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null
},
"linkedin_options": {
"anyOf": [
{
"type": "object",
"additionalProperties": true
},
{
"type": "null"
}
],
"default": null
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"media_url",
"tiktok_privacy_level",
"tiktok_disable_comment",
"tiktok_disable_duet",
"tiktok_disable_stitch"
],
"properties": {
"action": {
"const": "schedule_post_tiktok"
},
"strict": {
"type": "boolean",
"default": null
},
"media_url": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"schedule_type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"thumbnail_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"scheduled_time": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"timezone_offset": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null
},
"tiktok_your_brand": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null
},
"tiktok_disable_duet": {
"type": "boolean"
},
"tiktok_privacy_level": {
"type": "string"
},
"tiktok_disable_stitch": {
"type": "boolean"
},
"tiktok_branded_content": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null
},
"tiktok_disable_comment": {
"type": "boolean"
},
"tiktok_disclose_commercial_content": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action"
],
"properties": {
"action": {
"const": "schedule_post_x"
},
"strict": {
"type": "boolean",
"default": null
},
"thread": {
"anyOf": [
{
"type": "array",
"items": {}
},
{
"type": "null"
}
],
"default": null
},
"media_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"media_type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"media_urls": {
"anyOf": [
{
"type": "array",
"items": {}
},
{
"type": "null"
}
],
"default": null
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"schedule_type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"scheduled_time": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"timezone_offset": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null
},
"reply_to_tweet_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"media_url",
"title"
],
"properties": {
"title": {
"type": "string"
},
"action": {
"const": "schedule_post_youtube"
},
"strict": {
"type": "boolean",
"default": null
},
"media_url": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"schedule_type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"thumbnail_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"scheduled_time": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"timezone_offset": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null
},
"youtube_options": {
"anyOf": [
{
"type": "object",
"additionalProperties": true
},
{
"type": "null"
}
],
"default": null
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"post_id"
],
"properties": {
"tags": {
"anyOf": [
{
"type": "array",
"items": {}
},
{
"type": "null"
}
],
"default": null,
"description": "YouTube only — replaces the video's tags. Each tag 2+ characters, 400 characters in total."
},
"title": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "New title. YouTube: up to 100 characters, cannot be blank."
},
"action": {
"const": "update_published_post"
},
"post_id": {
"type": "string",
"description": "The post ID returned by the schedule_post_<platform> branch (the post must already be published)"
},
"category_id": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "YouTube only — video category ID (e.g. 22 People & Blogs, 24 Entertainment)."
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "New description/caption. YouTube: up to 5,000 characters."
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"post_id",
"fields"
],
"properties": {
"action": {
"const": "update_scheduled_post"
},
"fields": {
"type": "object",
"description": "Fields to update (sparse — only send what changes)",
"additionalProperties": true
},
"post_id": {
"type": "string",
"description": "The post ID to update"
}
},
"additionalProperties": false
}
]
},
"minItems": 1,
"description": "One or more typed publish actions: schedule_post_tiktok (media_url, tiktok_privacy_level, tiktok_disable_comment, tiktok_disable_duet, tiktok_disable_stitch, optional description/thumbnail_url/tiktok_disclose_commercial_content/tiktok_your_brand/tiktok_branded_content) | schedule_post_instagram (media_url, optional description/thumbnail_url/media_urls (2-10 = carousel)/instagram_music) | schedule_post_facebook (media_url, optional description/title/thumbnail_url) | schedule_post_youtube (media_url, title, optional description/thumbnail_url/youtube_options) | schedule_post_x (optional description/media_url/media_urls (up to 4 images)/media_type/thread/reply_to_tweet_id) | schedule_post_linkedin (optional description/media_url/media_urls (up to 9 images)/title/thumbnail_url/linkedin_options); every schedule_post_* branch also takes schedule_type ('now' | 'specific_time'; omitted it defaults to 'now' and publishes immediately), scheduled_time (ISO 8601 UTC), timezone_offset (hours), strict | publish_content (platform, media_url, description, schedule_type, optional title/media_type/scheduled_time/thumbnail_url/timezone_offset) | update_scheduled_post (post_id, fields) | delete_scheduled_post (post_id) | update_published_post (post_id, optional title/description/tags/category_id) | delete_published_post (post_id, two-phase — resend with confirm_token) | disconnect_social (platform, two-phase — resend with confirm_token). Reconnecting or refreshing an account is gen_discover publish.connect_url only — never disconnect_social first; connecting again replaces the old token."
},
"agent_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The agent ID that owns the connected accounts (envelope; routed per branch)"
},
"confirm_token": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Single-use token from a CONFIRMATION_REQUIRED error; repeat the same call with it to complete the destructive action it was issued for. Omit on the first call."
}
},
"x-gen-delegation": {
"actions": [],
"excluded_actions": []
},
"additionalProperties": false
}| agent_id | any | The agent ID that owns the jobs (envelope; routed per branch) |
| confirm_token | any | Single-use token from a CONFIRMATION_REQUIRED error; repeat the same call with it to complete the destructive action it was issued for. Omit on the first call. |
{
"type": "object",
"required": [
"actions"
],
"properties": {
"actions": {
"type": "array",
"items": {
"oneOf": [
{
"type": "object",
"required": [
"action",
"platform",
"search_type",
"value"
],
"properties": {
"days": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Filter to content from last N days: 0 (no filter), 1, 7, 30, 90, or 180"
},
"value": {
"type": "string",
"description": "Search value: @username, #hashtag, or keyword text"
},
"action": {
"const": "create_monitoring_job"
},
"platform": {
"type": "string",
"description": "Target platform"
},
"monitoring": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "true for ongoing monitoring, false for one-time scrape (default)"
},
"max_results": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Max results per scrape (1-50)"
},
"search_type": {
"type": "string",
"description": "Search type — must be supported by the chosen platform"
},
"comment_monitoring": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "true to also scrape comments (adds per-comment cost)"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"job_type",
"prompt",
"schedule"
],
"properties": {
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Display name. Defaults to the first 80 chars of prompt if omitted."
},
"action": {
"const": "create_recurring_job"
},
"prompt": {
"type": "string",
"description": "Natural-language prompt the agent runs each cycle (e.g. 'Generate 5 TikTok content ideas for my skincare brand')"
},
"actions": {
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
}
},
{
"type": "null"
}
],
"default": null
},
"delivery": {
"anyOf": [
{
"type": "object",
"additionalProperties": true
},
{
"type": "null"
}
],
"default": null,
"description": "Delivery config, e.g. {'type': 'chat_only'} or {'type': 'email', 'email': '[email protected]'}"
},
"job_type": {
"type": "string",
"description": "Job type. Default content-ideas pipeline: 'generate_content_ideas'."
},
"schedule": {
"type": "object",
"description": "REQUIRED schedule config (the backend 422s body.schedule without it), e.g. {'cadence': 'daily', 'time_of_day': '09:00', 'timezone': 'UTC'} or {'cadence': 'weekly', 'days_of_week': [0,2,4], 'time_of_day': '09:00', 'timezone': 'UTC'}. cadence and timezone are required; time_of_day is required for the calendar cadences (daily/weekly/monthly) and optional for minutely/hourly.",
"additionalProperties": true
},
"next_run_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "ISO-8601 timestamp to schedule the first run (defaults to the next slot from cadence)"
},
"auto_publish": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null
},
"row_strategy": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"actions_parallel": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null
},
"auto_generate_video": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"run_id",
"approved"
],
"properties": {
"action": {
"const": "decide_agent_run"
},
"run_id": {
"type": "string",
"description": "The run ID awaiting approval"
},
"approved": {
"type": "boolean",
"description": "true to approve and continue; false to reject the pending action"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action"
],
"properties": {
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The task's exact display name, when the id is not known. Send this OR job_id. Several tasks with the same name refuse with AMBIGUOUS_TASK_NAME and list the candidates; retry with one job_id."
},
"action": {
"const": "delete_recurring_job"
},
"job_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The recurring job id. Send this OR name."
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"job_id",
"vidsheet_url"
],
"properties": {
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Name for the copy (defaults to '<source name> (copy)')"
},
"action": {
"const": "duplicate_recurring_job"
},
"job_id": {
"type": "string",
"description": "The recurring job ID to duplicate"
},
"activate": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "Whether the copy starts active (default true)"
},
"vidsheet_url": {
"type": "string",
"description": "URL of the destination vidsheet to copy the job to"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action"
],
"properties": {
"action": {
"const": "ensure_default_recurring_job"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action"
],
"properties": {
"action": {
"const": "list_grants"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action"
],
"properties": {
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The task's exact display name, when the id is not known. Send this OR job_id. Several tasks with the same name refuse with AMBIGUOUS_TASK_NAME and list the candidates; retry with one job_id."
},
"action": {
"const": "pause_recurring_job"
},
"job_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The recurring job id. Send this OR name."
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"payload",
"assistant_content"
],
"properties": {
"action": {
"const": "render_email"
},
"payload": {
"type": "object",
"description": "The recurring-job run payload (job_type, name, delivery, run_id, ...).",
"additionalProperties": true
},
"grid_rows": {
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
}
},
{
"type": "null"
}
],
"default": null,
"description": "The run's grid-ready rows (url, thumbnail_url, ...)."
},
"saved_ideas": {
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
}
},
{
"type": "null"
}
],
"default": null,
"description": "The run's saved ideas, used to link clipped moments."
},
"served_ideas": {
"anyOf": [
{
"type": "object",
"additionalProperties": true
},
{
"type": "null"
}
],
"default": null,
"description": "The served-ideas MCP result for a content-plan run."
},
"action_results": {
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
}
},
{
"type": "null"
}
],
"default": null,
"description": "The run's recorded per-update action results, if any."
},
"missing_images": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"default": null,
"description": "Image URLs the sender confirmed missing (HTTP 404/410); they render as placeholders."
},
"assistant_content": {
"description": "The run's reply: an SDUI tree, a message list, or plain text."
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action"
],
"properties": {
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The task's exact display name, when the id is not known. Send this OR job_id. Several tasks with the same name refuse with AMBIGUOUS_TASK_NAME and list the candidates; retry with one job_id."
},
"action": {
"const": "resume_recurring_job"
},
"job_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The recurring job id. Send this OR name."
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"grant_id"
],
"properties": {
"action": {
"const": "revoke_grant"
},
"grant_id": {
"type": "string",
"description": "The grant to revoke, from list_grants."
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"job_id"
],
"properties": {
"action": {
"const": "run_recurring_job_now"
},
"job_id": {
"type": "string",
"description": "The recurring job id"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"job_id",
"platform",
"search_type",
"value"
],
"properties": {
"days": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Filter to content from last N days"
},
"value": {
"type": "string",
"description": "Search value: @username, #hashtag, or keyword text"
},
"action": {
"const": "update_monitoring_job"
},
"job_id": {
"type": "string",
"description": "The monitoring job ID to update"
},
"platform": {
"type": "string",
"description": "Target platform"
},
"monitoring": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "true for ongoing, false for one-time"
},
"max_results": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Max results per scrape (1-50)"
},
"search_type": {
"type": "string",
"description": "Search type"
},
"comment_monitoring": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "true to also scrape comments"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action"
],
"properties": {
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "New display name"
},
"action": {
"const": "update_recurring_job"
},
"job_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The recurring job id. Send this OR current_name."
},
"prompt": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "New prompt the agent will run each cycle"
},
"status": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"actions": {
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
}
},
{
"type": "null"
}
],
"default": null
},
"delivery": {
"anyOf": [
{
"type": "object",
"additionalProperties": true
},
{
"type": "null"
}
],
"default": null,
"description": "Delivery config (full replacement): e.g. {'type': 'email', 'email': '[email protected]'} or {'type': 'chat_only'}"
},
"job_type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"schedule": {
"anyOf": [
{
"type": "object",
"additionalProperties": true
},
{
"type": "null"
}
],
"default": null,
"description": "Schedule config (full replacement): e.g. {'cadence': 'weekly', 'days_of_week': [0,2,4], 'time_of_day': '09:00', 'timezone': 'UTC'}"
},
"next_run_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "ISO-8601 timestamp to override the next run time"
},
"auto_publish": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null
},
"current_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The task's CURRENT exact display name, when the id is not known (name is the new display name here). Send this OR job_id. Several tasks with the same name refuse with AMBIGUOUS_TASK_NAME and list the candidates; retry with one job_id."
},
"row_strategy": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"actions_parallel": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null
},
"auto_generate_video": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null
}
},
"additionalProperties": false
}
]
},
"minItems": 1,
"description": "One or more typed task actions (agent_id rides the envelope, never inside entries): create_recurring_job (job_type, prompt, optional name/schedule/delivery/next_run_at) | ensure_default_recurring_job | update_recurring_job (job_id + optional name/prompt/schedule/delivery/next_run_at) | pause_recurring_job (job_id) | resume_recurring_job (job_id) | delete_recurring_job (job_id) | run_recurring_job_now (job_id) | duplicate_recurring_job (job_id, vidsheet_url, optional name/activate) | create_monitoring_job (platform, search_type, value + optional days/max_results/monitoring/comment_monitoring) | update_monitoring_job (job_id, platform, search_type, value + same optionals) | decide_agent_run (run_id, approved) | list_grants | revoke_grant (grant_id)"
},
"agent_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The agent ID that owns the jobs (envelope; routed per branch)"
},
"confirm_token": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Single-use token from a CONFIRMATION_REQUIRED error; repeat the same call with it to complete the destructive action it was issued for. Omit on the first call."
}
},
"x-gen-delegation": {
"actions": [
"deliver_result"
],
"excluded_actions": []
},
"additionalProperties": false
}| agent_id |
| any |
| The agent that will own the uploaded asset (required for request_upload, create_drop and a host file reference) |
| filename | any | Original filename including extension (request_upload/create_drop); its extension must match content_type |
| folder_id | any | Place the completed asset inside this asset folder |
| upload_id | any | The upload_id returned by request_upload/create_drop (status only) |
| content_type | any | MIME type of the file (e.g. image/jpeg, audio/mpeg, video/mp4, application/pdf) |
{
"type": "object",
"properties": {
"file": {
"anyOf": [
{
"type": "object",
"required": [
"download_url",
"file_id"
],
"properties": {
"file_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The host's stable id for this file."
},
"file_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The file's original name, when the host supplies one."
},
"mime_type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The host's declared MIME type, when it supplies one."
},
"download_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Temporary HTTPS download URL supplied by the host (e.g. files.oaiusercontent.com). Never a local path: the server fetches it; the server never reads a client filesystem."
}
},
"description": "A host-provided file reference (OpenAI ``openai/fileParams``).\n\nThe four properties are the ones a host file parameter carries. The fields\nare declared optional so an incomplete reference reaches the handler and is\nanswered with a create_drop fallback rather than a schema error, while the\nserved schema still lists download_url and file_id as required so a host\nknows to send them."
},
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "A host-provided file reference {download_url, file_id, optional mime_type/file_name}, or the host's placeholder string. The server fetches download_url; never a local path."
},
"phase": {
"enum": [
"request_upload",
"create_drop",
"status"
],
"type": "string",
"default": "request_upload",
"description": "request_upload: mint a signed PUT URL and curl. create_drop: the same, framed for a browser drop page. status: read the owned asset for an upload_id."
},
"agent_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The agent that will own the uploaded asset (required for request_upload, create_drop and a host file reference)"
},
"filename": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Original filename including extension (request_upload/create_drop); its extension must match content_type"
},
"folder_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Place the completed asset inside this asset folder"
},
"upload_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The upload_id returned by request_upload/create_drop (status only)"
},
"content_type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "MIME type of the file (e.g. image/jpeg, audio/mpeg, video/mp4, application/pdf)"
}
},
"x-gen-delegation": {
"actions": [],
"excluded_actions": []
},
"additionalProperties": false
}| Argument | Type | Description |
|---|---|---|
| op | any | The write op (named in the tool description). Omit when sending the canonical 'actions' envelope. |
| url | any | File URL to import (import_asset) |
| mode | any | Analysis mode, default recreate (generate source_video_analysis) |
| name | any | Sheet name (create_sheet; duplicate_sheet renames the copy) |
| take | any | The generation job a cell's default take points at (set_cell, add_layer, update_layer): a job id (int or digits) or {id, type} with type UserJob|Job. |
| blank | any | Set true when the user asks for an empty or blank sheet, or names only the columns they want. Skips the onboarding template and default columns/rows; omitted or false preserves default creation. Cannot be combined with template_slug. |
| media | any | The whole typed media object the browser writes (the FE shape; gen_discover card_schema serves it). Send it alone, never with the media_* forms |
| model | any | Model override, default suno-v5-beta (generate song, recommend_song) |
| style | any | Musical style/genre/mood (generate song; trimmed, blank omitted) |
| title | any | Column title (add_column); song title (generate song, recommend_song) |
| value | any | Cell value (set_cell) |
| prompt | any | Generation prompt (generate song, recommend_song) |
| reason | any | Reason the output was unused (refund_unused_output); relayed to Rails unchanged |
| row_id | any | Source row for generate sound_matching |
| actions | any | Canonical Rails action envelope: a non-empty list of {"action", "target", "values"|"ids"} objects, relayed to Rails verbatim (GEN-6700); pass either this or a flat op, never both. A row's output video format (aspect ratio / resolution) is set only here, with a row update: values.video_settings.aspect_ratio 1:1 | 9:16 | 16:9, values.video_settings.resolution 1080p | 4k (either or both). Example, set a row to 1:1: [{"action": "update", "target": {"kind": "row", "vidsheet_id": 1001, "id": 2002}, "values": {"video_settings": {"aspect_ratio": "1:1"}}}] |
| cell_id | any | Cell ID (set_cell, layers, card owner/target); a global's value_cell_id addresses its value cell |
| idea_id | any | Idea ID (create_engine; requires template_slug) |
| no_paid | boolean | Refuse paid media generation for this run. Text and LLM work still bills normally. |
| recover | boolean | apply_storyboard: read-only comparison with the owned row after a lost reply; returns Draft without writes, models or jobs. |
| sources | any | target_state: owned content_resource_ids allowed as media sources |
| agent_id | any | The agent that owns the vidsheet. Optional when the call names the sheet (vidsheet_id): the owner resolves from the engine read. Required for create_sheet/clone_template/create_engine and a call naming no sheet (GEN-7151) |
| bindings | any | Saved-input bindings for this envelope (MCP-only; never relayed to Rails): one {index, references} per action, where index names that action and references is [{input_id, card_type?, field?}]. The MCP resolves each reference against source_inputs and the served card schema before any write (GEN-9391). |
| duration | any | Duration in seconds 1-480, default 240 (generate song, recommend_song); out of range is rejected, so estimate the seconds you ask for |
| layer_id | any | Layer ID (update_layer, generate layer, card owner/target) |
| overlays | any | Overlay sources (generate sound_matching) |
| position | any | Column position (add_column), from gen_discover columns; a column never lands right of VIDEO / FINAL VIDEO / STATS |
| settings | any | Layer settings (add_layer/update_layer); a trim (from, duration_in_frames, video_start_time) also sends userHasTrimmed=true, or the browser recomputes the full clip (GEN-7637) |
| audio_url | any | HTTPS audio URL (generate recommend_song reference — that card makes a PAID cover/remix of this one track; find suggestions with gen_discover view actions audio_library=recommended; avatar lip-sync audio) |
| avatar_id | any | Avatar model ID (generate video_from_avatar) |
| folder_id | any | Asset folder for the import (import_asset) |
| layer_row | any | Timeline row/track for add_layer and update_layer, 0-based (settings.row); layers sharing a row play sequentially. One of the ten tracks 0..9 |
| media_key | any | Media key: text | image | video | audio | var (set_cell/import_asset) |
| media_url | any | Media URL (set_cell/add_layer/update_layer media, import_asset) |
| video_url | any | Avatar video URL (generate video_from_avatar) |
| layer_name | any | Layer name (add_layer) |
| layer_type | any | Layer type (add_layer): clip, image, text, caption or sound; audio/voice/music map to sound, video to clip. Give a voice or music layer its sound type and timing before generating into it (GEN-7690) |
| media_name | any | Media name (set_cell/import_asset; song recommend binds the song title) |
| storyboard | any | apply_storyboard: scene-form BuildPlanV1 object, validated and applied to the selected owned row. |
| column_type | any | Column type (add_column) |
| description | any | Column description (add_column) |
| variable_id | any | Global-variable row id from gen_discover view=variables, never the value cell id: generate resolves it to that value cell as the owner (instead of cell_id/layer_id) |
| vidsheet_id | any | Vidsheet ID (every op except create_sheet/clone_template/create_engine) |
| auto_confirm | boolean | Approve one headless delete through Rails confirmation; edit access remains required. false keeps the UI preview/token flow. |
| build_run_id | any | Errored build run identity (refund_unused_output); relayed to Rails as audit metadata |
| caption_text | any | Caption text (update_layer) |
| instrumental | any | Instrumental flag (generate song, recommend_song) |
| row_position | any | apply_storyboard only: one-based displayed row position on the owned Vidsheet, instead of row_id |
| target_state | any | apply_storyboard alternative: edit the full gen_discover vidsheet sheet result. Writes only differences from a fresh read, deletes separately, no paid regeneration. Media must be on-sheet or in sources. |
| vocal_gender | any | 'm' or 'f' to bias vocal gender (generate song) |
| change_set_id | any | Stable edit-group ID for undo and retry |
| clear_content | any | Clear content flag (set_cell, layers) |
| confirm_token | any | Single-use token from a confirmation_required preview; completes the delete it was issued for |
| creation_card | any | Creation card payload (add_layer/update_layer) |
| generation_id | any | Generation ID (continue_generation, stop_generation, refund_unused_output) |
| is_commercial | any | Commercial-cleared sounds only (generate sound_matching) |
| negative_tags | any | Styles/instruments to avoid (generate song; trimmed, blank omitted) |
| source_inputs | any | Resolved saved input media for the envelope's per-action source references (MCP-only; never relayed to Rails): {attachments: [{ref, url, kind, content_resource_id, resource...}]}. Each reference binds into its action's card through the served card schema before any write, and an incompatible card/media pair is refused typed with effects zero (GEN-9391). |
| template_slug | any | Template slug (optional on create_sheet; clone_template; create_engine requires it with idea_id); discover valid choices with gen_discover vidsheet view=templates |
| video_type_id | any | apply_storyboard with target_state only: the storyboard's video type id (canonical timeline rows) |
| lip_sync_model | any | Lip-sync model (generate video_from_avatar) |
| media_asset_id | any | Owned ContentResource id of an uploaded/library asset to bind (set_cell); send with media_key image|video|audio |
| remove_silence | any | Remove audio silence (generate video_from_avatar) |
| auto_regenerate | any | false writes this batch without paid dependent regeneration (Rails: skipped); true/omitted keeps automatic regeneration. Use false for drafts. |
| content_idea_id | any | Saved-idea alias: create_sheet refuses it with the gen_content_action create_video_from_idea call |
| idempotency_key | any | Required for refund_unused_output. Reuse on retries to replay the job; omission generates a new key and may charge again. Forwarded to paid creation cards. |
| media_reference | any | A generation's owner as media (set_cell): {type: local_variable|video_layer|global_variable|final_video, value, name?} |
| spending_run_id | string | Stable run or conversation identity required with spending controls. The authenticated run owner shares one policy across workspaces. |
| target_agent_id | any | Target agent for cross-agent duplication (duplicate_sheet) |
| remove_background | any | Remove video background (generate video_from_avatar) |
| creation_card_type | string | Creation card pick. One of the 15 FE card types an FE picker offers (for example video-from-talking-avatar) or an MCP job card (sound_matching | recommend_song | song | video_from_avatar | source_video_analysis); the final render card final-video renders a row's final video into its FINAL VIDEO cell. creation_card_inputs is typed per card. |
| content_resource_id | any | Owned video asset ID to analyze (generate source_video_analysis) |
| creation_card_owner | any | 'cell' or 'layer': the owner a generate card pick is addressed at (use when both cell_id and layer_id are given) |
| max_paid_operations | integer | Maximum paid media reservations across all workspaces in this authenticated user/run, enforced atomically. Retries reuse their reservation. |
| reference_audio_url | any | HTTPS reference-audio URL for conditioning (generate song) |
| creation_card_inputs | any | Per-card inputs. Send the arm whose card matches creation_card_type; a field the card does not take is refused, never forwarded. The final render card's arm is optional — its composition is built from the row when omitted. |
{
"type": "object",
"allOf": [
{
"if": {
"required": [
"op"
],
"properties": {
"op": {
"const": "create_engine"
}
}
},
"then": {
"required": [
"idea_id",
"template_slug"
]
}
},
{
"if": {
"required": [
"op"
],
"properties": {
"op": {
"const": "refund_unused_output"
}
}
},
"then": {
"required": [
"agent_id",
"generation_id",
"idempotency_key"
]
}
}
],
"properties": {
"op": {
"anyOf": [
{
"enum": [
"create_sheet",
"clone_template",
"create_engine",
"duplicate_sheet",
"import_asset",
"validate_layout",
"continue_generation",
"stop_generation",
"refund_unused_output",
"add_column",
"set_cell",
"add_layer",
"update_layer",
"generate",
"apply_storyboard"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The write op (named in the tool description). Omit when sending the canonical 'actions' envelope."
},
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "File URL to import (import_asset)"
},
"mode": {
"anyOf": [
{
"enum": [
"recreate",
"reimagine"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Analysis mode, default recreate (generate source_video_analysis)"
},
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Sheet name (create_sheet; duplicate_sheet renames the copy)"
},
"take": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
},
{
"type": "object",
"additionalProperties": true
},
{
"type": "null"
}
],
"default": null,
"description": "The generation job a cell's default take points at (set_cell, add_layer, update_layer): a job id (int or digits) or {id, type} with type UserJob|Job."
},
"blank": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "Set true when the user asks for an empty or blank sheet, or names only the columns they want. Skips the onboarding template and default columns/rows; omitted or false preserves default creation. Cannot be combined with template_slug."
},
"media": {
"anyOf": [
{
"type": "object",
"additionalProperties": true
},
{
"type": "null"
}
],
"default": null,
"description": "The whole typed media object the browser writes (the FE shape; gen_discover card_schema serves it). Send it alone, never with the media_* forms"
},
"model": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Model override, default suno-v5-beta (generate song, recommend_song)"
},
"style": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Musical style/genre/mood (generate song; trimmed, blank omitted)"
},
"title": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Column title (add_column); song title (generate song, recommend_song)"
},
"value": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Cell value (set_cell)"
},
"prompt": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Generation prompt (generate song, recommend_song)"
},
"reason": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Reason the output was unused (refund_unused_output); relayed to Rails unchanged"
},
"row_id": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Source row for generate sound_matching"
},
"actions": {
"anyOf": [
{
"type": "array",
"items": {
"oneOf": [
{
"type": "object",
"required": [
"action",
"target"
],
"properties": {
"action": {
"const": "create"
},
"target": {
"type": "object",
"required": [
"kind"
],
"properties": {
"kind": {
"const": "vidsheet"
}
},
"additionalProperties": false
},
"values": {
"type": "object",
"required": [],
"properties": {
"name": {
"type": "string"
},
"blank": {
"type": "boolean"
},
"idea_id": {
"oneOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "string",
"pattern": "^[A-Za-z0-9_-]+$",
"maxLength": 128,
"minLength": 1
}
]
},
"is_default": {
"type": "boolean"
},
"template_slug": {
"type": "string",
"minLength": 1
}
},
"description": "Fields and a worked example: gen_discover domain=vidsheet view=actions target=\"create:vidsheet\".",
"minProperties": 1,
"additionalProperties": false
}
},
"description": "Fields and a worked example: gen_discover domain=vidsheet view=actions target=\"create:vidsheet\".",
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"target",
"values"
],
"properties": {
"ref": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$",
"maxLength": 64,
"minLength": 1,
"description": "Fields and a worked example: gen_discover domain=vidsheet view=actions target=\"create:column\"."
},
"action": {
"const": "create"
},
"target": {
"type": "object",
"required": [
"kind",
"vidsheet_id"
],
"properties": {
"kind": {
"const": "column"
},
"vidsheet_id": {
"oneOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "string",
"pattern": "^[A-Za-z0-9_-]+$",
"maxLength": 128,
"minLength": 1
}
]
}
},
"additionalProperties": false
},
"values": {
"type": "object",
"required": [
"title",
"type"
],
"properties": {
"type": {
"enum": [
"text",
"image",
"video",
"audio"
]
},
"title": {
"type": "string",
"pattern": "\\S",
"minLength": 1
},
"temp_title": {
"type": "string"
},
"description": {
"type": "string"
}
},
"description": "Fields and a worked example: gen_discover domain=vidsheet view=actions target=\"create:column\".",
"minProperties": 1,
"additionalProperties": false
},
"position": {
"type": "integer",
"minimum": 0,
"description": "Fields and a worked example: gen_discover domain=vidsheet view=actions target=\"create:column\"."
}
},
"description": "Fields and a worked example: gen_discover domain=vidsheet view=actions target=\"create:column\".",
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"target"
],
"properties": {
"ref": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$",
"maxLength": 64,
"minLength": 1,
"description": "Fields and a worked example: gen_discover domain=vidsheet view=actions target=\"create:row\"."
},
"action": {
"const": "create"
},
"target": {
"type": "object",
"required": [
"kind",
"vidsheet_id"
],
"properties": {
"kind": {
"const": "row"
},
"vidsheet_id": {
"oneOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "string",
"pattern": "^[A-Za-z0-9_-]+$",
"maxLength": 128,
"minLength": 1
}
]
}
},
"additionalProperties": false
},
"values": {
"type": "object",
"required": [],
"properties": {
"position": {
"type": "integer",
"minimum": 0
},
"row_height": {
"type": "number",
"exclusiveMinimum": 0
}
},
"description": "Fields and a worked example: gen_discover domain=vidsheet view=actions target=\"create:row\".",
"minProperties": 1,
"additionalProperties": false
},
"position": {
"type": "integer",
"minimum": 0,
"description": "Fields and a worked example: gen_discover domain=vidsheet view=actions target=\"create:row\"."
}
},
"description": "Fields and a worked example: gen_discover domain=vidsheet view=actions target=\"create:row\".",
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"target"
],
"properties": {
"ref": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$",
"maxLength": 64,
"minLength": 1,
"description": "Fields and a worked example: gen_discover domain=vidsheet view=actions target=\"create:layer\"."
},
"action": {
"const": "create"
},
"target": {
"type": "object",
"anyOf": [
{
"required": [
"cell_id"
]
},
{
"required": [
"column_id",
"row_id"
]
}
],
"required": [
"kind",
"vidsheet_id"
],
"properties": {
"kind": {
"const": "layer"
},
"row_id": {
"oneOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "string",
"pattern": "^[A-Za-z0-9_-]+$",
"maxLength": 128,
"minLength": 1
},
{
"type": "object",
"required": [
"ref"
],
"properties": {
"ref": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$",
"maxLength": 64,
"minLength": 1
}
},
"additionalProperties": false
}
]
},
"cell_id": {
"oneOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "string",
"pattern": "^[A-Za-z0-9_-]+$",
"maxLength": 128,
"minLength": 1
}
]
},
"column_id": {
"oneOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "string",
"pattern": "^[A-Za-z0-9_-]+$",
"maxLength": 128,
"minLength": 1
},
{
"type": "object",
"required": [
"ref"
],
"properties": {
"ref": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$",
"maxLength": 64,
"minLength": 1
}
},
"additionalProperties": false
}
]
},
"vidsheet_id": {
"oneOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "string",
"pattern": "^[A-Za-z0-9_-]+$",
"maxLength": 128,
"minLength": 1
}
]
}
},
"additionalProperties": false
},
"values": {
"type": "object",
"required": [],
"properties": {
"card": {
"type": "object",
"required": [
"type",
"inputs"
],
"properties": {
"type": {
"type": "string",
"minLength": 1
},
"inputs": {
"type": "object"
}
},
"additionalProperties": false
},
"name": {
"type": "string"
},
"take": {
"type": "object",
"required": [
"id",
"type"
],
"properties": {
"id": {
"oneOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "string",
"pattern": "^[A-Za-z0-9_-]+$",
"maxLength": 128,
"minLength": 1
}
]
},
"type": {
"enum": [
"UserJob",
"Job"
]
}
},
"additionalProperties": false
},
"type": {
"enum": [
"",
"clip",
"image",
"text",
"caption",
"sound",
"text-overlay"
]
},
"media": {
"type": "object",
"allOf": [
{
"anyOf": [
{
"not": {
"required": [
"key"
],
"properties": {
"key": {
"enum": [
"image"
]
}
}
}
},
{
"properties": {
"mediaType": {
"enum": [
"image"
]
}
}
}
]
},
{
"anyOf": [
{
"not": {
"required": [
"key"
],
"properties": {
"key": {
"enum": [
"video"
]
}
}
}
},
{
"properties": {
"mediaType": {
"enum": [
"video"
]
}
}
}
]
},
{
"anyOf": [
{
"not": {
"required": [
"key"
],
"properties": {
"key": {
"enum": [
"audio"
]
}
}
}
},
{
"properties": {
"mediaType": {
"enum": [
"audio"
]
}
}
}
]
},
{
"anyOf": [
{
"not": {
"required": [
"references"
]
}
},
{
"properties": {
"key": {
"enum": [
"var"
]
}
}
}
]
},
{
"anyOf": [
{
"not": {
"required": [
"key"
],
"properties": {
"key": {
"enum": [
"image",
"video",
"audio"
]
}
}
}
},
{
"properties": {
"value": {
"pattern": "^(|[1-9][0-9]*|https://\\S+|__pending_link_import__)$"
}
}
}
]
}
],
"properties": {
"key": {
"enum": [
"text",
"image",
"video",
"audio",
"var"
]
},
"name": {
"type": "string"
},
"value": {
"oneOf": [
{
"type": "string"
},
{
"type": "integer",
"minimum": 1
}
]
},
"duration": {
"type": "number"
},
"mediaType": {
"enum": [
"image",
"video",
"audio"
]
},
"references": {
"type": "object",
"required": [
"type",
"value"
],
"properties": {
"data": {
"type": "string"
},
"name": {
"type": "string"
},
"type": {
"enum": [
"local_variable",
"video_layer",
"global_variable",
"final_video"
]
},
"value": {
"type": "number"
}
},
"additionalProperties": false
},
"thumbnailUrl": {
"type": "string"
},
"library_reference": {
"type": "string",
"minLength": 1
}
},
"additionalProperties": false
},
"settings": {
"type": "object"
},
"clear_content": {
"const": true
}
},
"description": "Fields and a worked example: gen_discover domain=vidsheet view=actions target=\"create:layer\".",
"minProperties": 1,
"additionalProperties": false
},
"position": {
"type": "integer",
"minimum": 0,
"description": "Fields and a worked example: gen_discover domain=vidsheet view=actions target=\"create:layer\"."
}
},
"description": "Fields and a worked example: gen_discover domain=vidsheet view=actions target=\"create:layer\".",
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"target",
"values"
],
"properties": {
"ref": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$",
"maxLength": 64,
"minLength": 1,
"description": "Fields and a worked example: gen_discover domain=vidsheet view=actions target=\"create:variable\"."
},
"action": {
"const": "create"
},
"target": {
"type": "object",
"required": [
"kind",
"vidsheet_id"
],
"properties": {
"kind": {
"const": "variable"
},
"vidsheet_id": {
"oneOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "string",
"pattern": "^[A-Za-z0-9_-]+$",
"maxLength": 128,
"minLength": 1
}
]
}
},
"additionalProperties": false
},
"values": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"pattern": "\\S",
"minLength": 1
},
"media": {
"type": "object",
"allOf": [
{
"anyOf": [
{
"not": {
"required": [
"key"
],
"properties": {
"key": {
"enum": [
"image"
]
}
}
}
},
{
"properties": {
"mediaType": {
"enum": [
"image"
]
}
}
}
]
},
{
"anyOf": [
{
"not": {
"required": [
"key"
],
"properties": {
"key": {
"enum": [
"video"
]
}
}
}
},
{
"properties": {
"mediaType": {
"enum": [
"video"
]
}
}
}
]
},
{
"anyOf": [
{
"not": {
"required": [
"key"
],
"properties": {
"key": {
"enum": [
"audio"
]
}
}
}
},
{
"properties": {
"mediaType": {
"enum": [
"audio"
]
}
}
}
]
},
{
"anyOf": [
{
"not": {
"required": [
"references"
]
}
},
{
"properties": {
"key": {
"enum": [
"var"
]
}
}
}
]
},
{
"anyOf": [
{
"not": {
"required": [
"key"
],
"properties": {
"key": {
"enum": [
"image",
"video",
"audio"
]
}
}
}
},
{
"properties": {
"value": {
"pattern": "^(|[1-9][0-9]*|https://\\S+|__pending_link_import__)$"
}
}
}
]
}
],
"properties": {
"key": {
"enum": [
"text",
"image",
"video",
"audio",
"var"
]
},
"name": {
"type": "string"
},
"value": {
"oneOf": [
{
"type": "string"
},
{
"type": "integer",
"minimum": 1
}
]
},
"duration": {
"type": "number"
},
"mediaType": {
"enum": [
"image",
"video",
"audio"
]
},
"references": {
"type": "object",
"required": [
"type",
"value"
],
"properties": {
"data": {
"type": "string"
},
"name": {
"type": "string"
},
"type": {
"enum": [
"local_variable",
"video_layer",
"global_variable",
"final_video"
]
},
"value": {
"type": "number"
}
},
"additionalProperties": false
},
"thumbnailUrl": {
"type": "string"
},
"library_reference": {
"type": "string",
"minLength": 1
}
},
"additionalProperties": false
},
"value": {
"type": [
"string",
"null"
]
},
"clear_content": {
"const": true
}
},
"description": "Fields and a worked example: gen_discover domain=vidsheet view=actions target=\"create:variable\".",
"minProperties": 1,
"additionalProperties": false
}
},
"description": "Fields and a worked example: gen_discover domain=vidsheet view=actions target=\"create:variable\".",
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"target",
"values"
],
"properties": {
"action": {
"const": "update"
},
"target": {
"type": "object",
"required": [
"kind",
"id"
],
"properties": {
"id": {
"oneOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "string",
"pattern": "^[A-Za-z0-9_-]+$",
"maxLength": 128,
"minLength": 1
}
]
},
"kind": {
"const": "vidsheet"
}
},
"additionalProperties": false
},
"values": {
"type": "object",
"required": [],
"properties": {
"name": {
"type": "string"
},
"is_default": {
"type": "boolean"
},
"global_variables_workbook_asset_id": {
"oneOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "string",
"pattern": "^[A-Za-z0-9_-]+$",
"maxLength": 128,
"minLength": 1
}
]
}
},
"description": "Fields and a worked example: gen_discover domain=vidsheet view=actions target=\"update:vidsheet\".",
"minProperties": 1,
"additionalProperties": false
}
},
"description": "Fields and a worked example: gen_discover domain=vidsheet view=actions target=\"update:vidsheet\".",
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"target",
"values"
],
"properties": {
"action": {
"const": "update"
},
"target": {
"type": "object",
"anyOf": [
{
"required": [
"id"
]
},
{
"required": [
"ref"
]
}
],
"required": [
"kind",
"vidsheet_id"
],
"properties": {
"id": {
"oneOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "string",
"pattern": "^[A-Za-z0-9_-]+$",
"maxLength": 128,
"minLength": 1
}
]
},
"ref": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$",
"maxLength": 64,
"minLength": 1
},
"kind": {
"const": "column"
},
"vidsheet_id": {
"oneOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "string",
"pattern": "^[A-Za-z0-9_-]+$",
"maxLength": 128,
"minLength": 1
}
]
}
},
"additionalProperties": false
},
"values": {
"type": "object",
"required": [],
"properties": {
"title": {
"type": "string"
},
"temp_title": {
"type": "string"
},
"description": {
"type": "string"
}
},
"description": "Fields and a worked example: gen_discover domain=vidsheet view=actions target=\"update:column\".",
"minProperties": 1,
"additionalProperties": false
}
},
"description": "Fields and a worked example: gen_discover domain=vidsheet view=actions target=\"update:column\".",
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"target",
"values"
],
"properties": {
"action": {
"const": "update"
},
"target": {
"type": "object",
"anyOf": [
{
"required": [
"id"
]
},
{
"required": [
"ref"
]
}
],
"required": [
"kind",
"vidsheet_id"
],
"properties": {
"id": {
"oneOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "string",
"pattern": "^[A-Za-z0-9_-]+$",
"maxLength": 128,
"minLength": 1
}
]
},
"ref": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$",
"maxLength": 64,
"minLength": 1
},
"kind": {
"const": "row"
},
"vidsheet_id": {
"oneOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "string",
"pattern": "^[A-Za-z0-9_-]+$",
"maxLength": 128,
"minLength": 1
}
]
}
},
"additionalProperties": false
},
"values": {
"type": "object",
"required": [],
"properties": {
"position": {
"type": "integer",
"minimum": 0
},
"row_height": {
"type": "number",
"exclusiveMinimum": 0
},
"video_settings": {
"type": "object",
"properties": {
"resolution": {
"enum": [
"1080p",
"4k"
]
},
"aspect_ratio": {
"enum": [
"1:1",
"9:16",
"16:9"
]
}
},
"minProperties": 1,
"additionalProperties": false
}
},
"description": "Fields and a worked example: gen_discover domain=vidsheet view=actions target=\"update:row\".",
"minProperties": 1,
"additionalProperties": false
}
},
"description": "Fields and a worked example: gen_discover domain=vidsheet view=actions target=\"update:row\".",
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"target",
"values"
],
"properties": {
"action": {
"const": "update"
},
"target": {
"type": "object",
"anyOf": [
{
"required": [
"id"
]
},
{
"required": [
"ref"
]
},
{
"required": [
"column_id",
"row_id"
]
}
],
"required": [
"kind",
"vidsheet_id"
],
"properties": {
"id": {
"oneOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "string",
"pattern": "^[A-Za-z0-9_-]+$",
"maxLength": 128,
"minLength": 1
}
]
},
"ref": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$",
"maxLength": 64,
"minLength": 1
},
"kind": {
"const": "cell"
},
"row_id": {
"oneOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "string",
"pattern": "^[A-Za-z0-9_-]+$",
"maxLength": 128,
"minLength": 1
},
{
"type": "object",
"required": [
"ref"
],
"properties": {
"ref": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$",
"maxLength": 64,
"minLength": 1
}
},
"additionalProperties": false
}
]
},
"column_id": {
"oneOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "string",
"pattern": "^[A-Za-z0-9_-]+$",
"maxLength": 128,
"minLength": 1
},
{
"type": "object",
"required": [
"ref"
],
"properties": {
"ref": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$",
"maxLength": 64,
"minLength": 1
}
},
"additionalProperties": false
}
]
},
"vidsheet_id": {
"oneOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "string",
"pattern": "^[A-Za-z0-9_-]+$",
"maxLength": 128,
"minLength": 1
}
]
}
},
"additionalProperties": false
},
"values": {
"type": "object",
"required": [],
"properties": {
"take": {
"type": "object",
"required": [
"id",
"type"
],
"properties": {
"id": {
"oneOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "string",
"pattern": "^[A-Za-z0-9_-]+$",
"maxLength": 128,
"minLength": 1
}
]
},
"type": {
"enum": [
"UserJob",
"Job"
]
}
},
"additionalProperties": false
},
"media": {
"type": "object",
"allOf": [
{
"anyOf": [
{
"not": {
"required": [
"key"
],
"properties": {
"key": {
"enum": [
"image"
]
}
}
}
},
{
"properties": {
"mediaType": {
"enum": [
"image"
]
}
}
}
]
},
{
"anyOf": [
{
"not": {
"required": [
"key"
],
"properties": {
"key": {
"enum": [
"video"
]
}
}
}
},
{
"properties": {
"mediaType": {
"enum": [
"video"
]
}
}
}
]
},
{
"anyOf": [
{
"not": {
"required": [
"key"
],
"properties": {
"key": {
"enum": [
"audio"
]
}
}
}
},
{
"properties": {
"mediaType": {
"enum": [
"audio"
]
}
}
}
]
},
{
"anyOf": [
{
"not": {
"required": [
"references"
]
}
},
{
"properties": {
"key": {
"enum": [
"var"
]
}
}
}
]
},
{
"anyOf": [
{
"not": {
"required": [
"key"
],
"properties": {
"key": {
"enum": [
"image",
"video",
"audio"
]
}
}
}
},
{
"properties": {
"value": {
"pattern": "^(|[1-9][0-9]*|https://\\S+|__pending_link_import__)$"
}
}
}
]
}
],
"properties": {
"key": {
"enum": [
"text",
"image",
"video",
"audio",
"var"
]
},
"name": {
"type": "string"
},
"value": {
"oneOf": [
{
"type": "string"
},
{
"type": "integer",
"minimum": 1
}
]
},
"duration": {
"type": "number"
},
"mediaType": {
"enum": [
"image",
"video",
"audio"
]
},
"references": {
"type": "object",
"required": [
"type",
"value"
],
"properties": {
"data": {
"type": "string"
},
"name": {
"type": "string"
},
"type": {
"enum": [
"local_variable",
"video_layer",
"global_variable",
"final_video"
]
},
"value": {
"type": "number"
}
},
"additionalProperties": false
},
"thumbnailUrl": {
"type": "string"
},
"library_reference": {
"type": "string",
"minLength": 1
}
},
"additionalProperties": false
},
"value": {
"type": [
"string",
"null"
]
},
"clear_content": {
"const": true
}
},
"description": "Fields and a worked example: gen_discover domain=vidsheet view=actions target=\"update:cell\".",
"minProperties": 1,
"additionalProperties": false
}
},
"description": "Fields and a worked example: gen_discover domain=vidsheet view=actions target=\"update:cell\".",
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"target",
"values"
],
"properties": {
"action": {
"const": "update"
},
"target": {
"type": "object",
"anyOf": [
{
"required": [
"id"
]
},
{
"required": [
"ref"
]
}
],
"required": [
"kind",
"vidsheet_id"
],
"properties": {
"id": {
"oneOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "string",
"pattern": "^[A-Za-z0-9_-]+$",
"maxLength": 128,
"minLength": 1
}
]
},
"ref": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$",
"maxLength": 64,
"minLength": 1
},
"kind": {
"const": "layer"
},
"vidsheet_id": {
"oneOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "string",
"pattern": "^[A-Za-z0-9_-]+$",
"maxLength": 128,
"minLength": 1
}
]
}
},
"additionalProperties": false
},
"values": {
"type": "object",
"required": [],
"properties": {
"card": {
"type": "object",
"required": [
"type",
"inputs"
],
"properties": {
"type": {
"type": "string",
"minLength": 1
},
"inputs": {
"type": "object"
}
},
"additionalProperties": false
},
"name": {
"type": "string"
},
"take": {
"type": "object",
"required": [
"id",
"type"
],
"properties": {
"id": {
"oneOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "string",
"pattern": "^[A-Za-z0-9_-]+$",
"maxLength": 128,
"minLength": 1
}
]
},
"type": {
"enum": [
"UserJob",
"Job"
]
}
},
"additionalProperties": false
},
"media": {
"type": "object",
"allOf": [
{
"anyOf": [
{
"not": {
"required": [
"key"
],
"properties": {
"key": {
"enum": [
"image"
]
}
}
}
},
{
"properties": {
"mediaType": {
"enum": [
"image"
]
}
}
}
]
},
{
"anyOf": [
{
"not": {
"required": [
"key"
],
"properties": {
"key": {
"enum": [
"video"
]
}
}
}
},
{
"properties": {
"mediaType": {
"enum": [
"video"
]
}
}
}
]
},
{
"anyOf": [
{
"not": {
"required": [
"key"
],
"properties": {
"key": {
"enum": [
"audio"
]
}
}
}
},
{
"properties": {
"mediaType": {
"enum": [
"audio"
]
}
}
}
]
},
{
"anyOf": [
{
"not": {
"required": [
"references"
]
}
},
{
"properties": {
"key": {
"enum": [
"var"
]
}
}
}
]
},
{
"anyOf": [
{
"not": {
"required": [
"key"
],
"properties": {
"key": {
"enum": [
"image",
"video",
"audio"
]
}
}
}
},
{
"properties": {
"value": {
"pattern": "^(|[1-9][0-9]*|https://\\S+|__pending_link_import__)$"
}
}
}
]
}
],
"properties": {
"key": {
"enum": [
"text",
"image",
"video",
"audio",
"var"
]
},
"name": {
"type": "string"
},
"value": {
"oneOf": [
{
"type": "string"
},
{
"type": "integer",
"minimum": 1
}
]
},
"duration": {
"type": "number"
},
"mediaType": {
"enum": [
"image",
"video",
"audio"
]
},
"references": {
"type": "object",
"required": [
"type",
"value"
],
"properties": {
"data": {
"type": "string"
},
"name": {
"type": "string"
},
"type": {
"enum": [
"local_variable",
"video_layer",
"global_variable",
"final_video"
]
},
"value": {
"type": "number"
}
},
"additionalProperties": false
},
"thumbnailUrl": {
"type": "string"
},
"library_reference": {
"type": "string",
"minLength": 1
}
},
"additionalProperties": false
},
"settings": {
"type": "object"
},
"caption_text": {
"type": "string",
"maxLength": 2097152
},
"clear_content": {
"const": true
}
},
"description": "Fields and a worked example: gen_discover domain=vidsheet view=actions target=\"update:layer\".",
"minProperties": 1,
"additionalProperties": false
}
},
"description": "Fields and a worked example: gen_discover domain=vidsheet view=actions target=\"update:layer\".",
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"target",
"values"
],
"properties": {
"action": {
"const": "update"
},
"target": {
"type": "object",
"required": [
"kind",
"owner",
"slot"
],
"properties": {
"kind": {
"const": "creation_card"
},
"slot": {
"const": "draftForm"
},
"owner": {
"oneOf": [
{
"type": "object",
"anyOf": [
{
"required": [
"id"
]
},
{
"required": [
"ref"
]
},
{
"required": [
"column_id",
"row_id"
]
}
],
"required": [
"kind",
"vidsheet_id"
],
"properties": {
"id": {
"oneOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "string",
"pattern": "^[A-Za-z0-9_-]+$",
"maxLength": 128,
"minLength": 1
}
]
},
"ref": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$",
"maxLength": 64,
"minLength": 1
},
"kind": {
"const": "cell"
},
"row_id": {
"oneOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "string",
"pattern": "^[A-Za-z0-9_-]+$",
"maxLength": 128,
"minLength": 1
},
{
"type": "object",
"required": [
"ref"
],
"properties": {
"ref": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$",
"maxLength": 64,
"minLength": 1
}
},
"additionalProperties": false
}
]
},
"column_id": {
"oneOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "string",
"pattern": "^[A-Za-z0-9_-]+$",
"maxLength": 128,
"minLength": 1
},
{
"type": "object",
"required": [
"ref"
],
"properties": {
"ref": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$",
"maxLength": 64,
"minLength": 1
}
},
"additionalProperties": false
}
]
},
"vidsheet_id": {
"oneOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "string",
"pattern": "^[A-Za-z0-9_-]+$",
"maxLength": 128,
"minLength": 1
}
]
}
},
"additionalProperties": false
},
{
"type": "object",
"anyOf": [
{
"required": [
"id"
]
},
{
"required": [
"ref"
]
}
],
"required": [
"kind",
"vidsheet_id"
],
"properties": {
"id": {
"oneOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "string",
"pattern": "^[A-Za-z0-9_-]+$",
"maxLength": 128,
"minLength": 1
}
]
},
"ref": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$",
"maxLength": 64,
"minLength": 1
},
"kind": {
"const": "layer"
},
"vidsheet_id": {
"oneOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "string",
"pattern": "^[A-Za-z0-9_-]+$",
"maxLength": 128,
"minLength": 1
}
]
}
},
"additionalProperties": false
},
{
"type": "object",
"anyOf": [
{
"required": [
"id"
]
},
{
"required": [
"ref"
]
}
],
"required": [
"kind",
"vidsheet_id"
],
"properties": {
"id": {
"oneOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "string",
"pattern": "^[A-Za-z0-9_-]+$",
"maxLength": 128,
"minLength": 1
}
]
},
"ref": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$",
"maxLength": 64,
"minLength": 1
},
"kind": {
"const": "variable"
},
"vidsheet_id": {
"oneOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "string",
"pattern": "^[A-Za-z0-9_-]+$",
"maxLength": 128,
"minLength": 1
}
]
}
},
"additionalProperties": false
}
]
}
},
"additionalProperties": false
},
"values": {
"type": "object",
"required": [],
"properties": {
"type": {
"type": "string"
},
"inputs": {
"type": "object"
}
},
"description": "Fields and a worked example: gen_discover domain=vidsheet view=actions target=\"update:creation_card\".",
"minProperties": 1,
"additionalProperties": false
}
},
"description": "Fields and a worked example: gen_discover domain=vidsheet view=actions target=\"update:creation_card\".",
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"target",
"values"
],
"properties": {
"action": {
"const": "update"
},
"target": {
"type": "object",
"anyOf": [
{
"required": [
"id"
]
},
{
"required": [
"ref"
]
}
],
"required": [
"kind",
"vidsheet_id"
],
"properties": {
"id": {
"oneOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "string",
"pattern": "^[A-Za-z0-9_-]+$",
"maxLength": 128,
"minLength": 1
}
]
},
"ref": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$",
"maxLength": 64,
"minLength": 1
},
"kind": {
"const": "variable"
},
"vidsheet_id": {
"oneOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "string",
"pattern": "^[A-Za-z0-9_-]+$",
"maxLength": 128,
"minLength": 1
}
]
}
},
"additionalProperties": false
},
"values": {
"type": "object",
"required": [],
"properties": {
"name": {
"type": "string"
},
"media": {
"type": "object",
"allOf": [
{
"anyOf": [
{
"not": {
"required": [
"key"
],
"properties": {
"key": {
"enum": [
"image"
]
}
}
}
},
{
"properties": {
"mediaType": {
"enum": [
"image"
]
}
}
}
]
},
{
"anyOf": [
{
"not": {
"required": [
"key"
],
"properties": {
"key": {
"enum": [
"video"
]
}
}
}
},
{
"properties": {
"mediaType": {
"enum": [
"video"
]
}
}
}
]
},
{
"anyOf": [
{
"not": {
"required": [
"key"
],
"properties": {
"key": {
"enum": [
"audio"
]
}
}
}
},
{
"properties": {
"mediaType": {
"enum": [
"audio"
]
}
}
}
]
},
{
"anyOf": [
{
"not": {
"required": [
"references"
]
}
},
{
"properties": {
"key": {
"enum": [
"var"
]
}
}
}
]
},
{
"anyOf": [
{
"not": {
"required": [
"key"
],
"properties": {
"key": {
"enum": [
"image",
"video",
"audio"
]
}
}
}
},
{
"properties": {
"value": {
"pattern": "^(|[1-9][0-9]*|https://\\S+|__pending_link_import__)$"
}
}
}
]
}
],
"properties": {
"key": {
"enum": [
"text",
"image",
"video",
"audio",
"var"
]
},
"name": {
"type": "string"
},
"value": {
"oneOf": [
{
"type": "string"
},
{
"type": "integer",
"minimum": 1
}
]
},
"duration": {
"type": "number"
},
"mediaType": {
"enum": [
"image",
"video",
"audio"
]
},
"references": {
"type": "object",
"required": [
"type",
"value"
],
"properties": {
"data": {
"type": "string"
},
"name": {
"type": "string"
},
"type": {
"enum": [
"local_variable",
"video_layer",
"global_variable",
"final_video"
]
},
"value": {
"type": "number"
}
},
"additionalProperties": false
},
"thumbnailUrl": {
"type": "string"
},
"library_reference": {
"type": "string",
"minLength": 1
}
},
"additionalProperties": false
},
"value": {
"type": [
"string",
"null"
]
},
"clear_content": {
"const": true
}
},
"description": "Fields and a worked example: gen_discover domain=vidsheet view=actions target=\"update:variable\".",
"minProperties": 1,
"additionalProperties": false
}
},
"description": "Fields and a worked example: gen_discover domain=vidsheet view=actions target=\"update:variable\".",
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"target",
"card"
],
"properties": {
"card": {
"type": "object",
"required": [
"type",
"inputs"
],
"properties": {
"type": {
"enum": [
"text",
"text-overlay",
"raw-text",
"image-from-text",
"video-from-text",
"video-from-image",
"video-from-ingredients",
"video-from-image-from-text",
"video-from-talking-avatar",
"speech-from-text",
"lip-sync",
"lip-sync-trim",
"captions",
"media",
"song",
"final-video"
],
"type": "string"
},
"inputs": {
"type": "object"
}
},
"description": "A creation card {type, inputs}. Read the card's fields and models with gen_discover domain=vidsheet view=card_schema card_schema=<card_type>.",
"additionalProperties": false
},
"action": {
"const": "generate"
},
"target": {
"type": "object",
"required": [
"kind",
"vidsheet_id",
"id"
],
"properties": {
"id": {
"oneOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "string",
"pattern": "^[A-Za-z0-9_-]+$",
"maxLength": 128,
"minLength": 1
}
]
},
"kind": {
"const": "cell"
},
"vidsheet_id": {
"oneOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "string",
"pattern": "^[A-Za-z0-9_-]+$",
"maxLength": 128,
"minLength": 1
}
]
}
},
"additionalProperties": false
}
},
"description": "Fields and a worked example: gen_discover domain=vidsheet view=actions target=\"generate:cell\".",
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"target",
"card"
],
"properties": {
"card": {
"type": "object",
"required": [
"type",
"inputs"
],
"properties": {
"type": {
"enum": [
"text",
"text-overlay",
"raw-text",
"image-from-text",
"video-from-text",
"video-from-image",
"video-from-ingredients",
"video-from-image-from-text",
"video-from-talking-avatar",
"speech-from-text",
"lip-sync",
"lip-sync-trim",
"captions",
"media",
"song",
"final-video"
],
"type": "string"
},
"inputs": {
"type": "object"
}
},
"description": "A creation card {type, inputs}. Read the card's fields and models with gen_discover domain=vidsheet view=card_schema card_schema=<card_type>.",
"additionalProperties": false
},
"action": {
"const": "generate"
},
"target": {
"type": "object",
"required": [
"kind",
"vidsheet_id",
"id"
],
"properties": {
"id": {
"oneOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "string",
"pattern": "^[A-Za-z0-9_-]+$",
"maxLength": 128,
"minLength": 1
}
]
},
"kind": {
"const": "layer"
},
"vidsheet_id": {
"oneOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "string",
"pattern": "^[A-Za-z0-9_-]+$",
"maxLength": 128,
"minLength": 1
}
]
}
},
"additionalProperties": false
}
},
"description": "Fields and a worked example: gen_discover domain=vidsheet view=actions target=\"generate:layer\".",
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"target",
"card"
],
"properties": {
"card": {
"type": "object",
"required": [
"type",
"inputs"
],
"properties": {
"type": {
"enum": [
"text",
"text-overlay",
"raw-text",
"image-from-text",
"video-from-text",
"video-from-image",
"video-from-ingredients",
"video-from-image-from-text",
"video-from-talking-avatar",
"speech-from-text",
"lip-sync",
"lip-sync-trim",
"captions",
"media",
"song",
"final-video"
],
"type": "string"
},
"inputs": {
"type": "object"
}
},
"description": "A creation card {type, inputs}. Read the card's fields and models with gen_discover domain=vidsheet view=card_schema card_schema=<card_type>.",
"additionalProperties": false
},
"action": {
"const": "generate"
},
"target": {
"type": "object",
"required": [
"kind",
"owner",
"slot"
],
"properties": {
"kind": {
"const": "creation_card"
},
"slot": {
"const": "draftForm"
},
"owner": {
"oneOf": [
{
"type": "object",
"anyOf": [
{
"required": [
"id"
]
},
{
"required": [
"ref"
]
},
{
"required": [
"column_id",
"row_id"
]
}
],
"required": [
"kind",
"vidsheet_id"
],
"properties": {
"id": {
"oneOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "string",
"pattern": "^[A-Za-z0-9_-]+$",
"maxLength": 128,
"minLength": 1
}
]
},
"ref": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$",
"maxLength": 64,
"minLength": 1
},
"kind": {
"const": "cell"
},
"row_id": {
"oneOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "string",
"pattern": "^[A-Za-z0-9_-]+$",
"maxLength": 128,
"minLength": 1
},
{
"type": "object",
"required": [
"ref"
],
"properties": {
"ref": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$",
"maxLength": 64,
"minLength": 1
}
},
"additionalProperties": false
}
]
},
"column_id": {
"oneOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "string",
"pattern": "^[A-Za-z0-9_-]+$",
"maxLength": 128,
"minLength": 1
},
{
"type": "object",
"required": [
"ref"
],
"properties": {
"ref": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$",
"maxLength": 64,
"minLength": 1
}
},
"additionalProperties": false
}
]
},
"vidsheet_id": {
"oneOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "string",
"pattern": "^[A-Za-z0-9_-]+$",
"maxLength": 128,
"minLength": 1
}
]
}
},
"additionalProperties": false
},
{
"type": "object",
"anyOf": [
{
"required": [
"id"
]
},
{
"required": [
"ref"
]
}
],
"required": [
"kind",
"vidsheet_id"
],
"properties": {
"id": {
"oneOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "string",
"pattern": "^[A-Za-z0-9_-]+$",
"maxLength": 128,
"minLength": 1
}
]
},
"ref": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$",
"maxLength": 64,
"minLength": 1
},
"kind": {
"const": "layer"
},
"vidsheet_id": {
"oneOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "string",
"pattern": "^[A-Za-z0-9_-]+$",
"maxLength": 128,
"minLength": 1
}
]
}
},
"additionalProperties": false
},
{
"type": "object",
"anyOf": [
{
"required": [
"id"
]
},
{
"required": [
"ref"
]
}
],
"required": [
"kind",
"vidsheet_id"
],
"properties": {
"id": {
"oneOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "string",
"pattern": "^[A-Za-z0-9_-]+$",
"maxLength": 128,
"minLength": 1
}
]
},
"ref": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$",
"maxLength": 64,
"minLength": 1
},
"kind": {
"const": "variable"
},
"vidsheet_id": {
"oneOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "string",
"pattern": "^[A-Za-z0-9_-]+$",
"maxLength": 128,
"minLength": 1
}
]
}
},
"additionalProperties": false
}
]
}
},
"additionalProperties": false
}
},
"description": "Fields and a worked example: gen_discover domain=vidsheet view=actions target=\"generate:creation_card\".",
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"target"
],
"properties": {
"card": {
"type": "object",
"required": [
"type",
"inputs"
],
"properties": {
"type": {
"enum": [
"text",
"text-overlay",
"raw-text",
"image-from-text",
"video-from-text",
"video-from-image",
"video-from-ingredients",
"video-from-image-from-text",
"video-from-talking-avatar",
"speech-from-text",
"lip-sync",
"lip-sync-trim",
"captions",
"media",
"song",
"final-video"
],
"type": "string"
},
"inputs": {
"type": "object"
}
},
"description": "A creation card {type, inputs}. Read the card's fields and models with gen_discover domain=vidsheet view=card_schema card_schema=<card_type>.",
"additionalProperties": false
},
"action": {
"const": "generate"
},
"target": {
"type": "object",
"required": [
"kind",
"vidsheet_id",
"id"
],
"properties": {
"id": {
"oneOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "string",
"pattern": "^[A-Za-z0-9_-]+$",
"maxLength": 128,
"minLength": 1
}
]
},
"kind": {
"const": "column"
},
"vidsheet_id": {
"oneOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "string",
"pattern": "^[A-Za-z0-9_-]+$",
"maxLength": 128,
"minLength": 1
}
]
}
},
"additionalProperties": false
},
"preview": {
"type": "boolean",
"description": "Fields and a worked example: gen_discover domain=vidsheet view=actions target=\"generate:column\"."
},
"row_ids": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
},
"maxItems": 50,
"minItems": 1,
"description": "Fields and a worked example: gen_discover domain=vidsheet view=actions target=\"generate:column\".",
"uniqueItems": true
}
},
"description": "Fields and a worked example: gen_discover domain=vidsheet view=actions target=\"generate:column\".",
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"target"
],
"properties": {
"action": {
"const": "duplicate"
},
"target": {
"type": "object",
"required": [
"kind",
"id"
],
"properties": {
"id": {
"oneOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "string",
"pattern": "^[A-Za-z0-9_-]+$",
"maxLength": 128,
"minLength": 1
}
]
},
"kind": {
"const": "vidsheet"
}
},
"additionalProperties": false
},
"target_agent_id": {
"oneOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "string",
"pattern": "^[A-Za-z0-9_-]+$",
"maxLength": 128,
"minLength": 1
}
],
"description": "Fields and a worked example: gen_discover domain=vidsheet view=actions target=\"duplicate:vidsheet\"."
}
},
"description": "Fields and a worked example: gen_discover domain=vidsheet view=actions target=\"duplicate:vidsheet\".",
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"target"
],
"properties": {
"action": {
"const": "duplicate"
},
"target": {
"type": "object",
"required": [
"kind",
"vidsheet_id",
"id"
],
"properties": {
"id": {
"oneOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "string",
"pattern": "^[A-Za-z0-9_-]+$",
"maxLength": 128,
"minLength": 1
}
]
},
"kind": {
"const": "column"
},
"vidsheet_id": {
"oneOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "string",
"pattern": "^[A-Za-z0-9_-]+$",
"maxLength": 128,
"minLength": 1
}
]
}
},
"additionalProperties": false
}
},
"description": "Fields and a worked example: gen_discover domain=vidsheet view=actions target=\"duplicate:column\".",
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"target"
],
"properties": {
"action": {
"const": "duplicate"
},
"target": {
"type": "object",
"required": [
"kind",
"vidsheet_id",
"id"
],
"properties": {
"id": {
"oneOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "string",
"pattern": "^[A-Za-z0-9_-]+$",
"maxLength": 128,
"minLength": 1
}
]
},
"kind": {
"const": "row"
},
"vidsheet_id": {
"oneOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "string",
"pattern": "^[A-Za-z0-9_-]+$",
"maxLength": 128,
"minLength": 1
}
]
}
},
"additionalProperties": false
}
},
"description": "Fields and a worked example: gen_discover domain=vidsheet view=actions target=\"duplicate:row\".",
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"target"
],
"properties": {
"action": {
"const": "duplicate"
},
"target": {
"type": "object",
"required": [
"kind",
"vidsheet_id",
"id"
],
"properties": {
"id": {
"oneOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "string",
"pattern": "^[A-Za-z0-9_-]+$",
"maxLength": 128,
"minLength": 1
}
]
},
"kind": {
"const": "layer"
},
"vidsheet_id": {
"oneOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "string",
"pattern": "^[A-Za-z0-9_-]+$",
"maxLength": 128,
"minLength": 1
}
]
}
},
"additionalProperties": false
},
"values": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string"
}
},
"description": "Fields and a worked example: gen_discover domain=vidsheet view=actions target=\"duplicate:layer\".",
"additionalProperties": false
}
},
"description": "Fields and a worked example: gen_discover domain=vidsheet view=actions target=\"duplicate:layer\".",
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"target"
],
"properties": {
"action": {
"const": "delete"
},
"target": {
"type": "object",
"required": [
"kind",
"id"
],
"properties": {
"id": {
"oneOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "string",
"pattern": "^[A-Za-z0-9_-]+$",
"maxLength": 128,
"minLength": 1
}
]
},
"kind": {
"const": "vidsheet"
}
},
"additionalProperties": false
},
"confirm_token": {
"type": "string",
"minLength": 1,
"description": "Fields and a worked example: gen_discover domain=vidsheet view=actions target=\"delete:vidsheet\"."
}
},
"description": "Fields and a worked example: gen_discover domain=vidsheet view=actions target=\"delete:vidsheet\".",
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"target"
],
"properties": {
"action": {
"const": "delete"
},
"target": {
"type": "object",
"anyOf": [
{
"required": [
"id"
]
},
{
"required": [
"ref"
]
}
],
"required": [
"kind",
"vidsheet_id"
],
"properties": {
"id": {
"oneOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "string",
"pattern": "^[A-Za-z0-9_-]+$",
"maxLength": 128,
"minLength": 1
}
]
},
"ref": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$",
"maxLength": 64,
"minLength": 1
},
"kind": {
"const": "column"
},
"vidsheet_id": {
"oneOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "string",
"pattern": "^[A-Za-z0-9_-]+$",
"maxLength": 128,
"minLength": 1
}
]
}
},
"additionalProperties": false
},
"confirm_token": {
"type": "string",
"minLength": 1,
"description": "Fields and a worked example: gen_discover domain=vidsheet view=actions target=\"delete:column\"."
}
},
"description": "Fields and a worked example: gen_discover domain=vidsheet view=actions target=\"delete:column\".",
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"target"
],
"properties": {
"action": {
"const": "delete"
},
"target": {
"type": "object",
"anyOf": [
{
"required": [
"id"
]
},
{
"required": [
"ref"
]
}
],
"required": [
"kind",
"vidsheet_id"
],
"properties": {
"id": {
"oneOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "string",
"pattern": "^[A-Za-z0-9_-]+$",
"maxLength": 128,
"minLength": 1
}
]
},
"ref": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$",
"maxLength": 64,
"minLength": 1
},
"kind": {
"const": "row"
},
"vidsheet_id": {
"oneOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "string",
"pattern": "^[A-Za-z0-9_-]+$",
"maxLength": 128,
"minLength": 1
}
]
}
},
"additionalProperties": false
},
"confirm_token": {
"type": "string",
"minLength": 1,
"description": "Fields and a worked example: gen_discover domain=vidsheet view=actions target=\"delete:row\"."
}
},
"description": "Fields and a worked example: gen_discover domain=vidsheet view=actions target=\"delete:row\".",
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"target"
],
"properties": {
"action": {
"const": "delete"
},
"target": {
"type": "object",
"anyOf": [
{
"required": [
"id"
]
},
{
"required": [
"ref"
]
}
],
"required": [
"kind",
"vidsheet_id"
],
"properties": {
"id": {
"oneOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "string",
"pattern": "^[A-Za-z0-9_-]+$",
"maxLength": 128,
"minLength": 1
}
]
},
"ref": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$",
"maxLength": 64,
"minLength": 1
},
"kind": {
"const": "layer"
},
"vidsheet_id": {
"oneOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "string",
"pattern": "^[A-Za-z0-9_-]+$",
"maxLength": 128,
"minLength": 1
}
]
}
},
"additionalProperties": false
},
"confirm_token": {
"type": "string",
"minLength": 1,
"description": "Fields and a worked example: gen_discover domain=vidsheet view=actions target=\"delete:layer\"."
}
},
"description": "Fields and a worked example: gen_discover domain=vidsheet view=actions target=\"delete:layer\".",
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"target"
],
"properties": {
"action": {
"const": "delete"
},
"target": {
"type": "object",
"anyOf": [
{
"required": [
"id"
]
},
{
"required": [
"ref"
]
}
],
"required": [
"kind",
"vidsheet_id"
],
"properties": {
"id": {
"oneOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "string",
"pattern": "^[A-Za-z0-9_-]+$",
"maxLength": 128,
"minLength": 1
}
]
},
"ref": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$",
"maxLength": 64,
"minLength": 1
},
"kind": {
"const": "variable"
},
"vidsheet_id": {
"oneOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "string",
"pattern": "^[A-Za-z0-9_-]+$",
"maxLength": 128,
"minLength": 1
}
]
}
},
"additionalProperties": false
},
"confirm_token": {
"type": "string",
"minLength": 1,
"description": "Fields and a worked example: gen_discover domain=vidsheet view=actions target=\"delete:variable\"."
}
},
"description": "Fields and a worked example: gen_discover domain=vidsheet view=actions target=\"delete:variable\".",
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"target",
"ids"
],
"properties": {
"ids": {
"type": "array",
"items": {
"oneOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "string",
"pattern": "^[A-Za-z0-9_-]+$",
"maxLength": 128,
"minLength": 1
},
{
"type": "object",
"required": [
"ref"
],
"properties": {
"ref": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$",
"maxLength": 64,
"minLength": 1
}
},
"additionalProperties": false
}
]
},
"maxItems": 1000,
"minItems": 1,
"description": "Fields and a worked example: gen_discover domain=vidsheet view=actions target=\"reorder:column\".",
"uniqueItems": true
},
"action": {
"const": "reorder"
},
"target": {
"type": "object",
"required": [
"kind",
"vidsheet_id"
],
"properties": {
"kind": {
"const": "column"
},
"vidsheet_id": {
"oneOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "string",
"pattern": "^[A-Za-z0-9_-]+$",
"maxLength": 128,
"minLength": 1
}
]
}
},
"additionalProperties": false
}
},
"description": "Fields and a worked example: gen_discover domain=vidsheet view=actions target=\"reorder:column\".",
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"target",
"ids"
],
"properties": {
"ids": {
"type": "array",
"items": {
"oneOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "string",
"pattern": "^[A-Za-z0-9_-]+$",
"maxLength": 128,
"minLength": 1
},
{
"type": "object",
"required": [
"ref"
],
"properties": {
"ref": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$",
"maxLength": 64,
"minLength": 1
}
},
"additionalProperties": false
}
]
},
"maxItems": 1000,
"minItems": 1,
"description": "Fields and a worked example: gen_discover domain=vidsheet view=actions target=\"reorder:row\".",
"uniqueItems": true
},
"action": {
"const": "reorder"
},
"target": {
"type": "object",
"required": [
"kind",
"vidsheet_id"
],
"properties": {
"kind": {
"const": "row"
},
"vidsheet_id": {
"oneOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "string",
"pattern": "^[A-Za-z0-9_-]+$",
"maxLength": 128,
"minLength": 1
}
]
}
},
"additionalProperties": false
}
},
"description": "Fields and a worked example: gen_discover domain=vidsheet view=actions target=\"reorder:row\".",
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"target",
"ids"
],
"properties": {
"ids": {
"type": "array",
"items": {
"oneOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "string",
"pattern": "^[A-Za-z0-9_-]+$",
"maxLength": 128,
"minLength": 1
},
{
"type": "object",
"required": [
"ref"
],
"properties": {
"ref": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$",
"maxLength": 64,
"minLength": 1
}
},
"additionalProperties": false
}
]
},
"maxItems": 1000,
"minItems": 1,
"description": "Fields and a worked example: gen_discover domain=vidsheet view=actions target=\"reorder:layer\".",
"uniqueItems": true
},
"action": {
"const": "reorder"
},
"target": {
"type": "object",
"required": [
"kind",
"vidsheet_id",
"cell_id"
],
"properties": {
"kind": {
"const": "layer"
},
"cell_id": {
"oneOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "string",
"pattern": "^[A-Za-z0-9_-]+$",
"maxLength": 128,
"minLength": 1
}
]
},
"vidsheet_id": {
"oneOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "string",
"pattern": "^[A-Za-z0-9_-]+$",
"maxLength": 128,
"minLength": 1
}
]
}
},
"additionalProperties": false
}
},
"description": "Fields and a worked example: gen_discover domain=vidsheet view=actions target=\"reorder:layer\".",
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"target"
],
"properties": {
"action": {
"const": "undo"
},
"target": {
"type": "object",
"required": [
"kind",
"id"
],
"properties": {
"id": {
"oneOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "string",
"pattern": "^[A-Za-z0-9_-]+$",
"maxLength": 128,
"minLength": 1
}
]
},
"kind": {
"const": "vidsheet"
}
},
"additionalProperties": false
},
"change_set_id": {
"type": "string",
"format": "uuid",
"description": "Fields and a worked example: gen_discover domain=vidsheet view=actions target=\"undo:vidsheet\"."
}
},
"description": "Fields and a worked example: gen_discover domain=vidsheet view=actions target=\"undo:vidsheet\".",
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"target"
],
"properties": {
"action": {
"const": "redo"
},
"target": {
"type": "object",
"required": [
"kind",
"id"
],
"properties": {
"id": {
"oneOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "string",
"pattern": "^[A-Za-z0-9_-]+$",
"maxLength": 128,
"minLength": 1
}
]
},
"kind": {
"const": "vidsheet"
}
},
"additionalProperties": false
},
"change_set_id": {
"type": "string",
"format": "uuid",
"description": "Fields and a worked example: gen_discover domain=vidsheet view=actions target=\"redo:vidsheet\"."
}
},
"description": "Fields and a worked example: gen_discover domain=vidsheet view=actions target=\"redo:vidsheet\".",
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"target"
],
"properties": {
"action": {
"const": "export"
},
"target": {
"type": "object",
"required": [
"kind",
"id"
],
"properties": {
"id": {
"oneOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "string",
"pattern": "^[A-Za-z0-9_-]+$",
"maxLength": 128,
"minLength": 1
}
]
},
"kind": {
"const": "vidsheet"
}
},
"additionalProperties": false
},
"row_ids": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1
},
"maxItems": 2000,
"description": "Fields and a worked example: gen_discover domain=vidsheet view=actions target=\"export:vidsheet\".",
"uniqueItems": true
}
},
"description": "Fields and a worked example: gen_discover domain=vidsheet view=actions target=\"export:vidsheet\".",
"additionalProperties": false
}
]
}
},
{
"type": "null"
}
],
"default": null,
"examples": [
[
{
"action": "update",
"target": {
"id": 2002,
"kind": "row",
"vidsheet_id": 1001
},
"values": {
"video_settings": {
"aspect_ratio": "1:1"
}
}
}
]
],
"description": "Canonical Rails action envelope: a non-empty list of {\"action\", \"target\", \"values\"|\"ids\"} objects, relayed to Rails verbatim (GEN-6700); pass either this or a flat op, never both. A row's output video format (aspect ratio / resolution) is set only here, with a row update: values.video_settings.aspect_ratio 1:1 | 9:16 | 16:9, values.video_settings.resolution 1080p | 4k (either or both). Example, set a row to 1:1: [{\"action\": \"update\", \"target\": {\"kind\": \"row\", \"vidsheet_id\": 1001, \"id\": 2002}, \"values\": {\"video_settings\": {\"aspect_ratio\": \"1:1\"}}}]"
},
"cell_id": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Cell ID (set_cell, layers, card owner/target); a global's value_cell_id addresses its value cell"
},
"idea_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Idea ID (create_engine; requires template_slug)"
},
"no_paid": {
"type": "boolean",
"default": false,
"description": "Refuse paid media generation for this run. Text and LLM work still bills normally."
},
"recover": {
"type": "boolean",
"default": false,
"description": "apply_storyboard: read-only comparison with the owned row after a lost reply; returns Draft without writes, models or jobs."
},
"sources": {
"anyOf": [
{
"type": "array",
"items": {}
},
{
"type": "null"
}
],
"default": null,
"description": "target_state: owned content_resource_ids allowed as media sources"
},
"agent_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The agent that owns the vidsheet. Optional when the call names the sheet (vidsheet_id): the owner resolves from the engine read. Required for create_sheet/clone_template/create_engine and a call naming no sheet (GEN-7151)"
},
"bindings": {
"anyOf": [
{
"type": "array",
"items": {}
},
{
"type": "null"
}
],
"default": null,
"description": "Saved-input bindings for this envelope (MCP-only; never relayed to Rails): one {index, references} per action, where index names that action and references is [{input_id, card_type?, field?}]. The MCP resolves each reference against source_inputs and the served card schema before any write (GEN-9391)."
},
"duration": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Duration in seconds 1-480, default 240 (generate song, recommend_song); out of range is rejected, so estimate the seconds you ask for"
},
"layer_id": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Layer ID (update_layer, generate layer, card owner/target)"
},
"overlays": {
"anyOf": [
{
"type": "array",
"items": {}
},
{
"type": "null"
}
],
"default": null,
"description": "Overlay sources (generate sound_matching)"
},
"position": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Column position (add_column), from gen_discover columns; a column never lands right of VIDEO / FINAL VIDEO / STATS"
},
"settings": {
"anyOf": [
{
"type": "object",
"additionalProperties": true
},
{
"type": "null"
}
],
"default": null,
"description": "Layer settings (add_layer/update_layer); a trim (from, duration_in_frames, video_start_time) also sends userHasTrimmed=true, or the browser recomputes the full clip (GEN-7637)"
},
"audio_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "HTTPS audio URL (generate recommend_song reference — that card makes a PAID cover/remix of this one track; find suggestions with gen_discover view actions audio_library=recommended; avatar lip-sync audio)"
},
"avatar_id": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Avatar model ID (generate video_from_avatar)"
},
"folder_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Asset folder for the import (import_asset)"
},
"layer_row": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Timeline row/track for add_layer and update_layer, 0-based (settings.row); layers sharing a row play sequentially. One of the ten tracks 0..9"
},
"media_key": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Media key: text | image | video | audio | var (set_cell/import_asset)"
},
"media_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Media URL (set_cell/add_layer/update_layer media, import_asset)"
},
"video_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Avatar video URL (generate video_from_avatar)"
},
"layer_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Layer name (add_layer)"
},
"layer_type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Layer type (add_layer): clip, image, text, caption or sound; audio/voice/music map to sound, video to clip. Give a voice or music layer its sound type and timing before generating into it (GEN-7690)"
},
"media_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Media name (set_cell/import_asset; song recommend binds the song title)"
},
"storyboard": {
"anyOf": [
{
"type": "object",
"additionalProperties": true
},
{
"type": "null"
}
],
"default": null,
"description": "apply_storyboard: scene-form BuildPlanV1 object, validated and applied to the selected owned row."
},
"column_type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Column type (add_column)"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Column description (add_column)"
},
"variable_id": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Global-variable row id from gen_discover view=variables, never the value cell id: generate resolves it to that value cell as the owner (instead of cell_id/layer_id)"
},
"vidsheet_id": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Vidsheet ID (every op except create_sheet/clone_template/create_engine)"
},
"auto_confirm": {
"type": "boolean",
"default": false,
"description": "Approve one headless delete through Rails confirmation; edit access remains required. false keeps the UI preview/token flow."
},
"build_run_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Errored build run identity (refund_unused_output); relayed to Rails as audit metadata"
},
"caption_text": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Caption text (update_layer)"
},
"instrumental": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "Instrumental flag (generate song, recommend_song)"
},
"row_position": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "apply_storyboard only: one-based displayed row position on the owned Vidsheet, instead of row_id"
},
"target_state": {
"anyOf": [
{
"type": "object",
"additionalProperties": true
},
{
"type": "null"
}
],
"default": null,
"description": "apply_storyboard alternative: edit the full gen_discover vidsheet sheet result. Writes only differences from a fresh read, deletes separately, no paid regeneration. Media must be on-sheet or in sources."
},
"vocal_gender": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "'m' or 'f' to bias vocal gender (generate song)"
},
"change_set_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Stable edit-group ID for undo and retry"
},
"clear_content": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "Clear content flag (set_cell, layers)"
},
"confirm_token": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Single-use token from a confirmation_required preview; completes the delete it was issued for"
},
"creation_card": {
"anyOf": [
{
"type": "object",
"additionalProperties": true
},
{
"type": "null"
}
],
"default": null,
"description": "Creation card payload (add_layer/update_layer)"
},
"generation_id": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Generation ID (continue_generation, stop_generation, refund_unused_output)"
},
"is_commercial": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "Commercial-cleared sounds only (generate sound_matching)"
},
"negative_tags": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Styles/instruments to avoid (generate song; trimmed, blank omitted)"
},
"source_inputs": {
"anyOf": [
{
"type": "object",
"additionalProperties": true
},
{
"type": "null"
}
],
"default": null,
"description": "Resolved saved input media for the envelope's per-action source references (MCP-only; never relayed to Rails): {attachments: [{ref, url, kind, content_resource_id, resource...}]}. Each reference binds into its action's card through the served card schema before any write, and an incompatible card/media pair is refused typed with effects zero (GEN-9391)."
},
"template_slug": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Template slug (optional on create_sheet; clone_template; create_engine requires it with idea_id); discover valid choices with gen_discover vidsheet view=templates"
},
"video_type_id": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "apply_storyboard with target_state only: the storyboard's video type id (canonical timeline rows)"
},
"lip_sync_model": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Lip-sync model (generate video_from_avatar)"
},
"media_asset_id": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Owned ContentResource id of an uploaded/library asset to bind (set_cell); send with media_key image|video|audio"
},
"remove_silence": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "Remove audio silence (generate video_from_avatar)"
},
"auto_regenerate": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "false writes this batch without paid dependent regeneration (Rails: skipped); true/omitted keeps automatic regeneration. Use false for drafts."
},
"content_idea_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Saved-idea alias: create_sheet refuses it with the gen_content_action create_video_from_idea call"
},
"idempotency_key": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Required for refund_unused_output. Reuse on retries to replay the job; omission generates a new key and may charge again. Forwarded to paid creation cards."
},
"media_reference": {
"anyOf": [
{
"type": "object",
"additionalProperties": true
},
{
"type": "null"
}
],
"default": null,
"description": "A generation's owner as media (set_cell): {type: local_variable|video_layer|global_variable|final_video, value, name?}"
},
"spending_run_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,128}$",
"maxLength": 128,
"minLength": 1,
"description": "Stable run or conversation identity required with spending controls. The authenticated run owner shares one policy across workspaces."
},
"target_agent_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Target agent for cross-agent duplication (duplicate_sheet)"
},
"remove_background": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "Remove video background (generate video_from_avatar)"
},
"creation_card_type": {
"enum": [
"captions",
"final-video",
"image-from-text",
"lip-sync",
"lip-sync-trim",
"media",
"raw-text",
"recommend_song",
"song",
"sound_matching",
"source_video_analysis",
"speech-from-text",
"text",
"text-overlay",
"video-from-image",
"video-from-image-from-text",
"video-from-ingredients",
"video-from-talking-avatar",
"video-from-text",
"video_from_avatar"
],
"type": "string",
"description": "Creation card pick. One of the 15 FE card types an FE picker offers (for example video-from-talking-avatar) or an MCP job card (sound_matching | recommend_song | song | video_from_avatar | source_video_analysis); the final render card final-video renders a row's final video into its FINAL VIDEO cell. creation_card_inputs is typed per card."
},
"content_resource_id": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Owned video asset ID to analyze (generate source_video_analysis)"
},
"creation_card_owner": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "'cell' or 'layer': the owner a generate card pick is addressed at (use when both cell_id and layer_id are given)"
},
"max_paid_operations": {
"type": "integer",
"maximum": 2147483647,
"minimum": 0,
"description": "Maximum paid media reservations across all workspaces in this authenticated user/run, enforced atomically. Retries reuse their reservation."
},
"reference_audio_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "HTTPS reference-audio URL for conditioning (generate song)"
},
"creation_card_inputs": {
"anyOf": [
{
"type": "object",
"additionalProperties": true
},
{
"type": "null"
}
],
"description": "Per-card inputs. Send the arm whose card matches creation_card_type; a field the card does not take is refused, never forwarded. The final render card's arm is optional — its composition is built from the row when omitted."
}
},
"x-gen-delegation": {
"actions": [
"apply_storyboard",
"clone_template",
"create",
"create_sheet",
"delete",
"generate",
"update"
],
"excluded_actions": []
},
"additionalProperties": false
}| any |
| Single-use token from a CONFIRMATION_REQUIRED error; repeat the same call with it to complete the destructive action it was issued for. Omit on the first call. |
{
"type": "object",
"required": [
"actions"
],
"properties": {
"actions": {
"type": "array",
"items": {
"oneOf": [
{
"type": "object",
"required": [
"action",
"name"
],
"properties": {
"name": {
"type": "string",
"description": "REQUIRED — display name for the cloned voice"
},
"action": {
"const": "clone_voice"
},
"gender": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": ""
},
"language": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": ""
},
"audio_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "URL to an audio sample (mp3/wav). PREFERRED."
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": ""
},
"audio_base64": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Base64-encoded audio bytes. Only for small clips."
},
"voice_model_provider": {
"anyOf": [
{
"enum": [
"supertonic_3",
"qwen3_voice_design"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Voice model: 'supertonic_3' (default) or 'qwen3_voice_design' — the two the product offers (limitless-fe voiceConstants.ts VOICE_MODEL_PROVIDER_OPTIONS); voxcpm2 is deliberately not offered"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"voice_id"
],
"properties": {
"action": {
"const": "delete_voice"
},
"voice_id": {
"type": "string",
"description": "The voice ID to delete"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"generation_id",
"name"
],
"properties": {
"name": {
"type": "string",
"description": "REQUIRED — display name for the new voice"
},
"action": {
"const": "design_voice"
},
"gender": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": ""
},
"language": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": ""
},
"audio_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Downloadable URL to the sample audio; the one alternative to audio_base64 (Rails prefers it when both are sent). One of audio_base64 / audio_url is REQUIRED."
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": ""
},
"audio_base64": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "REQUIRED (unless audio_url is sent) — Base64 audio of the completed sample. Rails' UserVoiceResources::Create refuses a fal voice resource without base64_audio, and every other branch decodes it, so a call without sample audio is refused MISSING_REQUIRED_FIELD before any request. Take it from the voice.sample_status view's `audio` field."
},
"generation_id": {
"type": "string",
"description": "REQUIRED — opaque token from the gen_voice_action generate_voice_samples branch (poll the gen_discover voice.sample_status view until completed)"
},
"voice_model_provider": {
"anyOf": [
{
"enum": [
"supertonic_3",
"qwen3_voice_design"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Voice model: 'supertonic_3' (default) or 'qwen3_voice_design' — the two the product offers (limitless-fe voiceConstants.ts VOICE_MODEL_PROVIDER_OPTIONS); voxcpm2 is deliberately not offered"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"gender"
],
"properties": {
"action": {
"const": "generate_voice_description"
},
"gender": {
"type": "string",
"description": "REQUIRED — e.g. 'male', 'female', 'non-binary'"
},
"script": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The script from step 1 (helps tune the description)"
},
"language": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": ""
},
"voice_description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Optional user hint like 'warm and confident'"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"text"
],
"properties": {
"text": {
"type": "string",
"description": "REQUIRED — the script to speak (from step 1)"
},
"action": {
"const": "generate_voice_samples"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Style descriptor from step 2"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action"
],
"properties": {
"action": {
"const": "generate_voice_script"
},
"language": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Target language (e.g. 'en', 'es')"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"voice_id",
"text"
],
"properties": {
"text": {
"type": "string",
"description": "The text to speak (keep under 500 chars for fast preview)"
},
"action": {
"const": "preview_voice"
},
"voice_id": {
"type": "string",
"description": "The voice ID to preview"
},
"idempotency_key": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Stable retry key (sent as the Idempotency-Key header, max 255 chars). Reuse the same key when retrying this exact create so Rails replays the originally created resource (same id) instead of creating a duplicate. Omit to create unconditionally."
}
},
"additionalProperties": false
}
]
},
"minItems": 1,
"description": "One or more typed voice actions: clone_voice (name, optional audio_url/audio_base64/gender/language/description) | design_voice (generation_id, name, REQUIRED sample audio: audio_base64 (the Rails base64_audio, required for fal voice resources) or audio_url, optional gender/language/description) | delete_voice (voice_id) | preview_voice (voice_id, text) | generate_voice_description (gender, optional voice_description/language/script) | generate_voice_samples (text, optional description) | generate_voice_script (optional language)"
},
"agent_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The agent ID that owns the voices (envelope; routed into every branch)"
},
"confirm_token": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Single-use token from a CONFIRMATION_REQUIRED error; repeat the same call with it to complete the destructive action it was issued for. Omit on the first call."
}
},
"x-gen-delegation": {
"actions": [
"clone_voice",
"design_voice",
"generate_voice_samples",
"generate_voice_script",
"preview_voice"
],
"excluded_actions": []
},
"additionalProperties": false
}| agent_id | any | The agent ID that owns the watchlists (envelope; routed per branch) |
| confirm_token | any | Single-use token from a CONFIRMATION_REQUIRED error; repeat the same call with it to complete the destructive action it was issued for. Omit on the first call. |
{
"type": "object",
"required": [
"actions"
],
"properties": {
"actions": {
"type": "array",
"items": {
"oneOf": [
{
"type": "object",
"anyOf": [
{
"required": [
"watchlist_id"
]
},
{
"required": [
"watchlist_name"
]
}
],
"required": [
"action",
"platform",
"target_type",
"target_value"
],
"properties": {
"action": {
"const": "add_watchlist_source"
},
"platform": {
"enum": [
"tiktok",
"instagram",
"youtube",
"kick"
],
"type": "string",
"description": "Platform: tiktok | instagram | youtube | kick"
},
"target_type": {
"enum": [
"account",
"hashtag",
"keyword"
],
"type": "string",
"description": "Source kind: account=@handle, hashtag=tag (no #), keyword=free text"
},
"target_value": {
"type": "string",
"description": "@handle, hashtag name, or keyword text"
},
"watchlist_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The watchlist id (UUID). Pass this, or watchlist_name when the caller has no id."
},
"watchlist_name": {
"anyOf": [
{
"type": "string",
"maxLength": 200,
"minLength": 1
},
{
"type": "null"
}
],
"default": null,
"description": "Watchlist display name or its @list mention slug, resolved case-insensitively: an exact name or an equal slug as one candidate set, then a unique prefix. An ambiguous name answers the candidates and changes nothing. Use instead of watchlist_id."
},
"original_display_value": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Optional original form (e.g. '#glassskin')"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"action",
"name"
],
"properties": {
"name": {
"type": "string",
"description": "Watchlist display name (1-200 chars). Idempotent: same name reuses the existing watchlist."
},
"action": {
"const": "create_watchlist"
},
"sources": {
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"title": "WatchlistSourceInput",
"required": [
"platform",
"target_type",
"target_value"
],
"properties": {
"platform": {
"type": "string",
"title": "Platform",
"maxLength": 40,
"minLength": 1,
"description": "Platform: tiktok | instagram | youtube | kick"
},
"target_type": {
"enum": [
"account",
"hashtag",
"keyword"
],
"type": "string",
"title": "Target Type",
"description": "Source kind: account=@handle, hashtag=tag (no #), keyword=free text"
},
"target_value": {
"type": "string",
"title": "Target Value",
"maxLength": 500,
"minLength": 1,
"description": "@handle, hashtag name, or keyword text"
},
"original_display_value": {
"anyOf": [
{
"type": "string",
"maxLength": 1000
},
{
"type": "null"
}
],
"title": "Original Display Value",
"default": null,
"description": "Optional original form (e.g. '#glassskin')"
}
},
"description": "One ``create_watchlist.sources`` entry (agent-core\n``app/schemas/watchlist.py`` ``WatchSourceInput``). agent-core requires\nplatform/target_type/target_value, so the MCP states and enforces the same\nelement shape instead of forwarding a dict the backend 422s (GEN-7306).",
"additionalProperties": false
}
},
{
"type": "null"
}
],
"default": null,
"description": "Optional monitoring sources; each is {platform, target_type, target_value, optional original_display_value}. Omit for none."
},
"project_id": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Optional Rails project id to link this watchlist to a project shell"
},
"conversation_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Optional chat conversation that triggered creation (for attribution)"
},
"created_by_run_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Optional agent_run id that triggered creation (for attribution)"
}
},
"additionalProperties": false
},
{
"type": "object",
"anyOf": [
{
"required": [
"watchlist_id"
]
},
{
"required": [
"watchlist_name"
]
}
],
"required": [
"action"
],
"properties": {
"action": {
"const": "delete_watchlist"
},
"watchlist_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The watchlist id (UUID). Pass this, or watchlist_name when the caller has no id."
},
"watchlist_name": {
"anyOf": [
{
"type": "string",
"maxLength": 200,
"minLength": 1
},
{
"type": "null"
}
],
"default": null,
"description": "Watchlist display name or its @list mention slug, resolved case-insensitively: an exact name or an equal slug as one candidate set, then a unique prefix. An ambiguous name answers the candidates and changes nothing. Use instead of watchlist_id."
}
},
"additionalProperties": false
},
{
"type": "object",
"anyOf": [
{
"required": [
"watchlist_id"
]
},
{
"required": [
"watchlist_name"
]
}
],
"required": [
"action"
],
"properties": {
"action": {
"const": "pause_watchlist"
},
"watchlist_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The watchlist id (UUID). Pass this, or watchlist_name when the caller has no id."
},
"watchlist_name": {
"anyOf": [
{
"type": "string",
"maxLength": 200,
"minLength": 1
},
{
"type": "null"
}
],
"default": null,
"description": "Watchlist display name or its @list mention slug, resolved case-insensitively: an exact name or an equal slug as one candidate set, then a unique prefix. An ambiguous name answers the candidates and changes nothing. Use instead of watchlist_id."
}
},
"additionalProperties": false
},
{
"type": "object",
"anyOf": [
{
"required": [
"watchlist_id"
]
},
{
"required": [
"watchlist_name"
]
}
],
"required": [
"action",
"question"
],
"properties": {
"days": {
"anyOf": [
{
"type": "number",
"maximum": 365,
"minimum": 1
},
{
"type": "null"
}
],
"default": null,
"description": "Time window in days (1-365). When omitted, the chat layer's default policy applies."
},
"limit": {
"anyOf": [
{
"type": "number",
"maximum": 1000,
"minimum": 1
},
{
"type": "null"
}
],
"default": null,
"description": "How many results to return (1-1000). When omitted, defaults to 100."
},
"action": {
"const": "query_watchlist"
},
"sort_by": {
"anyOf": [
{
"enum": [
"engagement_rate",
"watch_count",
"like_count",
"comment_count",
"share_count",
"save_count",
"posted_at",
"trending_score"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Sort key: engagement_rate | watch_count | like_count | comment_count | share_count | save_count | posted_at | trending_score. Without it, the backend default ranking applies."
},
"question": {
"type": "string",
"description": "What to ask about the watchlist — e.g. 'top hooks', 'top videos', 'what are people saying', 'trending music'. Drives the analysis kind (top_hooks / trend_videos / comment_themes / top_sounds / top_creators / engagement_summary)."
},
"return_all": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "Walk every matching row up to the DW hard cap (1000). Pairs with async pagination downstream. Defaults to false."
},
"watchlist_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The watchlist id (UUID). Pass this, or watchlist_name when the caller has no id."
},
"watchlist_name": {
"anyOf": [
{
"type": "string",
"maxLength": 200,
"minLength": 1
},
{
"type": "null"
}
],
"default": null,
"description": "Watchlist display name or its @list mention slug, resolved case-insensitively: an exact name or an equal slug as one candidate set, then a unique prefix. An ambiguous name answers the candidates and changes nothing. Use instead of watchlist_id."
},
"min_engagement_rate": {
"anyOf": [
{
"type": "number",
"maximum": 1,
"minimum": 0
},
{
"type": "null"
}
],
"default": null,
"description": "Minimum engagement rate as a 0.0-1.0 fraction (0.05 == 5%)."
}
},
"additionalProperties": false
},
{
"type": "object",
"anyOf": [
{
"required": [
"watchlist_id",
"source_id"
]
},
{
"required": [
"watchlist_id",
"platform",
"target_type",
"target_value"
]
},
{
"required": [
"watchlist_name",
"source_id"
]
},
{
"required": [
"watchlist_name",
"platform",
"target_type",
"target_value"
]
}
],
"required": [
"action"
],
"properties": {
"action": {
"const": "remove_watchlist_source"
},
"platform": {
"anyOf": [
{
"enum": [
"tiktok",
"instagram",
"youtube",
"kick"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Platform (only needed when source_id is omitted)"
},
"source_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The source id (preferred). If omitted, all three of platform/target_type/target_value are required."
},
"target_type": {
"anyOf": [
{
"enum": [
"account",
"hashtag",
"keyword"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Source kind (only needed when source_id is omitted)"
},
"target_value": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Source value (only needed when source_id is omitted)"
},
"watchlist_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The watchlist id (UUID). Pass this, or watchlist_name when the caller has no id."
},
"watchlist_name": {
"anyOf": [
{
"type": "string",
"maxLength": 200,
"minLength": 1
},
{
"type": "null"
}
],
"default": null,
"description": "Watchlist display name or its @list mention slug, resolved case-insensitively: an exact name or an equal slug as one candidate set, then a unique prefix. An ambiguous name answers the candidates and changes nothing. Use instead of watchlist_id."
}
},
"additionalProperties": false
},
{
"type": "object",
"anyOf": [
{
"required": [
"watchlist_id"
]
},
{
"required": [
"watchlist_name"
]
}
],
"required": [
"action"
],
"properties": {
"action": {
"const": "resume_watchlist"
},
"watchlist_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The watchlist id (UUID). Pass this, or watchlist_name when the caller has no id."
},
"watchlist_name": {
"anyOf": [
{
"type": "string",
"maxLength": 200,
"minLength": 1
},
{
"type": "null"
}
],
"default": null,
"description": "Watchlist display name or its @list mention slug, resolved case-insensitively: an exact name or an equal slug as one candidate set, then a unique prefix. An ambiguous name answers the candidates and changes nothing. Use instead of watchlist_id."
}
},
"additionalProperties": false
},
{
"type": "object",
"anyOf": [
{
"required": [
"watchlist_id"
]
},
{
"required": [
"watchlist_name"
]
}
],
"required": [
"action"
],
"properties": {
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "New display name"
},
"action": {
"const": "update_watchlist"
},
"project_id": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "New Rails project id to link"
},
"watchlist_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The watchlist id (UUID). Pass this, or watchlist_name when the caller has no id."
},
"watchlist_name": {
"anyOf": [
{
"type": "string",
"maxLength": 200,
"minLength": 1
},
{
"type": "null"
}
],
"default": null,
"description": "Watchlist display name or its @list mention slug, resolved case-insensitively: an exact name or an equal slug as one candidate set, then a unique prefix. An ambiguous name answers the candidates and changes nothing. Use instead of watchlist_id."
},
"rails_project_error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Last Rails project sync error, if any"
}
},
"additionalProperties": false
}
]
},
"minItems": 1,
"description": "One or more typed watchlist actions: create_watchlist (name, optional sources/project_id/conversation_id/created_by_run_id) | update_watchlist (watchlist_id or watchlist_name, optional name/project_id/rails_project_error) | pause_watchlist (watchlist_id or watchlist_name) | resume_watchlist (watchlist_id or watchlist_name) | delete_watchlist (watchlist_id or watchlist_name; two-phase, resend with confirm_token) | add_watchlist_source (platform, target_type, target_value, watchlist_id or watchlist_name, optional original_display_value) | remove_watchlist_source (watchlist_id or watchlist_name, source_id or platform+target_type+target_value; two-phase, resend with confirm_token) | query_watchlist (question, watchlist_id or watchlist_name, optional days/limit/sort_by/min_engagement_rate/return_all). watchlist_name (a display name or its @list mention slug) resolves case-insensitively: an exact name or an equal slug as one candidate set, then a unique prefix; an ambiguous name returns the candidates and changes nothing. 'what did my watchlist say/find about X' = query_watchlist (it starts a run); gen_discover watchlist list/detail only enumerate saved watchlist records."
},
"agent_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The agent ID that owns the watchlists (envelope; routed per branch)"
},
"confirm_token": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Single-use token from a CONFIRMATION_REQUIRED error; repeat the same call with it to complete the destructive action it was issued for. Omit on the first call."
}
},
"x-gen-delegation": {
"actions": [],
"excluded_actions": []
},
"additionalProperties": false
}