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.
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/.
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());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, the plan of the account, or the workspace of the request 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 or null, boolean | The balance, and whether the account is exempt. While workspaces are switched on, the balance the key's lookups are charged to in its workspace, and null when they are free there (Usage) |
workspace |
object or null | While workspaces are switched on only: id, name and role of the workspace the key acts in, or null when it acts in none. Absent otherwise |
workspace_role |
string or null | While workspaces are switched on only: the role the key acts with in that workspace (member, reviewer or admin), the same as workspace.role. Absent otherwise |
role keeps its three values (entry, reviewer, admin) whether or not workspaces are switched on. Read
workspace_role for what a key may do in its workspace (Authentication).
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());200{
"id": "c8567543a45440a093d0d42fda7c8b86",
"name": "Administrator (API: Documentation examples)",
"email": "admin@example.com",
"role": "admin",
"role_label": "Admin",
"via": "api_key",
"avatar_url": "",
"credits": 0,
"unlimited": true
}
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, the plan of the account, or the workspace of the request 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).
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());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
}