# Introduction

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

H4C provides remote REST 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 - Accepted,
204 - Deleted,
400 - Bad request,
401 - Unauthorized,
402 - Payment required (not enough balance),
403 - Forbidden,
404 - Not found (out of stock),
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 https://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 https://host4coins.net/api/v1/balance

Responses:

200 Body application/json object

{
    "balance": _balance_
}

# Get currencies rates

The rates are updated once an hour from kraken (opens new window). Request: GET https://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 https://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 https://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 https://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.

For example:

{
    "catalog_id": "2",
    "operating_system": "1",
    "ssh_key": "ssh1"
}

Responses:

201 Body application/json object

{
    "id": _created_id_
}

You might want to see the details about your new service.

404,
402

# Get list of operating systems

Request: GET https://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 https://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 https://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 - your public SSH key, which is usually contained in the file '~/.ssh/id_ed25519.pub' or '~/.ssh/id_rsa.pub' and begins with 'ssh-ed25519' or 'ssh-rsa'. Don't use your private SSH key. See more detailed guide here.

For example:

{
    "name": "my_new_key",
    "value": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC0Ask6mHIVgCbFrcvjC9gzAwN6a3xn1/xySIgFSiX+Z+5iZMe+e7o/mLFkoROUDmpRgaq17HMSpoYXmle3hC8REeVG+16Oa/rnGGhhGgaX86GAKwC+l3aijf26feGrz3OvPuC4AGzuPkPlo2V6iKIoOKg8lexvbNLoV/sjrwhkhjmfPUdaBjP4KpKwBUMkz65KBX1ahDikPeLZNqsqsQJ59q8oMTfYoRyXLHSP/EHpD5tdhH5DhC3TJsfrANtGTmP/IMXZScmdy+mkAf/FgIlEkVHCQjvyS4OY1YALQ2W//88IDcvV/tjsI0aTPa/7atTvTGxorrJjkzTBIxNBj9nH"
}

Responses:

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

You might want to check your new ssh key.

# Get details about an ssh key

Request: GET https://host4coins.net/api/v1/ssh_key/{ssh_key_name}

Responses:

200 Body application/json object

{
    "ssh_key": {
        "name": _ssh_key_name_,
        "key": _ssh_key_name_,
        "used_in_services": [hostname family,...] or "Not used in services"
    }
}

# Delete an SSH key

Request: DELETE https://host4coins.net/api/v1/ssh_key/{ssh_key_name}

Responses:

204
401 application/json ⁠object - error message

# Get the list of your services

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

URI Parameters:

OPTIONAL:
- status - string. Can be "pending" or "P", "running" or "R", "installing" or "I", "expired" or "E" (case insensitive).
- renew - string. Can be "possible" or "impossible" (case insensitive).

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 https://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_
}

# Renew a service

Note that it is only possible to renew running or some expired services. Request: POST https://host4coins.net/api/v1/service/{service_id}/{renew_id}

{service_id} - the id of the service to renew,
{renew_id} - the id from the catalog, see the possible values in "renew options" of the service details.

Responses:

# Change the autorenew parameter of a service

It's only possible to set a running service for autorenew. If autorenew is enabled your service will be autorenewed from balance the moment it expires. If not enough of balance your service will expire. Request: PATCH https://host4coins.net/api/v1/service/{service_id}

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

REQUIRED:
- autorenew - string. Can be 'y'/"yes" or 'n'/"no" (case insensitive).

Responses:

200,
400,
500.

# Change the SSH key of a service

It's only possible to change an SSH key for pending services or some running or expired services. If it's a pending service the SSH key will be changed immediatelly, otherwise a task will be created (or updated if already existed) for that purpose. Note that changing SSH key will reboot your server. Request: PATCH https://host4coins.net/api/v1/service/{service_id}

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

REQUIRED:
- ssh_key - string. Has to be a name of a valid SSH key that you already provided before.

Responses:

200,
202,
400,
401,
500.

# Get list of tasks

Request: GET https://host4coins.net/api/v1/tasks

URI Parameters:

OPTIONAL:
(optional) status - string. Can be "pending", "doing", "done", "cancelled", "failed", "all".

Responses:

200 Body application/json object

{
  "tasks": [
        {
            "service_id": _service_id_,
            "service_family": _service_family_,
            "service_description": _service_description_,
            "host_name": _host_name_,
            "action": _action_,
            "status_extended": _extended_status_,
            "status": _status_,
            "dt_pending": _date_
        },
        ...
    ],
    "total_count": _N_
}

# Domains

# Check whether a domain name is available

Request: GET https://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. For example:

{
 "catalog_id": "6",
 "domain_name": "qpwoerty",
}

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 https://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. For example:

{
 "catalog_id": "6",
 "domain_name": "qpwoerty",
 "owner": "1"
}

Responses:

200 Body application/json object

# Get list of your domain contacts

Request: GET https://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 https://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 https://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). For example:

{
            "given": "Katia",
            "family": "Zayats",
            "orgname": "ears and tail",
            "email": "katia@zayats.fr",
            "country": "fr",
            "city": "paris",
            "zip": "75016",
            "streetaddr": "6 Villa Chanez",
            "phone": "+33656565656",
            "type": "0"
}

Responses:

201 Body application/json object

{
    "id": _contact_id_
}

# Update a domain contact

Request: PUT https://host4coins.net/api/v1/contact/{contact_id}

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:

# Delete a domain contact

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

Responses:

204
403 application/json ⁠object - error message

# Get list of your domains

Request: GET https://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 https://host4coins.net/api/v1/domain/{domain_id_or_full_name}

Examples:

https://host4coins.net/api/v1/domain/136
https://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: https://host4coins.net/api/v1/domain/{domain_id_or_full_name}/livedns

Request:

GET - returns LiveDNS status information for the given domain.

Responses:

The same as LiveDNS Management of Gandi API (opens new window)

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:

The same as LiveDNS Management of Gandi API (opens new window)

# Nameservers management

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

Request:

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

Responses:

The same as Nameservers Management of Gandi API (opens new window)

Request:

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

Body and Responses:

The same as Nameservers Management of Gandi API (opens new window)

# List record types

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

Request: GET https://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
}