openapi: 3.2.0
info:
  title: DomScan Domain Availability 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 Availability
  description: Check if domains are available for registration using RDAP
paths:
  /v1/status:
    get:
      tags:
      - Domain Availability
      summary: Check domain availability
      description: Check if a domain name is available for registration across multiple TLDs. Uses RDAP for authoritative results. Provide either the primary `name` + `tlds` format, or the single-domain shortcut `domain=example.com`.
      operationId: checkDomainAvailability
      parameters:
      - name: name
        in: query
        required: false
        description: Domain name without TLD. Use together with tlds (e.g., "example" for example.com)
        schema:
          type: string
          minLength: 1
          maxLength: 63
          example: mycompany
      - name: tlds
        in: query
        required: false
        description: Comma-separated list of TLDs to check (max 50). Use together with name.
        schema:
          type: string
          example: com,net,org,io
      - name: domain
        in: query
        required: false
        description: Single-domain shortcut for one TLD, for example "mycompany.com"
        schema:
          type: string
          example: mycompany.com
      - name: prefer_cache
        in: query
        description: Return cached results if available (faster)
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: Availability check results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
              example:
                name: mycompany
                results:
                - domain: mycompany.com
                  tld: com
                  available: false
                  source: rdap
                  latency_ms: 45
                - domain: mycompany.io
                  tld: io
                  available: true
                  source: rdap
                  latency_ms: 67
                meta:
                  total_checked: 2
                  available_count: 1
                  duration_ms: 120
        '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: 1
  /v1/status/bulk:
    post:
      tags:
      - Domain Availability
      summary: Bulk domain availability check
      description: 'Check availability of multiple full domain names at once. Domains are checked in parallel for optimal performance. Results include availability status, source (RDAP or cache), and latency.


        **Credits:** 1 credit per domain. Example: 10 domains = 10 credits, 50 domains = 50 credits.'
      operationId: bulkCheckDomains
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - domains
              properties:
                domains:
                  type: array
                  items:
                    type: string
                  minItems: 1
                  maxItems: 50
                  description: Array of full domain names to check
                  example:
                  - example.com
                  - startup.io
                  - brand.ai
                prefer_cache:
                  type: boolean
                  default: false
                  description: Return cached results if available (faster but may be stale)
      responses:
        '200':
          description: Bulk check results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkStatusResponse'
              example:
                results:
                - domain: example.com
                  tld: com
                  available: false
                  source: rdap
                  latency_ms: 45
                - domain: startup.io
                  tld: io
                  available: true
                  source: rdap
                  latency_ms: 67
                - domain: brand.ai
                  tld: ai
                  available: true
                  source: cache
                  latency_ms: 2
                meta:
                  total_checked: 3
                  available_count: 2
                  duration_ms: 120
        '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: 1
  /v1/domain-discovery/jobs:
    post:
      tags:
      - Domain Availability
      summary: Create an asynchronous domain discovery job
      description: Queue one cursor-paginated page from a curated English single-word corpus sourced from iannuttall/unclaimed under the MIT License. Filters are applied before page selection. Every selected word is checked across every requested TLD, and each word-TLD pair counts toward the hard limit of 100 checks per job and uses normal /v1/status pricing. Poll, retrieve results, or cancel the returned job through the existing /v1/batches endpoints. Use next_cursor to continue the filtered search. Unknown outcomes are preserved and are never reported as available.
      operationId: createDomainDiscoveryJob
      parameters:
      - name: Idempotency-Key
        in: header
        required: false
        description: Optional idempotency key for safe job creation retries. Reusing the key with the same payload returns the existing job; reusing it with a different payload returns 409.
        schema:
          type: string
          minLength: 1
          maxLength: 120
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
              - tlds
              properties:
                tlds:
                  type: array
                  minItems: 1
                  maxItems: 5
                  description: Supported TLDs to check, from 1 to 5 entries. Values are normalized and duplicates collapse before limits and billing are calculated. Each unique TLD creates one domain check for every word in the page.
                  items:
                    type: string
                    minLength: 1
                    maxLength: 253
                    pattern: ^\.?[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?(?:\.[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?)*$
                    example: io
                limit:
                  type: integer
                  minimum: 1
                  maximum: 100
                  description: Maximum corpus words to include in this page. limit multiplied by the number of unique TLDs must not exceed 100. By default, DomScan selects the largest page that stays within that cap.
                cursor:
                  type: string
                  minLength: 1
                  maxLength: 512
                  description: Opaque server-issued cursor from next_cursor on the previous discovery job. Omit it to start at the first filtered page. The cursor is bound to the corpus version, TLDs, and filter values; changing them returns 400.
                min_length:
                  type: integer
                  minimum: 1
                  maximum: 63
                  default: 3
                  description: Minimum corpus word length, inclusive. Must not exceed max_length when both are provided.
                max_length:
                  type: integer
                  minimum: 1
                  maximum: 63
                  default: 16
                  description: Maximum corpus word length, inclusive. Must be greater than or equal to min_length when both are provided.
                singular_only:
                  type: boolean
                  default: false
                  description: When true, exclude corpus entries that match the bundled corpus regular-plural heuristic.
            example:
              tlds:
              - io
              - ai
              limit: 50
              min_length: 4
              max_length: 8
              singular_only: true
      responses:
        '200':
          description: Existing discovery batch returned for an idempotent replay
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DomainDiscoveryJobResponse'
        '202':
          description: Discovery batch accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DomainDiscoveryJobResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '409':
          description: Idempotency key was reused with different discovery input
        '429':
          $ref: '#/components/responses/RateLimited'
      x-domscan-credits:
        model: per_item
        default: 1
        note: Each word-TLD pair uses the normal /v1/status credit cost, currently 1 credit. Billing and any eligible item refunds follow /v1/status behavior.
components:
  schemas:
    StatusResponse:
      type: object
      description: Domain availability check response
      properties:
        name:
          type: string
          description: Base domain name (without TLD)
        results:
          type: array
          items:
            $ref: '#/components/schemas/AvailabilityResult'
        confidence_summary:
          $ref: '#/components/schemas/AvailabilityConfidenceSummary'
        meta:
          type: object
          properties:
            total_checked:
              type: integer
              description: Number of TLDs checked
            available_count:
              type: integer
              description: Number of available domains
            duration_ms:
              type: integer
              description: Total check duration
    AvailabilityResult:
      type: object
      description: Single domain availability result
      properties:
        domain:
          type: string
          description: Full domain name
        tld:
          type: string
          description: Top-level domain
        available:
          type:
          - boolean
          - 'null'
          description: Whether domain is available for registration. null when status cannot be determined (e.g. RDAP and WHOIS both unavailable)
        source:
          type: string
          enum:
          - rdap
          - cache
          - dns
          - whois
          description: Data source used for check
        confidence:
          type: string
          enum:
          - authoritative
          - heuristic
          description: Result confidence level. "authoritative" for RDAP registry data, "heuristic" for DNS/WHOIS/cache fallbacks. Heuristic results may have false positives (e.g. parked domains without NS records may appear available)
        checked_at:
          type: string
          format: date-time
          description: Timestamp of check
        latency_ms:
          type: integer
          description: Check latency in milliseconds
        error:
          type: string
          description: Error message if check failed
    BulkStatusResponse:
      type: object
      description: Bulk domain availability check response
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/AvailabilityResult'
        confidence_summary:
          $ref: '#/components/schemas/AvailabilityConfidenceSummary'
        meta:
          type: object
          properties:
            total_checked:
              type: integer
            available_count:
              type: integer
            duration_ms:
              type: integer
    DomainDiscoveryJobResponse:
      type: object
      required:
      - job
      - discovery
      properties:
        job:
          $ref: '#/components/schemas/ApiBatchJob'
        discovery:
          type: object
          required:
          - corpus
          - corpus_version
          - total_matching_words
          - page_offset
          - page_words
          - domain_checks
          - tlds
          - filters
          - credits_per_domain
          - next_cursor
          properties:
            corpus:
              type: string
              enum:
              - iannuttall/unclaimed
            corpus_version:
              type: string
            total_matching_words:
              type: integer
              minimum: 1
            page_offset:
              type: integer
              minimum: 0
            page_words:
              type: integer
              minimum: 1
              maximum: 100
            domain_checks:
              type: integer
              minimum: 1
              maximum: 100
            tlds:
              type: array
              minItems: 1
              maxItems: 5
              items:
                type: string
            filters:
              type: object
              required:
              - min_length
              - max_length
              - singular_only
              properties:
                min_length:
                  type: integer
                  minimum: 1
                  maximum: 63
                max_length:
                  type: integer
                  minimum: 1
                  maximum: 63
                singular_only:
                  type: boolean
            credits_per_domain:
              type: integer
              minimum: 0
              description: Normal /v1/status cost at job creation time.
            next_cursor:
              type:
              - string
              - 'null'
              description: Opaque cursor for the next page of the filtered corpus. Null when the corpus is exhausted.
    ApiBatchJob:
      type: object
      required:
      - id
      - status
      - total
      - counts
      - billing
      - webhook
      - status_url
      - results_url
      - results_csv_url
      - created_at
      - updated_at
      - processing_deadline_at
      - results_expires_at
      properties:
        id:
          type: string
          pattern: ^bat_[a-f0-9]{32}$
        status:
          type: string
          enum:
          - queued
          - running
          - cancelling
          - completed
          - completed_with_errors
          - cancelled
        total:
          type: integer
          minimum: 1
          maximum: 100
        counts:
          type: object
          required:
          - pending
          - processing
          - succeeded
          - failed
          - cancelled
          properties:
            pending:
              type: integer
            processing:
              type: integer
            succeeded:
              type: integer
            failed:
              type: integer
            cancelled:
              type: integer
        billing:
          type: object
          required:
          - credits_charged
          - credits_refunded
          - credits_net
          properties:
            credits_charged:
              type: integer
            credits_refunded:
              type: integer
            credits_net:
              type: integer
        webhook:
          type: object
          required:
          - configured
          - status
          - attempts
          properties:
            configured:
              type: boolean
            status:
              type: string
              enum:
              - not_configured
              - waiting
              - pending
              - delivering
              - delivered
              - failed
            attempts:
              type: integer
        status_url:
          type: string
          format: uri
        results_url:
          type: string
          format: uri
        results_csv_url:
          type: string
          format: uri
        poll_after_ms:
          type:
          - integer
          - 'null'
        created_at:
          type: string
          format: date-time
        started_at:
          type:
          - string
          - 'null'
          format: date-time
        completed_at:
          type:
          - string
          - 'null'
          format: date-time
        cancelled_at:
          type:
          - string
          - 'null'
          format: date-time
        updated_at:
          type: string
          format: date-time
        processing_deadline_at:
          type: string
          format: date-time
        results_expires_at:
          type: string
          format: date-time
    AvailabilityConfidenceSummary:
      type: object
      description: Additive availability confidence rollup showing source mix, cache state, fallback chain, and ambiguity.
      properties:
        scope:
          type: string
          enum:
          - precise
          - estimate
        requested_count:
          type: integer
        result_count:
          type: integer
        invalid_count:
          type: integer
        available_count:
          type: integer
        registered_count:
          type: integer
        authoritative_count:
          type: integer
        heuristic_count:
          type: integer
        cached_count:
          type: integer
        error_count:
          type: integer
        ambiguous_count:
          type: integer
        source_counts:
          type: object
          additionalProperties:
            type: integer
        primary_source:
          type:
          - string
          - 'null'
        cache_status:
          type: string
          enum:
          - hit
          - miss
          - mixed
          - none
        rdap_calls:
          type: integer
        refreshes:
          type: integer
        cache_preference_misses:
          type: integer
        fallback_chain:
          type: array
          items:
            type: string
        confidence_level:
          type: string
          enum:
          - high
          - medium
          - low
        determinacy_rate:
          type: number
          minimum: 0
          maximum: 1
        ambiguity_reason:
          type:
          - string
          - 'null'
          enum:
          - errors_present
          - heuristic_dns_fallback
          - unknown_status
    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
  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
    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
  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