certdesk-dev Expiry API

openapi: 3.2.0
info:
  title: certdesk Expiry API
  version: 1.8.0
  description: 'TLS/SSL certificate diagnostics with a verdict: status OK | WARN | CRITICAL | UNKNOWN, judged from the certificate chain the server actually serves — measured from Korean point A (full chain, CRL revocation) plus point B and an overseas point on the Globalping public measurement network — verification, expiry, renewal point, revocation (CRL), chain, plus security grade, TLS error explanations and free expiry monitoring by email (double opt-in). If the server cannot be measured the status is UNKNOWN; CT logs are then shown only as an estimate and days left is null. No API key. Limit: 30 requests per minute per IP; results cached per domain for 10 minutes (security: 30 minutes). Free and best-effort. Docs: https://certdesk.dev/en/api/ · MCP server: https://certdesk.dev/mcp'
  contact:
    email: hello@certdesk.dev
    url: https://certdesk.dev/en/api/
servers:
- url: https://certdesk.dev/api/v1
tags:
- name: Expiry
paths:
  /expiry:
    get:
      operationId: checkExpiry
      summary: Expiry summary for up to 5 domains
      description: 'For CI jobs and inventories: per-domain combined status (certificate + domain registration via RDAP of the registrable domain), served-certificate days left (null when not measured) and Korean alert lines. A CI gate should fail unless `status` is `OK`.'
      parameters:
      - name: domains
        in: query
        required: true
        description: 1–5 domain names, comma-separated
        schema:
          type: string
          examples:
          - example.com,example.org
      - $ref: '#/components/parameters/client'
      - $ref: '#/components/parameters/warnDays'
      - $ref: '#/components/parameters/critDays'
      responses:
        '200':
          description: Per-domain results
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/ExpiryResult'
                  checkedAt:
                    type: string
                    format: date-time
        '400':
          $ref: '#/components/responses/Error'
        '429':
          $ref: '#/components/responses/RateLimited'
      tags:
      - Expiry
components:
  schemas:
    Thresholds:
      type: object
      description: Expiry thresholds actually applied
      properties:
        warnDays:
          type: integer
        critDays:
          type: integer
        custom:
          type: boolean
          description: true when warnDays/critDays were passed
        adjusted:
          type: boolean
          description: true when the defaults were shrunk for a short-lived certificate
    ExpiryResult:
      type: object
      properties:
        domain:
          type: string
        certificate:
          type: object
          properties:
            status:
              type: string
              enum:
              - OK
              - WARN
              - CRITICAL
              - UNKNOWN
              description: OK = no issue; WARN = past renewal point, chain order/extra certs, weak key/signature; CRITICAL = verification failed (any reason), revoked, expired or ≤7 days left, TLS below 1.2 only; UNKNOWN = could not be measured (never treat as OK)
            headline:
              type: string
            notAfter:
              type:
              - string
              - 'null'
              format: date-time
            daysLeft:
              type:
              - integer
              - 'null'
              description: Served leaf only; null when the server could not be measured
            issuer:
              type:
              - string
              - 'null'
            source:
              type:
              - string
              - 'null'
              enum:
              - served
              - ct
              - null
            estimate:
              type: boolean
        servedTlsOk:
          type:
          - boolean
          - 'null'
        domainExpiry:
          type:
          - string
          - 'null'
        domainDaysLeft:
          type:
          - integer
          - 'null'
        alerts:
          type: array
          items:
            type: string
        status:
          type: string
          enum:
          - OK
          - WARN
          - CRITICAL
          - UNKNOWN
          description: 'Combined verdict: certificate + domain registration (≤60 days → WARN, ≤7 → CRITICAL). CI: fail unless OK'
        headline:
          type: string
        reasons:
          type: array
          items:
            $ref: '#/components/schemas/Reason'
        domainExpiryNote:
          type:
          - string
          - 'null'
          description: Set when the registry publishes no real expiry date (e.g. 9999-12-31)
        thresholds:
          $ref: '#/components/schemas/Thresholds'
        contractExpiry:
          type:
          - string
          - 'null'
          description: Contract (subscription) end date recorded with the monitoring subscription
        contractDaysLeft:
          type:
          - integer
          - 'null'
        dcv:
          type:
          - string
          - 'null'
          enum:
          - dns
          - http
          - email
          - tls-alpn
          - null
      required:
      - domain
      - status
      - headline
      - reasons
      - certificate
    Reason:
      type: object
      properties:
        code:
          type: string
          description: e.g. EXPIRED, NOT_YET_VALID, EXPIRES_SOON (within critDays), HOSTNAME_MISMATCH, SELF_SIGNED, UNTRUSTED_ROOT, INCOMPLETE_CHAIN, ISSUER_NOT_FOUND, EXPIRED_INTERMEDIATE, REVOKED, LEGACY_TLS_ONLY, WEAK_KEY, WEAK_SIGNATURE, CHAIN_ORDER, EXTRA_CERTS, RENEWAL_OVERDUE (within warnDays), NODE_EXPIRING (another node serves a certificate within the thresholds), NODE_MISMATCH (addresses serve different certificates), STARTTLS_UNSUPPORTED, STARTTLS_FAILED, SECONDARY_UNAVAILABLE, NEWER_NOT_DEPLOYED, PROBE_UNAVAILABLE, DNS_NXDOMAIN, DNS_NO_ADDRESS, CONNECT_TIMEOUT, CONNECT_REFUSED, TLS_HANDSHAKE_FAILED … POINT_MISMATCH, REGION_DIFF, DIFFERENT_CERTS, PRIMARY_DOWN, FAMILY_MISMATCH, IPV6_UNREACHABLE, IPV6_NOT_MEASURED …
        severity:
          type: string
          enum:
          - critical
          - unknown
          - warn
          - info
        message:
          type: string
          description: One line, Korean
        messageEn:
          type: string
        detail:
          type:
          - string
          - 'null'
          description: Raw detail (e.g. missing intermediate names, original error text)
        explain:
          type:
          - string
          - 'null'
          description: Knowledge-base id for /api/v1/explain
        explainUrl:
          type:
          - string
          - 'null'
          format: uri
      required:
      - code
      - severity
      - message
  parameters:
    warnDays:
      name: warnDays
      in: query
      required: false
      description: Days before expiry that count as WARN (1-365, default 30). The default shrinks to 1/3 of the lifetime for certificates shorter than 90 days; explicit values are used as given. Also applies to domain registration expiry.
      schema:
        type: integer
        minimum: 1
        maximum: 365
    critDays:
      name: critDays
      in: query
      required: false
      description: Days before expiry that count as CRITICAL 'expiring soon' (1-365, default 15, must be < warnDays → otherwise 400 INVALID_THRESHOLD). The default shrinks to 1/6 of the lifetime for certificates shorter than 90 days.
      schema:
        type: integer
        minimum: 1
        maximum: 365
    client:
      name: client
      in: query
      required: false
      description: Optional name of your app or tool, used only for aggregate usage counts
      schema:
        type: string
  responses:
    Error:
      description: Invalid input
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
              code:
                type: string
                description: EMPTY, INVALID_DOMAIN, INVALID_PORT, PORT_UNSUPPORTED, IP_LITERAL, PRIVATE_ADDRESS (400); MEASURE_LIMIT, FRESH_LIMIT (429)
    RateLimited:
      description: More than 30 requests per minute from this IP
      headers:
        retry-after:
          schema:
            type: integer