rdapapi-io Nameserver API

openapi: 3.2.0
info:
  title: RDAP Nameserver API
  description: 'Normalized RDAP data for any domain, IP, ASN, nameserver or entity: one JSON shape across

    1,200+ TLDs, read from WHOIS where a registry has no RDAP server.


    **Get started:** pick a plan (7-day free trial), create a key on

    your dashboard, and send it as a Bearer token:


    ```bash

    curl https://rdapapi.io/api/v1/domain/google.com \

    -H "Authorization: Bearer YOUR_API_KEY"

    ```


    AI agents can use the same lookups over MCP.'
  version: 1.0.0
  contact:
    name: RDAP API Support
    url: https://rdapapi.io/contact
servers:
- url: https://rdapapi.io/api/v1
  description: Production
security:
- bearerAuth: []
tags:
- name: Nameserver
  description: Look up a nameserver host record, for the registries that publish one.
paths:
  /nameserver/{host}:
    get:
      operationId: lookupNameserver
      summary: Nameserver Lookup
      description: Registration data for a nameserver hostname, from the registries that publish one.
      tags:
      - Nameserver
      parameters:
      - name: host
        in: path
        required: true
        description: Nameserver hostname to look up
        schema:
          type: string
          example: ns1.google.com
      responses:
        '200':
          description: Successful lookup
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NameserverResponse'
              example:
                ldh_name: ns1.google.com
                unicode_name: null
                handle: NS1.GOOGLE.COM
                ip_addresses:
                  v4:
                  - 216.239.32.10
                  v6:
                  - 2001:4860:4802:32::a
                status:
                - active
                dates:
                  registered: '2004-01-01T00:00:00Z'
                  expires: null
                  updated: '2024-06-15T12:00:00Z'
                entities: {}
                meta:
                  server: rdap.verisign.com
                  source: rdap
                  rdap_server: https://rdap.verisign.com/com/v1/
                  raw_rdap_url: https://rdap.verisign.com/com/v1/nameserver/ns1.google.com
                  cached: false
                  cache_expires: '2026-02-24T15:30:00Z'
        '400':
          description: Invalid nameserver hostname format
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: invalid_nameserver
                message: The provided nameserver hostname is not valid.
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '403':
          $ref: '#/components/responses/NoSubscription'
        '404':
          description: 'No RDAP data found for this nameserver.


            - `not_found` — the TLD is covered, but no record exists for this host.

            - `not_supported` — the nameserver''s TLD has no RDAP coverage.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                not_found:
                  value:
                    error: not_found
                    message: No RDAP data was found for this nameserver.
                not_supported:
                  value:
                    error: not_supported
                    message: No RDAP server found for this nameserver.
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          $ref: '#/components/responses/UpstreamError'
        '504':
          $ref: '#/components/responses/Timeout'
components:
  responses:
    Timeout:
      x-common: true
      description: 'The request timed out, for example when an upstream RDAP server is

        extremely slow or during a transient infrastructure issue on our side.

        Safe to retry after a short delay.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: gateway_timeout
            message: The request did not complete in time. Safe to retry after a short delay.
    RateLimited:
      x-common: true
      description: Rate limit, monthly quota, or concurrent burst limit exceeded
      headers:
        Retry-After:
          $ref: '#/components/headers/Retry-After-RateLimit'
      content:
        application/json:
          schema:
            type: object
            required:
            - error
            - message
            properties:
              error:
                type: string
                example: rate_limit_exceeded
              message:
                type: string
                example: Rate limit of 60 requests per minute reached. Retry in 30 seconds.
              retry_after:
                type:
                - integer
                - 'null'
                description: Seconds until the per-minute window resets. Present on `rate_limit_exceeded` only; the quota and burst variants carry the wait in the `Retry-After` header alone.
                example: 30
          examples:
            rate_limit:
              summary: Per-minute rate limit exceeded
              value:
                error: rate_limit_exceeded
                message: Rate limit of 60 requests per minute reached. Retry in 30 seconds.
                retry_after: 30
            quota:
              summary: Monthly quota exceeded
              value:
                error: quota_exceeded
                message: Monthly request limit of 200000 reached. Upgrade your plan at https://rdapapi.io/pricing
            burst:
              summary: Concurrent burst limit exceeded
              value:
                error: too_many_requests
                message: Too many requests at once. Please slow down and retry.
    NoSubscription:
      x-common: true
      description: No active subscription
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: subscription_required
            message: An active subscription is required to use the API. Subscribe at https://rdapapi.io/pricing
    UpstreamError:
      description: 'The registry failed to answer (`lookup_failed`) or is throttling us

        (`temporarily_unavailable`). See [Errors](#tag/errors).

        '
      headers:
        Retry-After:
          $ref: '#/components/headers/Retry-After-Upstream'
      content:
        application/json:
          schema:
            type: object
            required:
            - error
            - message
            properties:
              error:
                type: string
                example: lookup_failed
              message:
                type: string
                example: RDAP lookup failed. Please try again later.
              retry_after:
                type:
                - integer
                - 'null'
                description: Seconds to wait before retrying. Null when there is no wait to give.
                example: 60
          examples:
            lookup_failed:
              summary: Upstream lookup failed
              value:
                error: lookup_failed
                message: RDAP lookup failed. Please try again later.
                retry_after: 60
            temporarily_unavailable:
              summary: Upstream server rate-limiting us
              value:
                error: temporarily_unavailable
                message: Data for this domain is temporarily unavailable. Please retry later.
                retry_after: 300
    Unauthenticated:
      x-common: true
      description: Missing or invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: unauthenticated
            message: 'No API token provided. Send it in an "Authorization: Bearer <token>" header. Find your token at https://rdapapi.io/dashboard'
  headers:
    X-RateLimit-Remaining:
      description: 'Requests left this minute. Absent on `403 subscription_required` and

        `429 quota_exceeded`.

        '
      schema:
        type: integer
      example: 299
    Retry-After-RateLimit:
      description: 'Seconds to wait before retrying; `error` says which limit you hit.

        '
      schema:
        type: integer
    X-RateLimit-Limit:
      description: Requests allowed per minute on your plan.
      schema:
        type: integer
      example: 300
    Retry-After-Upstream:
      description: Seconds until the failing server is expected to recover. Absent when we have no estimate.
      schema:
        type: integer
      required: false
  schemas:
    Dates:
      type: object
      required:
      - registered
      - expires
      - updated
      properties:
        registered:
          type:
          - string
          - 'null'
          format: date-time
          example: '1997-09-15T04:00:00Z'
        expires:
          type:
          - string
          - 'null'
          format: date-time
          example: '2028-09-14T04:00:00Z'
        updated:
          type:
          - string
          - 'null'
          format: date-time
          example: '2019-09-09T15:39:04Z'
    Meta:
      type: object
      description: 'Where the answer came from, and how it was served.

        '
      required:
      - server
      - source
      properties:
        server:
          type:
          - string
          - 'null'
          description: Host that answered, as `/tlds` reports it (usable as `?server=`). May be null on old cached records.
          example: rdap.verisign.com
        source:
          type: string
          enum:
          - rdap
          - whois
          description: Which protocol answered. Always `rdap` except on domain lookups, where a TLD with no RDAP server is answered over [WHOIS](#tag/whois-fallback).
          example: rdap
        rdap_server:
          type: string
          deprecated: true
          description: Base URL of the RDAP server, present only when `source` is `rdap`. Use `server` for the host that answered, or `raw_rdap_url` for the exact endpoint queried.
          example: https://rdap.verisign.com/com/v1/
        raw_rdap_url:
          type: string
          description: Direct URL to the raw RDAP response. Absent when `source` is `whois`, which has no URL form, or when a stored snapshot answered.
          example: https://rdap.verisign.com/com/v1/domain/google.com
        cached:
          type: boolean
          description: Whether the response was served from cache. Omitted from the partial `meta` of a failed bulk entry.
          example: true
        cache_expires:
          type: string
          format: date-time
          description: Cache expiration time (ISO 8601). Omitted from the partial `meta` of a failed bulk entry.
          example: '2026-02-18T15:30:00Z'
        followed:
          type: boolean
          description: Whether the registrar's RDAP server was queried for richer data. Only present when `?follow=true` is used and `source` is `rdap`.
        registrar_rdap_server:
          type:
          - string
          - 'null'
          description: URL of the registrar's RDAP record the registry linked to. Only present when `?follow=true` is used.
        follow_error:
          type:
          - string
          - 'null'
          description: Error message if the follow request failed. Only present when `?follow=true` is used and the request fails.
    Error:
      type: object
      required:
      - error
      - message
      properties:
        error:
          type: string
          description: Machine-readable error code
          example: invalid_domain
        message:
          type: string
          description: Human-readable error message
          example: The provided domain name is not valid.
        reason:
          type: string
          description: The registry's own wording, on `domain_reserved` only.
          example: si.si is forbidden (Rezervirano za RS)
        registrable_domain:
          type: string
          description: The registered domain the name sits under, on `not_registrable` only.
          example: example.com
    Contact:
      type: object
      description: 'One contact. Any field may be null or withheld.

        '
      required:
      - handle
      - name
      - organization
      - email
      - phone
      - address
      - contact_url
      - country_code
      properties:
        handle:
          type:
          - string
          - 'null'
          description: Registry handle for this entity
          example: ORG-ARAD1-AP
        name:
          type:
          - string
          - 'null'
        organization:
          type:
          - string
          - 'null'
          example: Google LLC
        email:
          type:
          - string
          - 'null'
        phone:
          type:
          - string
          - 'null'
          description: Voice telephone number in E.164, with a `;ext=42` suffix when the registry supplies an extension.
        address:
          type:
          - string
          - 'null'
        contact_url:
          type:
          - string
          - 'null'
          description: Where a server withholds `email` and publishes a web form instead, this carries it.
          example: https://domaincontact.registrar.cloudflare.com/example.com
        country_code:
          type:
          - string
          - 'null'
          description: ISO 3166-1 alpha-2 country code from the address. Unlike the text fields, a redaction placeholder here is dropped to `null` rather than passed through — it is not a country code.
          example: US
    NameserverResponse:
      type: object
      required:
      - ldh_name
      - unicode_name
      - handle
      - ip_addresses
      - status
      - dates
      - entities
      properties:
        ldh_name:
          type: string
          description: Nameserver hostname (lowercase). Empty string if the upstream returned a value that is not a valid LDH hostname.
          example: ns1.google.com
        unicode_name:
          type:
          - string
          - 'null'
          description: Unicode form as the registry sends it; some send the ASCII name
        handle:
          type:
          - string
          - 'null'
          description: Registry-assigned handle
          example: NS1.GOOGLE.COM
        ip_addresses:
          type: object
          required:
          - v4
          - v6
          properties:
            v4:
              type: array
              items:
                type: string
              description: IPv4 addresses
              example:
              - 216.239.32.10
            v6:
              type: array
              items:
                type: string
              description: IPv6 addresses
              example:
              - 2001:4860:4802:32::a
        status:
          type: array
          items:
            type: string
          description: Status codes
          example:
          - active
        dates:
          $ref: '#/components/schemas/Dates'
        entities:
          type: object
          description: Contact entities keyed by role (registrant, administrative, technical, billing, abuse)
          properties:
            registrant:
              $ref: '#/components/schemas/Contact'
            administrative:
              $ref: '#/components/schemas/Contact'
            technical:
              $ref: '#/components/schemas/Contact'
            billing:
              $ref: '#/components/schemas/Contact'
            abuse:
              $ref: '#/components/schemas/Contact'
        redacted:
          $ref: '#/components/schemas/Redaction'
        meta:
          $ref: '#/components/schemas/Meta'
    Redaction:
      type: object
      minProperties: 1
      description: 'Fields the server declared withheld, at the same path as in the record. See [Redaction](#tag/terminology).

        '
      properties:
        handle:
          $ref: '#/components/schemas/RedactionMethod'
        registrar:
          type: object
          description: Claims about the top-level `registrar` object. Domain lookups only.
          additionalProperties:
            $ref: '#/components/schemas/RedactionMethod'
        entities:
          type: object
          description: Claims keyed by contact role, then by field within that contact.
          additionalProperties:
            type: object
            additionalProperties:
              $ref: '#/components/schemas/RedactionMethod'
      example:
        handle: replacementValue
        registrar:
          iana_id: replacementValue
        entities:
          registrant:
            name: emptyValue
            email: removal
    RedactionMethod:
      type: string
      description: '`removal`, `emptyValue`, `partialValue` or `replacementValue`; see [Redaction](#tag/terminology).

        '
      example: removal
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key obtained from your dashboard