Skip to content
HostTracker Docs

Official SDKs

View as Markdown

Four official client libraries wrap the REST API v2 so you do not hand-write HTTP calls, paging, retries or signature checks. All four are generated from the same published OpenAPI document, so every operation, field and error code has the same name in every language. All four are at version 0.1.0 and MIT licensed.

Language Package Install Runtime Source
TypeScript / JavaScript @hosttracker/sdk (npm) npm install @hosttracker/sdk Node.js 20 or newer (read calls also work in a browser) hosttracker-sdk-js
Python hosttracker (PyPI) pip install hosttracker Python 3 (sync and async clients) hosttracker-sdk-python
Go github.com/HostTracker/hosttracker-sdk-go (pkg.go.dev) go get github.com/HostTracker/hosttracker-sdk-go Go 1.24 or newer hosttracker-sdk-go
.NET HostTracker.Sdk (NuGet) dotnet add package HostTracker.Sdk .NET 8 hosttracker-sdk-dotnet

The Go SDK is also what ht-cli and the Terraform provider are built on.

What every SDK does for you

Section titled “What every SDK does for you”

On top of the generated operations, a small hand-written layer behaves the same way in all four languages:

  • Bearer auth - your token on every request.
  • One error type - every failure is an RFC 9457 problem document with a machine-readable code. Branch on the code, not the HTTP status: rate_limited and quota_exceeded are both 429. See Error codes.
  • Automatic idempotency - every write carries a fresh Idempotency-Key, so a retried write replays the stored answer instead of doing the work twice.
  • Conservative retries - 429 rate_limited and a 503 with Retry-After are retried, honouring that header; quota_exceeded never is.
  • Cursor paging - a helper walks every page; cursors stay opaque.
  • Job and instant-check polling - bulk operations and one-off checks are followed to completion at the pace the server asks for.
  • Webhook signature verification - verify a delivery against your secret before you parse it. See Webhooks.

Authenticate

Section titled “Authenticate”

Mint a token under Integrations -> API (/integrations/api) with the scopes your code needs - see API authentication, tokens and scopes. Keep it out of source code; the examples read it from the HT_TOKEN environment variable.

Terminal window
export HT_TOKEN="your-api-token"

First calls

Section titled “First calls”

Each example lists monitors that are down and runs an instant check.

TypeScript / JavaScript

import { HostTracker } from '@hosttracker/sdk';


const ht = new HostTracker({ token: process.env.HT_TOKEN });


// Monitors that are down right now.
const page = await ht.monitors.listMonitor({ query: { limit: 10, state: ['down'] } });
console.log(page.data.length, 'monitors down');


// Start an instant check and wait for the locations to report.
const result = await ht.runCheck({ url: 'https://example.com', type: 'http' });
console.log(result.state, result.events?.length, 'locations reported');

Python

import os
from hosttracker import HostTracker


ht = HostTracker(token=os.environ["HT_TOKEN"])


page = ht.monitors.list_monitor(limit=50)
for monitor in page.data:
    print(monitor.name, monitor.state, monitor.url)


result = ht.run_check({"url": "https://example.com", "type": "http"})
print(result.state)

The same helpers are awaited on AsyncHostTracker.

Go

c, err := hosttracker.New(os.Getenv("HT_TOKEN"))
if err != nil {
    log.Fatal(err)
}


resp, err := c.ListMonitorWithResponse(ctx, &hosttracker.ListMonitorParams{
    Limit: hosttracker.Ptr(int32(10)),
    State: &[]hosttracker.ListMonitorParamsState{"down"},
})
for _, m := range resp.JSON200.Data {
    fmt.Println(m.Id, *m.Name)
}


res, err := c.RunCheck(ctx, hosttracker.IcCreateRequest{
    Url:  "https://example.com",
    Type: hosttracker.Ptr(hosttracker.IcCreateRequestTypeHttp),
}, nil)
for _, ev := range *res.Events {
    fmt.Println(*ev.Location, ev.Error)
}

Every operation is a flat <OperationId>WithResponse(ctx, ...) method on the client.

.NET

using HostTracker.Sdk;
using HostTracker.Sdk.Generated;


using var client = new HostTrackerClient(Environment.GetEnvironmentVariable("HT_TOKEN"));


var page = await client.Monitors.ListMonitorAsync(limit: 50);
foreach (var m in page.Data)
    Console.WriteLine($"{m.Name} - {m.State}");


var result = await client.RunCheckAsync(new IcCreateRequest { Url = "https://example.com", Type = "http" });
Console.WriteLine($"{result.State} with {result.Events?.Count ?? 0} location report(s)");

The client is thread-safe; register it as a singleton.

Method names

Section titled “Method names”

Methods are named after the API’s operation ids, so the operation you find in the API reference is the method you call: listMonitor, createMonitor, getIncident, createStatusPageIncident, and so on (with each language’s casing - list_monitor in Python, ListMonitorAsync in .NET).

Other languages

Section titled “Other languages”

The API publishes its own OpenAPI 3.1 description, mirrored with an OpenAPI 3.0 twin in the HostTracker/openapi repository. Point any OpenAPI generator at it to get a typed client for a language not listed here. A generated client gives you operations and schemas; the conventions above (auth, errors, idempotency, retries, paging, jobs, signatures) are described in REST API v2.

Questions about an SDK belong in its GitHub repository; account and billing questions go to [email protected].

Section titled “Related”