Skip to content
HostReputeHostReputeHostRepute Docs

Official SDKs

Reference
For:
Developers

HostRepute is preparing an official SDK for Go, Node.js, Python, PHP and Ruby. Each HostRepute SDK wraps the REST API v1: it manages domains and IPs, check profiles, alert channels and delivery hours, starts blocklist, certificate and email authentication checks, and reads Prometheus metrics. All five are at version 0.1.0 under the MIT license.

Languages and packages

Section titled “Languages and packages”
Language Planned package Install command (when it’s published) Minimum version
Go github.com/hostrepute/hostrepute-go go get github.com/hostrepute/hostrepute-go Go 1.23
Node.js @hostrepute/sdk on npm npm install @hostrepute/sdk Node.js 20.10
Python hostrepute on PyPI pip install hostrepute Python 3.10
PHP hostrepute/sdk on Packagist composer require hostrepute/sdk guzzlehttp/guzzle PHP 8.2
Ruby hostrepute on RubyGems gem install hostrepute Ruby 3.2

What works in 0.1.0

Section titled “What works in 0.1.0”

Version 0.1.0 of the Node.js, Python and PHP SDKs doesn’t read some of what the API sends. Use the REST API for the parts marked “No”:

Task Go Node.js Python PHP Ruby
Manage domains and IPs, check profiles, alert channels, delivery hours Yes Yes Yes Yes Yes
List blocklists Yes Yes Yes Yes Yes
Start a blocklist or certificate check Yes Yes Yes Yes Yes
Wait for a blocklist or certificate check and read its result Yes No No No Yes
Run an email authentication check Yes No No No Yes
Read Prometheus metrics Yes No No No Yes
Get a typed error for 402 (not enough credits) Yes No No No Yes
Send a test alert No No No No No

Each language’s page lists its problems under “Known problems in 0.1.0” or in a caution next to the method.

What every SDK shares

Section titled “What every SDK shares”
  • Setup. The client takes a team API token from Settings, then API tokens (read Authentication and API tokens) and talks to https://app.hostrepute.com unless you set another base URL. Give the base URL without /api/v1: the SDKs add it. Only the Ruby SDK reads an environment variable itself, HOSTREPUTE_API_TOKEN.
  • Names. The SDKs use the API’s names, not the portal’s. In the Node.js spelling, hosts are domains and IPs, dataSources blocklists, monitoringProfiles check profiles, alerts alert channels, contactGroups delivery hours and deliverability email authentication.
  • Retries. Up to 3 attempts in total. A 429 is retried for every method and honors Retry-After; 5xx and network errors are retried only for GET, HEAD, OPTIONS, PUT and DELETE, so a check is never started twice. Without Retry-After, the wait is random, up to 200 ms × 2attempt − 1 and at most 5 seconds.
  • Waiting for checks. CheckAndWait, checkAndWait or check_and_wait start a check and poll it every 2 seconds for up to 60 seconds by default. Email authentication checks answer in the same request, so the wait helpers don’t apply to them. Run checks and wait for results explains the API side.
  • Errors. Each SDK has its own classes for 401, 403, 404, 422, 429 and 5xx, with the field errors of a 422 and the Retry-After of a 429. Errors shows the response bodies.

Mistakes to avoid in every SDK

Section titled “Mistakes to avoid in every SDK”
  • Delivery hours. Every SDK sends schedule unchanged, so use the shape the API expects: keys mon to sun, each with enabled, start and end in HH:MM. The days and hours shape in the SDKs’ READMEs is rejected with 422.
  • Clearing a schedule. The SDKs leave out empty values, so update can’t turn existing delivery hours back to “any time”. Send "schedule": null with the REST API instead.
  • Slugs. The update methods for check profiles and delivery hours accept a slug, but the API ignores it on update.
  • Alert frequency. Every SDK offers a daily frequency that the API rejects with 422, and an every_check value that the API stores as once_on_listed_delisted. Use once_on_listed_delisted (Listed and removed) or once_per_check_while_listed (Only when listed).
  • Webhooks. The SDKs’ webhook helpers don’t match what HostRepute sends, so don’t use them. Verify webhook alerts as described in Receive webhooks; scan callbacks can’t be verified yet.

Pick your language

Section titled “Pick your language”
Go SDKTyped structs, context on every call, iterators.
Node.js SDKTypeScript client for Node.js 20.10 and later.
Python SDKSync and async clients built on httpx.
PHP SDKWorks with any PSR-18 HTTP client, such as Guzzle.
Ruby SDKStandard library only, with a shared default client.
Section titled “Related”
Report a problem with this pageHostReputeStatusLog in