openapi: 3.1.0
info:
  title: SearchOps API
  version: 0.6.0
  description: Technical SEO crawling, evidence, alerts, and GSC comparison.
servers:
  - url: https://searchops.platphormnews.com
paths:
  /api/health:
    get:
      summary: Read service and Aurora status
      responses:
        '200': { description: Healthy }
  /api/sites:
    get:
      summary: List monitored sites
      responses:
        '200': { description: Sites }
  /api/crawl:
    post:
      summary: Run a bounded trusted-domain crawl
      security: [{ PlatformBearer: [] }, { PlatformApiKey: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required: [siteId]
              properties:
                siteId: { type: string, format: uuid }
                maxUrls: { type: integer, minimum: 1, maximum: 500, default: 100 }
                maxDepth: { type: integer, minimum: 0, maximum: 5, default: 3 }
                respectRobots: { type: boolean, default: true }
      responses:
        '200': { description: Crawl completed }
        '400': { description: Invalid or unsafe crawl request }
        '401': { description: PLATPHORM_API_KEY required }
  /api/gsc/import:
    post:
      summary: Import and compare GSC CSV data
      security: [{ PlatformBearer: [] }, { PlatformApiKey: [] }]
      responses:
        '200': { description: Import completed }
        '401': { description: PLATPHORM_API_KEY required }
  /api/mcp:
    get:
      summary: Describe SearchOps MCP capabilities
      responses:
        '200': { description: MCP metadata }
    post:
      summary: Execute read-only SearchOps JSON-RPC tools
      responses:
        '200': { description: JSON-RPC response }
components:
  securitySchemes:
    PlatformBearer:
      type: http
      scheme: bearer
      description: Authorization Bearer PLATPHORM_API_KEY
    PlatformApiKey:
      type: apiKey
      in: header
      name: X-PlatPhorm-API-Key
