List domain version history

​

Returns the append-only lifecycle history of a domain as an ordered list of version events, newest first. Each event carries two things:

  • snapshot: the complete frozen state of the domain at that version (expiry, auto-renew, term, roid, sponsoring registrar, contacts, nameservers, EPP statuses, DNSSEC DS records).
  • changes: the field-level deltas versus the previous version, so a client can render Expiry: 1 Jan 2025 -> 1 Jan 2026 without diffing snapshots itself. The first (registration) event reports its seeded values as null -> value.

Change kinds

Each entry in changes has a kind describing how to render it:

Kind Meaning from/to shape
date timestamp field (expiry) RFC 3339 string
toggle boolean (auto-renew) bool
count integer (term) number
text scalar string (roid, sponsoring registrar) string
list set field (nameservers, EPP statuses, DS records) array
reference a contact role object

Pagination

Cursor-based. Pass cursor from a prior response's next_cursor (or prev_cursor with direction=previous) to page through a long history; limit bounds the page.

Permissions
Key type Accepted Permission required Notes
Org API key yes domain:read Key must be scoped to the org that owns the domain.
Personal API key yes domain:read Requires X-Org-ID for the owning org; caller needs a role granting domain:read and team visibility of the domain.
Error Codes
Code HTTP Description
domain_version.list.unauthorized 401 No authenticated identity
domain_version.list.no_org 403 No active organization in scope
domain_version.list.invalid_id 400 Malformed domain id
domain_version.list.invalid_cursor 400 Cursor is not a valid pagination token
domain_version.list.not_found 404 Domain does not exist or is not visible to the caller
domain_version.list.failed 500 History lookup failed
Path Parameters
  • id
    Type: string
    required

    Domain id (dom_...)

Query Parameters
  • limit
    Type: integer

    Items per page

  • cursor
    Type: string

    Pagination cursor from next_cursor / prev_cursor

  • direction
    Type: stringenum

    Page direction

    values
    • next
    • previous
Responses
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for get/domains/{id}/versions
curl 'https://api.nametrust.com/domains/{id}/versions?limit=1&cursor=&direction=next'

{
  "object": "list",
  "items": [
    {
      "object": "domain_version",
      "occurred_at": "2026-01-01T00:00:00Z",
      "id": "domv_01h455vb4pex5vsknk084sn02q",
      "domain_id": "dom_01h455vb4pex5vsknk084sn02q",
      "version": 3,
      "change_type": "renewed",
      "change_summary": "Renewed for 1 year",
      "snapshot": {
        "object": "domain_version_snapshot",
        "ds_records": [
          {
            "object": "domain_version_ds",
            "key_tag": 12345,
            "algorithm": 13,
            "digest_type": 2,
            "digest": "49FD46E6C4B45C55D4AC",
            "max_sig_life": 604800
          }
        ],
        "auto_renew": true,
        "period": {
          "object": "period",
          "count": 1,
          "unit": "y"
        },
        "expires_at": "2027-01-01T00:00:00Z",
        "roid": "D123-EXMP",
        "sponsoring_registrar": "registrar-1234",
        "contacts": [
          {
            "object": "domain_version_contact",
            "street2": "Suite 200",
            "city": "Mountain View",
            "region": "California",
            "postal_code": "94043",
            "country_code": "US",
            "disclose": false,
            "verification_status": "verified",
            "is_active": true,
            "role": "registrant",
            "first_name": "Jane",
            "last_name": "Doe",
            "org_name": "Acme Inc",
            "email": "jane@acme.com",
            "phone": "+1.5555550100",
            "fax": "+1.5555550101",
            "street1": "100 Main St"
          }
        ],
        "nameservers": [
          "ns1.example.com"
        ],
        "epp_statuses": [
          "clientTransferProhibited"
        ]
      },
      "changes": [
        {
          "object": "domain_version_change",
          "field": "expires_at",
          "label": "Expiry",
          "kind": "date",
          "from": {},
          "to": {}
        }
      ],
      "changed_by": {
        "object": "actor",
        "method": "session",
        "user": {
          "object": "user",
          "last_login_at": "2025-06-15T09:30:00Z",
          "last_active_at": "2025-06-15T09:30:00Z",
          "id": "user_01h455vb4pex5vsknk084sn02q",
          "email": "jane@acme.com",
          "first_name": "Jane",
          "last_name": "Doe",
          "avatar_url": "https://example.com/avatar.jpg",
          "mfa_enabled": true,
          "created_at": "2025-06-01T12:00:00Z",
          "updated_at": "2025-06-15T09:30:00Z"
        },
        "personal_key": {
          "object": "actor_personal_key",
          "id": "pkey_01h455vb4pex5vsknk084sn02q"
        },
        "org_key": {
          "object": "actor_org_key",
          "id": "okey_01h455vb4pex5vsknk084sn02q"
        }
      }
    }
  ],
  "pages": {
    "object": "cursor",
    "has_prev": true,
    "direction": "next",
    "cursor": "abc123",
    "next_cursor": "def456",
    "prev_cursor": "xyz789",
    "page": 2,
    "total_pages": 10,
    "total_items": 100,
    "limit": 20,
    "has_next": true
  }
}

Paginated version history