openapi: 3.2.0 info: title: DomScan Domain Health 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: Domain Health description: Comprehensive domain health analysis including DNS, SSL, and security paths: /v1/health: get: tags: - Domain Health summary: Full domain health check description: 'Comprehensive health analysis: DNS configuration, SSL certificates, email authentication records, security headers, and more. Accepts a subdomain (e.g. blog.example.com) as well as a registrable domain. Host-based checks run against the exact hostname, while registration and age data reflect the parent domain. Deprecated SMTP port probing is no longer performed.' operationId: getDomainHealth parameters: - name: domain in: query required: true description: Domain or subdomain to analyze (e.g. example.com or blog.example.com) schema: type: string example: example.com - name: details in: query description: Include detailed breakdown schema: type: boolean default: true responses: '200': description: Health check results content: application/json: schema: $ref: '#/components/schemas/HealthResponse' example: domain: cloudflare.com health_score: 94 grade: A checks: dns_configured: true ssl_valid: true email_deliverable: true blacklist_status: clean age_years: 15 registration_stable: true dnssec_enabled: true enriched: tls: grade: A+ protocol: TLSv1.3 cipher: TLS_AES_256_GCM_SHA384 chain_valid: true days_to_expiry: 72 hostname_match: true ocsp_stapling: true grade_reasons: - TLS 1.3 enabled - Valid certificate chain http_versions: http1_1: true http2: true http3: true alt_svc: h3=":443"; ma=86400 http3_advertised: true alt_svc_protocols: - h3 curl_http3_supported: true h2_alpn_accepted: h2 h3_alpn_accepted: h3 hsts: reachable: true final_url: https://cloudflare.com/ status_code: 200 header_present: true hsts_header: max-age=31536000; includeSubDomains max_age: 31536000 include_subdomains: true preload_directive: false preload_eligible: true preload_status: preloaded preloaded_domain: cloudflare.com preload_bulk: false issues: - missing preload directive errors: [] warnings: [] recommendations: - Publish the HSTS preload directive if you want preload-list eligibility. checked_at: '2026-04-18T21:00:00Z' details: dns: has_a_record: true has_aaaa_record: true has_nameservers: true has_mx_record: true nameservers: - ns3.cloudflare.com - ns5.cloudflare.com mx_records: - route1.mx.cloudflare.net a_records: - 104.16.132.229 - 104.16.133.229 aaaa_records: - 2606:4700::6810:84e5 - 2606:4700::6810:85e5 ssl: https_works: true certificate_valid: true days_until_expiry: 72 issuer: Google Trust Services email: has_mx: true has_spf: true has_dmarc: true has_dkim_selector: true spf_record: v=spf1 include:_spf.google.com ~all dmarc_policy: reject mx_hosts: - route1.mx.cloudflare.net security: dnssec_enabled: true has_caa_record: true caa_issuers: - digicert.com - letsencrypt.org http_to_https_redirect: true has_security_txt: true security_txt_fields: - Contact - Expires - Preferred-Languages security_headers: has_hsts: true hsts_max_age: 31536000 has_csp: true has_x_frame_options: true has_x_content_type_options: true has_referrer_policy: true has_permissions_policy: true score: 92 age: registration_date: '2010-07-06T00:00:00Z' expiration_date: '2030-07-06T00:00:00Z' last_updated: '2025-07-06T00:00:00Z' age_days: 5766 age_years: 15 days_until_expiry: 1540 registrar: Cloudflare Registrar blacklist: clean: true status: clean listed_on: [] checked_lists: - spamhaus - surbl domain_listed_on: [] ip_listed_on: [] check_type: mixed health_checks: - category: dns name: Authoritative DNS records present passed: true score: 100 weight: 15 meta: check_duration_ms: 248 served_by: pop=MAD country=ES '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/PaymentRequired' '429': $ref: '#/components/responses/RateLimited' x-domscan-credits: model: per_request default: 3 /v1/health/quick: get: tags: - Domain Health summary: Quick health check description: Fast health check focusing on DNS resolution and SSL certificate status. Accepts a subdomain (e.g. blog.example.com) as well as a registrable domain. operationId: getQuickHealth parameters: - name: domain in: query required: true description: Domain or subdomain to check (e.g. example.com or blog.example.com) schema: type: string example: example.com responses: '200': description: Quick health results content: application/json: schema: $ref: '#/components/schemas/QuickHealthResponse' example: domain: example.com dns_ok: true https_ok: true checked_at: '2026-04-18T21:00:00Z' meta: check_duration_ms: 89 '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/PaymentRequired' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' x-domscan-credits: model: per_request default: 1 /v1/health/bulk: post: tags: - Domain Health summary: Bulk health check description: 'Check health of multiple domains at once. Use quick=true for faster results with basic DNS/SSL checks only. **Credits:** 3 credits per domain. Example: 10 domains = 30 credits.' operationId: bulkHealthCheck requestBody: required: true content: application/json: schema: type: object required: - domains properties: domains: type: array items: type: string minItems: 1 maxItems: 10 description: Array of domains or subdomains to check (max 10) example: - example.com - google.com quick: type: boolean default: false description: Use quick check mode (DNS + SSL only) responses: '200': description: Bulk health results content: application/json: schema: $ref: '#/components/schemas/BulkHealthResponse' '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 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. InternalError: description: Unexpected service error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 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 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: BulkHealthResponse: type: object description: Bulk health check results properties: results: type: array items: type: object properties: domain: type: string health_score: type: integer grade: type: string checks: type: object warnings: type: array items: type: string error: type: string meta: type: object properties: total: type: integer successful: type: integer check_duration_ms: type: integer QuickHealthResponse: type: object description: Quick health check (DNS + SSL only) properties: domain: type: string dns_ok: type: - boolean - 'null' description: Whether DNS resolves correctly; null when resolver checks were unavailable. https_ok: type: - boolean - 'null' description: Whether HTTPS responds successfully; null when its DNS prerequisite is unknown. dns_complete: type: boolean description: Whether every DNS query needed by the quick check completed. checked_at: type: string format: date-time confidence: $ref: '#/components/schemas/QuickHealthConfidence' meta: type: object properties: check_duration_ms: type: integer QuickHealthConfidence: type: object description: Additive quick-health confidence object for DNS and HTTPS checks. properties: checks_run: type: array items: type: string enum: - dns - https passed_count: type: integer failed_count: type: integer unknown_count: type: integer confidence: type: string enum: - high - medium - low dns_ok: type: - boolean - 'null' https_ok: type: - boolean - 'null' HealthComponentSummary: type: object description: Additive full-health rollup for component pass/fail counts, warnings, recommendations, and optional enrichment coverage. properties: score: type: integer minimum: 0 maximum: 100 grade: type: string enum: - A - B - C - D - F check_count: type: integer passed_count: type: integer failed_count: type: integer warning_count: type: integer recommendation_count: type: integer confidence: type: string enum: - high - medium - low dns_ok: type: boolean https_ok: type: boolean email_ok: type: boolean blacklist_status: type: string enum: - clean - listed - unknown dnssec_enabled: type: boolean enriched_section_count: type: integer enriched_sections: type: array items: type: string HealthResponse: type: object description: Comprehensive domain health check response properties: domain: type: string description: Domain checked health_score: type: integer minimum: 0 maximum: 100 description: Overall health score grade: type: string enum: - A - B - C - D - F description: Health grade checks: type: object description: Individual check results properties: dns_configured: type: boolean ssl_valid: type: boolean email_deliverable: type: boolean blacklist_status: type: string enum: - clean - listed - unknown age_years: type: - integer - 'null' registration_stable: type: boolean dnssec_enabled: type: boolean enriched: type: object description: 'HLTH-003/006/008/009: additive supplemental probes. Only present when optional enrichment is configured and at least one probe returned data.' properties: tls: type: object description: Full TLS handshake introspection (HLTH-003 / REP-002). properties: grade: type: string enum: - A+ - A - B - C - F protocol: type: - string - 'null' cipher: type: - string - 'null' chain_valid: type: boolean days_to_expiry: type: integer hostname_match: type: - boolean - 'null' ocsp_stapling: type: boolean grade_reasons: type: array items: type: string http_versions: type: object description: 'HLTH-008: HTTP/1.1, HTTP/2, HTTP/3 support.' properties: http1_1: type: boolean http2: type: boolean http3: type: boolean alt_svc: type: - string - 'null' http3_advertised: type: boolean alt_svc_protocols: type: array items: type: string curl_http3_supported: type: boolean h2_alpn_accepted: type: - string - 'null' h3_alpn_accepted: type: - string - 'null' hsts: type: object description: 'HLTH-023: live HSTS header and preload-list audit from the proxy.' properties: reachable: type: boolean final_url: type: - string - 'null' status_code: type: - integer - 'null' header_present: type: boolean hsts_header: type: - string - 'null' max_age: type: - integer - 'null' include_subdomains: type: - boolean - 'null' preload_directive: type: - boolean - 'null' preload_eligible: type: boolean preload_status: type: - string - 'null' preloaded_domain: type: - string - 'null' preload_bulk: type: - boolean - 'null' issues: type: array items: type: string errors: type: array items: type: string smtp: type: object deprecated: true description: Deprecated legacy field. Health checks no longer perform SMTP port probes and this field is no longer emitted. properties: host: type: string port: type: integer reachable: type: boolean tls_mode: type: string enum: - implicit - starttls tls_negotiated: type: boolean tls_protocol: type: string tls_cipher: type: string starttls_offered: type: - boolean - 'null' banner: type: string error: type: string description: Failure detail when neither probed SMTP TLS path responded successfully. fcrdns: type: object description: 'HLTH-019: forward-confirmed reverse DNS check for the primary MX hostname.' properties: addresses: type: array items: type: string ptr_hostnames: type: array items: type: string all_forward_confirmed: type: boolean confirmed_addresses: type: array items: type: string unconfirmed_addresses: type: array items: type: string warnings: type: array items: type: string description: Warning messages recommendations: type: array items: type: string description: Improvement recommendations component_summary: $ref: '#/components/schemas/HealthComponentSummary' details: type: object description: Detailed check results health_checks: type: array description: Weighted per-check scoring details. Only present when details are included. items: type: object properties: category: type: string name: type: string passed: type: boolean score: type: integer weight: type: integer details: type: - string - 'null' checked_at: type: string format: date-time meta: type: object properties: check_duration_ms: type: integer served_by: type: string 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