VisibilityRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/aidemos-com/json-schema/aidemos-com-visibility-request-schema.json",
  "title": "VisibilityRequest",
  "x-generated": "2026-11-01",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/aidemos-com-openapi.json#/components/schemas/VisibilityRequest",
  "properties": {
    "mode": {
      "type": "string",
      "enum": [
        "serp",
        "citation",
        "gap"
      ],
      "title": "Mode"
    },
    "page_types": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "title": "Page Types"
    },
    "slugs": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "title": "Slugs",
      "description": "Restrict to specific slugs"
    },
    "limit": {
      "type": "integer",
      "minimum": 0.0,
      "title": "Limit",
      "description": "0 = all published pages in scope",
      "default": 0
    },
    "gsc": {
      "type": "boolean",
      "title": "Gsc",
      "description": "serp: also inspect indexation via Google Search Console",
      "default": true
    },
    "providers": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "title": "Providers",
      "description": "citation: defaults to the ROUTINE set (openai + perplexity). claude and gemini are excluded from the default on measured yield (2.2% and 0.7% cite rate vs 17.7%/34.5%) — pass them explicitly for the quarterly probe, e.g. [\"openai\",\"perplexity\",\"claude\",\"gemini\"]"
    },
    "runs": {
      "type": "integer",
      "maximum": 5.0,
      "minimum": 1.0,
      "title": "Runs",
      "description": "citation: repeat runs per query",
      "default": 1
    },
    "queries": {
      "type": "integer",
      "maximum": 5.0,
      "minimum": 1.0,
      "title": "Queries",
      "description": "citation: question-style queries per page",
      "default": 2
    },
    "citation_mode": {
      "type": "string",
      "enum": [
        "natural",
        "constrained"
      ],
      "title": "Citation Mode",
      "default": "natural"
    },
    "page_concurrency": {
      "type": "integer",
      "maximum": 8.0,
      "minimum": 0.0,
      "title": "Page Concurrency",
      "description": "citation/gap: concurrent pages (0 = default)",
      "default": 0
    },
    "citer_openai": {
      "anyOf": [
        {
          "$ref": "#/$defs/CiterOpenAIOverride"
        },
        {
          "type": "null"
        }
      ],
      "description": "citation: OpenAI citer config override (#297 eval)"
    },
    "reuse_queries": {
      "type": "boolean",
      "title": "Reuse Queries",
      "description": "citation: reuse each page's stored queries from previous sweeps (stable week-over-week measurement); false regenerates everything",
      "default": true
    },
    "winners": {
      "type": "integer",
      "maximum": 5.0,
      "minimum": 1.0,
      "title": "Winners",
      "description": "gap: top-N SERP winners to fetch per page",
      "default": 3
    },
    "batch": {
      "type": "boolean",
      "title": "Batch",
      "description": "citation/gap: run LLM judge legs via the Batch API",
      "default": true
    },
    "chunk": {
      "type": "integer",
      "maximum": 25.0,
      "minimum": 1.0,
      "title": "Chunk",
      "description": "pages per fan-out job row (1 = safest)",
      "default": 1
    }
  },
  "type": "object",
  "required": [
    "mode"
  ],
  "$defs": {
    "CiterOpenAIOverride": {
      "properties": {
        "model": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Model",
          "description": "e.g. gpt-5.6-luna (ALLOWED-MODELS only)"
        },
        "tool": {
          "anyOf": [
            {
              "type": "string",
              "enum": [
                "web_search",
                "web_search_preview"
              ]
            },
            {
              "type": "null"
            }
          ],
          "title": "Tool"
        },
        "search_context_size": {
          "anyOf": [
            {
              "type": "string",
              "enum": [
                "low",
                "medium",
                "high"
              ]
            },
            {
              "type": "null"
            }
          ],
          "title": "Search Context Size"
        }
      },
      "type": "object",
      "title": "CiterOpenAIOverride",
      "description": "#297: per-run override of the OpenAI citer config (model/tool/context). Used by the\nterra-vs-luna parity eval; the shipped default lives in app/services/utilities.py."
    }
  }
}