Jobs overview

The Jobs API lets you submit large numbers of operations for asynchronous execution. Instead of making thousands of individual API calls, you bundle commands into a batch, and OpusDNS processes them reliably in the background.

Core concepts

Batches and jobs

A batch is a container that holds one or more commands. When you submit a batch, OpusDNS creates individual jobs for each command (or each instance in a bulk command). Each job is processed independently and tracked through its own lifecycle.

Batch (up to 50,000 commands)
├── Job 1  →  domain_create "example.com"       → succeeded
├── Job 2  →  domain_create "example.net"       → succeeded
├── Job 3  →  domain_create "example.org"       → failed
└── ...

Single vs. bulk commands

There are two categories of commands:

Single-resource commands create one job per command. Each command targets a specific resource:

{
  "type": "domain_create",
  "payload": {
    "name": "example.com",
    "contacts": { "registrant": "contact_01h45ytscbebyvny4gc8cr8ma2" },
    "renewal_mode": "renew",
    "period": { "unit": "y", "value": 1 }
  }
}

Bulk commands use a template + instances pattern. The template defines shared settings, and each instance specifies a target resource with optional overrides. Each instance becomes its own job:

{
  "type": "domain_create_bulk",
  "payload": {
    "template": {
      "contacts": { "registrant": "contact_01h45ytscbebyvny4gc8cr8ma2" },
      "renewal_mode": "renew",
      "period": { "unit": "y", "value": 1 }
    },
    "instances": [
      { "name": "example.com" },
      { "name": "example.net" },
      { "name": "example.org" }
    ]
  }
}

This is significantly more efficient than submitting 3 individual domain_create commands — shared fields are defined once in the template rather than repeated in every command.

Submitting a batch

Create a batch with POST /v1/jobs:

curl "$OPUSDNS_API_BASE/v1/jobs" \
  --request POST \
  --header "X-Api-Key: $OPUSDNS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "label": "Q1 2026 bulk registration",
    "commands": [
      {
        "type": "domain_create",
        "payload": {
          "name": "example1.com",
          "contacts": {
            "registrant": "contact_01h45ytscbebyvny4gc8cr8ma2"
          },
          "renewal_mode": "renew",
          "period": { "unit": "y", "value": 1 }
        }
      },
      {
        "type": "domain_create",
        "payload": {
          "name": "example2.com",
          "contacts": {
            "registrant": "contact_01h45ytscbebyvny4gc8cr8ma2"
          },
          "renewal_mode": "renew",
          "period": { "unit": "y", "value": 1 }
        }
      }
    ]
  }'

Batch request fields

Batch response

{
  "batch_id": "batch_01h45ytscbebyvny4gc8cr8ma2",
  "total_commands": 2,
  "jobs_created": 2,
  "jobs_duplicated": 0,
  "jobs_failed": 0,
  "duplicates": [],
  "errors": [],
  "status_url": "/v1/jobs/batch_01h45ytscbebyvny4gc8cr8ma2"
}

Job lifecycle

Each job transitions through a defined set of statuses:

blocked → queued → running → succeeded
                           → failed
                           → dead_letter
              ↕
           paused
              ↓
          canceled

The batch has its own status:

Scheduling

Use not_before to schedule a batch for future execution:

{
  "label": "Scheduled renewal update",
  "not_before": "2026-06-01T00:00:00Z",
  "commands": [...]
}

Jobs remain blocked until the scheduled time, then move to queued for processing. This is useful for maintenance windows, coordinated rollouts, or time-sensitive operations.

Idempotency

Include an idempotency_key on any command to prevent duplicate processing:

{
  "type": "domain_create",
  "idempotency_key": "reg-example-com-2026-q1",
  "payload": {
    "name": "example.com",
    ...
  }
}

If a job with the same idempotency key has already been processed, the command is skipped. The batch response reports these in the duplicates array:

{
  "duplicates": [
    {
      "index": 0,
      "existing_job_id": "job_01h45ytscbebyvny4gc8cr8ma2",
      "existing_batch_id": "batch_01h35xrscbebyvny4gc8cr8ma2",
      "resource_key": "example.com"
    }
  ]
}

This is especially important for domain registrations and transfers where accidental duplicates would have financial impact.

Limits

Available commands

Single-resource commands

Bulk commands

See Domain commands and DNS & infrastructure commands for full payload details and examples.

Related API Reference

• POST /v1/jobs
• GET /v1/jobs
• GET /v1/jobs/{batch_id}
• GET /v1/jobs/{batch_id}/jobs