Skip to the content

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

System

Whether the HTS Pilot service is up, which account and role an API key belongs to, and what a request may hold - the upload, batch and description limits.

Three 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": "cce3280fe0e040f688065e1bf8dca65c",
  "name": "Administrator (API: Documentation examples)",
  "email": "admin@example.com",
  "role": "admin",
  "role_label": "Admin",
  "via": "api_key",
  "avatar_url": "",
  "credits": 0,
  "unlimited": true
}

Request limits

GET /api/limits

What a request may hold on the instance you call: the size and the shape of an upload file, the rows of a batch, the length of a description and the items of a SKU sync. An instance can be configured with other values, so read them here before sending a file instead of assuming a number. Any role may call it. The maximum of page_size and of limit, and the length of a text field, are the same on every instance and are stated in the schema of each operation.

Returns 200 with LimitsOut.

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.

Three of the limits are settings of the service, so the answer can differ from the example above: read them before sending a file instead of assuming a number. The others are not configurable today, and are published here so that a client has one place to read them.

Field Default What it limits
max_upload_mb 25 MB unless the service is configured otherwise The size of the file sent to POST /api/batches, in megabytes of 1,048,576 bytes. The text of all cells together is held to the same number, counted in the bytes it takes in UTF-8, with a quote, a backslash, a tab and a line break each counted twice (Batches): an .xlsx file is compressed, so its text can reach the limit while the file is smaller
max_batch_rows 2000 unless the service is configured otherwise The rows of one batch file. The header row is not counted; a blank row between two rows with data is. The plan of the account can allow fewer (Rate limits and quotas)
max_description_chars 2000 unless the service is configured otherwise The product description of a lookup and of a batch row, in characters. The description field of a request has a maximum of its own, 2000, stated in its schema
max_upload_unpacked_mb 50 The size of an .xlsx file once it is unpacked, all its parts together
upload_extensions .csv, .xlsx The file name extensions an upload may have. The case of the extension does not matter
max_upload_columns 64 The columns of an upload file that hold a value
max_upload_cell_chars 10000 The text of one cell of an upload file, in characters
max_sku_bulk_items 5000 The items of one POST /api/skus/bulk call

A request over max_upload_mb answers 413 with the code payload_too_large when its body is larger than the limit plus 64 KiB, which is allowed for what a multipart body adds around the file, and 422 when the file is over the limit by less than that, or when the text of its cells together, counted in bytes as above, is over it (Batches). The column names of row 1 have a limit that follows from max_upload_mb and from the rows of the file: their bytes, multiplied by the number of rows after the header, may not exceed max_upload_mb, and a file over it answers 422 (Batches). That limit is not a field of GET /api/limits. A request over any other of these limits answers 422 (Errors). One case is not a refusal of the request: a batch row whose description is longer than max_description_chars is reported on that row by the row check, and the rest of the file is accepted.

These limits are about what a request may hold. How many uploaded files the service reads at once is not among them: an upload that finds the service busy is answered 429 (Batches).

GET /api/limits
curl "https://htspilot.com/api/limits" \
  -H "X-API-Key: hts_EXAMPLE_KEY_REPLACE_ME"
import json
import os
import urllib.request

request = urllib.request.Request(
    "https://htspilot.com/api/limits",
    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/limits", {
  headers: { "X-API-Key": process.env.HTS_PILOT_API_KEY },
});
console.log(await response.json());
Response 200
{
  "max_upload_mb": 25,
  "max_upload_unpacked_mb": 50,
  "upload_extensions": [
    ".csv",
    ".xlsx"
  ],
  "max_upload_columns": 64,
  "max_upload_cell_chars": 10000,
  "max_batch_rows": 2000,
  "max_description_chars": 2000,
  "max_sku_bulk_items": 5000
}