rdapapi-io Entity API

openapi: 3.2.0
info:
  title: RDAP Entity 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: Entity
  description: Look up a contact or organization by RDAP handle.
paths:
  /entity/{handle}:
    get:
      operationId: lookupEntity
      summary: Entity Lookup
      description: 'An organization or contact at ARIN, RIPE NCC, APNIC, LACNIC or AFRINIC, by handle. The

        suffix picks the registry (`-RIPE`, `-AP`…); a bare handle like `GOGL` goes to ARIN.'
      tags:
      - Entity
      parameters:
      - name: handle
        in: path
        required: true
        description: Entity handle (e.g. GOGL, ABUSE5250-ARIN, ORG-GLLC1-RIPE)
        schema:
          type: string
          example: GOGL
      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/EntityResponse'
              example:
                handle: GOGL
                name: Google LLC
                organization: Google LLC
                email: null
                phone: null
                address: '1600 Amphitheatre Parkway

                  Mountain View

                  CA

                  94043

                  US'
                contact_url: null
                country_code: US
                roles:
                - registrant
                status:
                - active
                dates:
                  registered: '2000-03-30T05:00:00Z'
                  expires: null
                  updated: '2019-10-31T19:45:45Z'
                remarks:
                - title: Registration Comments
                  description: Please note that the recommended way to file abuse complaints are located in the following links.
                port43: whois.arin.net
                public_ids:
                - type: ARIN OrgID
                  identifier: GOGL
                entities:
                  abuse:
                    handle: ABUSE5250-ARIN
                    name: Abuse
                    organization: null
                    email: network-abuse@google.com
                    phone: '+16502530000'
                    address: null
                    contact_url: null
                    country_code: null
                autnums:
                - handle: AS15169
                  name: GOOGLE
                  start_autnum: 15169
                  end_autnum: 15169
                - handle: AS36040
                  name: YOUTUBE
                  start_autnum: 36040
                  end_autnum: 36040
                networks:
                - handle: NET-8-8-8-0-2
                  name: GOGL
                  start_address: 8.8.8.0
                  end_address: 8.8.8.255
                  ip_version: v4
                  cidr:
                  - 8.8.8.0/24
                meta:
                  server: rdap.arin.net
                  source: rdap
                  rdap_server: https://rdap.arin.net/registry/
                  raw_rdap_url: https://rdap.arin.net/registry/entity/GOGL
                  cached: false
                  cache_expires: '2026-02-24T15:30:00Z'
        '400':
          description: Invalid entity handle format
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: invalid_handle
                message: The provided entity handle is not valid.
        '401':
          $ref: '#/components/responses/Unauthenticated'
        '403':
          $ref: '#/components/responses/NoSubscription'
        '404':
          description: 'No RDAP data found for this entity handle.


            - `not_found` — the handle belongs to a regional registry, but no matching entity exists.

            - `not_supported` — the handle does not look like one from a supported registry.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                not_found:
                  value:
                    error: not_found
                    message: This entity was not found.
                not_supported:
                  value:
                    error: not_supported
                    message: No RDAP server found for this entity handle. Only RIR handles (ARIN, RIPE, APNIC, LACNIC, AFRINIC) are supported.
        '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.
    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'
    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
  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.
    RedactionMethod:
      type: string
      description: '`removal`, `emptyValue`, `partialValue` or `replacementValue`; see [Redaction](#tag/terminology).

        '
      example: removal
    EntityNetwork:
      type: object
      required:
      - handle
      - name
      - start_address
      - end_address
      - ip_version
      - cidr
      properties:
        handle:
          type:
          - string
          - 'null'
          example: NET-8-8-8-0-2
        name:
          type:
          - string
          - 'null'
          example: GOGL
        start_address:
          type:
          - string
          - 'null'
          example: 8.8.8.0
        end_address:
          type:
          - string
          - 'null'
          example: 8.8.8.255
        ip_version:
          type:
          - string
          - 'null'
          example: v4
        cidr:
          type: array
          items:
            type: string
          example:
          - 8.8.8.0/24
    EntityResponse:
      type: object
      required:
      - handle
      - name
      - organization
      - email
      - phone
      - address
      - contact_url
      - country_code
      - roles
      - status
      - dates
      - remarks
      - port43
      - public_ids
      - entities
      - autnums
      - networks
      properties:
        handle:
          type:
          - string
          - 'null'
          description: Registry-assigned entity handle
          example: GOGL
        name:
          type:
          - string
          - 'null'
          description: Full name (fn from vCard)
          example: Google LLC
        organization:
          type:
          - string
          - 'null'
          description: Organization name
          example: Google LLC
        email:
          type:
          - string
          - 'null'
          description: Contact email address
        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'
          description: Postal address
        contact_url:
          type:
          - string
          - 'null'
          description: Web form or page for reaching this contact, where one is published instead of an email address.
        country_code:
          type:
          - string
          - 'null'
          description: ISO 3166-1 alpha-2 country code
          example: US
        roles:
          type: array
          items:
            type: string
          description: Roles this entity serves
          example:
          - registrant
        status:
          type: array
          items:
            type: string
          description: Status codes
          example:
          - active
        dates:
          $ref: '#/components/schemas/Dates'
        remarks:
          type: array
          items:
            $ref: '#/components/schemas/Remark'
        port43:
          type:
          - string
          - 'null'
          description: Legacy WHOIS server hostname
          example: whois.arin.net
        public_ids:
          type: array
          items:
            $ref: '#/components/schemas/PublicId'
          description: Public identifiers (e.g. ARIN OrgID, IANA Registrar ID)
        entities:
          type: object
          description: Nested contact entities keyed by role
          properties:
            registrant:
              $ref: '#/components/schemas/Contact'
            abuse:
              $ref: '#/components/schemas/Contact'
            administrative:
              $ref: '#/components/schemas/Contact'
            technical:
              $ref: '#/components/schemas/Contact'
            billing:
              $ref: '#/components/schemas/Contact'
        autnums:
          type: array
          description: Autonomous system numbers owned by this entity
          items:
            $ref: '#/components/schemas/EntityAutnum'
        networks:
          type: array
          description: IP network blocks owned by this entity
          items:
            $ref: '#/components/schemas/EntityNetwork'
        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
    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
    PublicId:
      type: object
      required:
      - type
      - identifier
      properties:
        type:
          type:
          - string
          - 'null'
          description: Type of public identifier
          example: ARIN OrgID
        identifier:
          type:
          - string
          - 'null'
          description: The identifier value
          example: GOGL
    EntityAutnum:
      type: object
      required:
      - handle
      - name
      - start_autnum
      - end_autnum
      properties:
        handle:
          type:
          - string
          - 'null'
          example: AS15169
        name:
          type:
          - string
          - 'null'
          example: GOOGLE
        start_autnum:
          type:
          - integer
          - 'null'
          example: 15169
        end_autnum:
          type:
          - integer
          - 'null'
          example: 15169
    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'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key obtained from your dashboard