{
  "openapi": "3.1.0",
  "info": {
    "title": "AdVizion public API",
    "version": "1.1.0",
    "description": "The same operations as the AdVizion MCP server at https://www.advizion.ai/mcp. Read projects and creatives, quote and start analysis, read status and verdicts, run governance, and compare stored verdicts. A recommendation is not human approval and does not publish a campaign. Purchases, publishing, deletion, and generation are not part of this API. Documentation: https://www.advizion.ai/api-docs"
  },
  "servers": [
    {
      "url": "https://www.advizion.ai"
    }
  ],
  "paths": {
    "/api/public/v1/me": {
      "get": {
        "operationId": "get_profile",
        "summary": "Who is connected",
        "description": "Return the AdVizion account connected to this client.",
        "security": [
          {
            "apiKey": []
          },
          {
            "bearer": []
          },
          {
            "oauth2": [
              "advizion.read"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/400"
          },
          "401": {
            "$ref": "#/components/responses/401"
          },
          "402": {
            "$ref": "#/components/responses/402"
          },
          "403": {
            "$ref": "#/components/responses/403"
          },
          "404": {
            "$ref": "#/components/responses/404"
          },
          "409": {
            "$ref": "#/components/responses/409"
          },
          "429": {
            "$ref": "#/components/responses/429"
          }
        }
      }
    },
    "/api/public/v1/projects": {
      "get": {
        "operationId": "list_projects",
        "summary": "Find projects",
        "description": "List projects this account can open. Start here to get a project_id.",
        "security": [
          {
            "apiKey": []
          },
          {
            "bearer": []
          },
          {
            "oauth2": [
              "advizion.read"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/400"
          },
          "401": {
            "$ref": "#/components/responses/401"
          },
          "402": {
            "$ref": "#/components/responses/402"
          },
          "403": {
            "$ref": "#/components/responses/403"
          },
          "404": {
            "$ref": "#/components/responses/404"
          },
          "409": {
            "$ref": "#/components/responses/409"
          },
          "429": {
            "$ref": "#/components/responses/429"
          }
        },
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50
            }
          }
        ]
      }
    },
    "/api/public/v1/projects/{project_id}": {
      "get": {
        "operationId": "get_project_context",
        "summary": "Read project context",
        "description": "Return the campaign objective, audience, and applicable rulebooks for one accessible project.",
        "security": [
          {
            "apiKey": []
          },
          {
            "bearer": []
          },
          {
            "oauth2": [
              "advizion.read"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/400"
          },
          "401": {
            "$ref": "#/components/responses/401"
          },
          "402": {
            "$ref": "#/components/responses/402"
          },
          "403": {
            "$ref": "#/components/responses/403"
          },
          "404": {
            "$ref": "#/components/responses/404"
          },
          "409": {
            "$ref": "#/components/responses/409"
          },
          "429": {
            "$ref": "#/components/responses/429"
          }
        },
        "parameters": [
          {
            "name": "project_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/api/public/v1/projects/{project_id}/creatives": {
      "get": {
        "operationId": "list_creatives",
        "summary": "List creatives",
        "description": "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.",
        "security": [
          {
            "apiKey": []
          },
          {
            "bearer": []
          },
          {
            "oauth2": [
              "advizion.read"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/400"
          },
          "401": {
            "$ref": "#/components/responses/401"
          },
          "402": {
            "$ref": "#/components/responses/402"
          },
          "403": {
            "$ref": "#/components/responses/403"
          },
          "404": {
            "$ref": "#/components/responses/404"
          },
          "409": {
            "$ref": "#/components/responses/409"
          },
          "429": {
            "$ref": "#/components/responses/429"
          }
        },
        "parameters": [
          {
            "name": "project_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50
            }
          }
        ]
      }
    },
    "/api/public/v1/analyses/quote": {
      "post": {
        "operationId": "quote_analysis",
        "summary": "Quote an analysis",
        "description": "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.",
        "security": [
          {
            "apiKey": []
          },
          {
            "bearer": []
          },
          {
            "oauth2": [
              "advizion.analyze"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/400"
          },
          "401": {
            "$ref": "#/components/responses/401"
          },
          "402": {
            "$ref": "#/components/responses/402"
          },
          "403": {
            "$ref": "#/components/responses/403"
          },
          "404": {
            "$ref": "#/components/responses/404"
          },
          "409": {
            "$ref": "#/components/responses/409"
          },
          "429": {
            "$ref": "#/components/responses/429"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "media_type"
                ],
                "properties": {
                  "media_type": {
                    "type": "string",
                    "enum": [
                      "image",
                      "video",
                      "audio"
                    ]
                  },
                  "project_id": {
                    "type": "string"
                  },
                  "creative_version_id": {
                    "type": "string"
                  }
                },
                "additionalProperties": false
              }
            }
          }
        }
      }
    },
    "/api/public/v1/analyses": {
      "post": {
        "operationId": "start_analysis",
        "summary": "Start analysis",
        "description": "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.",
        "security": [
          {
            "apiKey": []
          },
          {
            "bearer": []
          },
          {
            "oauth2": [
              "advizion.analyze"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/400"
          },
          "401": {
            "$ref": "#/components/responses/401"
          },
          "402": {
            "$ref": "#/components/responses/402"
          },
          "403": {
            "$ref": "#/components/responses/403"
          },
          "404": {
            "$ref": "#/components/responses/404"
          },
          "409": {
            "$ref": "#/components/responses/409"
          },
          "429": {
            "$ref": "#/components/responses/429"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "project_id",
                  "creative_version_id",
                  "media_type",
                  "idempotency_key",
                  "max_credits"
                ],
                "properties": {
                  "project_id": {
                    "type": "string"
                  },
                  "creative_version_id": {
                    "type": "string"
                  },
                  "media_type": {
                    "type": "string",
                    "enum": [
                      "image",
                      "video",
                      "audio"
                    ]
                  },
                  "idempotency_key": {
                    "type": "string",
                    "minLength": 8,
                    "maxLength": 128
                  },
                  "max_credits": {
                    "type": "integer",
                    "minimum": 0
                  }
                },
                "additionalProperties": false
              }
            }
          }
        }
      }
    },
    "/api/public/v1/analyses/{review_id}": {
      "get": {
        "operationId": "get_analysis_status",
        "summary": "Analysis status",
        "description": "Return the status of an analysis this account can see, and each item's RUN, FIX, or REJECT verdict once its Decision Report exists.",
        "security": [
          {
            "apiKey": []
          },
          {
            "bearer": []
          },
          {
            "oauth2": [
              "advizion.read"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/400"
          },
          "401": {
            "$ref": "#/components/responses/401"
          },
          "402": {
            "$ref": "#/components/responses/402"
          },
          "403": {
            "$ref": "#/components/responses/403"
          },
          "404": {
            "$ref": "#/components/responses/404"
          },
          "409": {
            "$ref": "#/components/responses/409"
          },
          "429": {
            "$ref": "#/components/responses/429"
          }
        },
        "parameters": [
          {
            "name": "review_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/api/public/v1/projects/{project_id}/rulebooks": {
      "get": {
        "operationId": "get_brand_rulebook",
        "summary": "Brand rulebook",
        "description": "List the rulebooks that apply to a project, including status and version.",
        "security": [
          {
            "apiKey": []
          },
          {
            "bearer": []
          },
          {
            "oauth2": [
              "advizion.read"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/400"
          },
          "401": {
            "$ref": "#/components/responses/401"
          },
          "402": {
            "$ref": "#/components/responses/402"
          },
          "403": {
            "$ref": "#/components/responses/403"
          },
          "404": {
            "$ref": "#/components/responses/404"
          },
          "409": {
            "$ref": "#/components/responses/409"
          },
          "429": {
            "$ref": "#/components/responses/429"
          }
        },
        "parameters": [
          {
            "name": "project_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/api/public/v1/projects/{project_id}/governance": {
      "post": {
        "operationId": "run_governance_check",
        "summary": "Run governance",
        "description": "Check a project, or one creative version in it, against one active rulebook. The verdict is automated. It is not legal clearance.",
        "security": [
          {
            "apiKey": []
          },
          {
            "bearer": []
          },
          {
            "oauth2": [
              "advizion.analyze"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/400"
          },
          "401": {
            "$ref": "#/components/responses/401"
          },
          "402": {
            "$ref": "#/components/responses/402"
          },
          "403": {
            "$ref": "#/components/responses/403"
          },
          "404": {
            "$ref": "#/components/responses/404"
          },
          "409": {
            "$ref": "#/components/responses/409"
          },
          "429": {
            "$ref": "#/components/responses/429"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "rulebook_id"
                ],
                "properties": {
                  "rulebook_id": {
                    "type": "string"
                  },
                  "creative_version_id": {
                    "type": "string"
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "parameters": [
          {
            "name": "project_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/api/public/v1/projects/{project_id}/comparisons": {
      "post": {
        "operationId": "compare_creatives",
        "summary": "Compare stored verdicts",
        "description": "Compare two stored Decision Report verdicts for a stated objective. This does not invent a new score.",
        "security": [
          {
            "apiKey": []
          },
          {
            "bearer": []
          },
          {
            "oauth2": [
              "advizion.read"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/400"
          },
          "401": {
            "$ref": "#/components/responses/401"
          },
          "402": {
            "$ref": "#/components/responses/402"
          },
          "403": {
            "$ref": "#/components/responses/403"
          },
          "404": {
            "$ref": "#/components/responses/404"
          },
          "409": {
            "$ref": "#/components/responses/409"
          },
          "429": {
            "$ref": "#/components/responses/429"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "left_report_id",
                  "right_report_id",
                  "objective"
                ],
                "properties": {
                  "left_report_id": {
                    "type": "string"
                  },
                  "right_report_id": {
                    "type": "string"
                  },
                  "objective": {
                    "type": "string"
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "parameters": [
          {
            "name": "project_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "apiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key"
      },
      "bearer": {
        "type": "http",
        "scheme": "bearer",
        "description": "An AdVizion API key (advz_...) or an OAuth access token (advz_at_...)."
      },
      "oauth2": {
        "type": "oauth2",
        "flows": {
          "authorizationCode": {
            "authorizationUrl": "https://www.advizion.ai/oauth/authorize",
            "tokenUrl": "https://www.advizion.ai/oauth/token",
            "refreshUrl": "https://www.advizion.ai/oauth/token",
            "scopes": {
              "advizion.read": "Read projects, creatives, rulebooks, and results.",
              "advizion.analyze": "Quote and start analyses and governance checks."
            }
          }
        }
      }
    },
    "responses": {
      "400": {
        "description": "Missing or invalid argument.",
        "content": {
          "application/json": {
            "schema": {
              "type": "object"
            }
          }
        }
      },
      "401": {
        "description": "No valid API key or token. The WWW-Authenticate header points at OAuth discovery.",
        "content": {
          "application/json": {
            "schema": {
              "type": "object"
            }
          }
        }
      },
      "402": {
        "description": "The analysis costs more than max_credits.",
        "content": {
          "application/json": {
            "schema": {
              "type": "object"
            }
          }
        }
      },
      "403": {
        "description": "The key or token lacks the permission, or the account cannot use this project.",
        "content": {
          "application/json": {
            "schema": {
              "type": "object"
            }
          }
        }
      },
      "404": {
        "description": "Not found, or not visible to this account.",
        "content": {
          "application/json": {
            "schema": {
              "type": "object"
            }
          }
        }
      },
      "409": {
        "description": "The idempotency_key was already used for a different request.",
        "content": {
          "application/json": {
            "schema": {
              "type": "object"
            }
          }
        }
      },
      "429": {
        "description": "More than 30 analyses or governance checks this hour.",
        "content": {
          "application/json": {
            "schema": {
              "type": "object"
            }
          }
        }
      }
    }
  }
}