certdesk-dev Watch API

openapi: 3.2.0
info:
  title: certdesk Watch 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: Watch
paths:
  /watch:
    post:
      operationId: watchExpiry
      summary: Request free daily expiry monitoring by email
      description: 'Double opt-in: sends a confirmation email; monitoring starts only after the recipient clicks the link. Up to 5 domains per address. Use only an address the user owns. One confirmation email per address per 24 hours (429 MAIL_COOLDOWN) and a global daily cap (429 DAILY_MAIL_CAP). Alerts: verdict changes and recoveries, a weekly summary on Mondays, and new certificates recorded in Certificate Transparency logs — immediately when the issuing CA has not been seen for that domain before (possible unauthorized issuance), otherwise listed in the weekly summary.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - email
              - domains
              properties:
                email:
                  type: string
                  format: email
                domains:
                  type: array
                  items:
                    type: string
                  minItems: 1
                  maxItems: 5
                  description: 'Each item may carry the contract end date, the DCV method and per-domain WARN/CRITICAL days: "shop.example.com 2027-05-01 email 45/20", or an object {name, contractExpiry, dcv, warnDays, critDays}. Per-domain days override the subscription-wide warnDays/critDays. 400 INVALID_META for a misplaced or invalid value.'
                warnDays:
                  type: integer
                  minimum: 1
                  maximum: 365
                  description: Per-subscription WARN threshold in days (default 30)
                critDays:
                  type: integer
                  minimum: 1
                  maximum: 365
                  description: Per-subscription CRITICAL threshold in days (default 15, < warnDays)
                webhook:
                  type: string
                  description: 'Optional alert channel URL. Alerts are posted there too after the email confirmation, and a connection message is sent first. Accepts a Slack or Discord incoming-webhook URL, a Telegram URL https://api.telegram.org/bot<TOKEN>/sendMessage?chat_id=<CHAT_ID>, or any public https endpoint (default port, no IP or private names), which receives a JSON POST {version: 1, event: status_change | weekly_summary | connected, title, sentAt, results[]}. The URL is a secret: it is stored but never returned or logged. 400 INVALID_WEBHOOK for other formats. If the endpoint later answers 404/410 (or the Slack/Discord/Telegram equivalent), the channel is disconnected and the subscriber is emailed once.'
                slackWebhook:
                  type: string
                  description: Deprecated alias of webhook that accepts only Slack Incoming Webhook URLs (https://hooks.slack.com/services/...). Alerts are posted there too after the email confirmation; a confirmation message is sent to the channel. 400 INVALID_SLACK_WEBHOOK for other formats.
      responses:
        '202':
          description: Confirmation email sent
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  message:
                    type: string
        '400':
          $ref: '#/components/responses/Error'
        '429':
          $ref: '#/components/responses/RateLimited'
      tags:
      - Watch
components:
  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