openapi: 3.0.3
info:
  title: Domain Audit HQ API
  description: Developer reference for the Portfolio DNS & WHOIS Guard REST API.
  version: 1.0.0
servers:
  - url: http://localhost:8080/api
    description: Local API Server
paths:
  /domains:
    get:
      summary: List registered domains
      description: Returns all domains monitored under the user's tenant. Available to admin, user, and read_only roles.
      security:
        - BearerAuth: []
      responses:
        '200':
          description: A list of registered domains.
          content:
            application/json:
              schema:
                type: object
                properties:
                  tenant_id:
                    type: string
                    example: tenant-c88a101f
                  domains:
                    type: array
                    items:
                      $ref: '#/components/schemas/Domain'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
    post:
      summary: Register a new domain
      description: Adds a new domain to monitor. Restricted to admin and user roles.
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - domain_name
              properties:
                domain_name:
                  type: string
                  example: example.com
      responses:
        '201':
          description: Domain added successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Domain added successfully
                  domain_name:
                    type: string
                    example: example.com
                  status:
                    type: string
                    example: unverified
        '400':
          description: Bad Request
        '403':
          description: Forbidden
  /domains/{id}:
    delete:
      summary: Delete a domain
      description: Permanently removes a domain from monitoring. Restricted to admin role.
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          description: The unique ID of the domain record
          schema:
            type: string
      responses:
        '200':
          description: Domain deleted successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Domain deleted successfully
                  domain_id:
                    type: string
                    example: "123"
        '403':
          description: Forbidden
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    Domain:
      type: object
      properties:
        id:
          type: string
          example: e88d2296-1c2a-431c-8ff4-3dbf3c7e7e11
        domain_name:
          type: string
          example: google.com
        status:
          type: string
          example: verified