# Introduction

Welcome to H4C's v1 API! This is a general documentation for H4C public API.

H4C provides remote RESTful APIs over HTTP, making it easy to manage your products and build third-party applications.

This document is a complete reference guide to using H4C's v1 API.

Endpoint: https://host4coins.net/api/v1/

All connections to host4coins.net/api must be issued over HTTPS.

Stateless

H4C's API does not maintain sessions. In other words, a request does not depend on previous requests, only its arguments. It only provides object descriptions.

The API supports the following response codes:

  • 200 - OK,
  • 201 - Created,
  • 202 - No content,
  • 204 - Deleted,
  • 400 - Bad request,
  • 401 - Unauthorized,
  • 403 - Forbidden,
  • 409 - Conflict,
  • 500 - Internal server error.

# Authentication

Every request to H4C's API requires authentication. This is why all our routes require a unique H4C API Key in its headers. If you don't have one yet, you can generate your production API key from the API Key section in settings (opens new window). It consists of public (apipublic) and private (apiprivate) parts, both are required during authentication. Once generated the private part of the API key is only shown to you once and you have to copy it some place safe. Note that every request described below requires the following headers.

Headers:

  • REQUIRED:
    • apipublic
    • apiprivate

# General

# Get list of provided services and domains

Request: GET http://host4coins.net/api/v1/catalog

URI Parameters:

  • (optional) type - string. Can be "service", "domain", "all".

Responses:

  • 200 Body application/json object
{
    "catalog": {
        "services": [
            {
                "id": "1",
                "family": "VPS_S",
                "name": "VPS - Small",
                "description": "0.5 vCPU - 0.5 GB RAM - 16 GB Storage",
                "price": "8",
                "currency": "USD",
                "period": "M"
            },
            ...
        ],
        "domains": [
            {
                "id": "10",
                "family": "DOM_UK",
                "name": ".uk",
                "description": "Domain name .uk for a year",
                "price": "8",
                "currency": "USD",
                "period": "Y"
            },
            ...
        ],
        "rates": [
            {
                "currency": _currency_,
                "rate": {
                    "rate": _rate_,
                    "date": _last_update_date_
                }
            }
            ...
        ]
    },
    "total_count": _N_
}

# Check your balance

Request: GET http://host4coins.net/api/v1/balance

Responses:

  • 200 Body application/json object
{
    "balance": _balance_
}

# Get currencies rates

Request: GET http://host4coins.net/api/v1/rate

Responses:

  • 200 Body application/json object
{
    "rates": [
        {
            "currency": _currency_,
            "rate": {
                "rate": _rate_,
                "date": _last_update_rate_
            }
        }
    ]
}

# Get list of your invoices

Request: GET http://host4coins.net/api/v1/invoices

Responses:

  • 200 Body application/json object
{
    "invoices": [
        {
            "btcpay_id": _btcpay_id_,
            "date": _date_time_,
            "amount": _amount_sats_,
            "btcpay_status": _new/confirmed/complete/expired_
        },
        ...
    ],
    "total_count": _N_
}

# See your activity

Request: GET http://host4coins.net/api/v1/activity

Responses:

  • 200 Body application/json object
{
    "activity": [
        {
            "date": _date_time_,
            "reason": _added account balance/bought a new service/renewed a service/withdrawn money/refund_,
            "amount": _amount_sats_,
            "method": _balance/lightning/onchain_
        },
        ...
    ],
    "total_count": _N_
}

# Services

# Buy a new service

Request: POST http://host4coins.net/api/v1/service

Body: application/json ⁠object with the following properties:

  • REQUIRED
    • catalog_id - number, the id of the service from the catalog, run Get list of provided services to see and choose one,
    • operating_system - number, the id of the operating system run Get list of OS to see the available IDs,
    • ssh_key - string, the name of your SSH key, run Get SSH keys to see the available names.

Responses:

  • 201 Body application/json object
{
    "id": _created_id_
}

# Get list of operating systems

Request: GET http://host4coins.net/api/v1/operating_systems

Responses:

  • 200 Body application/json object
{
    "operating_systems": {
        "1": "Debian 10",
        "2": "Ubuntu Server 18.04 LTS",
        _id_:_name_
    },
    "total_count": _N_
}

# Get list of SSH keys

Request: GET http://host4coins.net/api/v1/ssh_keys

Responses:

  • 200 Body application/json object
{
    "ssh_keys": [
        {
            "name": _ssh_key_name_,
            "value": _ssh_key_value_
        },
        ...
    ],
    "total_count": _N_
}

# Add a new SSH key

Request: POST http://host4coins.net/api/v1/ssh_key

Body: application/json ⁠object with the following properties:

  • REQUIRED
    • name - string, a unique name of your SSH key,
    • value - the value of your SSH key.

Responses:

  • 201
  • 400 application/json ⁠object - error message
  • 500 application/json ⁠object - error message

# Delete an SSH key

Request: DELETE http://host4coins.net/api/v1/ssh_key/{your_key_name}

Responses:

  • 202
  • 403 application/json ⁠object - error message

# Get the list of your services

Request: GET http://host4coins.net/api/v1/services

Responses:

  • 200 Body application/json object
{
    "services": [
        {
            "id": _service_id_,
            "family": _service_family_,
            "description": _description_,
            "start_dt": _start_date_,
            "end_dt": _expiration_date_,
            "status": _service_status_,
            "operating_system": _operating_system_,
            "ssh_key": _ssh_key_name_,
            "host_name": _host_name_,
            "ipv4": _ipv4_,
            "ipv6": _ipv6_,
            "autorenew": _yes_or_no_
        },
        ...
    ],
    "total_count": _N_
}

# Get service details

Request: GET http://host4coins.net/api/v1/service/{service_id}

Responses:

  • 200 Body application/json object
{
    "service_details": {
        "id": _service_id_,
        "family": _service_family_,
        "description": _description_,
        "start_dt": _start_date_,
        "end_dt": _expiration_date_,
        "status": _service_status_,
        "operating_system": _operating_system_,
        "ssh_key": _ssh_key_name_,
        "host_name": _host_name_,
        "ipv4": _ipv4_,
        "ipv6": _ipv6_,
        "autorenew": _yes_or_no_
    },
    "renew_options": "None" or [
      {
        "id": _service_id_from_catalog_,
        "name": _service_name_,
        "description": _description_,
        "price": _price_,
        "currency": _currency_,
        "period": _month_or_year_
      },
      ...
    ],
    "autorenew": _possible_or_impossible_
}

# Domains

# Check whether a domain name is available

Request: GET http://host4coins.net/api/v1/domain

Body: application/json ⁠object with the following properties:

  • REQUIRED
    • catalog_id - number, domain id in the catalog, corresponds to a TLD, run catalog with the param type='domain' to see the TLDs we propose and their IDs,
    • domain_name - string, domain name - the part which goes before the period.

Responses:

  • 200 Body application/json object
{
    "domain_details": {
        "id": _domain_id_,
        "family": _family_,
        "name": _tld_,
        "description": _description_,
        "price": _price_,
        "currency": _currency_,
        "period": _year_or_other_
    },
    "domain _{your_domain_name}_ availability": _available/unavailable/invalid_
}

# Buy a domain name

Request: POST http://host4coins.net/api/v1/domain

Body: application/json ⁠object with the following properties:

  • REQUIRED
    • catalog_id - number, domain id in the catalog, corresponds to a TLD, run catalog with the param type='domain' to see the TLDs we propose and their IDs,
    • domain_name - string, domain name - the part which goes before the period,
    • owner - number, id of a contact entity which will be the domain owner, run contacts to see the list of your domain contacts, create a new domain contact if you don't have any.
  • OPTIONAL
    • admin - number, id of a contact entity which will be the domain administrator,
    • tech - number, id of a contact entity which will be the domain technical support,
    • billing - number, id of the domain's billing contact entity.

Responses:

  • 200 Body application/json object

# Get list of your domain contacts

Request: GET http://host4coins.net/api/v1/contacts

Responses:

  • 200 Body application/json object
{
    "contacts": [
        {
            "id": _contact_id_,
            "given": _given_name_,
            "family": _family_name_,
            "orgname": _company_name_,
            "email": _email_,
            "country": _country_code_,
            "city": _city_,
            "zip": _zip_code_,
            "streetaddr": _street_address_,
            "phone": _phone_number_,
            "type": _person/company/association/public_body/reseller_,
            "brand_number": _brand_number_,
            "fax": _fax_,
            "mobile": _mobile_,
            "siren": _siren_,
            "state": _state_
        },
        ...
    ],
    "total_count": _N_
}

# Get domain contact details

Request: GET http://host4coins.net/api/v1/contact/{contact_id}

Responses:

  • 200 Body application/json object
{
    "contact": {
        "id": _contact_id_,
        "contact": {
            "given": _given_name_,
            "family": _family_name_,
            "orgname": _company_name_,
            "email": _email_,
            "country": _country_code_,
            "city": _city_,
            "zip": _zip_code_,
            "streetaddr": _street_address_,
            "phone": _phone_number_,
            "type": _person/company/association/public_body/reseller_,
            "brand_number": _brand_number_,
            "fax": _fax_,
            "mobile": _mobile_,
            "siren": _siren_,
            "state": _state_
        }
    }
}

# Create a new domain contact

Request: POST http://host4coins.net/api/v1/contact

Body: application/json ⁠object with the following properties:

  • REQUIRED:
    • country ⁠- string, 2-letters country code,
    • email ⁠- string,
    • family - ⁠string, contact's family name (usualy the lastname)
    • given - ⁠string, contact's given name (usualy the firstname)
    • streetaddr - ⁠string,
    • type - ⁠integer, one of: 0, 1, 2, 3, 4; 0=person, 1=company, 2=association, 3=public body, 4=reseller,
    • city - ⁠string,
    • zip - ⁠string,
    • phone - ⁠string,
  • OPTIONAL:
    • brand_number - ⁠string,
    • fax - ⁠string,
    • mobile - ⁠string,
    • orgname - ⁠string, the legal name of the company, association, or public body if the contact type is not 0.
    • siren - ⁠string,
    • state - ⁠string, learn more about state codes here (opens new window).

Responses:

  • 201 Body application/json object
{
    "id": _contact_id_
}

# Delete a domain contact

Request: DELETE http://host4coins.net/api/v1/contact/{your_contact_id}

Responses:

  • 202
  • 403 application/json ⁠object - error message

# Get list of your domains

Request: GET http://host4coins.net/api/v1/domains

Responses:

  • 200 Body application/json object
{
    "domains": [
        {
            "id": _domain_id_,
            "family": _family_,
            "description": _description_,
            "start_dt": _start_date_,
            "end_dt": _expiration_date_,
            "status": _running/expired_,
            "autorenew": _yes/no_
        },
        ...
    ],
    "total_count": _N_
}

# Get domain details

Request: GET http://host4coins.net/api/v1/domain/{domain_id_or_full_name}

Examples:

  • http://host4coins.net/api/v1/domain/136
  • http://host4coins.net/api/v1/domain/host4coins.best

Responses:

  • 200 Body application/json object
{
    "domain_details": {
        "id": _domain_id_,
        "family": _family_,
        "description": _description_,
        "start_dt": _start_date_,
        "end_dt": _expiration_date_,
        "status": _running/expired_,
        "owner_contact": _contact_id_,
        "admin_contact": _contact_id_,
        "billing_contact": _contact_id_,
        "tech_contact": _contact_id_,
        "autorenew": _yes/no_,
        "domain_details": _domain_details_
    },
    "renew_options": "None" or _options_object_,
    "autorenew": _possible/impossible_
}

# LiveDNS management

Route: http://host4coins.net/api/v1/domain/{domain_id_or_full_name}/livedns

Request:

  • GET - returns LiveDNS status information for the given domain.

Responses:

Request:

  • POST - enable LiveDNS, this route is used to apply the correct LiveDNS nameservers for the given domain. It takes no content. If you want to disable LiveDNS, change the nameservers.

Responses:

# Nameservers management

Route: http://host4coins.net/api/v1/domain/{domain_id_or_full_name}/nameservers

Request:

  • GET - returns the nameservers that are currently set on this domain.

Responses:

Request:

  • PUT - change the nameservers that are set on a given domain.

Body and Responses:

# List record types

Returns the list of known record types (A, CNAME, …).

Request: GET http://host4coins.net/api/v1/livedns/rrtypes

Responses:

  • 200 Body application/json object

Example:

{
    "rrtypes": [
        "A",
        "AAAA",
        "ALIAS",
        "CAA",
        "CDS",
        "CNAME",
        "DNAME",
        "DS",
        "KEY",
        "LOC",
        "MX",
        "NS",
        "OPENPGPKEY",
        "PTR",
        "RP",
        "SPF",
        "SRV",
        "SSHFP",
        "TLSA",
        "TXT",
        "WKS"
    ],
    "total_count": 21
}

# Domain's records

Route:

  • http://host4coins.net/api/v1/domain/{domain_id_or_full_name}/records

Requests:

  • GET - list records associated with a domain,
  • POST - creates a new record,
  • PUT - replace the whole zone with new records,
  • DELETE - delete all records.

Bodies and Responses:

# Domain's records by name

Route:

  • http://host4coins.net/api/v1/domain/{domain_id_or_full_name}/records/{record_name}

Requests:

  • GET - list records named {record_name} associated with this domain,
  • POST - create a new record whose name is defined by the path,
  • PUT - replace all records named {record_name},
  • DELETE - delete all records named {record_name}.

Bodies and Responses:

# Domain's records by name and type

Route:

  • http://host4coins.net/api/v1/domain/{domain_id_or_full_name}/records/{record_name}/{record_type}

Requests:

  • GET - get a single single record with its name and type,
  • POST - create a new record whose name and type are defined by the path,
  • PUT - overwrites a single record with {record_name} and {record_type},
  • DELETE - delete record with {record_name} and {record_type}.

Bodies and Responses: