AI Demos Seo Visibility API

openapi: 3.2.0
info:
  title: Aidemos Com Seo Visibility API
  version: 0.1.0
  description: 'Operations tagged seo-visibility across 2 of this provider''s published API definitions: aidemos-com-openapi.json, mcp-openapi.json. Each path carries the servers of the definition it was published in.'
tags:
- name: seo-visibility
paths:
  /v1/seo/audit:
    post:
      tags:
      - seo-visibility
      summary: Submit Audit
      description: Free coverage + markdown-twin audit → sip run + findings (poll the job, then GET /v1/seo/audit).
      operationId: submit_audit_v1_seo_audit_post
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      - name: x-api-key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuditRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubmitResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    get:
      tags:
      - seo-visibility
      summary: Get Audit
      description: Latest coverage/twin audit run (defect findings included by default).
      operationId: get_audit_v1_seo_audit_get
      parameters:
      - name: findings
        in: query
        required: false
        schema:
          type: boolean
          default: true
          title: Findings
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      - name: x-api-key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/seo/visibility:
    post:
      tags:
      - seo-visibility
      summary: Submit Visibility
      description: 'Paid diagnostics: mode=serp (DataForSEO findability + GSC indexation), mode=citation

        (LLM answer visibility across providers), or mode=gap (#204 deserve-to-win).


        All three are RUN GRAPHS since #300, not single jobs: this creates the umbrella `run` row plus

        a coordinator, and the coordinator fans out one retryable job row per page. The returned

        `job_run_id` is the umbrella — `GET /v1/jobs/{id}` reports the aggregated run (per-unit status,

        cross-step cost, the finalize result), exactly as page generation does.'
      operationId: submit_visibility_v1_seo_visibility_post
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      - name: x-api-key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VisibilityRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubmitResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    get:
      tags:
      - seo-visibility
      summary: Get Visibility
      description: 'Latest run per mode (default: all three), or one run by id — with findings on request.'
      operationId: get_visibility_v1_seo_visibility_get
      parameters:
      - name: mode
        in: query
        required: false
        schema:
          anyOf:
          - enum:
            - audit
            - serp
            - citation
            - gap
            type: string
          - type: 'null'
          title: Mode
      - name: run_id
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
          - type: 'null'
          title: Run Id
      - name: findings
        in: query
        required: false
        schema:
          type: boolean
          description: Include the run's findings
          default: false
          title: Findings
        description: Include the run's findings
      - name: verdicts
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Comma-separated verdict filter
          title: Verdicts
        description: Comma-separated verdict filter
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      - name: x-api-key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/seo/provider-health:
    get:
      tags:
      - seo-visibility
      summary: Get Provider Health
      description: '#304: per-provider health for the Diagnostics dashboard alert. `alert: true` when any

        provider''s newest result is an error; `last_error` carries the verbatim message (e.g. the 401

        quota text). Refresh the citers via POST /v1/seo/visibility with a 1-page all-provider

        citation payload (the console''s Probe button).


        Two signal types, on purpose (#300): the four LLM citers are read PASSIVELY from their latest

        citation finding, because probing them costs money. Google Search Console is probed LIVE —

        that check is free, and inferring it from the last serp run means a credential that expired

        afterwards shows a confident green until the next sweep. A dashboard that reports health it

        has not measured is worse than one that says nothing.'
      operationId: get_provider_health_v1_seo_provider_health_get
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      - name: x-api-key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/seo/finding:
    get:
      tags:
      - seo-visibility
      summary: Get Finding
      description: 'One page''s latest finding with FULL detail (provider answer text, SERP top-N, GSC row) —

        the drill-down behind a merged-view row. The merged view itself is deliberately slim.'
      operationId: get_finding_v1_seo_finding_get
      parameters:
      - name: check_type
        in: query
        required: true
        schema:
          enum:
          - serp
          - citation
          - coverage
          - twin
          - gap
          type: string
          title: Check Type
      - name: page_type
        in: query
        required: true
        schema:
          type: string
          title: Page Type
      - name: slug
        in: query
        required: true
        schema:
          type: string
          title: Slug
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      - name: x-api-key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    AuditRequest:
      properties:
        page_types:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Page Types
          description: 'Default: all four families'
      type: object
      title: AuditRequest
    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: '#/components/schemas/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
      title: VisibilityRequest
    SubmitResponse:
      properties:
        job_run_id:
          type: string
          title: Job Run Id
        status:
          type: string
          title: Status
          default: queued
      type: object
      required:
      - job_run_id
      title: SubmitResponse
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    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

        terra-vs-luna parity eval; the shipped default lives in app/services/utilities.py.'
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
x-refined-from:
- aidemos-com-openapi.json
- mcp-openapi.json