Capabilities Reference

Capability reference

Generated from packages/core/src/lib/capabilities/catalog.ts. Do not hand-edit — run node scripts/gen-agent-docs.mjs.

Every row is one registry entry; the same entry drives the MCP tool, the /api/v1 request, the public mcp.json, the aicmo run <id> CLI dispatcher, and (where chat is a surface) the AI CMO runtime tool.

Legend — effect: read no state change · internal_write changes AICMOHQ state only · external_write posts/sends outside AICMOHQ · spend consumes credits · delete is irreversible. confirmation: approval = a human must approve before the effect lands, step_up = approval plus re-auth; the kernel enforces external_write ⇒ approval or step_up. * = required input.

Capability id	MCP tool	HTTP (/api/v1)	Scope	Effect	Risk	Confirmation	Surfaces	Inputs	Description
capabilities.list	capabilities_list	— (local)	none	read	low	none	cli, mcp	—	List supported chatbot, CLI, and MCP capabilities with risk and confirmation metadata.
strategy.run	strategy_run	POST /strategy/run	strategy:run	spend	medium	approval	cli, mcp	keywords, platform*	Run the full strategy loop: extract git context and generate ICP-validated drafts into the queue (LinkedIn, X, Reddit).
scout.research	scout	POST /scout	strategy:run	spend	low	none	chat, cli, mcp	keywords	Find marketing opportunities based on product and keywords.
writer.generate	write	POST /write	strategy:run	spend	medium	approval	chat, cli, mcp	platform*, from_git, topic, enqueue	Draft content from a topic or from recent git commits. Set enqueue=true to put the draft in the queue for LinkedIn/X publish.
docs.search	docs_search	— (local)	none	read	low	none	cli, mcp	query*, limit	Search tool docs: find which tool to call and its parameters. Pass a tool name for its full input schema. Local, read-only; no auth required.
connection.status	connection_status	— (local)	none	read	low	none	mcp	—	Auto-detect this MCP connection: whether a token is configured and valid, which API it targets, which platforms are connected, and the projects (products) reachable with it. One connection covers every project.
credits.costs	credit_costs	— (local)	none	read	low	none	cli, mcp	—	List the credit cost of each AICMOHQ agent action. Local, read-only; no auth required.
agents.list	agents_list	GET /agents	strategy:run	read	low	none	cli, mcp	—	List the six marketed agents (Ved, Shravan, Chanakya, Kavi, Mitra, Agni) with their charter and live status: effective approval mode and drafts awaiting review.
agents.status	agents_status	GET /agents/{id}	strategy:run	read	low	none	cli, mcp	id*	Read one marketed agent’s charter and live status (mode, pending approvals).
agents.run	agents_run	POST /agents/{id}/run	strategy:run	spend	medium	approval	cli, mcp	id*, platform, keywords, topic	Run one marketed agent’s entry capability now (Ved geo scan, Shravan mention scan, Chanakya strategy draft, Kavi draft, Mitra reply sweep, Agni autopilot cycle). Entry capabilities never publish externally — external_write/delete are refused — but may spend credits or write internal state (Agni’s autopilot cycle). Requires strategy:run plus the entry capability’s own scope (geo:run for Ved, autopilot:run for Agni; Shravan, Chanakya, Kavi, and Mitra entries already use strategy:run). Extra fields pass through as the entry capability’s input (e.g. platform, keywords, topic).
connections.list	connections_list	GET /connections	connections:read	read	low	none	cli, mcp	—	List connected platforms (check LinkedIn before publishing).
queue.list	queue_list	GET /queue?status={status}	queue:read	read	low	none	cli, mcp	status	List content queue items for the authenticated AICMOHQ account.
queue.get	queue_get	GET /queue/{id}	queue:read	read	low	none	cli, mcp	id*	Fetch one content queue item by id.
queue.delete	queue_delete	DELETE /queue/{id}	queue:write	delete	medium	approval	cli, mcp	id*	Permanently delete a queued draft.
queue.update	queue_update	PATCH /queue/{id}	queue:write	internal_write	low	none	cli, mcp	id*, content*	Update the content of a queued draft.
queue.approve	queue_approve	POST /queue/{id}/approve	queue:write	internal_write	medium	step_up	cli, mcp	id*	Approve a draft queue item so it can be published. Human-only: the API rejects CLI/MCP tokens.
queue.publish	queue_publish	POST /queue/{id}/publish	publish	external_write	high	approval	cli, mcp	id*	Publish an approved queue item (requires platform connection, e.g. LinkedIn).
queue.reject	queue_reject	PATCH /queue/{id}	queue:write	internal_write	low	none	cli, mcp	id*	Reject a draft so it will not publish.
queue.best_time	queue_best_time	GET /queue/best-time?platform={platform}&tz={tz}	queue:read	read	low	none	cli, mcp	platform*, tz	Suggest the best publish time for a platform — the workspace’s measured engagement history when available, else the platform’s researched golden-hour window. Advisory only; scheduling still goes through queue_schedule.
queue.schedule	queue_schedule	PATCH /queue/{id}	queue:write	internal_write	medium	approval	cli, mcp	id*, scheduled_for*	Schedule an approved queue item for cron publish (ISO timestamp).
queue.proof	queue_proof	POST /queue/{id}/proof	queue:write	internal_write	low	none	cli, mcp	id*, proofUrl*	Save a live post URL for Hacker News or Product Hunt (no API). Then call queue_publish to mark the item published.
reddit.status	reddit_status	GET /reddit/status	connections:read	read	low	none	cli, mcp	—	Inspect the connected Reddit account’s conservative warm-up stage and engagement limits.
reddit.warmup	reddit_warmup	POST /reddit/warmup	strategy:run	spend	low	none	chat, cli, mcp	keywords, subreddits, limit, productId	Use the connected Reddit OAuth account to find value-first threads. Saves opportunities only; never comments or publishes.
command.chat	command_chat	POST /command/chat	strategy:run	internal_write	low	none	cli, mcp	message*, sessionId, agentId	Send a natural-language mission to AICMOHQ Agent. Persists session memory and returns a proposed plan (approval-first; does not publish). When the response includes a plan, executionPolicy tells you the next step: call command_run with message.id to execute (auto=true only when auto_run_eligible), or command_status with runId to inspect a running one.
command.sessions	command_sessions	GET /command/sessions?limit=20	strategy:run	read	low	none	cli, mcp	limit	List recent AICMOHQ Agent chat sessions (shared memory with dashboard + CLI).
command.run	command_run	POST /command/run	strategy:run	internal_write	medium	approval	cli, mcp	messageId*, auto	Execute a proposed command plan by assistant message id. Rejects auto=true when approval is required. Streams NDJSON progress.
command.status	command_status	GET /command/run/{runId}	strategy:run	read	low	none	cli, mcp	runId*	Inspect a durable command run and its approval-gated steps.
command.approve_step	command_approve_step	POST /command/run/{runId}	strategy:run	internal_write	medium	approval	cli, mcp	runId*, stepId*	Approve one bound CMO step so execution resumes (expires in 15 minutes).
workspace.context	workspace_context	GET /workspace/context	strategy:run	read	low	none	cli, mcp	—	Read the workspace strategy context (product, ICPs, positioning, brand voice) agents ground drafts on.
workspace.get	workspace_get	GET /workspace	strategy:run	read	low	none	cli, mcp	—	Read the raw workspace record (company profile, positioning, ICPs) the agents ground on.
products.list	products_list	GET /products	strategy:run	read	low	none	cli, mcp	—	List the products in the workspace. Most agent work needs a product_id from here first.
products.create	products_create	POST /products	workspace:write	internal_write	low	none	cli, mcp	name*, description, url, target_audience, competitors	Add a product to the workspace so scans and drafts can be scoped to it.
products.update	products_update	PUT /products/{id}	workspace:write	internal_write	low	none	cli, mcp	id*, name, tagline, description, url	Update a product’s name, tagline, description, or url.
products.archive	products_archive	DELETE /products/{id}	workspace:write	delete	medium	approval	cli, mcp	id*	Delete a product. Its past artifacts stay, but new work can no longer target it.
artifacts.list	artifacts_list	GET /artifacts	strategy:run	read	low	none	cli, mcp	—	List agent artifacts (research briefs, drafts, reports) produced for this workspace.
listening.list	listening_list	GET /listening	strategy:run	read	low	none	cli, mcp	—	List captured listening mentions — places the product or its category was discussed.
listening.scan	listening_scan	POST /listening/scan	strategy:run	spend	low	none	cli, mcp	product_id, limit	Run a listening scan for new mentions of the product. Costs credits.
signals.scan	signals_scan	POST /signals/scan	strategy:run	internal_write	low	none	cli, mcp	query*, perSource	Search external sources for demand signals matching a query.
trends.list	trends_list	GET /trends?range={range}	none	read	low	none	cli, mcp	range	Read trending topics for the day or week to ground timely content.
opportunities.list	opportunities_list	GET /opportunities	strategy:run	read	low	none	cli, mcp	—	List scored growth opportunities derived from listening and signals.
opportunities.draft	opportunities_draft	POST /opportunities/{id}/draft	strategy:run	spend	low	none	cli, mcp	id*	Draft content for an opportunity. Costs credits; the draft still needs human approval to publish.
opportunities.queue	opportunities_queue	POST /opportunities/{id}/queue	queue:write	internal_write	low	none	cli, mcp	id*	Move an opportunity’s draft into the content queue as a pending item.
geo.status	geo_status	GET /geo	strategy:run	read	low	none	cli, mcp	—	Read current GEO (AI-citation) status: which AI answers mention the product.
geo.scan	geo_scan	POST /geo/scan	geo:run	spend	low	none	cli, mcp	product_id	Run a GEO scan to check whether AI assistants cite the product. Costs credits.
geo.checklist	geo_checklist	GET /geo/checklist	strategy:run	read	low	none	cli, mcp	—	Read the GEO readiness checklist (signal, status) plus which sources already cite the product.
geo.competitors	geo_competitors	GET /geo/competitors	strategy:run	read	low	none	cli, mcp	—	List competitor citation share and latest GEO visibility data.
geo.uncited	geo_uncited	GET /geo/uncited	strategy:run	read	low	none	cli, mcp	—	List high-value GEO queries where the product is not cited.
echo.mentions	echo_mentions	GET /echo/mentions	analytics:read	read	low	none	cli, mcp	—	List tracked brand and competitor mentions.
echo.scan	echo_scan	POST /echo/scan	strategy:run	spend	medium	approval	cli, mcp	—	Scan tracked sources for brand and competitor mentions.
listening.score	listening_score	— (local)	none	read	low	none	cli, mcp	mentions, threshold, brand_terms, category_terms	Score a mention feed for relevance, buying intent, and sentiment. Omit mentions to score the built-in demo. Local and read-only; nothing is sent or published.
listening.alert_preview	listening_alert_preview	— (local)	none	read	low	none	cli, mcp	kind	Preview the email and Slack payload for a spike or high-intent alert. Local and read-only; never sends notifications.
listening.listeners	listening_listeners	— (local)	none	read	low	none	cli, mcp	action, expression, negative, text, id, name	Boolean keyword listeners with negative keywords. Actions: list, add, remove, match.
listening.sov	listening_sov	— (local)	none	read	low	none	cli, mcp	mentions	Brand versus competitor mention counts for a weekly share-of-voice snapshot.
engage.high_intent_draft	engage_high_intent_draft	— (local)	none	read	low	none	cli, mcp	text, brand, source	Turn a high-intent mention into a Mitra reply draft for the approval queue. Returns the draft payload only. Nothing is sent.
geo.citations	geo_citations	— (local)	none	read	low	none	cli, mcp	mode, prompts, brand, competitors	Citation check for a saved prompt set. The demo uses fixtures for ChatGPT, Perplexity, and Gemini. Other engines are stubs. mode=live uses configured API keys and does not invent results.
geo.gap_draft	geo_gap_draft	— (local)	none	read	low	none	cli, mcp	query, brand, kind, missed_engines	Build an FAQ, schema JSON-LD, or short outline for a citation miss. The result is a draft. Nothing is published.
geo.prompts	geo_prompts	— (local)	none	read	low	none	cli, mcp	action, query, id, category, gsc_queries, active	Prompt library for a category, with optional question-shaped Search Console queries. Actions: list, seed, add, update, remove, scan. Scan uses fixtures unless you run a live GEO scan.
geo.crawler_audit	geo_crawler_audit	— (local)	none	read	low	none	cli, mcp	robots_txt	Report whether robots.txt allows GPTBot, ClaudeBot, PerplexityBot, and Google-Extended. Does not edit the file.
engage.reply_drafts	engage_reply_drafts	GET /engage/reply-drafts	queue:read	read	low	none	cli, mcp	—	List Mitra’s pending reply drafts — answers to new comments on your published posts and to negative brand mentions, waiting in the queue for approval.
engage.scan	engage_scan	POST /engage/scan	strategy:run	spend	medium	approval	cli, mcp	—	Run Mitra’s engagement sweep for your workspace: drafts replies to new comments on your published posts and answers negative brand mentions. Everything lands as queue drafts for approval — nothing posts.
voice.get	voice_get	GET /settings/voice	strategy:run	read	low	none	cli, mcp	—	Read canonical workspace brand voice.
voice.set	voice_set	PUT /settings/voice	settings:write	internal_write	medium	approval	cli, mcp	voice, guidelines, revision	Update canonical workspace brand voice with optimistic revision control.
audience.import	audience_import	POST /audience/import	workspace:write	internal_write	medium	approval	cli, mcp	csv*, consentSource*, source, enroll	Import subscribers from CSV with a required consent source.
recommendations.list	recommendations_list	GET /recommendations	strategy:run	read	low	none	cli, mcp	—	List the CMO’s current recommendations for the workspace.
recommendations.generate	recommendations_generate	POST /recommendations	strategy:run	internal_write	low	none	cli, mcp	—	Regenerate the recommendation set from the latest workspace data.
recommendations.decide	recommendations_decide	PATCH /recommendations/{id}	strategy:run	internal_write	low	none	cli, mcp	id*, action*	Accept or dismiss one recommendation. Accepting is what changes prioritization.
campaigns.list	campaigns_list	GET /campaigns	strategy:run	read	low	none	cli, mcp	—	List campaigns (multi-step marketing graphs) in the workspace.
campaigns.create	campaigns_create	POST /campaigns	campaigns:write	internal_write	low	none	cli, mcp	name*, graph	Create a campaign. Pass a node/edge graph to define its steps, or omit it for an empty draft.
campaigns.get	campaigns_get	GET /campaigns/{id}	strategy:run	read	low	none	cli, mcp	id*	Read one campaign including its full step graph.
campaigns.update	campaigns_update	PATCH /campaigns/{id}	campaigns:write	internal_write	low	none	cli, mcp	id*, name, status, graph	Update a campaign’s name, status (draft/active/archived), or step graph.
campaigns.archive	campaigns_archive	DELETE /campaigns/{id}	campaigns:write	delete	medium	approval	cli, mcp	id*	Delete a campaign.
workflows.start	workflows_start	POST /workflows/start	strategy:run	spend	low	none	cli, mcp	kind*, product_id*, limit, count	Start a background workflow (e.g. reddit_scan, hn_scan, content drafts) for a product. Costs credits.
workflows.execute	workflows_execute	POST /workflows/execute	strategy:run	spend	low	none	cli, mcp	workflowType*, input	Execute a named workflow synchronously with a small input map. Costs credits.
workflows.status	workflows_status	GET /workflows/{id}	strategy:run	read	low	none	cli, mcp	id*	Read a running workflow’s status and step results.
tasks.list	tasks_list	GET /tasks?status={status}&agent_id={agent_id}	strategy:run	read	low	none	cli, mcp	status, agent_id	List agent tasks, optionally filtered by status or agent.
tasks.create	tasks_create	POST /tasks	strategy:run	internal_write	low	none	cli, mcp	agent_id*, type*, input	Queue a task for one of the agents (scout, writer, publisher, engage, analyst).
tasks.get	tasks_get	GET /tasks/{id}	strategy:run	read	low	none	cli, mcp	id*	Read one task with its input, result, and error.
tasks.update	tasks_update	PATCH /tasks/{id}	strategy:run	internal_write	low	none	cli, mcp	id*, status, result, error	Update a task’s status, result, or error.
tasks.approve	tasks_approve	POST /tasks/{id}/approve	strategy:run	internal_write	medium	approval	cli, mcp	id*	Approve a task that is waiting for a human decision. Never approve your own work.
tasks.execute	tasks_execute	POST /tasks/{id}/execute	strategy:run	internal_write	medium	approval	cli, mcp	id*	Run an approved task now instead of waiting for the scheduler.
approvals.list	approvals_list	GET /approvals	queue:read	read	low	none	cli, mcp	—	List items waiting for a human approval decision.
approvals.approve	approvals_approve	POST /approvals/{id}/approve	publish	external_write	high	step_up	cli, mcp	id*	Record a human approval, which releases the item to publish. Agents must not call this on their own drafts.
approvals.reject	approvals_reject	POST /approvals/{id}/reject	queue:write	internal_write	medium	approval	cli, mcp	id*	Reject a pending approval so the item is never published.
launch.prepare	launch_prepare	POST /agents/launch	strategy:run	internal_write	low	none	cli, mcp	productId	Prepare launch assets (Product Hunt / Hacker News copy) for a product. Submission stays human-assisted.
listings.list	listings_list	GET /listings	strategy:run	read	low	none	cli, mcp	—	List directory launch listings (Product Hunt, Hacker News, directories) tracked for the workspace.
listings.create	listings_create	POST /listings	workspace:write	internal_write	low	none	cli, mcp	name*, url, status, notes	Track a new directory launch listing. Records intent only; submission stays human-assisted.
listings.update	listings_update	PATCH /listings/{id}	workspace:write	internal_write	low	none	cli, mcp	id*, name, url, status, notes	Update a tracked launch listing (status, URL, notes).
listings.archive	listings_archive	DELETE /listings/{id}	workspace:write	delete	medium	approval	cli, mcp	id*	Remove a tracked launch listing.
prospects.scan	prospects_scan	POST /prospect/scan	strategy:run	spend	low	none	cli, mcp	sources, keywords	Scan for prospects matching the workspace ICP. Costs credits.
inbox.list	inbox_list	GET /inbox	strategy:run	read	low	none	cli, mcp	—	List inbox conversations with prospects across email and DMs.
inbox.get	inbox_get	GET /inbox/{contactId}	strategy:run	read	low	none	cli, mcp	contactId*	Read one contact’s full inbox thread.
outreach.draft	outreach_draft	POST /inbox/send	outreach:write	internal_write	low	none	cli, mcp	contactId*, channel*, subject, body*	Draft an outreach message to a contact and queue it for human approval. Nothing is sent — approve and publish the queued item to actually deliver it.
crm.sync	crm_sync	POST /integrations/hubspot/sync	outreach:write	external_write	high	approval	cli, mcp	contactId	Push a contact to the connected HubSpot CRM. Writes to an external system, so it needs approval.
analytics.overview	analytics_overview	GET /analytics/overview?days=30	analytics:read	read	low	none	cli, mcp	days	Read aggregate performance over the last N days: totals per metric, per platform, and queue status.
analytics.attribution	analytics_attribution	GET /analytics/attribution	analytics:read	read	low	none	cli, mcp	—	Read attribution: which content and channels drove signups.
analytics.pagespeed	analytics_pagespeed	GET /analytics/pagespeed?url={url}	analytics:read	read	low	none	cli, mcp	url*	Run a PageSpeed check on a public url and return its performance scores.
analytics.report	analytics_report	GET /analytics/report?days=7	analytics:read	read	low	none	cli, mcp	days	Read the rolled-up performance report for the last N days (default 7).
analytics.benchmarks	analytics_benchmarks	GET /analytics/benchmarks?platform={platform}&days=30&industry={industry}&campaign_type={campaign_type}&objective={objective}&country={country}	analytics:read	read	low	none	cli, mcp	platform*, industry, campaign_type, objective, country, days	Read ad benchmarks (beta): your CTR/CPC/CPA against the anonymized pool for a platform, optionally narrowed by industry, campaign type, objective and country. Returns status not_enough_data, with no numbers, until the pool has enough real contributors.
feed.list	feed_list	GET /feed	strategy:run	read	low	none	cli, mcp	—	Read the agent activity feed — what the agents did and what needs attention.
feed.update	feed_update	PATCH /feed/{id}	strategy:run	internal_write	low	none	cli, mcp	id*	Mark one feed item as read or acted on.
ga4.pull	ga4_pull	GET /integrations/ga4	analytics:read	read	low	none	cli, mcp	—	Pull the latest metrics from the connected GA4 property.
github.repos	github_repos	GET /integrations/github/repos	connections:read	read	low	none	cli, mcp	—	List repos visible through the connected GitHub account, for shipping-log content.
connections.health	connections_health	GET /integrations/health	connections:read	read	low	none	cli, mcp	—	Check each connected platform’s token health before trying to publish.
agent_mode.get	agent_mode_get	GET /settings/agent-mode	strategy:run	read	low	none	ui, cli, mcp	—	Read the publishing mode (approve or autonomous) plus any per-agent overrides.
agent_mode.set	agent_mode_set	PUT /settings/agent-mode	settings:write	internal_write	high	step_up	ui, cli, mcp	global_mode, orchestrate_enabled, overrides	Change the publishing mode. Switching to autonomous removes the human approval gate, so it needs a human.
email_prefs.get	email_prefs_get	GET /settings/email-preferences	strategy:run	read	low	none	cli, mcp	—	Read the account email preferences: onboarding emails and the daily brief.
email_prefs.set	email_prefs_set	PUT /settings/email-preferences	settings:write	internal_write	medium	step_up	cli, mcp	onboarding_enabled, brief_enabled	Change account email preferences. Agents may only opt OUT (false); opting in is consent and needs a human in the dashboard.
billing.status	billing_status	GET /billing/status	billing:read	read	low	none	cli, mcp	—	Read the active plan, credit balance, and renewal date.
me.get	me_get	GET /me	billing:read	read	low	none	cli, mcp	—	Read the authenticated identity: user id, token type, and granted scopes.
audience.list	audience_list	GET /audience?status={status}&segment={segment}	strategy:run	read	low	none	cli, mcp	status, segment	List the email marketing audience for the workspace, with status and segment filters.
audience.create	audience_create	POST /audience	workspace:write	internal_write	low	none	cli, mcp	email*, consentSource, source, segments	Add one subscriber to the email audience. A consent source is recorded for compliance (defaults to manual).
brief.get	brief_get	GET /brief	queue:read	read	low	none	cli, mcp	—	Read the most recent stored daily brief: yesterday’s shipped items, engagement, pending actions, and alerts.
creative.plan	creative_plan	POST /creative/runs	creative:run	spend	medium	approval	ui, cli, mcp	mode, prompt, productUrl, productName, productId, feature, aspect	Derive a video storyboard: a launch video from productUrl (screen capture), or with mode “motion” a motion-graphics video from a prompt. Creates an approval; does not render or publish.
creative.render	creative_render	POST /creative/runs/{runId}/render	creative:run	spend	medium	approval	ui, cli, mcp	runId*	Start rendering an approved storyboard. Heavy work runs on the media worker.
creative.status	creative_status	GET /creative/runs/{runId}	creative:read	read	low	none	ui, cli, mcp	runId*	Read a creative run, its stages, and signed preview URLs.
creative.review	creative_review	GET /creative/runs/{runId}/review	creative:read	read	low	none	ui, cli, mcp	runId*	Read the storyboard awaiting approval for a run.
creative.assets	creative_assets	GET /creative/runs/{runId}/assets	creative:read	read	low	none	ui, cli, mcp	runId*	List signed output assets for a completed creative run.
creative.cancel	creative_cancel	POST /creative/runs/{runId}/cancel	creative:run	internal_write	low	none	ui, cli, mcp	runId*	Cancel a creative run and refund unstarted stages.
creative.queue	creative_queue	POST /creative/runs/{runId}/queue	queue:write	internal_write	medium	approval	ui, cli, mcp	runId*, platforms	Create content_queue drafts from a completed creative run. Does not publish.
creative.models	creative_models	GET /creative/models	creative:read	read	low	none	ui, cli, mcp	—	List the active Creative Studio generation models with their credit cost per billing unit.
creative.generate	creative_generate	POST /creative/generate	creative:run	spend	medium	approval	ui, cli, mcp	prompt*, modelId*, kind, mode, duration, imageUrl, videoUrl, referenceUrls, targetPlatform, audio, slides, aspectRatio	Generate a Creative Studio image, video or carousel (pass slides 2-6 for a carousel — one render per slide, poll creative_job to see slides land). Debits credits and drafts the result into the content queue for approval; never publishes.
ugc.batch	ugc_batch	POST /ugc/batch	creative:run	spend	high	approval	ui, cli, mcp	modelId*, count*, durationSec, aspect, productId, productUrl, formats, targetPlatform, audio, consent*, batchId	Generate a batch of UGC-style creator ad videos — one keyed job per deterministic hook angle. Whole-batch quota is reserved before any spend; per-angle failures return as data. Results land in the review gallery; never publishes.
ugc.batch_preflight	ugc_batch_preflight	GET /ugc/batch/preflight?modelId={modelId}&count={count}&durationSec={durationSec}&productId={productId}&productUrl={productUrl}&platforms={platforms}&consent={consent}	creative:read	read	low	none	ui, cli, mcp	modelId, count, durationSec, productId, productUrl, platforms, consent	Read-only readiness check for a UGC batch: engine key, model, quota, credits, consent, product context and platform connections. Returns fixable blockers plus the server-computed credit total.
ugc.performance	ugc_performance	GET /ugc/performance	analytics:read	read	low	none	ui, cli, mcp	—	Rank UGC batch hook angles by attributed revenue (GA4 first-touch). Hooks without pulled metrics report null — never a fabricated zero.
ugc.scale	ugc_scale	POST /ugc/scale	campaigns:write	external_write	high	approval	cli, mcp	hookId, jobId, platform*, dailyBudget, destinationUrl, dryRun, proposal	Hand a proven UGC hook to the paid lane — resolves the winning video and creates an ads.launch (creative_url = the video). Lands pending_approval or paused exactly like any launch.
creative.gallery	creative_gallery	GET /creative/gallery?kind={kind}&status={status}&cursor={cursor}&limit={limit}	creative:read	read	low	none	ui, cli, mcp	kind, status, cursor, limit	List Creative Studio generation jobs with signed output URLs, newest first.
creative.job	creative_job	GET /creative/jobs/{jobId}	creative:read	read	low	none	ui, cli, mcp	jobId*	Read one Creative Studio generation job and its signed output URL. Carousels list per-slide media_urls, filling toward slides while rendering.
creative.abort	creative_abort	POST /creative/jobs/{jobId}/abort	creative:run	internal_write	low	none	ui, cli, mcp	jobId*	Abort an in-flight Creative Studio generation job; credits are refunded when the provider had not yet spent them.
creative.revise	creative_revise	POST /creative/runs/{runId}/revise	creative:run	spend	medium	approval	ui, cli, mcp	runId*, note	Open a new storyboard revision that supersedes a previous run. Does not render or publish.
creative.variants	creative_variants	POST /creative/runs/{runId}/variants	creative:run	spend	medium	approval	ui, cli, mcp	runId*, sceneId*, count	Create up to 5 A/B copy variants of one motion scene as sibling runs, each needing its own approval. Does not render or publish.
creative.compositions_get	creative_compositions_get	GET /creative/runs/{runId}/compositions	creative:read	read	low	none	cli, mcp	runId*	Read the latest motion composition (template, variables, version) for each scene of a creative run.
creative.compositions_set	creative_compositions_set	POST /creative/runs/{runId}/compositions	creative:run	spend	medium	approval	cli, mcp	runId*, sceneId*, templateId, variables, mode, engine, instruction	Edit one motion scene: set template variables, or mode=freeform with an engine and instruction (LLM-written code, billed). Writes a new version and a fresh storyboard approval; nothing renders until a human approves.
creative.storyboard_edit	creative_storyboard_edit	POST /creative/runs/{runId}/storyboard	creative:run	internal_write	medium	approval	cli, mcp	runId*, ops*	Edit a run’s timeline with 1-20 ordered ops: reorder, trim, remove, add_upload, add_template. Free; the result needs a fresh storyboard approval before it renders.
scheduled_tasks.list	scheduled_tasks_list	GET /scheduled-tasks	queue:read	read	low	none	cli, mcp	—	List scheduled tasks (recurring agent prompts) and their recent runs.
scheduled_tasks.create	scheduled_tasks_create	POST /scheduled-tasks	workspace:write	internal_write	medium	approval	cli, mcp	title*, prompt, cadence, kind, product_id	Create a scheduled task: a prompt the agent runs on a cadence. Each run spends credits unattended.
scheduled_tasks.update	scheduled_tasks_update	PATCH /scheduled-tasks/{id}	workspace:write	internal_write	medium	approval	cli, mcp	id*, title, prompt, cadence, status	Update a scheduled task’s title, prompt, cadence or status (pause/resume).
scheduled_tasks.delete	scheduled_tasks_delete	DELETE /scheduled-tasks/{id}	workspace:write	delete	medium	approval	cli, mcp	id*	Permanently delete a scheduled task.
scheduled_tasks.run	scheduled_tasks_run	POST /scheduled-tasks/{id}/run	workspace:write	spend	medium	approval	cli, mcp	id*	Run a scheduled task now. Spends credits; does not move its schedule.
strategy.docs_get	strategy_docs_get	GET /strategy-docs?product_id={product_id}	strategy:run	read	low	none	cli, mcp	product_id	Read the saved strategy documents and plan for a product (defaults to the primary product).
strategy.docs_save	strategy_docs_save	POST /strategy-docs	strategy:run	spend	medium	approval	cli, mcp	product_id	Generate the strategy documents for a product and save them. Spends credits.
adlib.search	adlib_search	POST /command/chat	discovery:run	spend	low	approval	chat, cli, mcp	query, platforms, country, limit	Agni AdKit: Collect competitor ads from the public ad libraries (Meta/Google/LinkedIn/TikTok/X) for a query, persist them, and return the scored page. Costs ad_library_scan credits; a live scan can take 15-40s. Proposes a command plan; execute only after human approval.
adlib.browse	adlib_browse	GET /ad-library?q={q}&platform={platform}&competitor={competitor}&tier={tier}&board={board}&sort={sort}&limit={limit}&offset={offset}&min_runtime_days={min_runtime_days}&min_score={min_score}&saved_only=1&active_only=1	discovery:read	read	low	none	chat, cli, mcp	q, platform, competitor, tier, board, saved_only, min_runtime_days, min_score, active_only, sort, limit, offset	Agni AdKit: Browse ads already stored in the workspace’s ad library. Sort by score for Ad Score (beta). Tiers are high_conf | winner | emerging | loser.
adlib.get_ad	adlib_get_ad	GET /ad-library/{ad_id}	discovery:read	read	low	none	chat, cli, mcp	ad_id*	Agni AdKit: Read one stored ad by its ad_id.
adlib.get_score	adlib_get_score	GET /ad-library/{ad_id}/score	discovery:read	read	low	none	chat, cli, mcp	ad_id*	Agni AdKit: Read Ad Score (beta) for one ad: overall 0-100 plus a transparent breakdown (run duration, variants, creative reuse, still active).
adlib.list_assets	adlib_list_assets	GET /ad-library/assets	discovery:read	read	low	none	chat, cli, mcp	min_reuse, limit	Agni AdKit: List creative assets in the workspace ranked by reuse count (how many ads share the same primary creative).
adlib.saved	adlib_saved	GET /ad-library/saved?board={board}&platform={platform}&media_type={media_type}&delivery_status={delivery_status}	discovery:read	read	low	none	chat, cli, mcp	board, limit, platform, media_type, delivery_status, min_spend, max_spend	Agni AdKit: List saved ads with per-board counts and swipe-file filters.
adlib.boards	adlib_boards	GET /ad-library/boards	discovery:read	read	low	none	chat, cli, mcp	—	Agni AdKit: List swipe-file boards with save counts and public-share metadata.
adlib.create_board	adlib_create_board	POST /command/chat	discovery:run	internal_write	low	approval	chat, cli, mcp	name*	Agni AdKit: Create a named swipe-file board. Proposes a command plan; execute only after human approval.
adlib.set_board_public	adlib_set_board_public	POST /command/chat	discovery:run	internal_write	low	approval	chat, cli, mcp	board*, is_public*	Agni AdKit: Enable or disable a read-only public link for a swipe-file board. Proposes a command plan; execute only after human approval.
adlib.save_ad	adlib_save_ad	POST /command/chat	discovery:run	internal_write	low	approval	chat, cli, mcp	ad_id*, board, note	Agni AdKit: Save an ad to a swipe-file board (Unsorted when omitted). Proposes a command plan; execute only after human approval.
adlib.unsave_ad	adlib_unsave_ad	POST /command/chat	discovery:run	internal_write	low	approval	chat, cli, mcp	ad_id*, board	Agni AdKit: Remove an ad from a board (default board when omitted). Proposes a command plan; execute only after human approval.
adlib.alerts	adlib_alerts	GET /ad-library/alerts?unread_only=true	discovery:read	read	low	none	chat, cli, mcp	unread_only, limit	Agni AdKit: Competitor ads seen for the first time — the launch-alert feed.
adlib.ack_alerts	adlib_ack_alerts	POST /command/chat	discovery:run	internal_write	low	approval	chat, cli, mcp	ad_ids	Agni AdKit: Mark launch alerts read. Omit ad_ids to acknowledge everything unread. Proposes a command plan; execute only after human approval.
adlib.competitors	adlib_competitors	GET /ad-library/competitors?product_id={product_id}	discovery:read	read	low	none	chat, cli, mcp	product_id	Agni AdKit: List the competitor watchlist merged with advertisers already seen in the library.
adlib.track_competitor	adlib_track_competitor	POST /command/chat	discovery:run	internal_write	low	approval	chat, cli, mcp	name*, platform, domain, product_id	Agni AdKit: Add a competitor name to the watchlist (idempotent). Proposes a command plan; execute only after human approval.
adlib.untrack_competitor	adlib_untrack_competitor	POST /command/chat	discovery:run	internal_write	low	approval	chat, cli, mcp	name*, product_id	Agni AdKit: Remove a competitor from the watchlist. Proposes a command plan; execute only after human approval.
adlib.sync_competitor	adlib_sync_competitor	POST /command/chat	discovery:run	spend	low	approval	chat, cli, mcp	name*, platform, domain, country, limit	Agni AdKit: Track a competitor and refresh-pull its live ads now. Costs ad_library_scan credits; new ads raise alerts. Proposes a command plan; execute only after human approval.
adlib.clone	adlib_clone	POST /command/chat	discovery:run	internal_write	low	approval	chat, cli, mcp	ad_id*, generate, variants, aspect_ratio	Agni AdKit: Remix an ad’s hook into 3 deterministic variants for your own creatives. Proposes a command plan; execute only after human approval.
ads.launch	ads_launch	POST /command/chat	campaigns:write	external_write	high	approval	chat, cli, mcp	platform*, account_id, ad_id, name, hook, body, cta, creative_url, persona, daily_budget, draft_copy, dry_run	Agni AdKit: Plan (dry_run=true, default) or execute an ad launch. Execution is policy-gated: winner score >= 60 creates a paused campaign draft, below that it lands pending_approval for human sign-off — nothing ever goes live directly. Proposes a command plan; execute only after human approval.
ads.launches	ads_launches	GET /ads/launches?status={status}	analytics:read	read	low	none	chat, cli, mcp	status, limit	Agni AdKit: List launched/paused/pending ad campaigns in the workspace.
ads.get	ads_get	GET /ads/launches/{id}	analytics:read	read	low	none	chat, cli, mcp	id*	Agni AdKit: Read one ad launch by id.
ads.manage	ads_manage	POST /command/chat	campaigns:write	external_write	high	approval	chat, cli, mcp	id*, action, daily_budget	Agni AdKit: Manage one launch: action approve|activate|pause|archive (approve pending_approval -> paused; activate paused -> active; pause active -> paused; archive any -> archived) and/or set daily_budget. Proposes a command plan; execute only after human approval.
ads.performance	ads_performance	GET /ads/launches/{id}/performance	analytics:read	read	low	none	chat, cli, mcp	id*	Agni AdKit: Performance for one launch: spend, impressions, clicks, conversions, CTR, CPA, ROAS. synced:false + zeros until a platform metrics sync has written data.
autopilot.status	autopilot_status	GET /autopilot/status	autopilot:read	read	low	none	cli, mcp	—	Autopilot rollup: active loops, cycles run, pending proposals, learnings this week, plus every loop’s last-run state.
autopilot.learnings	autopilot_learnings	GET /autopilot/learnings?channel={channel}&kind={kind}&limit={limit}	autopilot:read	read	low	none	cli, mcp	channel, kind, limit	The readable learning files the loops append to each run — winner/miss/audit/digest lessons per channel with the rows that earned them.
autopilot.run	autopilot_run	POST /autopilot/run	autopilot:run	internal_write	low	none	cli, mcp	loop	Run one autopilot cycle now (or the weekly audit with loop=audit). Deterministic — grades signals, writes learnings, proposes actions. No credits; proposals still need approval.
autopilot.actions	autopilot_actions	GET /autopilot/actions?status={status}	autopilot:read	read	low	none	cli, mcp	status	List autopilot proposals — pending ones awaiting a decision, or applied/dismissed history.
autopilot.decide	autopilot_decide	POST /autopilot/actions	autopilot:write	external_write	high	approval	cli, mcp	id*, decision*	Decide one autopilot proposal: apply executes it (scale budget / pause launch / pause loop), dismiss closes it without side effects.
advocacy.list	advocates_list	GET /advocates?status={status}	advocacy:read	read	low	none	cli, mcp	status	Advocate leaderboard: repeat positive engagers scored on reach(momentum), loyalty, content and amplification, tiered micro_influencer/loyal_customer/ugc_creator/advocate.
advocacy.outreach	advocates_outreach	GET /advocates/{id}/outreach	advocacy:read	read	low	none	cli, mcp	id*	Ready-to-send DM template for one advocate, worded per tier (micro-influencer affiliate offer, loyal-customer early access, UGC feature request).
advocacy.set_status	advocates_set_status	PATCH /advocates	advocacy:write	internal_write	low	none	cli, mcp	id*, status*	Mark an advocate contacted / partner / dismissed once you’ve reached out.
sentiment.series	sentiment_series	GET /sentiment?days={days}	sentiment:read	read	low	none	cli, mcp	days	Daily per-platform sentiment rollup (positive/neutral/negative %) plus live anomalies vs the 7-day baseline — the crisis early-warning feed.
adlib.top_spend	adlib_top_spend	POST /command/chat	discovery:read	read	low	none	chat, cli, mcp	competitor, platform, min_score, limit	Agni AdKit: Find top stored ads ranked by estimated library spend; missing spend stays unknown.
adlib.weekly_digest	adlib_weekly_digest	POST /command/chat	discovery:read	read	low	none	chat, cli, mcp	—	Agni AdKit: Read the last seven days of competitor ad activity without sending email.
adlib.monitoring	adlib_monitoring	POST /command/chat	discovery:read	read	low	none	chat, cli, mcp	—	Agni AdKit: Read weekly digest and monitoring preferences.
adlib.set_digest	adlib_set_digest	POST /command/chat	discovery:run	internal_write	low	approval	chat, cli, mcp	weekly_digest_enabled*	Agni AdKit: Enable or disable the existing weekly competitor digest. Proposes a command plan; execute only after human approval.
adlib.create_alert_rule	adlib_create_alert_rule	POST /command/chat	discovery:run	internal_write	low	approval	chat, cli, mcp	kind*, competitor_name, min_score	Agni AdKit: Create a competitor, new-ad, or score-threshold monitoring rule. Proposes a command plan; execute only after human approval.
ads.benchmarks	ads_benchmarks	POST /command/chat	analytics:read	read	low	none	chat, cli, mcp	platform, industry, campaign_type, objective, country, days	Agni AdKit: Read anonymized ad benchmarks with the existing contributor privacy floor.
ads.report	ads_report	POST /command/chat	analytics:read	read	low	none	chat, cli, mcp	days	Agni AdKit: Read ad spend and performance by platform and project.

Scopes

Scope	Capabilities
advocacy:read	advocacy.list, advocacy.outreach
advocacy:write	advocacy.set_status
analytics:read	echo.mentions, analytics.overview, analytics.attribution, analytics.pagespeed, analytics.report, analytics.benchmarks, ga4.pull, ugc.performance, ads.launches, ads.get, ads.performance, ads.benchmarks, ads.report
autopilot:read	autopilot.status, autopilot.learnings, autopilot.actions
autopilot:run	autopilot.run
autopilot:write	autopilot.decide
billing:read	billing.status, me.get
campaigns:write	campaigns.create, campaigns.update, campaigns.archive, ugc.scale, ads.launch, ads.manage
connections:read	connections.list, reddit.status, github.repos, connections.health
creative:read	creative.status, creative.review, creative.assets, creative.models, ugc.batch_preflight, creative.gallery, creative.job, creative.compositions_get
creative:run	creative.plan, creative.render, creative.cancel, creative.generate, ugc.batch, creative.abort, creative.revise, creative.variants, creative.compositions_set, creative.storyboard_edit
discovery:read	adlib.browse, adlib.get_ad, adlib.get_score, adlib.list_assets, adlib.saved, adlib.boards, adlib.alerts, adlib.competitors, adlib.top_spend, adlib.weekly_digest, adlib.monitoring
discovery:run	adlib.search, adlib.create_board, adlib.set_board_public, adlib.save_ad, adlib.unsave_ad, adlib.ack_alerts, adlib.track_competitor, adlib.untrack_competitor, adlib.sync_competitor, adlib.clone, adlib.set_digest, adlib.create_alert_rule
geo:run	geo.scan
outreach:write	outreach.draft, crm.sync
publish	queue.publish, approvals.approve
queue:read	queue.list, queue.get, queue.best_time, engage.reply_drafts, approvals.list, brief.get, scheduled_tasks.list
queue:write	queue.delete, queue.update, queue.approve, queue.reject, queue.schedule, queue.proof, opportunities.queue, approvals.reject, creative.queue
sentiment:read	sentiment.series
settings:write	voice.set, agent_mode.set, email_prefs.set
strategy:run	strategy.run, scout.research, writer.generate, agents.list, agents.status, agents.run, reddit.warmup, command.chat, command.sessions, command.run, command.status, command.approve_step, workspace.context, workspace.get, products.list, artifacts.list, listening.list, listening.scan, signals.scan, opportunities.list, opportunities.draft, geo.status, geo.checklist, geo.competitors, geo.uncited, echo.scan, engage.scan, voice.get, recommendations.list, recommendations.generate, recommendations.decide, campaigns.list, campaigns.get, workflows.start, workflows.execute, workflows.status, tasks.list, tasks.create, tasks.get, tasks.update, tasks.approve, tasks.execute, launch.prepare, listings.list, prospects.scan, inbox.list, inbox.get, feed.list, feed.update, agent_mode.get, email_prefs.get, audience.list, strategy.docs_get, strategy.docs_save
workspace:write	products.create, products.update, products.archive, audience.import, listings.create, listings.update, listings.archive, audience.create, scheduled_tasks.create, scheduled_tasks.update, scheduled_tasks.delete, scheduled_tasks.run

User tokens (aicmo_usr_…, from aicmo login) carry all scopes. Agent tokens (aicmo_agt_…, from aicmo token create) carry an explicit subset. Capabilities with scope none are local and need no token.

Agent tokens currently reach only the native /api/v1/* handlers (queue, connections, workspace context, me), where withAuth enforces the declared scope. Capabilities served by a legacy /api/* route through the /api/v1 rewrite need a user token: those routes declare no scope, so a scoped agent token cannot be checked against one and is refused rather than silently granted everything. Declaring scopes on those handlers is what lifts the restriction.

Surfaces

chat capabilities are also AI CMO runtime tools under the same id. Every capability with an HTTP transport is reachable from the CLI as aicmo run <capability.id> '<json>' (run aicmo run with no id to list them); hand-written commands like aicmo queue approve are ergonomic aliases over the same registry entries.

Error envelope (all surfaces)

{ "error": { "code": "stable_snake_case", "message": "human readable", "status": 409, "retryable": false } }

MCP wraps it as { isError: true, content: [{ type: "text", text: "<that JSON>" }] }. Codes you will see: missing_auth_token, invalid_arguments, unknown_tool, untrusted_auth_override, untrusted_api_base_url, invalid_api_response, http_<status>, plus server codes such as reddit_not_connected, publish_not_approved, insufficient_credits, assisted_publish.

Live discovery endpoint: GET https://app.aicmohq.com/api/v1/capabilities.