openapi: "3.0.3"
info:
  title: Agentiview API
  description: |
    Agent readiness scoring and intelligence for any website or business.
    Agentiview measures ARS (Agent Readability Score), AAS (Agent Action Score),
    and AVS (Agent Viability Score) across 20 proprietary dimensions.

    Current API version provides service intake endpoints. Programmatic scoring
    endpoints (REST API v1) are in development, see roadmap at agentiview.com.
  version: "0.1.0"
  contact:
    name: Agentiview
    url: https://agentiview.com
    email: hello@agentiview.com
  termsOfService: https://agentiview.com/privacy-policy
  x-agentiview-scorer-version: "1.2.0"

servers:
  - url: https://agentiview.com
    description: Production

tags:
  - name: scoring
    description: Agent readiness scoring services
  - name: certification
    description: Certification registry
  - name: intake
    description: Service request intake

paths:
  /book:
    get:
      tags: [intake]
      summary: Request a scoring engagement
      description: |
        Human-assisted intake for all Agentiview scoring services.
        Submit your domain and requirements to receive a free ARS preview
        or initiate a paid assessment. Responses delivered by email.

        Free ARS preview: same-day delivery.
        ARS Full Report ($349): 5 business days.
        Full Readiness Assessment ($1,500): 5-7 business days.
      operationId: requestScoring
      parameters:
        - name: domain
          in: query
          description: Domain to score (e.g. example.com)
          schema:
            type: string
        - name: service
          in: query
          description: Service requested
          schema:
            type: string
            enum: [preview, ars-report, full-assessment, remediation, retainer]
      responses:
        "200":
          description: Booking page, complete intake form to submit request
          content:
            text/html:
              schema:
                type: string

  /certification:
    get:
      tags: [certification]
      summary: Query the public certification registry
      description: |
        Public registry of Agentiview-certified companies.
        Certification tiers: Agent-Readable (AVS 51+), Agent-Ready (AVS 76+),
        Agent-Native (AVS 91+). All certifications are based on verified deep scan AVS.
      operationId: getCertificationRegistry
      responses:
        "200":
          description: Certification registry page
          content:
            text/html:
              schema:
                type: string

  /api/v1/score:
    get:
      tags: [scoring]
      summary: Programmatic ARS scoring endpoint (coming Q2 2026)
      description: |
        REST API for programmatic agent readiness scoring.
        Returns ARS, AAS, AVS, score bands, and dimension breakdown for any domain.
        Currently in development, contact hello@agentiview.com for early access.
      operationId: getScore
      x-status: planned
      x-available: "Q2 2026"
      parameters:
        - name: domain
          in: query
          required: true
          description: Domain to score
          schema:
            type: string
            example: example.com
        - name: depth
          in: query
          description: Scan depth
          schema:
            type: string
            enum: [homepage, deep]
            default: homepage
      responses:
        "200":
          description: Agent readiness scores
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ScoreResult"
        "503":
          description: Endpoint not yet available, contact hello@agentiview.com

components:
  schemas:
    ScoreResult:
      type: object
      properties:
        domain:
          type: string
          example: example.com
        scorerVersion:
          type: string
          example: "1.2.0"
        scannedAt:
          type: string
          format: date-time
        ars:
          type: number
          minimum: 0
          maximum: 100
          description: Agent Readability Score
        aas:
          type: number
          minimum: 0
          maximum: 100
          description: Agent Action Score
        avs:
          type: number
          minimum: 0
          maximum: 100
          description: Agent Viability Score (composite)
        band:
          type: string
          enum:
            - Agent Invisible
            - Agent Detected
            - Agent Considered
            - Agent Eligible
            - Agent Ready
            - Agent Native
        certified:
          type: boolean
          description: Whether company holds an active Agentiview certification
        certificationTier:
          type: string
          nullable: true
          enum: [Agent-Readable, Agent-Ready, Agent-Native, null]
