Use the SDKs

hiloop ships a TypeScript and a Python SDK. Their typed operations and models are generated from the same API contract as the CLI and the API reference. The clients and generated models ship together and stay versioned in lockstep.

The SDKs are published at 0.x during the public preview: typed, versioned, and functional. Pin a version and expect the surface to evolve until GA.

Install

npm install @hiloopai/sdk

pnpm add @hiloopai/sdk

pip install hiloop

Configure a client

Point the client at the hiloop edge and authenticate with your API key. In TypeScript, pass it as the client’s auth option; in Python, as the AuthenticatedClient token. Either way the SDK sends it as an Authorization: Bearer header on every request.

import { createClient } from "@hiloopai/sdk";

const client = createClient({
  baseUrl: "https://api.hiloop.ai",
  auth: process.env.HILOOP_API_KEY,
});

import os
from hiloop import AuthenticatedClient

client = AuthenticatedClient(
    base_url="https://api.hiloop.ai",
    token=os.environ["HILOOP_API_KEY"],
)

In TypeScript, createClient builds an isolated instance you pass to each call as { client }. If you’d rather configure once and skip threading it through, set the package-level default client instead — then every operation uses it automatically:

TypeScript

import { client } from "@hiloopai/sdk";

client.setConfig({
  baseUrl: "https://api.hiloop.ai",
  auth: process.env.HILOOP_API_KEY,
});

The package also exports createConfig for building a config object you reuse across instances.

A first call

Echo your identity — the same check hiloop whoami runs:

import { identityServiceWhoAmI } from "@hiloopai/sdk";

const { data } = await identityServiceWhoAmI({ client });
console.log(data?.principal);

from hiloop.api.identity_service import identity_service_who_am_i

resp = identity_service_who_am_i.sync(client=client)
print(resp.principal)

Handle errors

Every API error uses the same typed envelope, and both SDKs surface it as ErrorBody. Branch on its stable snake_case code (for example not_found, quota_exceeded, rate_limited, internal) — never on the message text, whose wording can change. In TypeScript the envelope is the error half of each call’s result; in Python an error response is returned as an ErrorBody value you narrow with isinstance.

import { identityServiceWhoAmI } from "@hiloopai/sdk";

const { data, error } = await identityServiceWhoAmI({ client });
if (error) {
  throw new Error(`whoami failed (${error.code}): ${error.message}`);
}
console.log(data?.principal);

from hiloop.api.identity_service import identity_service_who_am_i
from hiloop.models import ErrorBody

resp = identity_service_who_am_i.sync(client=client)
if isinstance(resp, ErrorBody):
    raise RuntimeError(f"whoami failed ({resp.code}): {resp.message}")
print(resp.principal)

Two fields carry extra signal when present:

details.quota on quota_exceeded / rate_limited rejections names the limit that rejected the request (metric, limit, current, retry_after_seconds); rate limits also send a Retry-After header.
request_id on server faults (5xx) — quote it when contacting support to locate the failing request.

Patterns to know

Endpoint functions. Every operation is an importable function (for example, projectServiceListProjects) called with { client, body } in TypeScript, or a service module with sync / asyncio variants in Python.
Idempotency keys on create-style mutations. Supply a key explicitly when a retry must remain safe across processes.
Typed request and response models. Bodies and rows are typed (e.g. DataView, QueryRequest, QueryResponse), so your editor guides the call. Full type listings are in the TypeScript and Python SDK reference.

Where to go next

Query telemetry includes TypeScript and Python examples.
The generated TypeScript and Python reference lists every function and type.

Get started

How-to guides

Install

Configure a client

A first call

Handle errors

Patterns to know

Where to go next

​Install

​Configure a client

​A first call

​Handle errors

​Patterns to know

​Where to go next

Install

Configure a client

A first call

Handle errors

Patterns to know

Where to go next