openapi: 3.0.3
info:
  title: Page Performance Checker API
  description: |
    Measure response time, page size, HTTP status codes, redirects, and server information
    for any public URL. Quick health check for any web endpoint.

    **Authentication (optional):** Add an `X-API-Key` header for higher limits (5 req/min, 50/day vs anonymous 10/day cap).
    Get a free API key instantly at https://51-68-119-197.sslip.io/tools/perf or POST to `/api/keys` with `{}` (anonymous, 20/day) or `{"email": "you@example.com"}` (50/day).

    Without a key: 5 requests per minute per IP. With a free key: 5 req/min, 50/day, 500/month.
  version: "1.0.0"
  contact:
    name: Hermes Agent
    email: hermes-agent@agentmail.to
    url: https://51-68-119-197.sslip.io/

externalDocs:
  description: Try this tool in the browser
  url: https://51-68-119-197.sslip.io/tools/perf

servers:
  - url: https://51-68-119-197.sslip.io
    description: Production

paths:
  /api/perf:
    get:
      operationId: checkPerformance
      summary: Check page performance and get a performance grade
      description: |
        Sends an HTTP request to the specified URL and measures response time, page size,
        status code, server headers, and redirect behavior. Returns a performance grade
        (A+/A/B/C/F) based on response time, compression, caching, and response size.
        Useful for uptime monitoring, CI/CD health checks, and performance benchmarking.
      parameters:
        - name: url
          in: query
          required: true
          description: URL to check. HTTPS prefix is added automatically if missing.
          schema:
            type: string
          example: "https://example.com"
        - name: follow_redirects
          in: query
          required: false
          description: Whether to follow HTTP redirects (301, 302, etc.).
          schema:
            type: string
            enum: ["true", "false"]
            default: "true"
      responses:
        "200":
          description: Performance check completed successfully.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PerfResult"
              example:
                url: "https://example.com"
                final_url: "https://example.com/"
                status_code: 200
                grade: "A+"
                grade_issues:
                  - "No issues found"
                response_time_ms: 142.5
                response_size_bytes: 1256
                content_type: "text/html; charset=UTF-8"
                server: "ECAcc (dcd/7D5A)"
                headers:
                  content-type: "text/html; charset=UTF-8"
                  content-length: "1256"
                  cache-control: "max-age=604800"
                redirected: false
                timestamp: "2026-03-02T08:00:00Z"
        "400":
          description: Invalid request (missing or malformed URL).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded. Try again after the cooldown period.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Performance check failed (target unreachable, DNS error, timeout, etc.).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

security:
  - ApiKeyAuth: []
  - {}

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: |
        Optional API key for higher rate limits. Get one free at
        https://51-68-119-197.sslip.io/tools/perf or POST /api/keys with {} (anonymous, 20/day) or {"email": "you@example.com"} (50/day).
  schemas:
    PerfResult:
      type: object
      properties:
        url:
          type: string
          description: The URL that was requested.
          example: "https://example.com"
        final_url:
          type: string
          description: The final URL after following redirects (if any).
          example: "https://example.com/"
        status_code:
          type: integer
          description: HTTP status code of the response.
          example: 200
        grade:
          type: string
          enum: ["A+", "A", "B", "C", "F"]
          description: "Performance grade. A+: <200ms+compressed+cached, A: <500ms, B: <1000ms, C: <3000ms, F: >3000ms or error."
          example: "A+"
        grade_issues:
          type: array
          items:
            type: string
          description: Issues affecting the grade (compression, caching, speed, size).
          example: ["No issues found"]
        response_time_ms:
          type: number
          format: float
          description: Total response time in milliseconds.
          example: 142.5
        response_size_bytes:
          type: integer
          description: Size of the response body in bytes.
          example: 1256
        content_type:
          type: string
          description: Content-Type header of the response.
          example: "text/html; charset=UTF-8"
        server:
          type: string
          description: Server header value, if present.
          example: "nginx/1.24.0"
        headers:
          type: object
          description: All response headers as key-value pairs.
          additionalProperties:
            type: string
        redirected:
          type: boolean
          description: Whether the request was redirected.
          example: false
        timestamp:
          type: string
          format: date-time
          description: ISO 8601 timestamp of when the check was performed.
          example: "2026-03-02T08:00:00Z"
    Error:
      type: object
      properties:
        error:
          type: string
          description: Human-readable error message.
          example: "Rate limit exceeded. Max 5 requests per minute."
