Skip to the content

You are reading the reference as of 2026-10-03. The API serves the latest version. Read this page for the latest version

System

Whether the HTS Pilot service is up, and which account and role an API key belongs to.

Two operations for the first minutes of an integration and for monitoring it afterwards.

Service status

GET /api/health No API key

Answers 200 while the service is up. status is ok or degraded, with the reasons in issues. No key is needed.

Returns 200 with a JSON object, as in the example.

Errors: 500 An unexpected failure.

GET /api/health needs no key. It answers 200 while the service is up; status is ok or degraded, and issues names what is degraded. background reports things that never change status, and version names the running build (null when the environment does not name one).

background Values Meaning
vn_tariff disabled, no_release, pending, loading, loaded, failed, differs, unknown The load of the bundled Vietnam tariff release. differs: the file of that release is not the one that was loaded, and nothing was loaded over it
query_embedding ok, paused paused: lookups run on text search alone for the moment (Lookups, result.retrieval)

New keys and new values can be added: treat one you do not know as informational. The service status over time is published at https://status.htspilot.com/.

GET /api/health
curl "https://htspilot.com/api/health"
import json
import os
import urllib.request

request = urllib.request.Request(
    "https://htspilot.com/api/health",
    headers={},
    method="GET",
)
with urllib.request.urlopen(request) as response:
    print(json.load(response))
const response = await fetch("https://htspilot.com/api/health");
console.log(await response.json());
Response 200
{
  "status": "ok",
  "environment": "development",
  "demo_mode": true,
  "sample_data_markets": [
    "US"
  ],
  "issues": [],
  "background": {
    "query_embedding": "ok",
    "vn_tariff": "disabled"
  },
  "version": null
}

GET /api/auth/me

Returns 200 with a JSON object, as in the example.

Errors: 401 No valid API key was sent; 403 The role of the key, or the plan of the account, does not allow this call; 422 The request is not valid; 500 An unexpected failure.

Field Type Meaning
id, name, email string The account that created the key. name carries the name of the key
role, role_label string The effective role of the key (Authentication)
via string api_key for a request recognised by its key
credits, unlimited number, boolean The balance, and whether the account is exempt
GET /api/auth/me
curl "https://htspilot.com/api/auth/me" \
  -H "X-API-Key: hts_EXAMPLE_KEY_REPLACE_ME"
import json
import os
import urllib.request

request = urllib.request.Request(
    "https://htspilot.com/api/auth/me",
    headers={"X-API-Key": os.environ["HTS_PILOT_API_KEY"]},
    method="GET",
)
with urllib.request.urlopen(request) as response:
    print(json.load(response))
const response = await fetch("https://htspilot.com/api/auth/me", {
  headers: { "X-API-Key": process.env.HTS_PILOT_API_KEY },
});
console.log(await response.json());
Response 200
{
  "id": "a7ba4a2440c7422fb695a1fd80d65ce5",
  "name": "Administrator (API: Documentation examples)",
  "email": "admin@example.com",
  "role": "admin",
  "role_label": "Admin",
  "via": "api_key",
  "avatar_url": "",
  "credits": 0,
  "unlimited": true
}