Domain Lab Events API

openapi: 3.2.0
info:
  title: Domain Lab Events API
  version: 1.0.0
  description: 'REST API for Domain Lab, a domain-monitoring service. Query monitored domains, plan limits and usage, per-domain alert settings, AI reviews, registrar connections, WHOIS/registration data, SSL certificates, DNS records, email security (SPF, DKIM, DMARC, MTA-STS, TLS reporting, BIMI, DNSSEC) with grades and history, change events, and alert history; add, update, and remove monitored domains. Requires an active subscription or trial. Limits: 120 requests/minute, 50,000 requests/month (adding a domain, rescanning, running an AI review and syncing a registrar connection each count as 5). Every response carries X-RateLimit-Remaining-Minute and X-RateLimit-Remaining-Month headers.'
  contact:
    url: https://www.domainlab.app/help
servers:
- url: https://www.domainlab.app/api/v1
security:
- apiKey: []
tags:
- name: Events
paths:
  /events:
    get:
      operationId: listEvents
      summary: Change events across all domains, newest first
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 50
          maximum: 100
          minimum: 1
        description: Maximum number of items to return
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          default: 0
          minimum: 0
        description: Number of items to skip
      - name: domain_id
        in: query
        required: false
        schema:
          type: integer
        description: Filter to one domain
      - name: event_type_id
        in: query
        required: false
        schema:
          type: integer
        description: Filter by event type
      responses:
        '200':
          description: 'Paginated events, each including domain: { id, domain_name }'
          content:
            application/json:
              schema:
                type: object
                properties:
                  events:
                    type: array
                    items:
                      $ref: '#/components/schemas/Event'
                  total:
                    type: integer
                  limit:
                    type: integer
                  offset:
                    type: integer
        '401':
          description: Missing or invalid API key
        '403':
          description: Account lacks API access (no active subscription or trial)
        '429':
          description: Rate limit or monthly quota exceeded. Respect the Retry-After header. code is RATE_LIMITED (short-lived) or MONTHLY_QUOTA_EXCEEDED (resets next period).
      tags:
      - Events
components:
  schemas:
    Event:
      type: object
      description: A detected change event
      properties:
        id:
          type: integer
        detected_at:
          type: string
          format: date-time
        description:
          type: string
        status:
          type:
          - string
          - 'null'
        payload:
          type:
          - object
          - 'null'
          description: Before/after detail of the change
        created_at:
          type: string
          format: date-time
        event_type:
          type: object
          properties:
            id:
              type: integer
            name:
              type: string
            description:
              type:
              - string
              - 'null'
        domain:
          type: object
          description: Present on GET /events (cross-domain listing) only
          properties:
            id:
              type: integer
            domain_name:
              type: string
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: 'Domain Lab API key (dlb_...), created in Preferences → API. Send as: Authorization: Bearer dlb_...'