{
  "openapi": "3.1.0",
  "info": {
    "title": "BuyerOS AI Visibility API",
    "version": "1.1.0",
    "description": "Create brand profiles, maintain stable tracked questions, run repeatable AI visibility audits and retrieve evidence-backed results."
  },
  "servers": [{ "url": "https://api.buyeros.ai" }],
  "tags": [
    { "name": "Enrollment" },
    { "name": "Brands" },
    { "name": "Questions" },
    { "name": "Audits" }
  ],
  "paths": {
    "/health": {
      "get": {
        "operationId": "getHealth",
        "responses": { "200": { "description": "Healthy" } }
      }
    },
    "/v1/enrollments": {
      "post": {
        "operationId": "startEnrollment",
        "tags": ["Enrollment"],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnrollmentInput" } } }
        },
        "responses": {
          "201": { "description": "Enrollment created" },
          "429": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/v1/enrollments/{id}": {
      "get": {
        "operationId": "getEnrollmentStatus",
        "tags": ["Enrollment"],
        "security": [{ "enrollmentToken": [] }],
        "parameters": [{ "$ref": "#/components/parameters/Id" }],
        "responses": { "200": { "description": "Enrollment status" } }
      }
    },
    "/v1/brands": {
      "post": {
        "operationId": "createBrand",
        "tags": ["Brands"],
        "security": [{ "agentToken": [] }],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandInput" } } }
        },
        "responses": {
          "202": { "description": "Brand accepted for profile research", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Brand" } } } },
          "400": { "$ref": "#/components/responses/Error" }
        }
      },
      "get": {
        "operationId": "listBrands",
        "tags": ["Brands"],
        "security": [{ "agentToken": [] }],
        "parameters": [{ "$ref": "#/components/parameters/Limit" }],
        "responses": { "200": { "description": "Brand list" } }
      }
    },
    "/v1/brands/{brandId}": {
      "get": {
        "operationId": "getBrand",
        "tags": ["Brands"],
        "security": [{ "agentToken": [] }],
        "parameters": [{ "$ref": "#/components/parameters/BrandId" }],
        "responses": {
          "200": { "description": "Brand", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Brand" } } } },
          "404": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/v1/brands/{brandId}/refresh": {
      "post": {
        "operationId": "refreshBrandProfile",
        "tags": ["Brands"],
        "security": [{ "agentToken": [] }],
        "parameters": [{ "$ref": "#/components/parameters/BrandId" }],
        "responses": { "202": { "description": "Profile refresh queued" } }
      }
    },
    "/v1/brands/{brandId}/questions/generate": {
      "post": {
        "operationId": "generateBrandQuestions",
        "tags": ["Questions"],
        "security": [{ "agentToken": [] }],
        "parameters": [{ "$ref": "#/components/parameters/BrandId" }],
        "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarketInput" } } } },
        "responses": {
          "202": { "description": "Question generation queued or existing set returned" },
          "409": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/v1/brands/{brandId}/questions": {
      "get": {
        "operationId": "listBrandQuestions",
        "tags": ["Questions"],
        "security": [{ "agentToken": [] }],
        "parameters": [
          { "$ref": "#/components/parameters/BrandId" },
          { "name": "active", "in": "query", "schema": { "type": "boolean" } }
        ],
        "responses": { "200": { "description": "Tracked question list" } }
      },
      "post": {
        "operationId": "addBrandQuestion",
        "tags": ["Questions"],
        "security": [{ "agentToken": [] }],
        "parameters": [{ "$ref": "#/components/parameters/BrandId" }],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuestionInput" } } }
        },
        "responses": { "201": { "description": "Tracked question created" } }
      }
    },
    "/v1/brands/{brandId}/questions/{questionId}": {
      "patch": {
        "operationId": "setBrandQuestionActive",
        "tags": ["Questions"],
        "security": [{ "agentToken": [] }],
        "parameters": [
          { "$ref": "#/components/parameters/BrandId" },
          { "$ref": "#/components/parameters/QuestionId" }
        ],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "type": "object", "properties": { "active": { "type": "boolean" } }, "required": ["active"] } } }
        },
        "responses": { "200": { "description": "Question state updated" } }
      }
    },
    "/v1/brands/{brandId}/audits": {
      "post": {
        "operationId": "runBrandAudit",
        "tags": ["Audits"],
        "security": [{ "agentToken": [] }],
        "parameters": [
          { "$ref": "#/components/parameters/BrandId" },
          { "$ref": "#/components/parameters/IdempotencyKey" }
        ],
        "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditOptions" } } } },
        "responses": {
          "202": { "description": "Audit queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Audit" } } } },
          "409": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/v1/audits": {
      "post": {
        "operationId": "runAudit",
        "tags": ["Audits"],
        "security": [{ "agentToken": [] }],
        "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditInput" } } }
        },
        "responses": { "202": { "description": "Audit queued" } }
      },
      "get": {
        "operationId": "listAudits",
        "tags": ["Audits"],
        "security": [{ "agentToken": [] }],
        "parameters": [
          { "$ref": "#/components/parameters/Limit" },
          { "name": "brandId", "in": "query", "schema": { "type": "string", "format": "uuid" } }
        ],
        "responses": { "200": { "description": "Audit list" } }
      }
    },
    "/v1/audits/{id}": {
      "get": {
        "operationId": "getAudit",
        "tags": ["Audits"],
        "security": [{ "agentToken": [] }],
        "parameters": [{ "$ref": "#/components/parameters/Id" }],
        "responses": { "200": { "description": "Audit status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Audit" } } } } }
      }
    },
    "/v1/audits/{id}/results": {
      "get": {
        "operationId": "getAuditResults",
        "tags": ["Audits"],
        "security": [{ "agentToken": [] }],
        "parameters": [{ "$ref": "#/components/parameters/Id" }],
        "responses": { "200": { "description": "Aggregate results" }, "409": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/v1/audits/{id}/runs": {
      "get": {
        "operationId": "getAuditRuns",
        "tags": ["Audits"],
        "security": [{ "agentToken": [] }],
        "parameters": [{ "$ref": "#/components/parameters/Id" }],
        "responses": { "200": { "description": "Question-level requests, answers, citations, costs and evaluations" } }
      }
    },
    "/v1/audits/{id}/cancel": {
      "post": {
        "operationId": "cancelAudit",
        "tags": ["Audits"],
        "security": [{ "agentToken": [] }],
        "parameters": [{ "$ref": "#/components/parameters/Id" }],
        "responses": { "200": { "description": "Cancellation requested" } }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "agentToken": { "type": "http", "scheme": "bearer", "bearerFormat": "br_agent_…" },
      "enrollmentToken": { "type": "http", "scheme": "bearer", "bearerFormat": "br_enroll_…" }
    },
    "parameters": {
      "Id": { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } },
      "BrandId": { "name": "brandId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } },
      "QuestionId": { "name": "questionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } },
      "Limit": { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } },
      "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8 } }
    },
    "responses": {
      "Error": {
        "description": "Machine-readable error",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      }
    },
    "schemas": {
      "EnrollmentInput": {
        "type": "object",
        "properties": {
          "email": { "type": "string", "format": "email" },
          "agentName": { "type": "string", "default": "AI agent" },
          "scopes": { "type": "array", "items": { "enum": ["audits:create", "audits:read", "audits:cancel"] } }
        }
      },
      "BrandInput": {
        "type": "object",
        "properties": {
          "website": { "type": "string", "format": "uri" },
          "country": { "type": "string" },
          "language": { "type": "string", "default": "English" }
        },
        "required": ["website", "country"]
      },
      "Brand": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "website": { "type": "string", "format": "uri" },
          "profileStatus": { "enum": ["pending", "queued", "crawling", "planning", "ready", "failed"] },
          "questionStatus": { "enum": ["not_started", "queued", "planning", "ready", "failed"] },
          "activeQuestionCount": { "type": "integer" },
          "profile": { "type": ["object", "null"], "additionalProperties": true }
        },
        "required": ["id", "website", "profileStatus", "questionStatus", "activeQuestionCount"]
      },
      "MarketInput": {
        "type": "object",
        "properties": { "country": { "type": "string" }, "language": { "type": "string" } }
      },
      "QuestionInput": {
        "type": "object",
        "properties": {
          "text": { "type": "string", "minLength": 5 },
          "category": { "enum": ["discovery", "customer_need", "purchase_constraint", "comparison", "branded"] },
          "country": { "type": "string" },
          "language": { "type": "string" }
        },
        "required": ["text", "category"]
      },
      "AuditOptions": {
        "type": "object",
        "properties": {
          "country": { "type": "string" },
          "language": { "type": "string" },
          "config": { "$ref": "#/components/schemas/AuditConfig" }
        }
      },
      "AuditInput": {
        "allOf": [
          { "$ref": "#/components/schemas/AuditOptions" },
          { "type": "object", "properties": { "brandId": { "type": "string", "format": "uuid" } }, "required": ["brandId"] }
        ]
      },
      "AuditConfig": {
        "type": "object",
        "properties": {
          "repetitions": { "type": "integer", "minimum": 1, "maximum": 5, "default": 1 },
          "models": { "type": "array", "minItems": 1, "maxItems": 6, "items": { "type": "string" } },
          "maxCostUsd": { "type": "number", "exclusiveMinimum": 0, "maximum": 100 }
        }
      },
      "Audit": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "brandId": { "type": "string", "format": "uuid" },
          "website": { "type": "string", "format": "uri" },
          "country": { "type": "string" },
          "language": { "type": "string" },
          "status": { "enum": ["queued", "testing", "evaluating", "completed", "partial", "cancelled", "failed"] },
          "progress": { "type": "object", "additionalProperties": true },
          "costUsd": { "type": "number" },
          "error": { "type": ["object", "null"] }
        },
        "required": ["id", "brandId", "website", "country", "language", "status", "progress", "costUsd"]
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": { "code": { "type": "string" }, "message": { "type": "string" } },
            "required": ["code", "message"]
          }
        },
        "required": ["error"]
      }
    }
  }
}