List change requests

​

Returns a paginated, newest-first feed of governed changes across the organization's domains, narrowed to the domains you can see.

This is the queue view behind every 202. Poll one change by id for detail; read this to see everything in flight at once, or to find a change whose id you did not keep.

Pagination

Cursor-based. Pass the prior response's next_cursor as cursor to page forward, and direction=previous to page back. limit bounds the page and is clamped to 100. A cursor is a position and not a permission: it is always evaluated inside your own organization's feed.

Filtering

All filters are optional and narrow the result; an unrecognised value returns 400 with the offending parameter named in fields. Parameters marked (repeatable) accept multiple values via repeated keys, OR-ed together, and AND across parameters (e.g. ?status=open&kind=domain.dnssec means "still in flight, and touching DNSSEC").

Query param Values
status open or settled
kind (repeatable) any value from the kinds field of a change
domain_id Restricts the feed to one domain
requested_by User ID; restricts to changes one member submitted
correlation_id Groups a bulk submission back together; every change one bulk write created shares it

status is the coarse lifecycle question: open is everything that has not settled (draft, pending_approval, approved, executing, pending_registry) and settled is every terminal one (applied, failed, rejected, cancelled), whatever the outcome. Every row carries its precise state and display_status, so narrowing further is a filter over the page you already hold rather than a second request.

domain_id names a domain rather than filtering the feed after the fact: a domain your organization does not hold returns 404, and one it holds outside your team scope returns 403, exactly as reading that domain would.

Permissions
Key type Accepted Permission required Notes
Org API key yes domain:read Reads changes on every domain in the key's org scope
Personal API key yes domain:read Caller must have an active membership in the org named by X-Org-ID; the feed carries only changes on domains inside their teams
Error Codes
Code HTTP Description
change.unauthorized 401 No valid credentials
change.no_org 403 No active organization in scope for the call
change.list.invalid_filter 400 A filter or pagination parameter was refused; fields names it
change.not_found 404 domain_id names a domain that does not exist or belongs to another organization
change.no_team_access 403 domain_id names a domain your organization holds but which is outside your team scope
change.list.scope_failed 500 Your visible domain scope could not be resolved
change.list.failed 500 The feed could not be read
change.list.items_failed 500 The feed loaded but what its changes carry could not be read

Query Parameters

  • cursor
    Type: string

    Cursor from the prior response's next_cursor

  • direction
    Type: "next" or "previous"enum

    Page direction

  • limit
    Type: integer

    Items per page (default 20, max 100)

  • status
    Type: "open" or "settled"enum

    Filter by coarse lifecycle: open is everything unsettled, settled is every terminal state

  • kind
    Type: array of stringenum

    Filter by the class of mutation carried (repeatable; values are OR-ed)

    values
    domain.nameserversdomain.subordinate_hostsdomain.dnssecdomain.contactsdomain.transfer_lockdomain.update_lockdomain.auth_codedomain.transfer_outdomain.deletiondomain.auto_renewdomain.team_assignmentdomain.record_removal
  • domain_id
    Type: string

    Restrict the feed to one domain (e.g. dom_01h455vb4pex5vsknk084sn02q)

  • requested_by
    Type: string

    Restrict to changes one member submitted (e.g. user_01h455vb4pex5vsknk084sn02q)

  • correlation_id
    Type: string

    Restrict to the changes one bulk submission created

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for get/changes
curl 'https://api.nametrust.com/changes?direction=next&status=open'

{
  "object": "list",
  "items": [
    {
      "object": "change_request",
      "slots": [
        "delegation"
      ],
      "applied_version": 8,
      "base_version": 7,
      "comment": "repoint to the new provider",
      "failure_code": "registry_rejected",
      "cancellation_reason": "expired",
      "cancellation_comment": "domain sold, no longer needed",
      "requested_by": {
        "object": "actor",
        "kind": "user",
        "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"
        }
      },
      "cancelled_by": {
        "object": "actor",
        "kind": "user",
        "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"
        }
      },
      "expires_at": "string",
      "id": "chr_01h455vb4pex5vsknk084sn02q",
      "settled_at": "string",
      "created_at": "string",
      "updated_at": "string",
      "approval": {
        "object": "change_approval",
        "blocked": false,
        "stage_count": 2,
        "stages_cleared": 0,
        "current_stage_id": "chs_01h455vb4pex5vsknk084sn02q",
        "current_stage_no": 1,
        "current_label": "Legal review",
        "quorum": 2,
        "approvals_cast": 1,
        "approvers_live": 3
      },
      "viewer": {
        "open_stage_id": "chs_01h455vb4pex5vsknk084sn02q",
        "actions": [
          {
            "action": "cancel",
            "allowed": false,
            "reason": "not_requester"
          }
        ]
      },
      "domain_id": "dom_01h455vb4pex5vsknk084sn02q",
      "domain_name": "acme.com",
      "state": "approved",
      "display_status": "applying",
      "outcome": "allow",
      "evaluation_pass": 1,
      "kinds": [
        "domain.nameservers"
      ]
    }
  ],
  "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 change feed