# Official SDKs

Four official client libraries wrap the [REST API v2](/integrations/rest-api/) 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](https://www.npmjs.com/package/@hosttracker/sdk)) | `npm install @hosttracker/sdk` | Node.js 20 or newer (read calls also work in a browser) | [hosttracker-sdk-js](https://github.com/HostTracker/hosttracker-sdk-js) |
| Python | `hosttracker` ([PyPI](https://pypi.org/project/hosttracker/)) | `pip install hosttracker` | Python 3 (sync and async clients) | [hosttracker-sdk-python](https://github.com/HostTracker/hosttracker-sdk-python) |
| Go | `github.com/HostTracker/hosttracker-sdk-go` ([pkg.go.dev](https://pkg.go.dev/github.com/HostTracker/hosttracker-sdk-go)) | `go get github.com/HostTracker/hosttracker-sdk-go` | Go 1.24 or newer | [hosttracker-sdk-go](https://github.com/HostTracker/hosttracker-sdk-go) |
| .NET | `HostTracker.Sdk` ([NuGet](https://www.nuget.org/packages/HostTracker.Sdk)) | `dotnet add package HostTracker.Sdk` | .NET 8 | [hosttracker-sdk-dotnet](https://github.com/HostTracker/hosttracker-sdk-dotnet) |

The Go SDK is also what [`ht-cli`](/integrations/cli/) and the [Terraform provider](/integrations/terraform/) are
built on.

:::note[Plan requirement]
The SDKs call the API with your API token, so your plan must include API access. See
[Rate limits and quotas](/integrations/rate-limits/#which-plans-include-the-api).
:::

## 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](/reference/error-codes/#rest-api-v2-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](/integrations/webhooks/#verify-a-delivery).

## Authenticate

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

```sh
export HT_TOKEN="your-api-token"
```

## First calls

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

**TypeScript / JavaScript**

```js
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**

```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**

```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**

```csharp
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

Methods are named after the API's operation ids, so the operation you find in the
[API reference](https://www.host-tracker.com/apidocs/v2) 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

The API publishes its own OpenAPI 3.1 description, mirrored with an OpenAPI 3.0 twin in the
[HostTracker/openapi](https://github.com/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](/integrations/rest-api/).

Questions about an SDK belong in its GitHub repository; account and billing questions go to
[ht2support@host-tracker.com](mailto:ht2support@host-tracker.com).

## Related

- [REST API v2](/integrations/rest-api/)
- [ht-cli](/integrations/cli/)
- [Terraform provider](/integrations/terraform/)
- [Webhooks](/integrations/webhooks/)