rdapapi-io TLDs API

openapi: 3.2.0
info:
  title: RDAP TLDs 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: TLDs
  description: Check which TLDs are supported, in bulk or one at a time.
paths:
  /tlds:
    get:
      operationId: listTlds
      summary: List Supported TLDs
      description: 'Every TLD we answer for: its protocol, when support was added, and how often its registry

        fills the main fields (field availability). Free, sorted by `tld`, and

        sent with an `ETag`: pass it as `If-None-Match` to get `304 Not Modified`.'
      tags:
      - TLDs
      parameters:
      - name: since
        in: query
        required: false
        description: ISO 8601 timestamp. Only TLDs supported after it.
        schema:
          type: string
          format: date-time
          example: '2026-04-01T00:00:00Z'
      - name: server
        in: query
        required: false
        description: Only TLDs answered by this server, e.g. `rdap.verisign.com`.
        schema:
          type: string
          example: rdap.verisign.com
      responses:
        '200':
          description: List of supported TLDs
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            ETag:
              description: Opaque value representing the current list state. Pass this back as `If-None-Match` to get `304 Not Modified` when nothing has changed.
              schema:
                type: string
            Cache-Control:
              description: HTTP cache directive. Lets your own caches and any CDN in front of you hold the response for an hour.
              schema:
                type: string
                example: max-age=3600, public
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/TldEntry'
                  meta:
                    $ref: '#/components/schemas/TldListMeta'
              example:
                data:
                - tld: com
                  supported_since: '2026-03-07T00:00:00Z'
                  rdap_server_host: rdap.verisign.com
                  rdap_server_url: https://rdap.verisign.com/com/v1/
                  field_availability:
                    registrar: sometimes
                    registered_at: always
                    expires_at: always
                    nameservers: always
                    status: always
                - tld: fr
                  supported_since: '2026-03-07T00:00:00Z'
                  rdap_server_host: rdap.nic.fr
                  rdap_server_url: https://rdap.nic.fr/
                  field_availability: null
                meta:
                  computed_at: '2026-04-22T10:00:00Z'
                  count: 2
                  coverage: 0.5
                  thresholds:
                    always: 0.99
                    usually: 0.8
                    sometimes: 0.0
        '304':
          description: Not modified. Returned when the `If-None-Match` header matches the current `ETag`. No response body.
        '400':
          description: Invalid `since` query parameter
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: invalid_since
                message: Query parameter 'since' must be an ISO 8601 timestamp (e.g. 2026-04-01T00:00:00Z).
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '403':
          $ref: '#/components/responses/NoSubscription'
        '429':
          $ref: '#/components/responses/RateLimitedMetadata'
  /tlds/{tld}:
    get:
      operationId: getTld
      summary: Get a Single TLD
      description: The same object as in the list, for one TLD. Free.
      tags:
      - TLDs
      parameters:
      - name: tld
        in: path
        required: true
        description: Lowercase TLD label without a leading dot (e.g. `com`, `fr`, `co.uk`).
        schema:
          type: string
          example: com
      responses:
        '200':
          description: TLD found
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            ETag:
              schema:
                type: string
            Cache-Control:
              schema:
                type: string
                example: max-age=3600, public
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    $ref: '#/components/schemas/TldEntry'
                  meta:
                    type: object
                    required:
                    - computed_at
                    - thresholds
                    properties:
                      computed_at:
                        type: string
                        format: date-time
                      thresholds:
                        $ref: '#/components/schemas/TldListMeta/properties/thresholds'
              example:
                data:
                  tld: com
                  supported_since: '2026-03-07T00:00:00Z'
                  rdap_server_host: rdap.verisign.com
                  rdap_server_url: https://rdap.verisign.com/com/v1/
                  field_availability:
                    registrar: sometimes
                    registered_at: always
                    expires_at: always
                    nameservers: always
                    status: always
                meta:
                  computed_at: '2026-04-22T10:00:00Z'
                  thresholds:
                    always: 0.99
                    usually: 0.8
                    sometimes: 0.0
        '304':
          description: Not modified.
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '403':
          $ref: '#/components/responses/NoSubscription'
        '404':
          description: Unknown TLD
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: not_found
                message: No RDAP server is registered for the TLD 'doesnotexist'.
        '429':
          $ref: '#/components/responses/RateLimitedMetadata'
components:
  schemas:
    AvailabilityLevel:
      type: string
      enum:
      - always
      - usually
      - sometimes
      - never
      description: Qualitative bucket describing how often a field is populated in the TLD's registry RDAP response.
    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
    TldEntry:
      type: object
      required:
      - tld
      - protocol
      - supported_since
      - server
      - rdap_server_host
      - rdap_server_url
      - field_availability
      properties:
        tld:
          type: string
          description: Lowercase TLD label without a leading dot.
          example: com
        protocol:
          type: string
          enum:
          - rdap
          - whois
          description: Which protocol answers for this TLD. `whois` marks the TLDs IANA lists no RDAP server for.
          example: rdap
        supported_since:
          type: string
          format: date-time
          description: When this TLD was first added to the RDAP API index. Not the same as when IANA delegated the TLD.
        server:
          type: string
          description: Hostname of the upstream that answers for this TLD. This is what `?server=` filters on, and what a lookup's `meta.server` returns.
          example: rdap.verisign.com
        rdap_server_host:
          type:
          - string
          - 'null'
          deprecated: true
          description: Superseded by `server`. Null when `protocol` is `whois`.
          example: rdap.verisign.com
        rdap_server_url:
          type:
          - string
          - 'null'
          format: uri
          description: Full URL of the upstream RDAP server. Null when `protocol` is `whois`, which has no URL form.
          example: https://rdap.verisign.com/com/v1/
        field_availability:
          type:
          - object
          - 'null'
          description: 'How often the registry fills each field, without follow. `null` for WHOIS TLDs and

            until there is enough data.

            '
          required:
          - registrar
          - registered_at
          - expires_at
          - nameservers
          - status
          properties:
            registrar:
              $ref: '#/components/schemas/AvailabilityLevel'
            registered_at:
              $ref: '#/components/schemas/AvailabilityLevel'
            expires_at:
              $ref: '#/components/schemas/AvailabilityLevel'
            nameservers:
              $ref: '#/components/schemas/AvailabilityLevel'
            status:
              $ref: '#/components/schemas/AvailabilityLevel'
    TldListMeta:
      type: object
      required:
      - computed_at
      - count
      - coverage
      - thresholds
      properties:
        computed_at:
          type: string
          format: date-time
          description: Server time when the cached payload was built. May be up to 1 hour old.
        count:
          type: integer
          description: Number of TLDs in `data` (after any filtering).
        coverage:
          type: number
          format: float
          minimum: 0
          maximum: 1
          description: 'Share of RDAP TLDs with enough data for `field_availability`.

            '
          example: 0.93
        thresholds:
          type: object
          description: 'Percentage cutoffs used to pick each label:


            - `always` = populated in 99% or more of responses

            - `usually` = 80% or more

            - `sometimes` = more than 0%

            - `never` = 0%

            '
          required:
          - always
          - usually
          - sometimes
          properties:
            always:
              type: number
              format: float
              example: 0.99
            usually:
              type: number
              format: float
              example: 0.8
            sometimes:
              type: number
              format: float
              example: 0.0
  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
  responses:
    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
    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'
    RateLimitedMetadata:
      x-common: true
      description: Per-minute rate limit exceeded
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        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
            burst:
              summary: Concurrent burst limit exceeded (only Retry-After, no X-RateLimit-* headers)
              value:
                error: too_many_requests
                message: Too many requests at once. Please slow down and retry.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key obtained from your dashboard