Skip to main content

Unofficial Client for API

Project description

Unofficial API Client and Certbot DNS Auth Plugin

Python3 library for accessing the dns api.

PyPI version


This is an unofficial client for the API. I have only implemented very few functions that I need for another hobby project. I am not in any way connected to other then being a paying customer.

I'd be happy to give up this library for an official and supported library.

I have built this library to use it for ddns scripts and let's encrypt wildcard certificate requests.

Validation and sanitizing of any inputs is expected to be done at higher level.



  • certbot dns authenticator plugin
  • implemented all api zone and record functions
  • retry on busy api objects
  • custom dns api helper functions
  • dns api filter helpers
  • dns api helpers

Certbot DNS Authenticator Plugin

Introduced in version 0.3.0, this certbot dns authenticator plugin allows certificates to be requested from letsencrypt for domains hosted by

This allows to create certificates for hosts that may not be reachable for webroot authentication, or that require dns validation. e.g.: internal servers with private dns, wildcard certificates.


  • credentials (path to ini file containing apikey)
  • propagation-seconds (delay between dns record creation and validation) [default: 60]



This is the api key configured at profile - the api key needs only the permissions to list and edit zones. ( DNS_ZONES_LIST & DNS_ZONES_EDIT )

Install with certbot

The plugin is for certbot, which is not yet python3 compatible. Make sure to use python2.

pip install certbot no-hostingde-api


After installation and creating the ini file containing the credentials, the following command can be used to request a certificate using this plugin.

certbot certonly \
    -a no-hostingde-api:dns-hostingde \
    --no-hostingde-api:dns-hostingde-credentials ~/credentials.ini \
    --no-hostingde-api:dns-hostingde-propagation-seconds 60 \

DNS Api Client

So far, only functions for zones, records and zoneConfigs have been implemented. Some functions have been implemented, to allow easier usage of the api for single records, that will query more or less information from the api.

The DnsApiClient has a builtin retry for busy api objects, by default 2s delay and 2 retries.

API functions

The DNS API functions that I have implemented so far are:

  • recordsFind(recordFilter, limit=25, page=1, sort=None)
  • zoneConfigsFind(zoneConfigFilter, limit=25, page=1, sort=None)
  • zonesFind(zoneFilter, limit=25, page=1, sort=None)
  • zoneCreate(zoneConfig, records, useDefaultNameserverSet=False, nameserverSetId=None)
  • zoneDelete(zoneConfigId=None, zoneConfigName=None)
  • zoneRecreate(zoneConfig, records, useDefaultNameserverSet=False, nameserverSetId=None)
  • zoneUpdate(zoneConfig, recordsToAdd, recordsToDelete=[])

There are also helpers to aid with correct data structes for these functions and helper functions, that require less information.

Custom API functions

  • getZonesByFilter(zoneFilter, limit=25, page=1, sort=None)

  • getZonesByRecord(recordName, recordType=None, recordContent=None, limit=25, page=1, sort=None)

  • getZonesByDomainHierarchy(recordName, limit=25, page=1, sort=None)

  • getZoneByRecord(recordName, recordType=None, recordContent=None, limit=25, page=1)

  • getZoneByDomain(recordName, recordType=None, recordContent=None, limit=25, page=1)

  • getRecordsByFilter(recordFilter, limit=50, page=1, sort=None)

  • getRecords(recordName, recordType=None, recordContent=None, limit=50, page=1, sort=None)

  • addZoneRecordWithConfig(zoneConfig, recordName, recordType, recordContent, ttl=600)

  • deleteZoneRecordWithConfig(zoneConfig, recordName, recordType, recordContent)

  • updateZoneRecordWithConfig(zoneConfig, recordName, recordType, recordContent, oldContent, ttl=600)

  • deleteZoneRecordsWithFilter(zoneFilter, recordName, recordType, recordContent=None)

  • setZoneRecordWithFilter(zoneFilter, recordName, recordType, recordContent, oldContent=None, ttl=600)

  • addZoneRecord(zoneName, recordName, recordType, recordContent, ttl=600)

  • deleteZoneRecord(zoneName, recordName, recordType, recordContent)

  • updateZoneRecord(zoneName, recordName, recordType, recordContent, oldContent, ttl=600)

  • deleteZoneRecords(zoneName, recordName, recordType, recordContent=None)

  • setZoneRecord(zoneName, recordName, recordType, recordContent, oldContent=None, ttl=600)

  • addRecord(recordName, recordType, recordContent, ttl=600)

  • deleteRecord(recordName, recordType, recordContent=None)

  • setRecord(recordName, recordType, recordContent, oldContent=None, ttl=600)

  • updateRecord(recordName, recordType, recordContent, oldContent=None, ttl=600)


Adding IPv4 IP:

from hostingde.api.dns import DnsApiClient
client = DnsApiClient("MySecretLongApiKey")
# only 1 api call because we know the zone name:
client.AddZoneRecord("", "", "A", "", ttl=8400)
# alternative for unknown zone - requires 2 api calls, because we need to find the zone first - expensive!
client.AddRecord("", "A", "", ttl=8400)

Adding IPv6 IP:

from hostingde.api.dns import DnsApiClient
client = DnsApiClient("MySecretLongApiKey")
client.AddZoneRecord("", "", "AAAA", "AFFE::1", ttl=8400)

Update IPv4 IP:

from hostingde.api.dns import DnsApiClient
client = DnsApiClient("MySecretLongApiKey")
client.UpdateRecord("", "A", "", "", 60)

In this case the zoneConfigName and TTL are used from the first previous record, ttl can be specified. Value is only updated if there is more than one record or the current value differs from the new value.

Known Issues

  • No warning handling from responses


  • requests



pip install no-hostingde-api


Local install:

git clone
cd hostingde-api
python develop


git clone
cd hostingde-api
pip install -e .


pip install -r dev.requirements.txt
python sdist bdist_wheel


pip install -r dev.requirements.txt
twine upload dist/*


  • 0.3.1: Fix for api zoneConfig changes.


Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

no-hostingde-api-0.3.1.tar.gz (13.2 kB view hashes)

Uploaded source

Built Distribution

no_hostingde_api-0.3.1-py2.py3-none-any.whl (12.7 kB view hashes)

Uploaded py2 py3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page