Domain Lab Inbox API

openapi: 3.2.0
info:
  title: Domain Lab Inbox 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: Inbox
paths:
  /inbox:
    get:
      operationId: listInbox
      summary: Alerts delivered to the assistant inbox, newest first
      description: Populated when the "AI Assistant" notification provider is enabled in Preferences. Items are kept 90 days.
      parameters:
      - name: since
        in: query
        required: false
        schema:
          type: string
          format: date-time
        description: Only items created at or after this ISO timestamp
      - name: unread_only
        in: query
        required: false
        schema:
          type: boolean
        description: true or 1 to return only unread items
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 25
          maximum: 100
          minimum: 1
      responses:
        '200':
          description: Inbox items and the total unread count
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/InboxItem'
                  unread_count:
                    type: integer
                    description: All unread items for the account, not just this page
                  limit:
                    type: integer
        '400':
          description: INVALID_SINCE
        '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).
        '503':
          description: The assistant inbox is not set up yet.
      tags:
      - Inbox
  /inbox/read:
    post:
      operationId: markInboxRead
      summary: Mark inbox items as read
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Provide exactly one of ids or all.
              properties:
                ids:
                  type: array
                  items:
                    type: integer
                    minimum: 1
                  minItems: 1
                  maxItems: 500
                all:
                  type: boolean
                  enum:
                  - true
                  description: Mark every unread item read
      responses:
        '200':
          description: Number of items newly marked read
          content:
            application/json:
              schema:
                type: object
                properties:
                  marked:
                    type: integer
        '400':
          description: INVALID_BODY or INVALID_IDS
        '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).
        '503':
          description: The assistant inbox is not set up yet.
      tags:
      - Inbox
components:
  schemas:
    InboxItem:
      type: object
      description: An alert delivered to the assistant inbox
      properties:
        id:
          type: integer
        created_at:
          type: string
          format: date-time
        read_at:
          type:
          - string
          - 'null'
          format: date-time
        domain_id:
          type:
          - integer
          - 'null'
        domain_name:
          type:
          - string
          - 'null'
        event_id:
          type:
          - integer
          - 'null'
        event_type:
          type:
          - string
          - 'null'
        severity:
          type:
          - string
          - 'null'
        message:
          type: string
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: 'Domain Lab API key (dlb_...), created in Preferences → API. Send as: Authorization: Bearer dlb_...'