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.