Domains

Domains are called zones inside the API.

Fields

• default_ttl - Default TTL (cache time) of host records that don’t otherwise specify a TTL. In seconds.
• delegation_errors - 0 or more errors about the domain’s current delegation status. (Read-only)
• delegation_updates - Whether automatic delegation updates are active or inactive.
• domain - The domain itself. Punycode format for international domains.
• domain_provider_id - Detected Registrar, if any. (Read-only)
• domain_utf8 - A copy of domain but with international domains rendered in UTF8. (Read-only)
• external_ref - Arbitrary identifier used to cross reference this zone with a record in your app.
• glue_errors - 0 or more errors about the domain’s current glue status, if used as a vanity domain. (Read-only)
• hosts - 0 or more Host records. (Read-only - update via Hosts)
• id - DNScaster’s ID for the zone, eg: zon_sample123456. (Read-only)
• in_use - When true, ineligible to be deleted (likely in use as a vanity name). (Read-only)
• live_checked_at - Time of the last delegation and glue check. (Read-only)
• nameserver_set_id - Nameserver set to which this domain belongs.
• notes - Plaintext notes.
• nx_ttl - TTL (cache time) used for Non-eXistent records. In seconds.
• object - Always zone. (Read-only)
• synced - Indicated whether all host records are fully synced to all nameservers. (Read-only)
• tags - 0 or more text tags.
• vanity_set_id - Which set of Vanity names is used for this zone’s NS records. If set to best, auto-selects the vanity name with a matching .tld, or if none found, the default vanity name.

List zones

Query params

• external_ref - Filter by external_ref.
• nameserver_set_id - Filter by nameserver_set_id.
• tags - Filter by tags. Specify multiple as one,two; will be OR’d.
• vanity_set_id - Filter by vanity_set_id.
• Plus standard paging params.
  • sort - Fields: domain (default), id.

Request

GET /v1/zones
GET /v1/zones?tags=one,two

Response

On success, 200 with 0 or more zones.

{
  "collection": [
    {
      "default_ttl": 900,
      "delegation_updates": "inactive",
      "domain": "example.com",
      "domain_utf8": "example.com",
      "external_ref": null,
      "glue_updates": "inactive",
      "id": "zon_sample123456",
      "nameserver_set_id": "nst_sample123456",
      "nx_ttl": 900,
      "object": "zone",
      "tags": [],
      "vanity_set_id": null
    }
  ],
  "more_results": false
}

Retrieve a zone

Retrieves a zone by the zone ID or domain name.

Query params

• expand=hosts - Include hosts in the response.

Request

GET /v1/zones/zon_sample123456
GET /v1/zones/example.com
GET /v1/zones/zon_sample123456?expand=hosts

Response

On success, 200 with the zone.

{
  "default_ttl": 900,
  "delegation_errors": [],
  "delegation_updates": "inactive",
  "domain": "example.com",
  "domain_provider_id": null,
  "domain_utf8": "example.com",
  "external_ref": null,
  "glue_errors": [],
  "glue_updates": "inactive",
  "hosts": [],
  "id": "zon_sample123456",
  "in_use": false,
  "live_checked_at": null,
  "nameserver_set_id": "nst_sample123456",
  "notes": null,
  "nx_ttl": 900,
  "object": "zone",
  "synced": true,
  "tags": [],
  "vanity_set_id": null
}

Create a zone

Request

POST /v1/zones

{
  "zone": {
    "domain": "example.org",
    "nameserver_set_id": "nst_sample123456"
  }
}

Response

On success, 201 with the new zone.
On error, 422 with standard error response.

{
  "default_ttl": 900,
  "delegation_errors": [],
  "delegation_updates": "inactive",
  "domain": "example.org",
  "domain_provider_id": null,
  "domain_utf8": "example.org",
  "external_ref": null,
  "glue_errors": [],
  "glue_updates": "inactive",
  "id": "zon_sample123456",
  "in_use": false,
  "live_checked_at": null,
  "nameserver_set_id": "nst_sample123456",
  "notes": null,
  "nx_ttl": 900,
  "object": "zone",
  "synced": true,
  "tags": [],
  "vanity_set_id": null
}

Update a zone

Request

PUT /v1/zones/zon_sample123456
PUT /v1/zones/example.com

{
  "zone": {
    "notes": "DNScaster is amazing!"
  }
}

Response

On success, 200 with the updated zone.
On error, 422 with standard error response.

{
  "default_ttl": 900,
  "delegation_errors": [],
  "delegation_updates": "inactive",
  "domain": "example.com",
  "domain_provider_id": null,
  "domain_utf8": "example.com",
  "external_ref": null,
  "glue_errors": [],
  "glue_updates": "inactive",
  "id": "zon_sample123456",
  "in_use": false,
  "live_checked_at": null,
  "nameserver_set_id": "nst_sample123456",
  "notes": "DNScaster is amazing!",
  "nx_ttl": 900,
  "object": "zone",
  "synced": true,
  "tags": [],
  "vanity_set_id": null
}

Delete a zone

Request

DELETE /v1/zones/zon_sample123456
DELETE /v1/zones/example.com

Response

On success, 202 with an empty response.
On error, 422 with standard error response.

Recheck a zone’s delegation and glue status

Cause DNScaster to recheck a zone’s delegation and glue (where applicable) status. Will return immediately while the domain is rechecked in the background. Wait a bit and then retrieve the zone to see any updated status.

Request

POST /v1/zones/zon_sample123456/check
POST /v1/zones/example.com/check

Response

On success, 202 with an empty response.