Skip to content
This repository was archived by the owner on Mar 26, 2026. It is now read-only.

DOCS.md

Latest commit

 

History

History
1111 lines (776 loc) · 61 KB

DOCS.md

File metadata and controls

1111 lines (776 loc) · 61 KB

Documentation

Table of Contents

Class: HetznerDnsClient

Hetzner DNS API client for Node.js

new HetznerDnsClient(token, [baseUrl])

Create a new Hetzner DNS API client

  • token string Hetzner DNS API token/key
  • baseUrl URL | undefined Base URL for the API (default: https://dns.hetzner.com/api/v1)

hetznerDnsClient.zones

A secondary zone can be created, by adding a primary server before adding any records.

hetznerDnsClient.zones.getAll([options])

Get all Zones

  • options Object Search options
    • options.name string | undefined Full name of a zone. Will return an array with one or no results. Example: example.com
    • options.page number | undefined A page parameter specifies the page to fetch. The number of the first page is 1. Must be >= 1.
    • options.perPage number | undefined Number of zones to be shown per page. Returns 100 by default. Maximum 100.
    • options.searchName string | undefined Partial name of a zone. Will return an array with zones that contain the searched string. Example: example
  • Returns: Promise<Zones>
  • Throws: ApiError, ClientParseError

hetznerDnsClient.zones.create(name, [ttl])

Create Zone

hetznerDnsClient.zones.get(id)

Get Zone

hetznerDnsClient.zones.update(id, name, [ttl])

Update Zone

hetznerDnsClient.zones.delete(id)

Delete Zone

hetznerDnsClient.zones.importZone(id, file)

Import Zone file plain

hetznerDnsClient.zones.exportZone(id)

Export Zone file

hetznerDnsClient.zones.validateZone(file)

Validate Zone file plain

Warning: As of Jan 19, 2023, this endpoint appears to always return an empty array for valid records.

hetznerDnsClient.records

hetznerDnsClient.records.getAll(zoneId)

Get All Records

hetznerDnsClient.records.create(zoneId, name, type, value, [ttl])

Create Record

hetznerDnsClient.records.get(id)

Get Record

hetznerDnsClient.records.update(id, zoneId, type, name, value, [ttl])

Update Record

hetznerDnsClient.records.delete(id)

Delete Record

hetznerDnsClient.records.bulkCreate(records)

Bulk Create Records

hetznerDnsClient.records.bulkUpdate(records)

Bulk Update Records

hetznerDnsClient.primaryServers

Primary servers can only be added to a zone, if no records were added to it, yet. By adding a primary server to a newly created zone, it automatically becomes a secondary zone.

hetznerDnsClient.primaryServers.getAll([zoneId])

Get All Primary Servers

hetznerDnsClient.primaryServers.create(zoneId, address, port)

Create Primary Server

hetznerDnsClient.primaryServers.get(id)

Get Primary Server

hetznerDnsClient.primaryServers.update(id, zoneId, address, port)

Update Primary Server

hetznerDnsClient.primaryServers.delete(id)

Delete Primary Server

Class: Zone

Hetzner DNS Zone

zone.id

Zone ID

zone.name

Zone name (i.e. domain name)

zone.created

Zone creation time

  • Type: Date
  • Read only

zone.modified

Zone modification time

  • Type: Date
  • Read only

zone.ttl

Zone default TTL (time to live) in seconds

zone.secondary

Whether this is a secondary zone Secondary zones have primary servers (see zone.getPrimaryServers()) instead of records (see zone.getRecords())

zone.recordsCount

The number of records in this zone

zone.setTtl(ttl)

Change zone default TTL (time to live)

  • ttl number New zone default TTL
  • Returns: Promise<Zone> The updated zone object. Note: Avoid using the old object after updating it to avoid inconsistencies. You should use the new zone object returned by this method.
  • Throws: ApiError, ClientParseError

zone.importZone(file)

Import records from a zone file

zone.exportZone()

Export zone file

zone.delete()

Delete this zone

zone.getRecords()

Get all records in this zone

zone.getPrimaryServers()

Get all primary servers for this zone

zone.createRecord(name, type, value, [ttl])

Create a new record in this zone

zone.createPrimaryServer(address, port)

Create a primary server for this zone

Class: DnsRecord

Hetzner DNS Record

Enum: DnsRecord.Type

Type of record

  • A A records are the most commonly used type of record. They simply point your hostname to an IPv4 address.
  • AAAA AAAA (quad-A) records are similar to A records, but they point your hostname to an IPv6 address instead of an IPv4 address.
  • PTR PTR records are used to map an IP address to a hostname. They are commonly used for reverse DNS lookups.
  • NS NS records determine which name servers are authoritative to the domain (or subdomain). They are typically used together with A records. Several NS records may be associated with a single zone at once.
  • MX MX records handle the exchange of e-mails, and are used specifically for mail servers.

    Attention: In the “Value” field, remember to put a dot . at the end of the hostname reference if you need one.

  • CNAME CNAME records point your hostname to another domain. IP addresses are not accepted, as these will be handled by the records of the target domain. CNAME records cannot be added to a zone if there are any other existing records with the same name, regardless of type.

    Attention: In the “Value” field, remember to put a dot . at the end of the hostname reference if you need one.

  • RP Information about the responsible person(s) for the domain. Usually an email address with the @ replaced by a .
  • TXT TXT records are plain text records that contain general information about your domain. A TXT record may often follow a certain specification (e.g. DKIM, DMARC) depending on its purpose.
  • SOA Specifies authoritative information about a DNS zone, including the primary name server, the email of the domain administrator, the domain serial number, and several timers relating to refreshing the zone.

    Note: Creating SOA records is not supported by the API.

  • HINFO Record intended to provide information about host CPU type and operating system. It was intended to allow protocols to optimize processing when communicating with similar peers.
  • SRV SRV records are used to specify server locations and their specified services.
  • DANE

    Note: Creating DANE records is not supported by the API.

  • TLSA A record for DANE. RFC 6698 defines “The TLSA DNS resource record is used to associate a TLS server certificate or public key with the domain name where the record is found, thus forming a 'TLSA certificate association'“.
  • DS The record used to identify the DNSSEC signing key of a delegated zone.
  • CAA CAA Records allow you to specify which Certification Authorities can issue a certificate for your zone.

Static method: DnsRecord.getTypeFromString(type)

Get the record type from string

dnsRecord.id

Record ID

dnsRecord.name

Record name

dnsRecord.type

Record type

dnsRecord.value

Record value

dnsRecord.ttl

Record TTL (time to live) in seconds

Null if not set (i.e. depends on the zone default)

dnsRecord.created

Time record was created

  • Type: Date
  • Read only

dnsRecord.modified

Time record was last updated

  • Type: Date
  • Read only

dnsRecord.zoneId

Zone ID this record is associated with

dnsRecord.getZone()

Get the zone object this record belongs to

dnsRecord.update(options)

Update the record

dnsRecord.delete()

Delete the record

Class: PrimaryServer

Primary server

primaryServer.id

ID of the primary server

primaryServer.address

IPv4 or IPv6 address of the primary server

primaryServer.port

Port number of the primary server (from 1 to 65535)

primaryServer.zoneId

ID of zone this primary server is associated with

primaryServer.created

Time primary server was created

  • Type: Date
  • Read only

primaryServer.modified

Time primary server was last updated

  • Type: Date
  • Read only

primaryServer.getZone()

Get zone this primary server is associated with

primaryServer.update(options)

Update primary server

primaryServer.delete()

Delete this primary server

Class: ApiResponse<T extends ErrorModel>

API response object

apiResponse.response

Fetch response

apiResponse.raw

Raw response body

apiResponse.options

Request options

apiResponse.client

API client instance used to make the request

apiResponse.body

Get response body as string

apiResponse.json

Get parsed response body (if JSON). null if not JSON or parsing fails.

  • Type: T | null
  • Read only

Class: Zones

A collection of zones

zones.zones

Get zones in this collection

  • Type: Zone[]
  • Read only

zones.count

Get number of zones in this collection

zones.isLastPage

Check if this is the last page

zones.isComplete

Whether this collection contains all possible zones from the time of fetching.

zones.fetchNextPage()

Fetch next page of zones and attach them to this collection

zones.fetchAllPages()

Fetch all pages after the current page and attach them to this collection.

Note: This method will make multiple API calls and may take a while, depending on the number of zones.

Class: ClientObject<T>

Client object

  • Template: T Raw data model

clientObject.client

API client instance

clientObject._data

Raw data

  • Type: T
  • Read only

Class: BulkCreateRecordsPretty

Response from bulk creating records

bulkCreateRecordsPretty.invalidRecords

Invalid records

bulkCreateRecordsPretty.records

Records that were created

bulkCreateRecordsPretty.validRecords

Valid records

Class: BulkUpdateRecordsPretty

Response from bulk updating records

bulkUpdateRecordsPretty.failedRecords

Failed records

bulkUpdateRecordsPretty.records

Records that were updated

Class: ZoneValidationPretty

Hetzner DNS Zone Validation

zoneValidationPretty.parsedRecords

Number of parsed records

zoneValidationPretty.validRecords

Valid records

Class: ApiError

Hetzner API error

Class property: ApiError.messages

Standard messages returned by the API i.e. messages returned with a standard error JSON response

Class property: ApiError.specialMessages

Non-standard error messages

Sometimes the Hetzner API returns non-JSON responses, or e.g. it issues a redirect to the login page when credentials are invalid

apiError.name

Name of the error

  • Type: "ApiError"
  • Read only
  • Override

apiError.code

Error code

apiError.apiResponse

Full API response

Class: ClientParseError

API client failed to understand and parse the API response

clientParseError.name

Name of the error

  • Type: "ClientParseError"
  • Read only

clientParseError.message

  • Type: "API client failed to understand and parse the API response"
  • Read only

Interface: ErrorModel

Error model of API responses

Interface: ZoneModel

Hetzner DNS zone model

  • id string Unique identifier of the zone
  • created string Zone creation timestamp in ISO 8601 format
  • modified string Timestamp of the last change of the zone in ISO 8601 format
  • legacy_dns_host string Legacy DNS host name of the zone
  • legacy_ns string[] Legacy name server names of the zone
  • name string Name of the zone
  • ns string[] Name server names of the zone
  • owner string Zone owner
  • paused boolean Whether the zone is paused
  • permission string Permission of the zone
  • project string Project of the zone
  • registrar string Zone registrar
  • status "verified" Status of the zone
  • ttl number Default TTL (time to live) in seconds for records in this DNS zone
  • verified string Zone verification timestamp in ISO 8601 format or empty string
  • records_count number Number of records in the zone
  • txt_verification Object TXT record verification
    • name string Name of the TXT record
    • token string Verification token (value of the TXT record)
  • is_secondary_dns boolean Whether this is a secondary zone

Interface: BulkCreateRecords

Bulk create records API response model

Interface: BulkUpdateRecords

Bulk update records response model

Interface: BaseRecordModel

Base record model

Interface: RecordModel

Record model

Interface: PrimaryServerModel

Primary server model

  • id string Primary server ID
  • address string IPv4 or IPv6 address of the primary server
  • port number Port number of the primary server (from 1 to 65535)
  • zone_id string ID of zone this primary server is associated with
  • created_at string Time primary server was created (ISO 8601)
  • updated_at string Time primary server was last updated (ISO 8601)

Interface: PaginatedZones

API response with paginated zones

Interface: PaginatedData

Paginated API response

  • Extends: ErrorModel
  • meta Object Response metadata
    • pagination Object Pagination information
      • page number The current page number (starting at 1)
      • per_page number The number of items shown per page
      • last_page number The number of the last page
      • total_entries number The total number of items

Interface: ZoneValidation

Zone file validation response