API and MCP documentation

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.

No app can buy credits, generate ads, publish campaigns, approve a creative, or delete anything through AdVizion MCP or this API.

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 resource parameter, and iss on 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-Authenticate header 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.

• get_profileread

  Return the AdVizion account connected to this client.

• list_projectsread

  List projects this account can open. Start here to get a project_id.

• get_project_contextread

  Return the campaign objective, audience, and applicable rulebooks for one accessible project.

• list_creativesread

  List the creatives saved in a project with their latest version id. Use latest_version_id as creative_version_id when quoting or starting an analysis.

• quote_analysisanalyze

  Report 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_analysisanalyze

  Start 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_statusread

  Return the status of an analysis this account can see, and each item's RUN, FIX, or REJECT verdict once its Decision Report exists.

• get_brand_rulebookread

  List the rulebooks that apply to a project, including status and version.

• run_governance_checkanalyze

  Check a project, or one creative version in it, against one active rulebook. The verdict is automated. It is not legal clearance.

• compare_creativesread

  Compare 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/projects/{project_id}/rulebooksBrand rulebook
• POST/projects/{project_id}/governanceRun governance
• POST/projects/{project_id}/comparisonsCompare stored verdicts

Request and response shapes are in the OpenAPI file.

curl https://www.advizion.ai/api/public/v1/projects \
  -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}'

Limits and errors

• Each account can start 30 analyses and 30 governance checks per hour.
• start_analysis never spends more than max_credits. Retrying with the same idempotency_key returns 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 project.
• 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.

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
# or
Authorization: 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.

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/grant

A 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.