Bulk tools

Multi-domain changes go through OpusDNS Jobs, never a loop of single calls. You supply a selector and one shared template; the server resolves the matching domains and submits a single batch.

Always bulk_preview before bulk_submit: the preview is what tells you the selector matched 412 domains rather than 4,127. See Bulk operations with Jobs for the full flow.

bulk_preview

Preview a bulk domain operation — approval required: no

Dry-run a bulk operation. Resolves the selector by reading the domain list from the OpusDNS API, then renders the planned Jobs template + instances. It reads but never writes, so it needs the same credentials as any other call and no approval. Review matchedDomains, then call bulk_submit with the same arguments.

When to use it. Always run this first. It resolves the selector and shows you the matched count, the shared template, and a sample of the instances that would be created — without submitting anything or asking for approval.

Unknown parameters are rejected.

• Read-only: never changes anything in your account.
• Repeating the same call has the same effect.
• Calls the OpusDNS API.

Example call.

{
  "templateType": "domain_update_bulk",
  "template": {
    "status_changes": {
      "add": [
        "clientTransferProhibited"
      ]
    }
  },
  "selector": {
    "tld": [
      "com"
    ],
    "expires_in_30_days": true
  },
  "sampleSize": 3
}

Example result.

{
  "status": "dry_run",
  "templateType": "domain_update_bulk",
  "command": "domain_update_bulk",
  "matchedDomains": 412,
  "template": {
    "status_changes": {
      "add": [
        "clientTransferProhibited"
      ]
    }
  },
  "sampleDomains": [
    {
      "name": "acme-labs.com",
      "domain_id": "domain_01h45ytscbebyvny4gc8cr8ma2"
    },
    {
      "name": "acme-labs.net",
      "domain_id": "domain_01h45yv2m8fbcwnz9pq3kr7txe"
    },
    {
      "name": "acme-shop.com",
      "domain_id": "domain_01h45yw7q2gdexpa4bt6mn8zvc"
    }
  ],
  "sampleInstances": [
    {
      "domain_id": "domain_01h45ytscbebyvny4gc8cr8ma2"
    },
    {
      "domain_id": "domain_01h45yv2m8fbcwnz9pq3kr7txe"
    },
    {
      "domain_id": "domain_01h45yw7q2gdexpa4bt6mn8zvc"
    }
  ],
  "note": "Nothing was submitted. Call bulk_submit with the same templateType, template and selector to execute. You will be asked to approve the action first."
}

bulk_submit

Submit a bulk domain operation — approval required: yes

Submit a bulk operation as an OpusDNS Job. Resolves the selector to domains server-side, builds a Jobs template batch, and requires explicit user approval before it runs. The approval is bound to the exact resolved set: if the selector resolves differently on retry, you must confirm again.

When to use it. Run it with the same arguments you previewed. The approval you give is bound to the exact set of domains that were resolved, so if that set changes before you retry, you are asked again.

Unknown parameters are rejected.

• Can modify or delete data. Requires your explicit approval before it runs.
• Repeating the call repeats the effect.
• Calls the OpusDNS API.

Example call.

{
  "templateType": "domain_update_bulk",
  "template": {
    "status_changes": {
      "add": [
        "clientTransferProhibited"
      ]
    }
  },
  "selector": {
    "tld": [
      "com"
    ],
    "expires_in_30_days": true
  },
  "label": "lock-expiring-com"
}

Example result.

{
  "status": "ok",
  "operationId": "create_batch_v1_jobs_post",
  "httpStatus": 201,
  "headers": {
    "content-type": "application/json"
  },
  "data": {
    "batch_id": "batch_01k3n0m5xrf9pab6t2wqzhkvr3",
    "jobs_created": 412,
    "jobs_failed": 0,
    "jobs_duplicated": 0,
    "duplicates": [],
    "errors": [],
    "total_commands": 1,
    "status_url": "/v1/jobs/batch_01k3n0m5xrf9pab6t2wqzhkvr3"
  },
  "truncated": false
}

job_batch_status

Get job batch status — approval required: no

Get the status of a submitted job batch: progress percentage and counts by job state (queued, running, succeeded, failed, dead_letter, ...).

When to use it. Poll this after bulk_submit to watch a batch progress. Counts are per job state, so a partly-failed batch is visible without listing every job.

Unknown parameters are rejected.

• Read-only: never changes anything in your account.
• Repeating the same call has the same effect.
• Calls the OpusDNS API.

Example call.

{
  "batchId": "batch_01k3n0m5xrf9pab6t2wqzhkvr3"
}

Example result.

{
  "status": "ok",
  "operationId": "get_batch_v1_jobs__batch_id__get",
  "httpStatus": 200,
  "headers": {
    "content-type": "application/json"
  },
  "data": {
    "batch_id": "batch_01k3n0m5xrf9pab6t2wqzhkvr3",
    "label": "lock-expiring-com",
    "total": 412,
    "queued": 0,
    "running": 6,
    "succeeded": 401,
    "failed": 5,
    "blocked": 0,
    "paused": 0,
    "canceled": 0,
    "dead_letter": 0,
    "progress_percentage": 98
  },
  "truncated": false
}

job_batch_control

Control a job batch — approval required: yes

Control a submitted job batch: pause, resume, retry (optionally only a given errorClass), or cancel queued jobs. These are write operations and require explicit user approval before they run.

When to use it. Steer a batch that is already running: pause it, resume it, cancel the jobs still queued, or retry the failures. retry with an errorClass retries only the jobs that failed that way — useful after fixing one cause and leaving the rest alone.

Unknown parameters are rejected.

• Can modify or delete data. Requires your explicit approval before it runs.
• Repeating the call repeats the effect.
• Calls the OpusDNS API.

Example call.

{
  "batchId": "batch_01k3n0m5xrf9pab6t2wqzhkvr3",
  "action": "retry",
  "errorClass": [
    "BillingInsufficientFundsError"
  ]
}

Example result.

{
  "status": "ok",
  "operationId": "retry_batch_v1_jobs__batch_id__retry_post",
  "httpStatus": 200,
  "headers": {
    "content-type": "application/json"
  },
  "data": {
    "batch_id": "batch_01k3n0m5xrf9pab6t2wqzhkvr3",
    "retried_count": 5,
    "queued_count": 5,
    "blocked_count": 0
  },
  "truncated": false
}