Hosts

Fields

• boundary_id - Associated Boundary, if any.
• data - DNS record data or content.
• dns_type - DNS record type.
• effective_ttl - ttl if present, or domain’s default_ttl. (Read-only)
• external_ref - Arbitrary identifier used to cross reference this host with a record in your app.
• fqdn - Hostname and domain combined. In punycode for international domains. (Read-only)
• fqdn_utf8 - A copy of fqdn but with international domains rendered in UTF8. (Read-only)
• hostname - The hostname without the domain. In punycode for international hostnames. (May write both punycode and utf8.)
• hostname_utf8 - A copy of hostname but with international hostnames rendered in UTF8. (Read-only)
• id - DNScaster’s ID for the host, eg: hst_sample123456. (Read-only)
• ip_monitor_id - Associated Monitor, if any.
• notes - Plaintext notes.
• object - Always host. (Read-only)
• priority - DNS priority field for MX and SRV records.
• role - primary (default) or secondary.
• state - active or inactive.
• ttl - TTL (cache time). In seconds. If null, uses the domain’s default_ttl.
• zone_id - Domain to which this host record belongs.

List hosts

Query params

• boundary_id - Filter by boundary_id.
• external_ref - Filter by external_ref.
• dns_type - Filter by dns_type. Specify multiple as A,AAAA; will be OR’d.
• hostname - Filter by hostname.
• ip_monitor_id - Filter by ip_monitor_id.
• state - Filter by state.
• zone_id - Filter by zone_id.
• Plus standard paging params.
  • sort - Fields: hostname (default), id.

One of boundary_id, external_ref, ip_monitor_id, zone_id is required.

Request

GET /v1/hosts?zone_id=zon_sample123456

Response

On success, 200 with 0 or more hosts.

{
  "collection": [
    {
      "boundary_id": null,
      "data": "10.0.0.1",
      "dns_type": "A",
      "effective_ttl": 900,
      "external_ref": null,
      "fqdn": "example.com",
      "fqdn_utf8": "example.com",
      "hostname": null,
      "hostname_utf8": null,
      "id": "hst_sample123456",
      "ip_monitor_id": null,
      "object": "host",
      "priority": null,
      "role": "primary",
      "state": "active",
      "ttl": null,
      "zone_id": "zon_sample123456"
    },
    {
      "boundary_id": null,
      "data": "10.0.0.1",
      "dns_type": "A",
      "effective_ttl": 900,
      "external_ref": null,
      "fqdn": "www.example.com",
      "fqdn_utf8": "www.example.com",
      "hostname": "www",
      "hostname_utf8": "www",
      "id": "hst_sample123456",
      "ip_monitor_id": null,
      "object": "host",
      "priority": null,
      "role": "primary",
      "state": "active",
      "ttl": null,
      "zone_id": "zon_sample123456"
    }
  ],
  "more_results": false
}

Retrieve a host

Request

GET /v1/hosts/hst_sample123456

Response

On success, 200 with the host.

{
  "boundary_id": null,
  "data": "10.0.0.1",
  "dns_type": "A",
  "effective_ttl": 900,
  "external_ref": null,
  "fqdn": "www.example.com",
  "fqdn_utf8": "www.example.com",
  "hostname": "www",
  "hostname_utf8": "www",
  "id": "hst_sample123456",
  "ip_monitor_id": null,
  "notes": null,
  "object": "host",
  "priority": null,
  "role": "primary",
  "state": "active",
  "ttl": null,
  "zone_id": "zon_sample123456"
}

Create a host

Request

POST /v1/hosts

{
  "host": {
    "data": "party time",
    "dns_type": "TXT",
    "zone_id": "zon_sample123456"
  }
}

Response

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

{
  "boundary_id": null,
  "data": "party time",
  "dns_type": "TXT",
  "effective_ttl": 900,
  "external_ref": null,
  "fqdn": "example.com",
  "fqdn_utf8": "example.com",
  "hostname": null,
  "hostname_utf8": null,
  "id": "hst_sample123456",
  "ip_monitor_id": null,
  "notes": null,
  "object": "host",
  "priority": null,
  "role": "primary",
  "state": "active",
  "ttl": null,
  "zone_id": "zon_sample123456"
}

Update a host

Request

PUT /v1/hosts/hst_sample123456

{
  "host": {
    "data": "10.0.0.1"
  }
}

Response

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

{
  "boundary_id": null,
  "data": "10.0.0.1",
  "dns_type": "A",
  "effective_ttl": 900,
  "external_ref": null,
  "fqdn": "www.example.com",
  "fqdn_utf8": "www.example.com",
  "hostname": "www",
  "hostname_utf8": "www",
  "id": "hst_sample123456",
  "ip_monitor_id": null,
  "notes": null,
  "object": "host",
  "priority": null,
  "role": "primary",
  "state": "active",
  "ttl": null,
  "zone_id": "zon_sample123456"
}

Delete a host

Request

DELETE /v1/hosts/hst_sample123456

Response

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