openapi: 3.2.0
info:
  title: DomScan IP Intelligence 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: IP Intelligence
  description: IP geolocation, ASN lookup, and reverse DNS
paths:
  /v1/ip:
    get:
      tags:
      - IP Intelligence
      summary: IP geolocation lookup
      description: Get nested geolocation, ASN, security, datacenter classification, and FCrDNS info for an IP or a domain resolved to IP.
      operationId: getIpInfo
      parameters:
      - name: ip
        in: query
        description: IP address to analyze. Provide either ip or domain.
        required: false
        schema:
          type: string
          example: 8.8.8.8
      - name: domain
        in: query
        description: Domain or subdomain hostname to resolve and analyze. Provide either domain or ip.
        required: false
        schema:
          type: string
          example: status.openai.com
      responses:
        '200':
          description: IP geolocation data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IpInfoResponse'
              example:
                ip: 8.8.8.8
                domain: null
                geolocation:
                  country: US
                  country_name: United States
                  region: null
                  region_name: California
                  city: Mountain View
                  postal: null
                  latitude: 37.422
                  longitude: -122.085
                  timezone: null
                  precision: city
                network:
                  asn: 15169
                  asn_name: AS15169
                  asn_org: Google LLC
                  isp: null
                  connection_type: hosting
                security:
                  is_proxy: false
                  is_vpn: false
                  is_tor: false
                  is_tor_exit: false
                  is_datacenter: true
                  is_cloud: true
                  cloud_provider: Google Cloud
                  threat_score: 0
                  type_classification:
                    type: datacenter
                    confidence: high
                  fcrdns:
                    ptr: dns.google
                    fcrdns_valid: true
                intelligence_summary:
                  query_type: ip
                  domain_resolved: false
                  cache_status: miss
                  data_source: db-ip-lite+enrichment
                  confidence: high
                  confidence_score: 100
                  asn_present: true
                  organization_present: true
                  country_present: true
                  security_signal_count: 2
                  risk_flags:
                  - cloud
                  - datacenter
                  hosting_category: cloud
                meta:
                  query_time_ms: 118
                  cached: false
                  source: db-ip-lite+enrichment
                  data_updated_at: '2026-08-01T01:42:04.000Z'
                  attribution:
                    name: DB-IP Lite
                    url: https://db-ip.com
                    license: CC BY 4.0
                    license_url: https://creativecommons.org/licenses/by/4.0/
                    modified: true
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          description: The IP intelligence dataset is temporarily unavailable. The request credits are refunded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: UPSTREAM_UNAVAILABLE
                  message: Service temporarily unavailable
                  suggestion: Try again in a moment
                  retry_after: 300
        '504':
          description: IP lookup timed out
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-domscan-credits:
        model: per_request
        default: 1
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
    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:
    IpIntelligenceSummary:
      type: object
      description: Compact source, confidence, ASN, security signal, and hosting-category summary for IP intelligence responses.
      properties:
        query_type:
          type: string
          enum:
          - ip
          - domain
        domain_resolved:
          type: boolean
        cache_status:
          type: string
          enum:
          - hit
          - miss
        data_source:
          type: string
        confidence:
          type: string
          enum:
          - high
          - medium
          - low
        confidence_score:
          type: integer
          minimum: 0
          maximum: 100
        asn_present:
          type: boolean
        organization_present:
          type: boolean
        country_present:
          type: boolean
        security_signal_count:
          type: integer
        risk_flags:
          type: array
          items:
            type: string
        hosting_category:
          type: string
          enum:
          - cloud
          - datacenter
          - residential
          - unknown
    IpInfoResponse:
      type: object
      description: IP geolocation and intelligence data. IP-intrinsic enrichment is cached independently from any caller-supplied domain; rDNS classification uses the returned PTR hostname.
      properties:
        ip:
          type: string
        domain:
          type:
          - string
          - 'null'
        geolocation:
          type: object
          properties:
            country:
              type:
              - string
              - 'null'
            country_name:
              type:
              - string
              - 'null'
            region:
              type:
              - string
              - 'null'
            region_name:
              type:
              - string
              - 'null'
            city:
              type:
              - string
              - 'null'
            postal:
              type:
              - string
              - 'null'
            latitude:
              type:
              - number
              - 'null'
            longitude:
              type:
              - number
              - 'null'
            timezone:
              type:
              - string
              - 'null'
            precision:
              type: string
              enum:
              - city
              - region
              - country
              - unknown
        network:
          type: object
          properties:
            asn:
              type:
              - integer
              - 'null'
            asn_name:
              type:
              - string
              - 'null'
            asn_org:
              type:
              - string
              - 'null'
            isp:
              type:
              - string
              - 'null'
            connection_type:
              type:
              - string
              - 'null'
        security:
          type: object
          properties:
            is_proxy:
              type: boolean
            is_vpn:
              type: boolean
            is_tor:
              type: boolean
            is_tor_exit:
              type: boolean
            is_datacenter:
              type: boolean
            is_cloud:
              type: boolean
            cloud_provider:
              type:
              - string
              - 'null'
            threat_score:
              type: integer
            is_vpn_suspected:
              type: boolean
            vpn_suspected_provider:
              type:
              - string
              - 'null'
            type_classification:
              type:
              - object
              - 'null'
              properties:
                type:
                  type: string
                  enum:
                  - datacenter
                  - residential
                  - unknown
                confidence:
                  type: string
                  enum:
                  - high
                  - medium
                  - low
            fcrdns:
              type:
              - object
              - 'null'
              properties:
                ptr:
                  type:
                  - string
                  - 'null'
                fcrdns_valid:
                  type:
                  - boolean
                  - 'null'
        intelligence_summary:
          $ref: '#/components/schemas/IpIntelligenceSummary'
        meta:
          type: object
          properties:
            query_time_ms:
              type: integer
            cached:
              type: boolean
            source:
              type: string
            data_updated_at:
              type:
              - string
              - 'null'
              format: date-time
            attribution:
              type: object
              properties:
                name:
                  type: string
                  example: DB-IP Lite
                url:
                  type: string
                  format: uri
                  example: https://db-ip.com
                license:
                  type: string
                  example: CC BY 4.0
                license_url:
                  type: string
                  format: uri
                  example: https://creativecommons.org/licenses/by/4.0/
                modified:
                  type: boolean
                  description: True because DomScan normalizes and combines the source fields.
                  example: true
            warning_code:
              type:
              - string
              - 'null'
              description: Reserved for partial non-critical enrichment warnings. Core IP dataset unavailability returns HTTP 503.
    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