rdapapi-io IP API

openapi: 3.2.0
info:
  title: RDAP IP 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: Ip
  description: Look up an IP address or CIDR block.
paths:
  /ip/{ip}:
    get:
      operationId: lookupIp
      summary: IP Address Lookup
      description: 'The network an IPv4 or IPv6 address belongs to: the most specific allocation, or the exact

        block for a CIDR.'
      tags:
      - Ip
      parameters:
      - name: ip
        in: path
        required: true
        description: IPv4 or IPv6 address, optionally with CIDR prefix (e.g. `8.8.8.8` or `8.8.8.0/24`)
        schema:
          type: string
          example: 8.8.8.8
      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/IpResponse'
              example:
                handle: NET-8-8-8-0-2
                name: GOGL
                type: DIRECT ALLOCATION
                start_address: 8.8.8.0
                end_address: 8.8.8.255
                ip_version: v4
                parent_handle: NET-8-0-0-0-0
                country: null
                status:
                - active
                dates:
                  registered: '2023-12-28T22:24:33Z'
                  expires: null
                  updated: '2023-12-28T22:24:56Z'
                entities:
                  registrant:
                    handle: GOGL
                    name: Google LLC
                    organization: null
                    email: null
                    phone: null
                    address: '1600 Amphitheatre Parkway

                      Mountain View

                      CA

                      94043

                      United States'
                    contact_url: null
                    country_code: null
                cidr:
                - 8.8.8.0/24
                geofeed: null
                remarks: []
                port43: whois.arin.net
                meta:
                  server: rdap.arin.net
                  source: rdap
                  rdap_server: https://rdap.arin.net/registry/
                  raw_rdap_url: https://rdap.arin.net/registry/ip/8.8.8.8
                  cached: false
                  cache_expires: '2026-02-24T15:30:00Z'
        '400':
          description: Invalid IP address format
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_ip:
                  summary: Not an IP address
                  value:
                    error: invalid_ip
                    message: The provided IP address is not valid.
                invalid_prefix:
                  summary: CIDR prefix out of range for the address family
                  value:
                    error: invalid_prefix
                    message: CIDR prefix length must be between 0 and 32 for IPv4.
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '403':
          $ref: '#/components/responses/NoSubscription'
        '404':
          description: 'No RDAP data found for this IP address.


            - `not_found` — the range is covered, but the address has no record.

            - `not_supported` — the address is outside every allocated range.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                not_found:
                  value:
                    error: not_found
                    message: No RDAP data was found for this IP address.
                not_supported:
                  value:
                    error: not_supported
                    message: No RDAP server found for this IP address.
        '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.
    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
    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
    Remark:
      type: object
      required:
      - title
      - description
      properties:
        title:
          type:
          - string
          - 'null'
          example: description
        description:
          type: string
          example: 'APNIC and Cloudflare DNS Resolver project

            Routed globally by AS13335/Cloudflare'
    IpResponse:
      type: object
      required:
      - handle
      - name
      - type
      - start_address
      - end_address
      - ip_version
      - parent_handle
      - country
      - status
      - dates
      - entities
      - cidr
      - geofeed
      - remarks
      - port43
      properties:
        handle:
          type:
          - string
          - 'null'
          description: Registry-assigned handle
          example: NET-8-8-8-0-2
        name:
          type:
          - string
          - 'null'
          description: Network name
          example: GOGL
        type:
          type:
          - string
          - 'null'
          description: Allocation type
          example: DIRECT ALLOCATION
        start_address:
          type:
          - string
          - 'null'
          description: Start of the IP address range
          example: 8.8.8.0
        end_address:
          type:
          - string
          - 'null'
          description: End of the IP address range
          example: 8.8.8.255
        ip_version:
          type:
          - string
          - 'null'
          description: IP version (v4 or v6)
          example: v4
        parent_handle:
          type:
          - string
          - 'null'
          description: Parent network handle
          example: NET-8-0-0-0-0
        country:
          type:
          - string
          - 'null'
          description: Country code (if provided by registry)
          example: US
        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'
            abuse:
              $ref: '#/components/schemas/Contact'
            billing:
              $ref: '#/components/schemas/Contact'
        cidr:
          type: array
          items:
            type: string
          description: CIDR notation for the network
          example:
          - 8.8.8.0/24
        geofeed:
          type:
          - string
          - 'null'
          description: 'The network''s RFC 8805 geofeed URL, as published. `null` when there is none.

            '
          example: https://geofeed.ipxo.com/geofeed.txt
        remarks:
          type: array
          items:
            $ref: '#/components/schemas/Remark'
          description: Remarks from the registry (network description, abuse info, etc.)
        port43:
          type:
          - string
          - 'null'
          description: Legacy WHOIS server hostname
          example: whois.apnic.net
        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