openapi: 3.0.3
info:
  title: Hermes Website Audit Bundle API
  description: |
    Comprehensive website audit combining tech stack detection, SSL certificate check,
    and performance metrics in a single API call. Optionally includes full SEO audit.

    Designed for web agencies and developers who need to quickly assess client websites
    across multiple dimensions without making separate API calls.
  version: '1.0'
  contact:
    email: hermes-agent@agentmail.to
    url: https://51-68-119-197.sslip.io/api
servers:
  - url: https://51-68-119-197.sslip.io
    description: Production
paths:
  /api/audit:
    get:
      operationId: auditWebsite
      summary: Run a comprehensive website audit
      description: |
        Combines tech stack detection, SSL certificate validation, and performance
        measurement in one API call. Add seo=true for browser-based SEO audit (slower).
      parameters:
        - name: url
          in: query
          required: true
          schema:
            type: string
          description: URL to audit (e.g. https://example.com)
          example: https://example.com
        - name: seo
          in: query
          required: false
          schema:
            type: string
            enum: ['true', 'false']
            default: 'false'
          description: Include browser-based SEO audit (adds ~5s)
      responses:
        '200':
          description: Audit results
          content:
            application/json:
              schema:
                type: object
                properties:
                  url:
                    type: string
                  audit_timestamp:
                    type: string
                    format: date-time
                  techstack:
                    type: object
                    description: Detected technologies (frameworks, CMS, CDN, analytics, etc.)
                  ssl:
                    type: object
                    description: SSL certificate details (validity, issuer, expiration)
                  performance:
                    type: object
                    description: Response time, page size, status code
                  seo:
                    type: object
                    description: SEO audit results (only if seo=true)
              example:
                url: https://example.com
                audit_timestamp: '2026-03-04T22:00:00Z'
                techstack:
                  technologies_detected: 2
                  technologies:
                    - name: Cloudflare
                      category: cdn
                      confidence: high
                ssl:
                  valid: true
                  issuer:
                    organizationName: Let's Encrypt
                  expires: Jun 15 2026
                performance:
                  response_time_ms: 245.3
                  response_size_bytes: 1256
                  status_code: 200
        '400':
          description: Invalid URL
        '429':
          description: Rate limit exceeded
      security:
        - ApiKeyAuth: []
        - {}
  /api/keys:
    post:
      operationId: createApiKey
      summary: Create a free API key
      description: Get an instant API key for higher rate limits (50 req/day)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [email]
              properties:
                email:
                  type: string
                  format: email
      responses:
        '200':
          description: API key created
          content:
            application/json:
              schema:
                type: object
                properties:
                  api_key:
                    type: string
                  limits:
                    type: object
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: |
        Optional API key for higher rate limits.
        Free tier (no key): 1 request per 2 minutes.
        With key: 5 requests/minute, 50/day, 500/month.
        Create one instantly: POST /api/keys with {"email":"you@example.com"}
