DomScan OSINT API

openapi: 3.2.0
info:
  title: DomScan OSINT 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: OSINT
  description: Open source intelligence tools for domain analysis
paths:
  /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:
      - OSINT
      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/rdap/bulk:
    post:
      operationId: bulkGetRdap
      summary: Run multiple raw RDAP lookups
      description: Get raw RDAP data for a homogeneous batch of domains, IP addresses, CIDR ranges, or autonomous system numbers. One type applies to the entire batch. 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:
      - OSINT
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - queries
              properties:
                queries:
                  type: array
                  minItems: 1
                  maxItems: 10
                  items:
                    type: string
                type:
                  type: string
                  enum:
                  - domain
                  - ip
                  - autnum
                  default: domain
            example:
              queries:
              - example.com
              - cloudflare.com
              type: domain
      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/email-auth:
    get:
      tags:
      - OSINT
      summary: Email authentication check
      description: Check DMARC, SPF, DKIM, MTA-STS and TLS-RPT policies, and recursive SPF lookup behavior.
      operationId: getEmailAuth
      parameters:
      - name: domain
        description: Domain whose SPF, DKIM and DMARC configuration should be checked.
        in: query
        required: true
        schema:
          type: string
      - name: selectors
        in: query
        required: false
        description: Optional comma-separated DKIM selectors. At most 50 valid DNS selector names are accepted.
        schema:
          type: string
          example: google,selector1,sendgrid
      responses:
        '200':
          description: Email authentication status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailAuthResponse'
              example:
                domain: google.com
                spf:
                  record: v=spf1 include:_spf.google.com ~all
                  lookup_estimate: 1
                  includes:
                  - _spf.google.com
                  redirect: null
                  macros_present: false
                  macro_references: []
                  lookup_walk_count: 1
                  lookup_limit_exceeded: false
                  walk:
                  - domain: google.com
                    depth: 0
                    record: v=spf1 include:_spf.google.com ~all
                    mechanisms:
                    - include:_spf.google.com
                    - ~all
                    includes:
                    - _spf.google.com
                    redirect: null
                    direct_lookup_count: 1
                    total_lookup_count: 1
                    macros_present: false
                    macro_references: []
                    multiple_records: 1
                  walk_errors: []
                  lookup_tree:
                    root_domain: google.com
                    node_count: 1
                    max_depth: 0
                    cycles_detected: []
                    nodes:
                    - domain: google.com
                      depth: 0
                      status: present
                      direct_lookup_count: 1
                      total_lookup_count: 1
                      includes:
                      - _spf.google.com
                      redirect: null
                      mechanisms:
                      - include:_spf.google.com
                      - ~all
                      errors: []
                    edges:
                    - from: google.com
                      to: _spf.google.com
                      type: include
                dkim:
                - selector: google
                  record: v=DKIM1; k=rsa; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A
                  key_type: rsa
                  key_size: 2048
                dkim_audit:
                  selectors_checked:
                  - google
                  - default
                  - selector1
                  - selector2
                  selectors_found:
                  - selector: google
                    dns_name: google._domainkey.google.com
                    record: v=DKIM1; k=rsa; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A
                    record_type: TXT
                    cname_targets: []
                    provider_hint: Google Workspace
                    key_type: rsa
                    key_size: 2048
                    valid: true
                    revoked: false
                    weak: false
                    hash_algorithms:
                    - sha256
                    service_type: email
                    flags:
                    - s
                    issues: []
                  total_found: 1
                  providers_detected:
                  - Google Workspace
                  valid_selector_count: 1
                  weak_selector_count: 0
                  revoked_selector_count: 0
                bimi:
                  exists: true
                  record: v=BIMI1; l=https://example.com/logo.svg; a=https://example.com/vmc.pem
                  valid: true
                  logo_url: https://example.com/logo.svg
                  authority_url: https://example.com/vmc.pem
                  logo_fetch_ok: true
                  logo_http_status: 200
                  logo_content_type: image/svg+xml
                  logo_bytes: 2048
                  logo_svg_detected: true
                  vmc_present: true
                  vmc_fetched: true
                  vmc_http_status: 200
                  vmc_content_type: application/x-pem-file
                  vmc_certificate_valid: true
                  vmc_subject: /CN=Example Inc VMC
                  vmc_issuer: /CN=Example Issuer
                  vmc_not_before: '2026-01-01T00:00:00Z'
                  vmc_not_after: '2027-01-01T00:00:00Z'
                  vmc_days_to_expiry: 258
                  vmc_fingerprint_sha256: AA:BB:CC:DD
                  vmc_san_domains:
                  - google.com
                  errors: []
                dmarc:
                  record: v=DMARC1; p=reject; rua=mailto:mailauth-reports@google.com
                  tags:
                    v: DMARC1
                    p: reject
                    rua: mailto:mailauth-reports@google.com
                mta_sts:
                  exists: true
                  record: v=STSv1; id=2024010101Z
                  valid: true
                  policy_id: 2024010101Z
                  policy_fetch_ok: true
                  policy_http_status: 200
                  mode: enforce
                  max_age: 86400
                  mx_hosts:
                  - '*.google.com'
                  mx_records:
                  - aspmx.l.google.com
                  policy_matches_mx: true
                  uncovered_mx: []
                  errors: []
                tls_rpt:
                  exists: true
                  record: v=TLSRPTv1; rua=mailto:sts-reports@google.com
                  valid: true
                  rua:
                  - mailto:sts-reports@google.com
                  errors: []
                client_access:
                  provider_hint:
                    id: google_workspace
                    name: Google Workspace
                  mx_records:
                  - aspmx.l.google.com
                  services:
                  - service: imap
                    host: imap.gmail.com
                    port: 993
                    source: provider_default
                    priority: null
                    weight: null
                    tls_mode: implicit
                    reachable: true
                    tls_negotiated: true
                    starttls_offered: null
                    protocol: TLSv1.3
                    cipher: TLS_AES_256_GCM_SHA384
                    certificate:
                      subject: /CN=imap.gmail.com
                      issuer: /CN=WR2
                      not_before: '2026-01-01T00:00:00Z'
                      not_after: '2026-07-01T00:00:00Z'
                      days_to_expiry: 70
                      expired: false
                      san_domains:
                      - imap.gmail.com
                      public_key_type: EC
                      public_key_bits: 256
                      fingerprint_sha256: CC:DD:EE:FF
                      hostname_match: true
                      chain_valid: true
                      chain_error: null
                    chain_depth: 2
                    error: null
                  reachable_service_count: 1
                  secure_service_count: 1
                autodiscover:
                  provider_hint:
                    id: google_workspace
                    name: Google Workspace
                  mx_records:
                  - aspmx.l.google.com
                  srv:
                    autodiscover: []
                    submission: []
                    submissions: []
                    imap: []
                    imaps: []
                    pop3: []
                    pop3s: []
                  thunderbird_autoconfig:
                    subdomain:
                      url: https://autoconfig.google.com/mail/config-v1.1.xml?emailaddress=postmaster%40google.com
                      status_code: 404
                      content_type: text/html
                      final_url: https://autoconfig.google.com/mail/config-v1.1.xml?emailaddress=postmaster%40google.com
                      redirect_count: 0
                      incoming: []
                      outgoing: []
                      error: null
                    well_known:
                      url: https://google.com/.well-known/autoconfig/mail/config-v1.1.xml?emailaddress=postmaster%40google.com
                      status_code: 200
                      content_type: application/xml
                      final_url: https://google.com/.well-known/autoconfig/mail/config-v1.1.xml?emailaddress=postmaster%40google.com
                      redirect_count: 0
                      incoming:
                      - type: imap
                        hostname: imap.gmail.com
                        port: 993
                        socket_type: SSL
                      outgoing:
                      - type: smtp
                        hostname: smtp.gmail.com
                        port: 587
                        socket_type: STARTTLS
                      error: null
                  outlook_autodiscover:
                    url: https://autodiscover.google.com/autodiscover/autodiscover.xml
                    status_code: 401
                    content_type: text/html
                    final_url: https://autodiscover.google.com/autodiscover/autodiscover.xml
                    redirect_count: 0
                    auth_required: true
                    error: null
                  recommended:
                  - service: imap
                    host: imap.gmail.com
                    port: 993
                    tls_mode: implicit
                    source: provider_default
                edge_summary:
                  relay_configured: true
                  evidence_sources:
                  - spf_walk
                  - mail_policies
                  - bimi_audit
                  - dkim_audit
                  - mail_client_access
                  - mail_autodiscover
                  spf_lookup_count: 1
                  spf_lookup_limit_exceeded: false
                  dkim_valid_selector_count: 1
                  dkim_weak_selector_count: 0
                  dkim_revoked_selector_count: 0
                  providers_detected:
                  - Google Workspace
                  mta_sts_enforced: true
                  tls_rpt_configured: true
                  bimi_logo_verified: true
                  vmc_certificate_valid: true
                  client_access_reachable_services: 1
                  client_access_secure_services: 1
                  autodiscover_recommendation_count: 1
                provider_selector_recommendations:
                - provider: Google Workspace
                  selectors:
                  - google
                  - '20230601'
                  - '20210112'
                  source: detected
                  checked_selectors:
                  - google
                  found_selectors:
                  - google
                  missing_selectors:
                  - '20230601'
                  - '20210112'
                grade: A
                notes: []
        '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_request
        default: 3
  /v1/similarity:
    get:
      tags:
      - OSINT
      summary: Domain similarity check
      description: Compare two domains for visual/textual similarity
      operationId: getDomainSimilarity
      parameters:
      - name: domain1
        description: First domain to compare. The alias source is also accepted.
        in: query
        required: true
        schema:
          type: string
      - name: domain2
        description: Second domain to compare. The alias target is also accepted.
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Similarity analysis
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimilarityResponse'
        '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_request
        default: 2
  /v1/mac:
    get:
      tags:
      - OSINT
      summary: MAC address lookup
      description: Identify device manufacturer from MAC address
      operationId: getMacInfo
      parameters:
      - name: mac
        in: query
        required: true
        description: MAC address (any format)
        schema:
          type: string
          example: 00:1A:2B:3C:4D:5E
      responses:
        '200':
          description: MAC vendor information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MacInfoResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          description: Vendor evidence is temporarily unavailable. The request is refunded and can be retried.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: UPSTREAM_UNAVAILABLE
                  message: MAC vendor lookup temporarily unavailable
      x-domscan-credits:
        model: per_request
        default: 1
  /v1/mac/info:
    get:
      tags:
      - OSINT
      summary: Get MAC lookup endpoint details
      description: Returns parameter help and an example response for the MAC address lookup endpoint.
      operationId: getMacLookupInfo
      responses:
        '200':
          description: MAC endpoint reference
          content:
            application/json:
              schema:
                type: object
                properties:
                  endpoint:
                    type: string
                  description:
                    type: string
                  parameters:
                    type: object
                  example_request:
                    type: string
                  example_response:
                    type: object
              example:
                endpoint: /v1/mac
                description: Lookup MAC address metadata and vendor information.
                parameters:
                  mac:
                    type: string
                    required: true
                    description: MAC address string in any common format
                    example: 44:38:39:ff:ef:57
                example_request: /v1/mac?mac=44:38:39:ff:ef:57
                example_response:
                  mac: 44:38:39:FF:EF:57
                  type: eui-48
                  oui: '44:38:39'
                  device_id: FF:EF:57
                  flags:
                    multicast: false
                    locally_administered: false
                    broadcast: false
                  vendor:
                    name: Cumulus Networks, Inc
                    found: true
                    source: cache
                    cached: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
      x-domscan-credits:
        model: per_request
        default: 0
  /v1/report:
    get:
      tags:
      - OSINT
      summary: Comprehensive domain report
      description: Full domain intelligence report combining all available data
      operationId: getFullReport
      parameters:
      - name: domain
        description: Domain to build the combined report for.
        in: query
        required: true
        schema:
          type: string
      - name: sections
        in: query
        required: false
        description: Comma-separated report sections to include.
        schema:
          type: string
          example: availability,dns,whois,ssl
      responses:
        '200':
          description: Comprehensive report
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FullReportResponse'
        '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_request
        default: 5
components:
  schemas:
    SimilarityResponse:
      type: object
      description: Domain similarity analysis
      properties:
        domain1:
          type: string
        domain2:
          type: string
        overall_similarity:
          type: number
          minimum: 0
          maximum: 100
        risk_level:
          type: string
          enum:
          - none
          - low
          - medium
          - high
          - critical
        analysis:
          type: object
          properties:
            levenshtein_distance:
              type: integer
            levenshtein_similarity:
              type: number
              minimum: 0
              maximum: 100
            jaro_winkler_similarity:
              type: number
              minimum: 0
              maximum: 100
            visual_similarity:
              type: number
              minimum: 0
              maximum: 100
            keyboard_distance:
              type: number
            common_prefix_length:
              type: integer
            common_suffix_length:
              type: integer
        matching_methods:
          type: array
          items:
            type: string
        is_potential_typosquat:
          type: boolean
        checked_at:
          type: string
          format: date-time
        meta:
          type: object
          additionalProperties: true
    SpfLookupTree:
      type: object
      description: Recursive SPF lookup graph with per-node status, includes, redirects, and cycle/limit visibility.
      properties:
        root_domain:
          type: string
        node_count:
          type: integer
        max_depth:
          type: integer
        cycles_detected:
          type: array
          items:
            type: string
        nodes:
          type: array
          items:
            type: object
            properties:
              domain:
                type: string
              depth:
                type: integer
              status:
                type: string
                enum:
                - present
                - missing
                - cycle
                - error
                - limit_exceeded
              direct_lookup_count:
                type: integer
              total_lookup_count:
                type: integer
              includes:
                type: array
                items:
                  type: string
              redirect:
                type:
                - string
                - 'null'
              mechanisms:
                type: array
                items:
                  type: string
              errors:
                type: array
                items:
                  type: string
        edges:
          type: array
          items:
            type: object
            properties:
              from:
                type: string
              to:
                type: string
              type:
                type: string
                enum:
                - include
                - redirect
    EmailAuthResponse:
      type: object
      description: Email authentication (SPF/DKIM/DMARC) status with BIMI/VMC, MTA-STS, and TLS-RPT checks
      properties:
        domain:
          type: string
        spf:
          type: object
          properties:
            record:
              type:
              - string
              - 'null'
            lookup_estimate:
              type: integer
            includes:
              type: array
              items:
                type: string
            redirect:
              type:
              - string
              - 'null'
            macros_present:
              type: boolean
            macro_references:
              type: array
              items:
                type: string
            lookup_walk_count:
              type: integer
            lookup_limit_exceeded:
              type: boolean
            walk:
              type: array
              description: Extended recursive SPF analysis with macro detection.
              items:
                type: object
                properties:
                  domain:
                    type: string
                  depth:
                    type: integer
                  record:
                    type: string
                  mechanisms:
                    type: array
                    items:
                      type: string
                  includes:
                    type: array
                    items:
                      type: string
                  redirect:
                    type:
                    - string
                    - 'null'
                  direct_lookup_count:
                    type: integer
                  total_lookup_count:
                    type: integer
                  macros_present:
                    type: boolean
                  macro_references:
                    type: array
                    items:
                      type: string
                  multiple_records:
                    type: integer
            walk_errors:
              type: array
              items:
                type: string
            lookup_tree:
              $ref: '#/components/schemas/SpfLookupTree'
        dkim:
          type: array
          items:
            type: object
            properties:
              selector:
                type: string
              record:
                type:
                - string
                - 'null'
              key_type:
                type:
                - string
                - 'null'
              key_size:
                type:
                - integer
                - 'null'
        dkim_audit:
          type: object
          description: Extended DKIM selector discovery and key-strength audit.
          properties:
            selectors_checked:
              type: array
              items:
                type: string
            selectors_found:
              type: array
              items:
                type: object
                properties:
                  selector:
                    type: string
                  dns_name:
                    type: string
                  record:
                    type:
                    - string
                    - 'null'
                  record_type:
                    type:
                    - string
                    - 'null'
                    enum:
                    - TXT
                    - CNAME
                  cname_targets:
                    type: array
                    items:
                      type: string
                  provider_hint:
                    type:
                    - string
                    - 'null'
                  key_type:
                    type:
                    - string
                    - 'null'
                  key_size:
                    type:
                    - integer
                    - 'null'
                  valid:
                    type: boolean
                  revoked:
                    type: boolean
                  weak:
                    type: boolean
                  hash_algorithms:
                    type: array
                    items:
                      type: string
                  service_type:
                    type:
                    - string
                    - 'null'
                  flags:
                    type: array
                    items:
                      type: string
                  issues:
                    type: array
                    items:
                      type: string
            total_found:
              type: integer
            providers_detected:
              type: array
              items:
                type: string
            valid_selector_count:
              type: integer
            weak_selector_count:
              type: integer
            revoked_selector_count:
              type: integer
        bimi:
          type: object
          description: Extended BIMI logo and VMC validation.
          properties:
            exists:
              type: boolean
            record:
              type:
              - string
              - 'null'
            valid:
              type: boolean
            logo_url:
              type:
              - string
              - 'null'
            authority_url:
              type:
              - string
              - 'null'
            logo_fetch_ok:
              type:
              - boolean
              - 'null'
            logo_http_status:
              type:
              - integer
              - 'null'
            logo_content_type:
              type:
              - string
              - 'null'
            logo_bytes:
              type:
              - integer
              - 'null'
            logo_svg_detected:
              type:
              - boolean
              - 'null'
            vmc_present:
              type: boolean
            vmc_fetched:
              type:
              - boolean
              - 'null'
            vmc_http_status:
              type:
              - integer
              - 'null'
            vmc_content_type:
              type:
              - string
              - 'null'
            vmc_certificate_valid:
              type:
              - boolean
              - 'null'
            vmc_subject:
              type:
              - string
              - 'null'
            vmc_issuer:
              type:
              - string
              - 'null'
            vmc_not_before:
              type:
              - string
              - 'null'
              format: date-time
            vmc_not_after:
              type:
              - string
              - 'null'
              format: date-time
            vmc_days_to_expiry:
              type:
              - integer
              - 'null'
            vmc_fingerprint_sha256:
              type:
              - string
              - 'null'
            vmc_san_domains:
              type: array
              items:
                type: string
            errors:
              type: array
              items:
                type: string
        dmarc:
          type: object
    

# --- truncated at 32 KB (59 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/domscan/refs/heads/main/openapi/domscan-osint-api-openapi.yml