Developer
API and MCP documentation
Connect an AI assistant to AdVizion with MCP, or call the same operations over HTTP. Both use your AdVizion account and see only the campaigns you can already open. A RUN, FIX, or REJECT recommendation is not approval to publish.
Connect an AI assistant (MCP)
AdVizion runs a remote MCP server. Add this address to your assistant, sign in to AdVizion when it asks, and click Allow.
https://www.advizion.ai/mcpUse the address exactly as shown, including www. It speaks Streamable HTTP. Opening it in a browser shows a status page instead.
Then ask things like “List my AdVizion projects” or “Analyze the latest creative in my Spring launch project and tell me RUN, FIX, or REJECT.”
Claude (web, desktop, and mobile)
- Open Customize, Connectors and click Add custom connector.
- Name it AdVizion and enter the server address above. Keep the recommended sign-in options, then click Add.
- Click Connect, sign in to AdVizion, and click Allow.
On Team and Enterprise plans an Owner adds the connector once in Organization settings, Connectors (Add, Custom, Web). Each member then clicks Connect.
ChatGPT
- In Settings, Apps, Advanced settings, turn on Developer mode.
- In Settings, Apps, click Create. Name it AdVizion, enter the server address, and choose OAuth.
- Click Scan Tools, sign in to AdVizion, click Allow, then Create.
OpenAI offers custom MCP apps with every tool on ChatGPT Business, Enterprise, and Edu. A workspace admin may need to enable developer mode first.
Cursor
Add this to ~/.cursor/mcp.json, or to .cursor/mcp.json in one campaign:
{
"mcpServers": {
"advizion": {
"url": "https://www.advizion.ai/mcp"
}
}
}In Cursor Settings, Tools & MCP, click Needs login next to advizion, sign in, and click Allow.
Claude Code
claude mcp add --transport http advizion https://www.advizion.ai/mcpThen run /mcp in Claude Code, choose advizion, and pick Authenticate.
VS Code (GitHub Copilot agent mode)
Add this to .vscode/mcp.json:
{
"servers": {
"advizion": {
"type": "http",
"url": "https://www.advizion.ai/mcp"
}
}
}Click Start above the entry and sign in when VS Code asks.
Gemini CLI
Add this to ~/.gemini/settings.json:
{
"mcpServers": {
"advizion": {
"httpUrl": "https://www.advizion.ai/mcp"
}
}
}Then run /mcp auth advizion.
Other assistants
Any client that supports remote MCP servers over Streamable HTTP with OAuth works with the same address. A client that cannot sign in can send an API key instead, as shown in the next section.
Sign-in and permissions
Signing in from an assistant
Your assistant opens an AdVizion page that names the app, shows where you will return, and lists what it can do. Access lasts an hour and renews automatically for 30 days. To disconnect an app, open Account, API, Connected apps. Its access stops right away.
| Permission | What it allows |
|---|---|
advizion.read | Read campaigns, creatives, brand rulebooks, and analysis results. |
advizion.analyze | Quote and start analyses and governance checks. An analysis uses credits. |
No app can buy credits, generate ads, publish campaigns, approve a creative, or delete anything through AdVizion MCP or this API. An app you grant the separate advizion.campaigns.manage permission can approve or dismiss the actions AdVizion suggests on your live campaigns, such as pausing an ad that missed its target, and choose whether a missed target asks you first or pauses on its own (spend limits always pause at once). It only approves what AdVizion proposed within your saved limits; it never launches ads or chooses amounts.
Using an API key instead
Scripts and assistants without OAuth can send a key as Authorization: Bearer advz_… or x-api-key: advz_…. A full-access key can read and analyze. A read-only key can read. Keys are available on eligible Premium and Enterprise plans; see Your API key. Keep the key in an environment variable, not in a file you share.
{
"mcpServers": {
"advizion": {
"url": "https://www.advizion.ai/mcp",
"headers": {
"Authorization": "Bearer ${env:ADVIZION_API_KEY}"
}
}
}
}claude mcp add --transport http advizion https://www.advizion.ai/mcp \
--header "Authorization: Bearer $ADVIZION_API_KEY"For client developers
- Protected resource metadata: https://www.advizion.ai/.well-known/oauth-protected-resource
- Authorization server metadata: https://www.advizion.ai/.well-known/oauth-authorization-server
- Authorization code with PKCE (S256), the
resourceparameter, andisson every authorization response. - Clients register with dynamic client registration or a Client ID Metadata Document. Every client is public.
- Redirects can be https, loopback http on any port, or the app's own URL scheme.
- A request without a valid token gets HTTP 401 with a
WWW-Authenticateheader that points at the metadata.
Tools
A typical session runs list_projects, list_creatives, quote_analysis, start_analysis, then get_analysis_status until the verdict is ready. Read the evidence with get_analysis_report, hand a client the full Decision Report as a PDF with get_report_pdf, and use submit_for_review to put the recommendation in front of a person: only a person approves.
get_profilereadReturn the AdVizion account connected to this client.
list_projectsreadList projects this account can open: its own and those a teammate shared with it (access and role say which). Start here to get a project_id.
get_project_contextreadReturn the campaign objective, audience, and applicable rulebooks for one accessible project.
list_creativesreadList the creatives saved in a project with their latest version id and, when that version was already analysed, its newest stored verdict, latest_report_id and latest_review_id. Read or compare an existing report with get_analysis_report or compare_creatives before paying for a new analysis. Use latest_version_id as creative_version_id when quoting or starting an analysis.
quote_analysisanalyzeReport the credit cost of analyzing one image, video, or audio creative. This does not start work. With a creative_version_id, an earlier identical analysis is reused at no cost.
start_analysisanalyzeStart a real AdVizion analysis of one saved creative version and return the review id. It spends credits, never more than max_credits; call quote_analysis first. Reusing the same idempotency_key returns the same review. Poll get_analysis_status for the RUN, FIX, or REJECT verdict. A verdict is not human approval.
get_analysis_statusreadReturn the status of an analysis this account can see, and each item's RUN, FIX, or REJECT verdict once its Decision Report exists. Read the full report with get_analysis_report.
get_analysis_reportreadReturn one stored Decision Report: the RUN, FIX, or REJECT verdict, why, the evidence-anchored findings, placements, governance status, approval state, and a link to open it in AdVizion. Use the decision_report_id from get_analysis_status or latest_report_id from list_creatives. Attention values are model predictions, not eye tracking.
get_report_pdfreadBuild the complete Decision Report as a client-ready PDF: the verdict and why, the three actions, clearance, video keyframes or the image with attention overlays, every measured signal, product and competitor intelligence, placement fit, the action plan, AdVizion's signal suite and the evidence appendix. Returns a download link that works without signing in for 15 minutes. Set include_file to also receive the PDF itself as an embedded file. detail=summary gives the one-page brief instead.
submit_for_reviewanalyzeSave a Decision Report's recommendation into AdVizion's approval workflow so a person approves or requests changes. It moves a draft (or a report sent back for changes) to waiting for review; calling it again changes nothing. It never approves, rejects, or publishes.
get_brand_rulebookreadList the rulebooks that apply to a project, including status and version.
run_governance_checkanalyzeCheck a project, or one creative version in it, against one active rulebook. The verdict is automated. It is not legal clearance.
list_campaignsreadList campaigns this account can open (the same ids as list_projects). Start here to get a campaign_id.
get_campaign_contextreadReturn the objective, audience, market and applicable rulebooks for one campaign.
get_campaign_planreadWhere, when, and how & how much to run a reviewed ad: three decisions with reasons, sources and a confidence level (evidence support, never a promise of results). Reading never builds a plan.
replan_campaignanalyzeAsk for a fresh Campaign Plan for a report (free, a few per campaign per day). It takes about a minute; read it with get_campaign_plan.
get_market_briefreadThe dated, sourced market research behind a report's Campaign Plan: season, news, competitors and the calendar.
list_guard_proposalsreadActions AdVizion suggests on live Google Ads and Meta campaigns (such as pausing an ad that missed its target) that wait for the owner's OK.
approve_guard_proposalmanageApprove one action AdVizion suggested on a live campaign, for the account owner. It only approves AdVizion's own proposal; it never sets amounts or launches anything. Needs the advizion.campaigns.manage permission.
dismiss_guard_proposalmanageDismiss one suggested action and keep the campaign as it is. Needs the advizion.campaigns.manage permission.
set_guard_modemanageFor a launch AdVizion already protects, choose what happens when it misses the owner's target: ask_first (a one-click proposal) or pause_on_its_own. Spend limits always pause at once. It never changes targets or budgets and never runs a campaign. Needs the advizion.campaigns.manage permission.
compare_creativesreadCompare two stored Decision Report verdicts for a stated objective. This does not invent a new score.
REST API
The same operations over HTTP, with the same sign-in. Base URL:
https://www.advizion.ai/api/public/v1- GET
/meWho is connected - GET
/projectsFind projects - GET
/projects/{project_id}Read project context - GET
/projects/{project_id}/creativesList creatives - POST
/analyses/quoteQuote an analysis - POST
/analysesStart analysis - GET
/analyses/{review_id}Analysis status - GET
/reports/{report_id}Read the Decision Report - GET
/reports/{report_id}/pdfDecision Report PDF - POST
/reports/{report_id}/review-requestsSend for human review - GET
/projects/{project_id}/rulebooksBrand rulebook - POST
/projects/{project_id}/governanceRun governance - GET
/campaignsFind campaigns - GET
/campaigns/{campaign_id}Read campaign context - GET
/reports/{report_id}/campaign-planRead the Campaign Plan - POST
/reports/{report_id}/campaign-planUpdate the Campaign Plan - GET
/reports/{report_id}/market-briefRead the market brief - GET
/guard/proposalsActions waiting for OK - POST
/guard/proposals/{proposal_id}/approveApprove a suggested action - POST
/guard/proposals/{proposal_id}/dismissDismiss a suggested action - PUT
/guard/launches/{deploy_id}/modeAsk first or pause on its own - POST
/projects/{project_id}/comparisonsCompare stored verdicts
Request and response shapes are in the OpenAPI file.
curl https://www.advizion.ai/api/public/v1/campaigns \
-H "Authorization: Bearer $ADVIZION_API_KEY"curl -X POST https://www.advizion.ai/api/public/v1/analyses \
-H "Authorization: Bearer $ADVIZION_API_KEY" \
-H "Content-Type: application/json" \
-d '{"project_id": "PROJECT_ID", "creative_version_id": "VERSION_ID",
"media_type": "image", "idempotency_key": "spring-hero-v3-0001", "max_credits": 10}'Webhooks
Instead of asking AdVizion again and again, your app can register an address and AdVizion sends it a signed message when something happens. Events carry ids and links only; read the details through the API with your app's own permissions.
review.completedA check finished. Includes the report id and the RUN, FIX or REJECT verdict.campaign_plan.readyThe Campaign Plan for a report is ready: where, when, and how and how much to run the ad.guard.proposal.createdCampaign Guard asks the owner to approve an action on a live campaign, such as pausing an ad that missed its target.guard.action.executedCampaign Guard paused or changed a live campaign, at a hard limit the owner set or after the owner approved.
Register an address
The reply contains a signing secret (whsec_...). It is shown once, so store it right away. Leave out events to receive all four. GET /webhooks lists your app's addresses, DELETE /webhooks/{id} stops one, and POST /webhooks/{id}/test sends a test event.
curl -X POST https://www.advizion.ai/api/public/v1/webhooks \
-H "Authorization: Bearer $ADVIZION_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url": "https://example.com/advizion-events",
"events": ["campaign_plan.ready", "guard.proposal.created"]}'What arrives
{
"id": "evt_5d1c0f9e...",
"type": "campaign_plan.ready",
"created": 1795075200,
"api_version": "2026-11-18",
"data": {
"plan_id": "REPORT_ID:1",
"report_id": "REPORT_ID",
"campaign_id": "CAMPAIGN_ID",
"revision": 1,
"gated_by_verdict": false,
"link": "https://www.advizion.ai/app/decision-reports/REPORT_ID"
}
}Check that it came from AdVizion
Every message has an AdVizion-Signature header: t= the time in Unix seconds and v1= an HMAC-SHA256 of t, a dot and the raw body, keyed with your secret. Refuse messages whose signature does not match or whose time is more than five minutes off.
import crypto from "node:crypto";
// rawBody: the exact request body as a string. secret: the whsec_... value from registration.
export function isFromAdvizion(rawBody, signatureHeader, secret) {
const parts = Object.fromEntries(signatureHeader.split(",").map((part) => part.split("=")));
if (!parts.t || !parts.v1 || Math.abs(Date.now() / 1000 - Number(parts.t)) > 300) return false;
const expected = crypto.createHmac("sha256", secret).update(`${parts.t}.${rawBody}`).digest("hex");
return expected.length === parts.v1.length && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}- Addresses must start with https:// and use port 443 or 8443. Private and internal network addresses are refused, and redirects are not followed.
- Answer with any 2xx status within 10 seconds. A failed delivery is retried after 1 minute, 5 minutes, 30 minutes and 2 hours, then dropped.
- The same event keeps the same
idon every retry, so you can ignore repeats. - Each app sees and manages only the addresses it registered, up to 10 per account. They stop when you disconnect the app, or replace the API key that created them.
Limits and errors
- Each account can start 30 analyses and 30 governance checks per hour.
start_analysisnever spends more thanmax_credits. Retrying with the sameidempotency_keyreturns the same analysis. The same key with different inputs is refused.- 401: sign in again, or check the key. 403: the key or token lacks the permission, or your account cannot use that campaign.
- 404: not found, or not visible to your account. 429: the hourly limit was reached.
- In MCP, a sign-in problem returns HTTP 401 so your assistant can ask you to sign in. Other problems come back as a tool result marked as an error, with a message the assistant can show you.
Your API key
Programmatic requests use the x-api-key header (not your login password). Browser sessions use Cognito Bearer tokens; API automations use this key.
Sign in to reveal or refresh your API key.
Product API
These are the endpoints the AdVizion web app uses, including generation and Google Ads. They can change. For an integration, use the MCP server or the REST API above. Send one of these headers:
x-api-key: YOUR_API_KEY# orAuthorization: Bearer YOUR_COGNITO_ACCESS_TOKEN
The Cognito Bearer token is what the web app uses. A key can call only the scopes granted to it, and usage and credit limits still apply. Rotate or revoke a key from Account when access changes.
Analysis
- POST
/api/upload/Image saliency / sequence / brand attention / complexity (multipart). - POST
/api/video/Video saliency + brand attention + complexity (multipart). - POST
/upload_video/Same as /api/video/ — used by the web UI. - POST
/api/video_understanding/AdVizion video intelligence analysis (markdown summary). - POST
/api/emotional_prediction_analysis/Emotional sentiment per image. - POST
/api/customer_intent_analysis/Predicted intent action + reason. - POST
/api/reverse_image_search_upload/Reverse image search + uniqueness score. - POST
/api/asr_transcription/Audio / video transcription with timestamps. - POST
/api/resolve_media_url/Resolve a YouTube/TikTok/IG URL to an S3 URL.
Decision Report & Chat
- POST
/api/decision_report/AdVizion Decision Report for an image or video. - POST
/api/chat/Unified multimodal coach (image/video/asr/comparison/decision modes). - POST
/api/marketing_agent/Ad Copilot: build an editable brief; generation requires the returned quote and explicit confirmation. - POST
/advertisement_analysis/First-pass AdVizion AI Coach on uploaded images.
Image & Video Generation
- GET
/api/generation/capabilitiesRead supported media, output sizes, and source-edit availability. - POST
/api/generation/image-quoteBind an image quote to variant count, size, analysis and creation context. - POST
/api/generation/video-quoteQuote a scenario, render, composition or supported source edit. - GET
/api/generation/operations/{id}Resume a saved generation operation without resubmitting paid work. - POST
/api/generation/operations/{id}/cancelRequest cancellation and reconcile any already accepted provider work. - POST
/api/ai-visual-editor/AdVizion image generation / editing. - POST
/api/video_generate/scenarioAdVizion scenario writer (1-4 × 8s segments). - POST
/api/video_generate/segmentRender one 8-second video segment (chained via last-frame). - POST
/api/video_generate/Orchestrator — scenario + segments + concat + auto-analyze.
Campaigns, Decisions & Sharing
- POST
/api/v2/brief-importsExtract PDF or DOCX sources into an editable brief and Brand Rules with provenance and conflicts. - POST
/api/v2/brief-imports/{id}/rerunDraft the proposal again from the saved document text for an import that failed or awaits review. - POST
/api/v2/brief-imports/{id}/confirmConfirm the reviewed revision before creating or updating campaign context. - POST
/api/v2/creation-draftsSave a revisioned creation brief, exact source versions and operation reference. - GET
/api/projects/List the caller's campaigns. - POST
/api/projects/Create a campaign (brief + brand + platforms). - GET
/api/projects/{id}Get one campaign + roll-up counts. - GET
/api/projects/{id}/itemsList analyses + generated versions in a campaign. - POST
/api/projects/{id}/decisionsSave a Run/Fix/Reject decision to the campaign. - POST
/api/projects/{id}/learningsSave a learning. - GET
/api/projects/{id}/google-ads/deploysList Google Ads deploys for a campaign. - POST
/api/share/{item_id}Create a public share link for an item.
Google Ads
- GET
/api/google-ads/capabilitiesVerify account eligibility before native creation or launch. - POST
/api/google-ads/deploys/{id}/actionsOwner-approved native launch, pause or bounded budget changes with a verified campaign and current review. - POST
/api/google-ads/deploys/{id}/reconcileReconcile asynchronous uploads and uncertain provider requests. - POST
/api/google-ads/deploys/{id}/optimization-proposalsCreate an evidence-linked editable proposal. Generation and ad replacement each require separate confirmation. - GET
/api/google-ads/statusIs the caller connected to Google Ads? - GET
/api/google-ads/accountsList Google Ads accounts the connected Google user can access. - POST
/api/google-ads/deployPrepare supported paused Demand Gen image or video campaigns when native capability checks pass. Unsupported handoffs are labeled separately. - GET
/api/google-ads/deploysList all Google Ads deploys for the caller. - GET
/api/google-ads/deploys/{id}/metricsFetch cached or live campaign metrics. - POST
/api/google-ads/deploys/{id}/statusPause a campaign previously created through AdVizion. PAUSED is the only accepted status.
Campaign Decisions
- GET
/api/campaign-decisionsList STOP/SCALE/FIX/RELAUNCH/KEEP TESTING events. - GET
/api/projects/{id}/campaign-decisionsList campaign decision events for one campaign. - POST
/api/campaign-decisions/evaluateCreate an explicit during-campaign recommendation event.
Operator-only legacy utilities
- POST
/api/admin/users/{user_id}/grantOperator-only legacy entitlement migration utility; not a collaboration or membership API. - POST
/api/admin/users/{user_id}/rotate-keyOperator-only legacy key rotation utility.
Base URL: https://www.advizion.ai.
Examples
const formData = new FormData();
formData.append('file', fileInput.files[0]);
formData.append('prediction_type', 'saliency');
formData.append('condition', '2');
fetch('https://advizion.ai/api/upload/', {
method: 'POST',
headers: { 'x-api-key': 'YOUR_API_KEY' },
body: formData,
});Operator-only legacy utilities
These preserved endpoints support controlled entitlement migration and incident recovery. They require the existing operator authorization and do not create workspace membership, invitations, assignments, or unrestricted API access:
curl -X POST \
-H "Authorization: Bearer $ADMIN_TOKEN" \
-H "Content-Type: application/json" \
-d '{"role":"tester","rotate_key":true}' \
https://www.advizion.ai/api/admin/users/$TEAMMATE_USER_ID/grantA successful rotation can return a one-time key secret. Transfer it through an approved secrets manager — never paste keys into chat or commit them to git. For project and workspace collaboration, use in-product email invites rather than this operator grant. Talk to sales to scope supported Enterprise access.