openapi: 3.2.0
info:
  title: DomScan Security API
  description: DomScan is a domain intelligence API providing domain analysis tools.
  version: 2.15.0
  contact:
    name: DomScan Support
    url: https://domscan.net
    email: support@domscan.net
  termsOfService: https://domscan.net/legal/terms
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
servers:
- url: https://domscan.net
  description: Production server
security:
- apiKey: []
tags:
- name: Security
  description: Security posture, reputation, exposure, and vulnerability intelligence
paths:
  /v1/certificates/bulk:
    post:
      operationId: bulkGetCertificates
      summary: Search certificates for multiple domains
      description: Search public Certificate Transparency data for multiple domains with shared filtering options. Accepts up to 10 items, preserves input order, and uses bounded concurrency. The outer response is HTTP 200 when the batch is accepted, so inspect each result for data or an error. Billing is 2 credits per validated item with no bulk discount, including items that return a per-item lookup error.
      tags:
      - Security
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - domains
              properties:
                domains:
                  type: array
                  minItems: 1
                  maxItems: 10
                  items:
                    type: string
                    format: hostname
                include_subdomains:
                  type: boolean
                  default: true
                include_expired:
                  type: boolean
                  default: false
                limit:
                  type: integer
                  minimum: 1
                  maximum: 1000
                  default: 100
            example:
              domains:
              - example.com
              - cloudflare.com
              include_subdomains: true
              limit: 100
      responses:
        '200':
          description: Batch accepted. Each ordered result contains either data or a per-item error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkLookupResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '429':
          $ref: '#/components/responses/RateLimited'
      x-domscan-credits:
        model: per_item
        default: 2
  /v1/subdomains/bulk:
    post:
      operationId: bulkGetSubdomains
      summary: Discover subdomains for multiple domains
      description: Run the best-effort passive hostname evidence pipeline for multiple root domains. Discovery coverage is incomplete and result entries retain source labels. Accepts up to 10 items, preserves input order, and uses bounded concurrency. The outer response is HTTP 200 when the batch is accepted, so inspect each result for data or an error. Billing is 4 credits per validated item by default, or 5 credits per item when verify=true, with no bulk discount. Items that return a per-item lookup error are still billed.
      tags:
      - Security
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - domains
              properties:
                domains:
                  type: array
                  minItems: 1
                  maxItems: 10
                  items:
                    type: string
                    format: hostname
                verify:
                  type: boolean
                  default: false
                include_wildcards:
                  type: boolean
                  default: false
                limit:
                  type: integer
                  minimum: 1
                  maximum: 2000
                  default: 500
            example:
              domains:
              - example.com
              - cloudflare.com
              verify: false
              limit: 500
      responses:
        '200':
          description: Batch accepted. Each ordered result contains either data or a per-item error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkLookupResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '429':
          $ref: '#/components/responses/RateLimited'
      x-domscan-credits:
        model: per_item
        default: 4
        variants:
        - parameter: verify
          equals: true
          credits: 5
        note: 4 credits per item by default; 5 credits per item when verify=true.
  /v1/email-auth/bulk:
    post:
      operationId: bulkGetEmailAuth
      summary: Audit email authentication for multiple domains
      description: Check SPF, DKIM, DMARC, MTA-STS, TLS-RPT, and recursive SPF behavior for multiple domains with an optional shared DKIM selector list. Accepts up to 10 items, preserves input order, and uses bounded concurrency. The outer response is HTTP 200 when the batch is accepted, so inspect each result for data or an error. Billing is 3 credits per validated item with no bulk discount, including items that return a per-item lookup error.
      tags:
      - Security
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - domains
              properties:
                domains:
                  type: array
                  minItems: 1
                  maxItems: 10
                  items:
                    type: string
                    format: hostname
                selectors:
                  type: array
                  minItems: 1
                  maxItems: 50
                  items:
                    type: string
            example:
              domains:
              - example.com
              - cloudflare.com
              selectors:
              - selector1
              - selector2
      responses:
        '200':
          description: Batch accepted. Each ordered result contains either data or a per-item error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkLookupResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '429':
          $ref: '#/components/responses/RateLimited'
      x-domscan-credits:
        model: per_item
        default: 3
  /v1/vulnerabilities:
    get:
      tags:
      - Security
      summary: Scan exposed software for known vulnerabilities
      description: Run a passive, evidence-first vulnerability snapshot for a public URL or domain. DomScan correlates exposed technology versions with authoritative public advisories and exploitation-priority data, and reports deterministic response-header misconfigurations separately. Deep mode adds one isolated JavaScript-rendered page. The scan sends no exploit payloads, preserves unknown coverage, and never treats a versionless fingerprint as a detected vulnerability.
      operationId: getVulnerabilities
      x-required-any-of:
      - - url
      - - domain
      parameters:
      - name: url
        in: query
        required: false
        description: Full public HTTP(S) URL to analyze. Takes precedence over domain when both are supplied.
        schema:
          type: string
          format: uri
          minLength: 1
          maxLength: 2048
      - name: domain
        in: query
        required: false
        description: Public domain or HTTP(S) URL to analyze. At least one of url or domain is required.
        schema:
          type: string
          minLength: 1
          maxLength: 2048
      - name: mode
        in: query
        required: false
        description: Choose standard for bounded response inspection or deep to add isolated JavaScript rendering.
        schema:
          type: string
          enum:
          - standard
          - deep
          default: standard
      responses:
        '200':
          description: Passive vulnerability intelligence result with explicit evidence and coverage limits.
          content:
            application/json:
              schema:
                type: object
                required:
                - target
                - scan
                - summary
                - findings
                - components
                - coverage
                - sources
                properties:
                  target:
                    type: object
                    required:
                    - requested_url
                    - final_url
                    - hostname
                    properties:
                      requested_url:
                        type: string
                        format: uri
                      final_url:
                        type: string
                        format: uri
                      hostname:
                        type: string
                  scan:
                    type: object
                    required:
                    - mode
                    - status
                    - checked_at
                    - duration_ms
                    - disclaimer
                    properties:
                      mode:
                        type: string
                        enum:
                        - standard
                        - deep
                      status:
                        type: string
                        enum:
                        - complete
                        - partial
                      checked_at:
                        type: string
                        format: date-time
                      duration_ms:
                        type: integer
                        minimum: 0
                      disclaimer:
                        type: string
                  summary:
                    type: object
                    required:
                    - posture
                    - risk_level
                    - finding_count
                    - version_affected_count
                    - misconfiguration_count
                    - urgent_count
                    - severity_counts
                    properties:
                      posture:
                        type: string
                        enum:
                        - action_required
                        - review
                        - no_known_findings
                        - unknown
                      risk_level:
                        type: string
                        enum:
                        - critical
                        - high
                        - medium
                        - low
                        - none
                        - unknown
                      finding_count:
                        type: integer
                        minimum: 0
                      version_affected_count:
                        type: integer
                        minimum: 0
                      misconfiguration_count:
                        type: integer
                        minimum: 0
                      urgent_count:
                        type: integer
                        minimum: 0
                      severity_counts:
                        type: object
                        additionalProperties:
                          type: integer
                          minimum: 0
                  findings:
                    type: array
                    items:
                      type: object
                      required:
                      - fingerprint
                      - classification
                      - severity
                      - priority
                      - title
                      - summary
                      - evidence
                      - remediation
                      - sources
                      properties:
                        fingerprint:
                          type: string
                        classification:
                          type: string
                          enum:
                          - version_affected
                          - security_misconfiguration
                        severity:
                          type: string
                          enum:
                          - critical
                          - high
                          - medium
                          - low
                          - info
                          - unknown
                        priority:
                          type: string
                          enum:
                          - urgent
                          - high
                          - elevated
                          - normal
                        title:
                          type: string
                        summary:
                          type: string
                        component:
                          type: object
                          properties:
                            technology_id:
                              type: string
                            name:
                              type: string
                            detected_version:
                              type: string
                            version_kind:
                              type: string
                              enum:
                              - product
                              - asset
                              - protocol
                              - edge_build
                            confidence:
                              type: string
                              enum:
                              - high
                              - medium
                              - low
                            confidence_score:
                              type: integer
                              minimum: 0
                              maximum: 100
                            ecosystem:
                              type: string
                            package:
                              type: string
                            purl:
                              type: string
                        advisory:
                          type: object
                          properties:
                            id:
                              type: string
                            aliases:
                              type: array
                              items:
                                type: string
                            cves:
                              type: array
                              items:
                                type: string
                            published_at:
                              type:
                              - string
                              - 'null'
                              format: date-time
                            modified_at:
                              type:
                              - string
                              - 'null'
                              format: date-time
                            cvss:
                              type: array
                              items:
                                type: object
                                properties:
                                  type:
                                    type: string
                                  vector:
                                    type: string
                            fixed_versions:
                              type: array
                              items:
                                type: string
                            affected_ranges:
                              type: array
                              items:
                                type: object
                                additionalProperties: true
                            references:
                              type: array
                              items:
                                type: string
                                format: uri
                        exploitation:
                          type: object
                          properties:
                            cisa_kev:
                              type:
                              - boolean
                              - 'null'
                            kev_added_at:
                              type:
                              - string
                              - 'null'
                              format: date
                            kev_required_action:
                              type:
                              - string
                              - 'null'
                            known_ransomware_use:
                              type:
                              - string
                              - 'null'
                            epss_probability:
                              type:
                              - number
                              - 'null'
                              minimum: 0
                              maximum: 1
                            epss_percentile:
                              type:
                              - number
                              - 'null'
                              minimum: 0
                              maximum: 1
                            epss_date:
                              type:
                              - string
                              - 'null'
                              format: date
                        evidence:
                          type: object
                          required:
                          - confidence
                          - observed
                          - limitations
                          properties:
                            confidence:
                              type: string
                              enum:
                              - high
                              - medium
                              - low
                            observed:
                              type: array
                              items:
                                type: string
                            limitations:
                              type: array
                              items:
                                type: string
                        remediation:
                          type: object
                          required:
                          - summary
                          - fixed_versions
                          properties:
                            summary:
                              type: string
                            fixed_versions:
                              type: array
                              items:
                                type: string
                        sources:
                          type: array
                          items:
                            type: string
                            enum:
                            - osv
                            - cisa_kev
                            - first_epss
                            - target_response
                  components:
                    type: array
                    items:
                      type: object
                      required:
                      - technology_id
                      - name
                      - detected_version
                      - version_kind
                      - confidence
                      - advisory_status
                      - matched_advisories
                      properties:
                        technology_id:
                          type: string
                        name:
                          type: string
                        detected_version:
                          type:
                          - string
                          - 'null'
                        version_kind:
                          type:
                          - string
                          - 'null'
                        confidence:
                          type: string
                          enum:
                          - high
                          - medium
                          - low
                        advisory_status:
                          type: string
                          enum:
                          - checked
                          - version_unavailable
                          - mapping_unavailable
                          - version_kind_not_supported
                          - version_format_not_supported
                          - not_checked_limit
                          - unknown
                          description: Package advisory coverage for this component. not_checked_limit means the component was eligible but fell beyond the bounded per-scan query limit.
                        matched_advisories:
                          type: integer
                          minimum: 0
                  coverage:
                    type: object
                    properties:
                      target_response:
                        type: string
                      technology_detection:
                        type: string
                      package_advisories:
                        type: string
                      known_exploitation:
                        type: string
                      exploitation_probability:
                        type: string
                      detected_components:
                        type: integer
                      versioned_components:
                        type: integer
                      advisory_eligible_components:
                        type: integer
                      advisory_checked_components:
                        type: integer
                      advisory_deferred_components:
                        type: integer
                        description: Eligible components not queried because they exceeded the bounded per-scan advisory limit.
                      advisory_query_limit:
                        type: integer
                        description: Maximum package-version advisory queries performed per scan.
                      relay_used:
                        type: boolean
                      limitations:
                        type: array
                        items:
                          type: string
                  sources:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        name:
                          type: string
                        owner:
                          type: string
                        url:
                          type: string
                          format: uri
                        status:
                          type: string
                        retrieved_at:
                          type:
                          - string
                          - 'null'
                          format: date-time
                        cache_hit:
                          type: boolean
                        expected_freshness:
                          type: string
                        fallback_behavior:
                          type: string
                        cost:
                          type: string
                          enum:
                          - none
                  _meta:
                    type: object
                    additionalProperties: true
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          $ref: '#/components/responses/TechServiceUnavailable'
      x-domscan-credits:
        model: per_request
        default: 8
        variants:
        - parameter: mode
          equals: deep
          credits: 12
        note: Standard passive scans cost 8 credits. Deep scans add isolated JavaScript rendering and cost 12 credits.
components:
  responses:
    RateLimited:
      description: Rate limit exceeded. Free accounts can sustain 120 requests per minute per account with a burst capacity of 60. Free bulk traffic is additionally limited to 20 requests per minute per account across all bulk endpoints and 100 per minute per IPv4 address or IPv6 /56 network. Paid accounts can sustain 600 requests per minute with a burst capacity of 120.
      headers:
        Retry-After:
          schema:
            type: integer
          description: Seconds to wait before retrying
        X-RateLimit-Plan:
          schema:
            type: string
            enum:
            - free
            - paid
          description: The account plan whose policy was applied.
        X-RateLimit-Limit:
          schema:
            type: integer
          description: The immediate burst capacity, or the active bulk fixed-window limit when a bulk-specific limit is exceeded.
        X-RateLimit-Remaining:
          schema:
            type: integer
            example: 0
          description: Immediate burst tokens remaining, or requests remaining in the active bulk fixed window.
        X-RateLimit-Policy:
          schema:
            type: string
          description: Machine-readable summary of the active tier and limit policy.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: RATE_LIMITED
              message: Rate limit exceeded. Please wait before making more requests.
    PaymentRequired:
      description: Insufficient credits for this request
      headers:
        X-Credits-Remaining:
          schema:
            type: integer
          description: Credits remaining on your API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: INSUFFICIENT_CREDITS
              message: Insufficient credits. This endpoint costs 2 credits but you have 0. Purchase more at https://domscan.net/billing or wait for your monthly reset.
              credits_remaining: 0
              credits_required: 2
              purchase_url: https://domscan.net/billing
    Unauthorized:
      description: 'Authentication required. All API endpoints require a valid API key (x-api-key header or Authorization: Bearer) or an active session cookie.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: AUTH_REQUIRED
              message: 'Authentication required. Provide an API key via x-api-key header or Authorization: Bearer header.'
              docs: https://domscan.net/docs/authentication
              get_key: https://domscan.net/login
    TechServiceUnavailable:
      description: DomScan could not perform the requested detection work. The request charge is refund-eligible. Target HTTP errors, blocks, empty responses, and target network failures are returned as billable 200 responses with partial analysis metadata instead.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: UPSTREAM_UNAVAILABLE
              message: Failed to fetch website
    BadRequest:
      description: Bad request - invalid parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: BAD_REQUEST
              message: Invalid domain format
              suggestion: Domain must be a valid format like example.com
  schemas:
    BulkLookupResponse:
      type: object
      description: Ordered bulk lookup response. A successful outer response can contain per-item failures.
      required:
      - results
      - meta
      properties:
        results:
          type: array
          description: Results in the same order as the submitted inputs.
          items:
            oneOf:
            - type: object
              required:
              - input
              - data
              properties:
                input:
                  type: string
                data:
                  type: object
                  additionalProperties: true
            - type: object
              required:
              - input
              - error
              properties:
                input:
                  type: string
                error:
                  type: object
                  required:
                  - code
                  - message
                  - status
                  properties:
                    code:
                      type: string
                    message:
                      type: string
                    status:
                      type: integer
                  additionalProperties: true
        meta:
          type: object
          required:
          - total
          - succeeded
          - failed
          - max_items
          - credits_per_item
          - duration_ms
          properties:
            total:
              type: integer
              minimum: 1
              maximum: 10
            succeeded:
              type: integer
              minimum: 0
              maximum: 10
            failed:
              type: integer
              minimum: 0
              maximum: 10
            max_items:
              type: integer
              enum:
              - 10
            credits_per_item:
              type: integer
              minimum: 1
            duration_ms:
              type: integer
              minimum: 0
    ErrorResponse:
      type: object
      description: Standard error response format
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: Error code for programmatic handling
              example: INVALID_DOMAIN
            type:
              type: string
              enum:
              - authentication_error
              - credits_error
              - permission_error
              - not_found_error
              - conflict_error
              - rate_limit_error
              - timeout_error
              - validation_error
              - upstream_error
              - api_error
              - request_error
              description: Stable error category used by official SDK subclasses
            message:
              type: string
              description: Human-readable error message
              example: Invalid domain format
            status:
              type: integer
              minimum: 400
              maximum: 599
              description: HTTP status repeated in the JSON error for queue and log processors
            retryable:
              type: boolean
              description: Whether retrying can be appropriate after applying retry guidance
            request_id:
              type: string
              description: Request identifier matching the X-Request-Id response header
            suggestion:
              type: string
              description: Suggestion for fixing the error
            details:
              type: object
              description: Optional structured context for the error
              additionalProperties: true
            retry_after:
              type: integer
              minimum: 0
              description: Seconds to wait before retrying when the error is temporary
              example: 300
            docs_url:
              type: string
              description: Link to relevant documentation
              example: /docs#parameters
          required:
          - type
          - code
          - message
          - status
          - retryable
          - request_id
          - docs_url
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: 'API key for authentication. Get yours free at https://domscan.net. Also accepts Authorization: Bearer header.'
    sessionCookie:
      type: apiKey
      in: cookie
      name: session
      description: Active DomScan browser session. Used by account-management endpoints.
externalDocs:
  description: Full API Documentation
  url: https://domscan.net/docs
x-rapidapi-product: domscan
x-domscan-rate-limits:
  free:
    general:
      scope: account
      sustained_requests_per_minute: 120
      burst_capacity: 60
      shared_across_api_keys_and_sessions: true
    bulk:
      scope: all bulk endpoints combined
      account_requests_per_minute: 20
      network_requests_per_minute: 100
      ipv6_network_prefix: 56
  paid:
    general:
      scope: API key for key-authenticated requests; IP for browser sessions
      sustained_requests_per_minute: 600
      burst_capacity: 120
    free_bulk_budget_applies: false
  response:
    status: 429
    retry_header: Retry-After
    headers_on_every_authenticated_response:
    - X-RateLimit-Plan
    - X-RateLimit-Limit
    - X-RateLimit-Remaining
    - X-RateLimit-Policy
    burst_headers:
    - X-RateLimit-Limit
    - X-RateLimit-Remaining
    policy_header: X-RateLimit-Policy
x-domscan-response-metadata:
  compatibility: additive response headers; established JSON success bodies are unchanged
  headers:
    X-Request-Id: Unique request identifier for logs and support
    X-API-Version: DomScan API release version
    X-Response-Time: Server processing duration in milliseconds
    X-Credits-Requested: Credits requested before refund settlement
    X-Credits-Charged: Credits retained after settlement
    X-Credits-Refunded: Credits returned during settlement
    X-Credits-Remaining: Authenticated account balance after the request
    X-Data-Freshness: fresh, cached, stale, mixed, or unknown
    X-RateLimit-Limit: Active burst capacity
    X-RateLimit-Remaining: Remaining burst capacity
    X-RateLimit-Plan: Active plan, or not_applicable before authentication
    X-RateLimit-Policy: Machine-readable active rate policy