openapi: 3.1.0
info:
  title: SGE-SCORE Agent API
  version: 1.0.0
  description: |
    Public API for autonomous AI agents to audit landing pages against 57 Google-patent-derived
    checkpoints for AI-search readiness (Google SGE, ChatGPT, Perplexity, Claude, Gemini) and
    optionally purchase a structured Master-Fix.

    Pricing:
      • Free audit: 2/24h per email+IP.
      • Master-Fix Single: $9 — 2 credits, valid 30 days.
      • Master-Fix Bulk:   $99 — 100 credits, valid 12 months. Bulk session_id lifts the audit rate limit to 20/24h.
  contact:
    name: SGE-SCORE Support
    email: info@sge-score.com
    url: https://sge-score.com/contact
  license:
    name: Proprietary
servers:
  - url: https://jhocisiphtyopyxrahgo.supabase.co/functions/v1
    description: Production
paths:
  /agent-analyze:
    post:
      operationId: startAnalysis
      summary: Start a new SGE-SCORE audit
      description: Queues an audit of the given URL. Returns an analysis_id for polling. Free.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [url, email]
              properties:
                url:
                  type: string
                  format: uri
                  example: https://example.com/product
                email:
                  type: string
                  format: email
                  description: Required for receipt and support contact.
                language:
                  type: string
                  enum: [en, de, es, fr]
                  default: en
                bulk_session_id:
                  type: string
                  description: Optional Stripe session_id from a $99 Bulk purchase. Lifts the rate limit to 20/24h.
      responses:
        '202':
          description: Analysis queued
          content:
            application/json:
              schema:
                type: object
                properties:
                  analysis_id: { type: string, format: uuid }
                  status: { type: string, example: queued }
                  status_url: { type: string, format: uri }
                  poll_interval_seconds: { type: integer, example: 5 }
                  estimated_duration_seconds: { type: integer, example: 60 }
        '400': { description: Invalid input }
        '429': { description: Rate limit (2 per 24h per email/IP) exceeded }
  /agent-analysis-status:
    get:
      operationId: getAnalysisStatus
      summary: Poll analysis status
      parameters:
        - name: id
          in: query
          required: true
          schema: { type: string, format: uuid }
      responses:
        '200':
          description: Current state
          content:
            application/json:
              schema:
                type: object
                properties:
                  analysis_id: { type: string }
                  status: { type: string, enum: [queued, processing, completed, failed] }
                  progress: { type: integer, minimum: 0, maximum: 100 }
                  overall_score: { type: integer, nullable: true, description: "0-114" }
                  max_score: { type: integer, example: 114 }
                  checkpoints_passed: { type: integer, nullable: true }
                  checkpoints_total: { type: integer, example: 57 }
                  sectors: { type: object, nullable: true }
                  master_fix: { type: object, nullable: true }
        '404': { description: Not found }
  /agent-checkout:
    post:
      operationId: createCheckout
      summary: Create a Stripe checkout for the Master-Fix (single $9 or bulk $99)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [email]
              properties:
                analysis_id:
                  type: string
                  format: uuid
                  description: Required for sku=masterfix_2; optional for masterfix_100.
                email: { type: string, format: email }
                sku:
                  type: string
                  enum: [masterfix_2, masterfix_100]
                  default: masterfix_2
                  description: |
                    masterfix_2  = $9, 2 credits, valid 30 days (single page workflow).
                    masterfix_100 = $99, 100 credits, valid 12 months (agency / bulk workflow).
      responses:
        '200':
          description: Checkout session created
          content:
            application/json:
              schema:
                type: object
                properties:
                  session_id: { type: string }
                  checkout_url: { type: string, format: uri }
                  sku: { type: string, enum: [masterfix_2, masterfix_100] }
                  amount_usd: { type: number, example: 9 }
                  currency: { type: string, example: USD }
                  credits: { type: integer }
                  valid_for_days: { type: integer }
                  masterfix_endpoint: { type: string, format: uri }
        '404': { description: Analysis not found }
        '409': { description: Analysis not yet completed }
  /agent-masterfix:
    get:
      operationId: getMasterFix
      summary: Retrieve the structured Master-Fix after payment
      description: Validates Stripe payment, then returns the full master_fix_prompt as markdown JSON. Idempotent.
      parameters:
        - name: session_id
          in: query
          required: true
          schema: { type: string }
        - name: analysis_id
          in: query
          required: false
          description: Required for bulk purchases (sku=masterfix_100); optional for single (uses bound id).
          schema: { type: string, format: uuid }
      responses:
        '200':
          description: Master-fix payload
          content:
            application/json:
              schema:
                type: object
                properties:
                  analysis_id: { type: string }
                  url: { type: string }
                  overall_score: { type: integer }
                  max_score: { type: integer, example: 114 }
                  sectors: { type: object }
                  master_fix_prompt: { type: string, description: "Markdown with copy-paste-ready code blocks" }
                  format: { type: string, example: markdown }
        '402': { description: Payment not completed }
        '404': { description: Purchase or analysis not found }
  /agent-knowledge-search:
    get:
      operationId: searchKnowledge
      summary: Search the SGE/GEO knowledge base
      description: |
        Full-text search across ~1500 schema.org reference entries and published SGE/GEO blog posts.
        Returns structured JSON. Free. Rate limit: 30 requests per hour per IP.
      parameters:
        - name: q
          in: query
          required: true
          description: Search query (min 2 chars)
          schema: { type: string, minLength: 2 }
        - name: type
          in: query
          required: false
          schema: { type: string, enum: [all, schema, blog], default: all }
        - name: language
          in: query
          required: false
          schema: { type: string, enum: [en, de, es, fr], default: en }
        - name: limit
          in: query
          required: false
          schema: { type: integer, default: 10, maximum: 25 }
      responses:
        '200':
          description: Search results
          content:
            application/json:
              schema:
                type: object
                properties:
                  query: { type: string }
                  type: { type: string }
                  language: { type: string }
                  total: { type: integer }
                  results:
                    type: array
                    items:
                      type: object
                      properties:
                        type: { type: string, enum: [schema, blog] }
                        name: { type: string }
                        title: { type: string }
                        category: { type: string }
                        description: { type: string }
                        summary: { type: string }
                        url: { type: string, format: uri }
                        json_ld_example: { type: string }
        '400': { description: Invalid query }
        '429': { description: Rate limit (30/h per IP) exceeded }

