openapi: 3.0.3
info:
  title: SSL Certificate Checker API
  description: |
    Check SSL/TLS certificate details for any domain. Returns a security grade (A+/A/B/C/F),
    certificate validity, expiration date (with days remaining), issuer information,
    Subject Alternative Names, TLS protocol version, cipher suite, and connection timing.

    Useful for monitoring certificate expiry across infrastructure, CI/CD checks,
    security audits, and compliance verification.

    **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/ssl 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/ssl

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

paths:
  /api/ssl:
    get:
      operationId: checkSSLCertificate
      summary: Check SSL certificate and get security grade
      description: |
        Connects to the specified domain on port 443, retrieves the SSL/TLS certificate,
        and returns a security grade (A+ through F) plus detailed information including
        validity status, expiration date, issuer, subject, SANs, protocol version,
        and cipher suite.
      parameters:
        - name: domain
          in: query
          required: true
          description: Domain name or URL to check. If a full URL is provided, the hostname is extracted automatically.
          schema:
            type: string
          example: "example.com"
      responses:
        "200":
          description: SSL certificate check completed successfully.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SSLResult"
              example:
                domain: "example.com"
                valid: true
                grade: "A+"
                grade_issues:
                  - "No issues found"
                subject:
                  common_name: "*.example.com"
                  organization: "Example Inc."
                issuer:
                  common_name: "DigiCert SHA2 Extended Validation Server CA"
                  organization: "DigiCert Inc"
                validity:
                  issued: "2026-01-15T00:00:00Z"
                  expires: "2027-01-15T23:59:59Z"
                  days_remaining: 319
                subject_alt_names:
                  - "*.example.com"
                  - "example.com"
                protocol: "TLSv1.3"
                cipher:
                  name: "TLS_AES_256_GCM_SHA384"
                  bits: 256
                serial_number: "0A1B2C3D4E5F6789"
                connection_time_ms: 45.2
                timestamp: "2026-03-02T09:00:00Z"
        "400":
          description: Invalid request (missing domain, DNS resolution failed).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "502":
          description: Connection refused on port 443.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "504":
          description: Connection timed out.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: SSL check failed (general error).
          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/ssl or POST /api/keys with {} (anonymous, 20/day) or {"email": "you@example.com"} (50/day).
  schemas:
    SSLResult:
      type: object
      properties:
        domain:
          type: string
          description: The domain that was checked.
          example: "example.com"
        valid:
          type: boolean
          description: Whether the certificate is currently valid (not expired, verification passed).
          example: true
        grade:
          type: string
          enum: ["A+", "A", "B", "C", "F"]
          description: |
            Security grade based on protocol, cipher strength, and certificate validity.
            A+: TLSv1.3 + 256-bit cipher + 30+ days validity.
            A: TLSv1.2+ with strong cipher.
            B: Certificate expiring within 7 days.
            C: TLS 1.1 or weak cipher (<128 bits).
            F: Expired certificate or SSLv3/TLSv1.
          example: "A+"
        grade_issues:
          type: array
          description: List of issues affecting the grade. Empty grades show "No issues found".
          items:
            type: string
          example: ["No issues found"]
        subject:
          type: object
          description: Certificate subject information.
          properties:
            common_name:
              type: string
              description: Common Name (CN) of the certificate subject.
              example: "*.example.com"
            organization:
              type: string
              description: Organization name from the certificate subject.
              example: "Example Inc."
        issuer:
          type: object
          description: Certificate issuer (Certificate Authority) information.
          properties:
            common_name:
              type: string
              description: Common Name of the issuing CA.
              example: "DigiCert SHA2 Extended Validation Server CA"
            organization:
              type: string
              description: Organization name of the issuing CA.
              example: "DigiCert Inc"
        validity:
          type: object
          description: Certificate validity period.
          properties:
            issued:
              type: string
              format: date-time
              description: Certificate issue date (ISO 8601).
              example: "2026-01-15T00:00:00Z"
            expires:
              type: string
              format: date-time
              description: Certificate expiration date (ISO 8601).
              example: "2027-01-15T23:59:59Z"
            days_remaining:
              type: integer
              description: Number of days until the certificate expires. Negative if expired.
              example: 319
        subject_alt_names:
          type: array
          description: List of Subject Alternative Names (DNS names) covered by the certificate. Limited to first 20.
          items:
            type: string
          example: ["*.example.com", "example.com"]
        protocol:
          type: string
          description: Negotiated TLS protocol version.
          example: "TLSv1.3"
        cipher:
          type: object
          description: Negotiated cipher suite.
          properties:
            name:
              type: string
              description: Cipher suite name.
              example: "TLS_AES_256_GCM_SHA384"
            bits:
              type: integer
              description: Key length in bits.
              example: 256
        serial_number:
          type: string
          description: Certificate serial number (hexadecimal).
          example: "0A1B2C3D4E5F6789"
        connection_time_ms:
          type: number
          format: float
          description: Time to establish SSL connection in milliseconds.
          example: 45.2
        timestamp:
          type: string
          format: date-time
          description: ISO 8601 timestamp of when the check was performed.
          example: "2026-03-02T09:00:00Z"
    Error:
      type: object
      properties:
        error:
          type: string
          description: Human-readable error message.
          example: "Rate limit exceeded. Max 5 checks per minute."
