Batches
Classify a file of products - upload an .xlsx or .csv file, choose the columns, start it, follow its progress and download the results.
A batch classifies every row of a spreadsheet. The flow has five steps:
- Upload the file (
POST /api/batches). The answer lists the columns found, a suggested mapping and a preview. Nothing is classified yet. - Optionally check the rows with your column mapping (
POST /api/batches/{batch_id}/validate). - Start it (
POST /api/batches/{batch_id}/start) with the column mapping. The start can answer402with one of three codes:out_of_creditswhen the account cannot be charged for the rows,trial_endedwhen the free trial of the account has ended, andowner_trial_endedwhen the batch belongs to another account whose trial has ended (A read-only account). - Poll
GET /api/batches/{batch_id}/progressuntil the status iscompletedorcompleted_with_errors, or wait for thebatch.completedwebhook (Asynchronous work). - Read the rows (
GET /api/batches/{batch_id}/rows) or download the results as Excel (GET /api/batches/{batch_id}/export).
Each row that is classified becomes a lookup of the kind batch (Lookups) and can be charged (Rate limits and quotas). Rows
send no lookup.completed event: the batch sends batch.completed when it is done. Batches need the plan
feature feature.batch, and the number of rows is limited by the plan
(Rate limits and quotas).
An .xlsx or .csv file whose first row holds the column names. GET /api/batches/template gives a file to
start from, with the columns description, material, use, composition, origin, notes, sku and
hts_code. Your own column names work too: the column mapping says which column holds which field. Only
description is required.
The size of the file is limited, and the limits are read from GET /api/limits
(System) rather than assumed: the service can be configured with other values.
| Limit | Field of GET /api/limits |
Default |
|---|---|---|
| The size of the file, and the text of all its cells together | max_upload_mb |
25 MB unless the service is configured otherwise |
| The rows of the file. The header row is not counted; a blank row between two rows with data is | max_batch_rows |
2000 unless the service is configured otherwise |
The size of an .xlsx file once unpacked |
max_upload_unpacked_mb |
50 MB |
| The columns that hold a value | max_upload_columns |
64 |
| The text of one cell | max_upload_cell_chars |
10000 characters |
| The description of a row | max_description_chars |
2000 characters unless the service is configured otherwise |
A file over one of the first five is refused at upload, whole: it is never cut short. A file that is too large is
answered 413 or 422 (When an upload is refused); a file over any of the other
limits, and a file whose cells hold more text together than the size limit, is answered 422. The text of the
cells is counted in bytes (How the text of a file is counted), and the column
names have a limit of their own (The column names). A row whose description is too long does
not refuse the file: the row check reports it on that row. The plan of the account can allow fewer rows than the
service does, and answers 403 with the code plan_limit (Errors).
| Mapping field | Column that holds |
|---|---|
description |
The product description. Required |
material, use, composition, origin, notes |
The same fields as on a lookup |
sku |
Your SKU code. Needed for save_to_catalog |
existing_code |
The code in use today. It is checked against the tariff schedule and compared with the suggestion |
The text of all the cells of a file together, the header row included, is held to max_upload_mb. It is counted in
the bytes the text takes in UTF-8, not in characters, and a quote ("), a backslash, a tab and a line break inside
a cell are each counted twice. A file over that is answered 422 with the code validation_error and the detail
File exceeds the 25 MB limit (English, with the number in force): the same answer as for a file that is too large.
So a file that is under max_upload_mb can be refused for its text:
- an
.xlsxfile is compressed, so its text can be much larger than the file; - a
.csvfile in a legacy single-byte encoding takes one byte for an accented letter, which takes two bytes in UTF-8; - a file full of quotes, backslashes, tabs or line breaks is counted at twice their number.
The same file is refused again. Split it into several files, with fewer rows each.
A row is stored and returned with its column names, so the names count once for every row: the bytes of all the
column names of row 1 together (counted as in How the text of a file is counted),
multiplied by the number of rows after the header, may not exceed max_upload_mb. The rows are the ones
max_batch_rows counts. A name that is repeated is stored with a number after it, and an empty name is replaced by
a label made from its column letter; both count as they are stored.
A file over that is answered 422 with the code validation_error and the detail "The column names in row 1 are
too long for a file of 2000 rows. Shorten them and send the file again." (English, with the number of rows of the
file). At the defaults, 25 MB and 2000 rows, the names of row 1 may take a little over 13,000 bytes in all; that
number is an example of the defaults and not a limit of its own. This limit is not a field of GET /api/limits: it
follows from max_upload_mb and from the rows of the file. The same file is refused again: shorten the names, or
send fewer rows in each file.
The service cleans the text of each cell when it reads the file. Every control character other than a tab and a
line feed (the codes U+0000 to U+001F and U+007F to U+009F) becomes a space, CR LF and a lone CR become a line
feed, and the cell is trimmed. So preview, the raw of a row (The row object) and the exported
file can differ from the bytes of the file in exactly that way. Tabs and line feeds inside a cell are kept.
| Field | Type | Meaning |
|---|---|---|
id |
string | The id of the batch |
created_at, updated_at |
string | ISO 8601, UTC |
filename |
string | The name of the uploaded file |
status |
string | uploaded, queued, running, completed or completed_with_errors |
columns |
array | The column names found in the file |
column_mapping |
object | The mapping the batch was started with |
market, dataset_version |
string | The market and tariff version of the batch |
validation |
object | The suggested mapping and the result of the row check |
total_rows, processed_rows, failed_rows |
integer | Counters |
counts |
object | Rows per row status |
error |
string or null | Not set today: a failure belongs to a row, and a batch with failed rows ends as completed_with_errors |
save_to_catalog |
boolean | Whether rows are saved to the SKU catalog |
preview |
array | The first rows of the file: after an upload, and on GET /api/batches/{batch_id} with preview=true |
| Field | Type | Meaning |
|---|---|---|
row_index |
integer | The row number in the file. The first data row is 2 |
raw |
object | The cells of the row, by column name |
status |
string | pending, processing, done, error, skipped or duplicate (the same product as an earlier row, named in duplicate_of, whose result it reuses) |
issues |
array | What the row check found |
duplicate_of |
integer or null | The row_index it duplicates |
lookup_id |
string or null | The lookup of the row |
attempts |
integer | How often it was tried |
error |
string or null | Why it failed |
result_status, recommended_code, confidence |
- | The outcome of the lookup |
code_check |
object | The check of the existing code, when a column was mapped to existing_code |
final_code |
string or null | The reviewer's code, once decided |
When the free trial of the account has ended, the account is read-only: reading a batch, its rows and its results,
and downloading them, still work. Uploading a file, checking the rows, starting a batch, retrying the failed rows
and editing a row are answered 402 with the code trial_ended, before the fields of the request are checked
and before the batch is looked up, so an unknown batch id is answered 402 too. No batch is created and nothing
is changed (Errors).
A batch that exists runs for the account that owns it. Starting it, retrying it and editing one of its rows are
also refused when the trial of the owner has ended and the caller is another account, a key with the reviewer or
admin role: the answer is 402 with the code owner_trial_ended, which does not say when the trial ended. The
owner is answered trial_ended, with the date.
A batch that is running when the trial of its owner ends is not stopped as a whole. The rows that were not processed
yet end with the status error, and their error says that the row was not processed because the free trial of
the account that owns the batch had ended. For the owner that text names the day the trial ended, for as long as
the trial is ended; every other reader, in the list of rows and in the exported file, reads the text without the
date. POST /api/batches/{batch_id}/retry is refused for as long as the account is read-only.
GET /api/batches/template
An .xlsx file with the columns description, material, use, composition, origin, notes, sku and hts_code, example rows and a guide sheet.
Returns 200 with a file (application/vnd.openxmlformats-officedocument.spreadsheetml.sheet).
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.
curl "https://htspilot.com/api/batches/template" \
-H "X-API-Key: hts_EXAMPLE_KEY_REPLACE_ME" \
-o "hts_lookup_template.xlsx"import json
import os
import urllib.request
request = urllib.request.Request(
"https://htspilot.com/api/batches/template",
headers={"X-API-Key": os.environ["HTS_PILOT_API_KEY"]},
method="GET",
)
with urllib.request.urlopen(request) as response, open("hts_lookup_template.xlsx", "wb") as out:
out.write(response.read())import { writeFile } from "node:fs/promises";
const response = await fetch("https://htspilot.com/api/batches/template", {
headers: { "X-API-Key": process.env.HTS_PILOT_API_KEY },
});
await writeFile("hts_lookup_template.xlsx", Buffer.from(await response.arrayBuffer()));200{
"file": true,
"content_type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
"content_disposition": "attachment; filename=\"hts_lookup_template.xlsx\"",
"bytes": 11736
}
POST /api/batches
Changes data in your account when executed. Send the file as multipart/form-data in the field file. The first row holds the column names; GET /api/batches/template gives a file to start from. The answer lists the columns found, a suggested mapping and a preview; nothing is classified until the batch is started.
Request body (multipart/form-data)
| Name | Type | Required | Description |
|---|---|---|---|
file |
file | Yes | - |
Returns 200 with BatchOut.
Errors: 401 No valid API key was sent; 402 The free trial of the account has ended and the account is read-only: trial_ended; 403 The role of the key, the plan of the account, or the workspace of the request does not allow this call; 408 The body of the request did not arrive in time. The file was not read and the connection is closed; 413 The body is larger than the upload limit allows (max_upload_mb of GET /api/limits); 415 The body is not multipart/form-data; 422 The request is not valid; 429 The service is reading other files, or the same caller already has uploads waiting. The file was not read: send it again after the seconds in the Retry-After header; 500 An unexpected failure.
curl -X POST https://htspilot.com/api/batches \
-H "X-API-Key: hts_EXAMPLE_KEY_REPLACE_ME" \
-F "file=@products.csv"
Give an upload a request timeout above 90 seconds plus the time your connection needs to send the file: when the service is busy reading other files, the answer can be held that long before it comes (An upload that waits). The wait starts only once the whole file has arrived, so a timeout that covers the whole request must also cover the sending.
Read the answer as it arrives. The service gives a reader a time to take the whole answer, counted from the start of
the answer, its status line and headers included: the time its size takes at 64 KiB per second, never less than 10
seconds and never more than 60. The answer of this call is small, so a reader has about 10 seconds. After that the
service sends no more and closes the connection, and the client sees a body shorter than the length it was told. The file was read by then and the batch may exist, so read GET /api/batches before you send the
file again, as after any timeout or connection error.
curl -X POST "https://htspilot.com/api/batches" \
-H "X-API-Key: hts_EXAMPLE_KEY_REPLACE_ME" \
-F "file=@products.csv"import json
import os
import urllib.request
boundary = "hts-pilot-example"
data = b""
for field, name in [["file", "products.csv"]]:
with open(name, "rb") as f:
data += (f"--{boundary}\r\nContent-Disposition: form-data; name=\"{field}\"; filename=\"{name}\"\r\n"
"Content-Type: application/octet-stream\r\n\r\n").encode() + f.read() + b"\r\n"
data += f"--{boundary}--\r\n".encode()
request = urllib.request.Request(
"https://htspilot.com/api/batches",
data=data,
headers={"X-API-Key": os.environ["HTS_PILOT_API_KEY"], "Content-Type": f"multipart/form-data; boundary={boundary}"},
method="POST",
)
with urllib.request.urlopen(request) as response:
print(json.load(response))import { readFile } from "node:fs/promises";
const form = new FormData();
form.append("file", new Blob([await readFile("products.csv")]), "products.csv");
const response = await fetch("https://htspilot.com/api/batches", {
method: "POST",
headers: { "X-API-Key": process.env.HTS_PILOT_API_KEY },
body: form,
});
console.log(await response.json());200{
"id": "505324244bd449b68bdf62d6e2ab15a8",
"created_at": "2026-10-09T03:17:01.126388Z",
"updated_at": "2026-10-09T03:17:01.126897Z",
"filename": "products.csv",
"status": "uploaded",
"columns": [
"description",
"material"
],
"column_mapping": {
"description": "description",
"material": "material",
"origin": "origin",
"sku": "sku",
"existing_code": "hts_code"
},
"market": "",
"dataset_version": null,
"validation": {
"suggested_mapping": {
"description": "description",
"material": "material",
"origin": "origin",
"sku": "sku",
"existing_code": "hts_code"
},
"precheck": {
"total": 3,
"empty": 0,
"examples": 0,
"invalid": 0,
"duplicates": 0,
"valid": 3,
"warnings": 0,
"issues": []
}
},
"total_rows": 3,
"processed_rows": 0,
"failed_rows": 0,
"error": null,
"save_to_catalog": false,
"counts": {
"pending": 3
},
"preview": [
{
"row_index": 2,
"description": "Men's T-shirt, knitted, 100% cotton, short sleeves",
"material": "cotton",
"origin": "VN",
"sku": "EXAMPLE-TSH-001",
"hts_code": "6109.10.00.12"
},
{
"row_index": 3,
"description": "Cotton terry bath towel, 70 x 140 cm",
"material": "cotton",
"origin": "IN",
"sku": "EXAMPLE-TWL-014",
"hts_code": ""
}
]
}
Besides the answers every operation has (Errors), an upload can be refused because the account is
read-only, for its size, for how it is sent, because its body arrives too slowly, or because the service is busy. All these answers have the body of every
other error: detail, in the language of the request, and code (Errors).
| Status | code |
Meaning | What to do |
|---|---|---|---|
401 |
unauthenticated |
The request names no key, or the key is not accepted (A request with no key). No batch was created | Send a valid key in X-API-Key. Do not retry the same call |
402 |
trial_ended |
The free trial of the account has ended and the account is read-only (A read-only account). No batch was created | Do not retry: the same upload is refused again |
408 |
request_timeout |
The file took too long to arrive and was not read (A file that arrives too slowly). No batch was created | Do not retry on your own: a person or the calling program decides (a faster connection, a smaller file). Sending again is safe |
413 |
payload_too_large |
The request is larger than the upload limit allows. No batch was created | Do not send it again: the same file is refused again. Split the file |
415 |
unsupported_media_type |
The body is not multipart/form-data (A body that is not a file). Nothing was read |
Fix how the request is built: a form with the field file. Do not retry |
422 |
validation_error |
The file is over the size limit by only a little, or its text or its column names are too long, or it is over another limit, or it cannot be read (The file) | Fix the file; the same file fails again |
429 |
rate_limited |
The service is reading other files and had no room for yours, or the same key already has uploads waiting, or too many files are arriving at the moment (An upload that waits). Nothing was read and no batch was created | Wait the seconds in Retry-After, then send the same upload again |
The request is refused when its body is larger than max_upload_mb of GET /api/limits (megabytes of 1,048,576
bytes) plus 64 KiB, which is allowed for what a multipart body adds around the file. A length declared in
Content-Length that is over this is refused before the body is parsed and before the key is checked, so such a
413 does not tell you whether the key is valid. A body sent without a declared length is counted as it arrives, and
is refused with 413 when the count passes the limit; its key was checked before that. detail is
File exceeds the 25 MB limit (English, with the number in force); the answer has no details.
A file that is over max_upload_mb by less than those 64 KiB passes that first check and is refused when the file
is read, with 422 (validation_error) and the same detail. So a file over max_upload_mb is answered 413, or
422 in that narrow band: treat both as "the file is too large". The other limits of The file are
answered 422 only.
What to do:
- Read
max_upload_mbfromGET /api/limitsbefore you send, and split a larger file into several. - Do not retry a
413. - A client that writes its whole body before it reads the answer (a browser, most HTTP libraries) can read the
413when the whole body is at most 64 MiB, or twice the largest body the route lets through when that is more: the rest of the body is read and thrown away, the413is sent when the body has ended, and the connection stays usable. A larger body, or one still arriving 60 seconds after the refusal, gets the413at once with the headerConnection: close, and a client that is still writing may see the connection reset instead of the answer. Treat a connection reset during the upload of a very large file as "probably too large": compare its size withmax_upload_mb. - A client that sends
Expect: 100-continueis answered at once, before it sends its body.
A request that names no credential at all, with no X-API-Key and no Authorization: Bearer ..., is answered 401
with the code unauthenticated before its body is read. In English the detail is "Please sign in". A key that is
sent and not accepted is answered 401 in the same way, before its body is read and before any wait in line.
The checks made before the body is read come in this order: a declared Content-Length over the limit gives 413
first (so that 413 says nothing about the key), then a missing or not accepted credential gives 401, then a body
that is not a form gives 415, then too many files arriving at the moment give 429
(An upload that waits). So for a caller that is not accepted, the 401 comes before
the 415, and before the 408 and the 413 of a body that has no declared length. Like the 413, these answers
are sent when the rest of the body has been read and thrown away, if it is small enough; otherwise the answer is
sent at once with Connection: close, and a client that is still writing may see the connection closed instead of
the answer.
Nothing was read and no batch was created. A 401 is a problem of configuration: do not retry it
(Authentication).
A file is sent as multipart/form-data, in a form with the field file. A body whose Content-Type is anything
else, or that has none, is answered 415 with the code unsupported_media_type before the body is read. In English
the detail is "The file must be sent as multipart/form-data." The media type is read without its parameters and
in any case.
This is a defect of the client: the same request is refused again. Fix how the request is built, and do not retry
it. With curl, -F "file=@products.csv" builds the form and sets the Content-Type; let your HTTP client do the
same instead of writing the header by hand.
A body under the size limit has a time to arrive in. The whole of it has the time the largest allowed body takes at
128 KiB per second (about 1 Mbit/s), and never less than 60 seconds: about 200 seconds at the default limit of 25
MB. That time follows the limit in force and not the size of the file you send. Between two pieces of the body there
may be at most 30 seconds. Past either, the answer is 408 with the code request_timeout, and in English the
detail is "The file took too long to arrive and was not read. Send it again."
The answer has the header Connection: close, and a client that is still writing may see the connection closed
instead of the answer. The clock stops when the body has arrived: waiting in line (An upload that
waits) and reading the file are not on it. Nothing was read and no batch was created.
What to do:
- Do not retry a
408automatically. The same file over the same connection is likely to be too slow again. A person, or the program that calls, decides: a faster connection, or a smaller file. - Sending the file again is safe: nothing was stored.
The service reads a limited number of uploaded files at the same time: 2 unless the service is configured
otherwise. An upload that finds no room waits in line, first come first served, for up to 30 seconds (unless the
service is configured otherwise, and never more than 90), and is then answered 429 with the code rate_limited,
the header Retry-After: 10 and details.retry_after_seconds: 10. When the line is already full (four waiting for
each place) the answer is the same and comes at once. In English the detail is "Other files are being read at the
moment. Your file was not read; send it again in 10 seconds." The key is checked before the body is read and before
the wait: a call with a key that is not accepted is answered 401.
The same answer is given before the file is read, when too many files are arriving at the moment. The service takes at
most 16 upload bodies at the same time (unless it is configured otherwise), three of them from one caller. A body
counts from the moment the service lets it through until its last byte has arrived; then the places above bound what
is held. One more body is answered 429 with the same detail, Retry-After: 10 and
details.retry_after_seconds: 10, and nothing of it is kept.
The places are shared between callers. A caller is an API key: two keys of one account are two callers. One caller
holds one place at a time and may have two more uploads waiting; one upload more from the same caller is answered
429 at once, with the same body, Retry-After: 10 and details.retry_after_seconds: 10. An upload that waits for
a place of its own caller does not keep another caller from a place that is free. A place is held until the answer
of the upload has been read, not only until the file is parsed (Rate limits and
quotas).
The file was not read and no batch was created, so sending the same upload again is safe and creates one batch. This is the one failure of an upload that is right to repeat on its own:
- Send the uploads of one key one after the other. A
429that comes at once means that the same caller already has uploads waiting or arriving, that the line is full, or that the service has as many files arriving as it takes. - Wait the seconds in
Retry-After, send the same upload again, and stop after a bounded number of attempts. - Give the request a timeout above 90 seconds plus the time your connection needs to send the file, so that the answer is not lost to your own client.
- After any other failure of an upload, above all a timeout or a connection error, do not send the file again
blindly: the batch may exist. Read
GET /api/batchesfirst. An upload whose caller goes away while it waits in line is not read and not stored, but the client cannot know whether its file was still waiting or already read.
This is not a limit per minute: it does not count your calls, it only bounds how many files are read at once (Rate limits and quotas).
POST /api/batches/{batch_id}/validate
Changes data in your account when executed.
Path parameters
| Name | Type | Description |
|---|---|---|
batch_id |
string | - |
Request body (application/json)
| Name | Type | Required | Description |
|---|---|---|---|
column_mapping |
ColumnMapping | Yes | - |
market |
string | No | Up to 8 characters |
tariff_version |
string or null | No | - |
save_to_catalog |
boolean | No | Save/update the SKU in the shared catalog (requires a sku column). Default false |
column_mapping: ColumnMapping
| Name | Type | Required | Description |
|---|---|---|---|
description |
string | Yes | - |
material |
string or null | No | - |
use |
string or null | No | - |
composition |
string or null | No | - |
origin |
string or null | No | - |
notes |
string or null | No | - |
sku |
string or null | No | - |
existing_code |
string or null | No | Column with the HTS code currently in use: it is checked for validity and compared with the suggestion |
Returns 200 with BatchOut.
Errors: 401 No valid API key was sent; 402 The free trial of the account has ended and the account is read-only: trial_ended; 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.
curl -X POST "https://htspilot.com/api/batches/505324244bd449b68bdf62d6e2ab15a8/validate" \
-H "X-API-Key: hts_EXAMPLE_KEY_REPLACE_ME" \
-H "Content-Type: application/json" \
-d '{
"column_mapping": {
"description": "description",
"material": "material",
"origin": "origin",
"sku": "sku",
"existing_code": "hts_code"
},
"market": "US",
"save_to_catalog": false
}'import json
import os
import urllib.request
request = urllib.request.Request(
"https://htspilot.com/api/batches/505324244bd449b68bdf62d6e2ab15a8/validate",
data=json.dumps({
"column_mapping": {
"description": "description",
"material": "material",
"origin": "origin",
"sku": "sku",
"existing_code": "hts_code",
},
"market": "US",
"save_to_catalog": False,
}).encode(),
headers={"X-API-Key": os.environ["HTS_PILOT_API_KEY"], "Content-Type": "application/json"},
method="POST",
)
with urllib.request.urlopen(request) as response:
print(json.load(response))const response = await fetch("https://htspilot.com/api/batches/505324244bd449b68bdf62d6e2ab15a8/validate", {
method: "POST",
headers: { "X-API-Key": process.env.HTS_PILOT_API_KEY, "Content-Type": "application/json" },
body: JSON.stringify({
"column_mapping": {
"description": "description",
"material": "material",
"origin": "origin",
"sku": "sku",
"existing_code": "hts_code"
},
"market": "US",
"save_to_catalog": false
}),
});
console.log(await response.json());200{
"id": "505324244bd449b68bdf62d6e2ab15a8",
"created_at": "2026-10-09T03:17:01.126388",
"updated_at": "2026-10-09T03:17:01.126897",
"filename": "products.csv",
"status": "uploaded",
"columns": [
"description",
"material"
],
"column_mapping": {
"description": "description",
"material": "material",
"origin": "origin",
"sku": "sku",
"existing_code": "hts_code"
},
"market": "",
"dataset_version": null,
"validation": {
"suggested_mapping": {
"description": "description",
"material": "material",
"origin": "origin",
"sku": "sku",
"existing_code": "hts_code"
},
"precheck": {
"total": 3,
"empty": 0,
"examples": 0,
"invalid": 0,
"duplicates": 0,
"valid": 3,
"warnings": 0,
"issues": []
}
},
"total_rows": 3,
"processed_rows": 0,
"failed_rows": 0,
"error": null,
"save_to_catalog": false,
"counts": {
"pending": 3
},
"preview": [
{
"row_index": 2,
"description": "Men's T-shirt, knitted, 100% cotton, short sleeves",
"material": "cotton",
"origin": "VN",
"sku": "EXAMPLE-TSH-001",
"hts_code": "6109.10.00.12"
},
{
"row_index": 3,
"description": "Cotton terry bath towel, 70 x 140 cm",
"material": "cotton",
"origin": "IN",
"sku": "EXAMPLE-TWL-014",
"hts_code": ""
}
]
}
POST /api/batches/{batch_id}/start
Changes data in your account when executed. column_mapping names the column of the file for each field; only description is required. Spends credits for every row that is classified.
Path parameters
| Name | Type | Description |
|---|---|---|
batch_id |
string | - |
Request body (application/json)
| Name | Type | Required | Description |
|---|---|---|---|
column_mapping |
ColumnMapping | Yes | - |
market |
string | No | Up to 8 characters |
tariff_version |
string or null | No | - |
save_to_catalog |
boolean | No | Save/update the SKU in the shared catalog (requires a sku column). Default false |
column_mapping: ColumnMapping
| Name | Type | Required | Description |
|---|---|---|---|
description |
string | Yes | - |
material |
string or null | No | - |
use |
string or null | No | - |
composition |
string or null | No | - |
origin |
string or null | No | - |
notes |
string or null | No | - |
sku |
string or null | No | - |
existing_code |
string or null | No | Column with the HTS code currently in use: it is checked for validity and compared with the suggestion |
Returns 200 with BatchOut.
Errors: 401 No valid API key was sent; 402 The free trial of the account has ended and the account is read-only: trial_ended. The batch belongs to another account, whose free trial has ended: owner_trial_ended. The credits of the account that is charged do not cover the lookups of the call: out_of_credits; 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.
A batch can be started once, from the status uploaded; a second start answers 409.
curl -X POST "https://htspilot.com/api/batches/505324244bd449b68bdf62d6e2ab15a8/start" \
-H "X-API-Key: hts_EXAMPLE_KEY_REPLACE_ME" \
-H "Content-Type: application/json" \
-d '{
"column_mapping": {
"description": "description",
"material": "material",
"origin": "origin",
"sku": "sku",
"existing_code": "hts_code"
},
"market": "US",
"save_to_catalog": false
}'import json
import os
import urllib.request
request = urllib.request.Request(
"https://htspilot.com/api/batches/505324244bd449b68bdf62d6e2ab15a8/start",
data=json.dumps({
"column_mapping": {
"description": "description",
"material": "material",
"origin": "origin",
"sku": "sku",
"existing_code": "hts_code",
},
"market": "US",
"save_to_catalog": False,
}).encode(),
headers={"X-API-Key": os.environ["HTS_PILOT_API_KEY"], "Content-Type": "application/json"},
method="POST",
)
with urllib.request.urlopen(request) as response:
print(json.load(response))const response = await fetch("https://htspilot.com/api/batches/505324244bd449b68bdf62d6e2ab15a8/start", {
method: "POST",
headers: { "X-API-Key": process.env.HTS_PILOT_API_KEY, "Content-Type": "application/json" },
body: JSON.stringify({
"column_mapping": {
"description": "description",
"material": "material",
"origin": "origin",
"sku": "sku",
"existing_code": "hts_code"
},
"market": "US",
"save_to_catalog": false
}),
});
console.log(await response.json());200{
"id": "505324244bd449b68bdf62d6e2ab15a8",
"created_at": "2026-10-09T03:17:01.126388",
"updated_at": "2026-10-09T03:17:01.152042Z",
"filename": "products.csv",
"status": "queued",
"columns": [
"description",
"material"
],
"column_mapping": {
"description": "description",
"material": "material",
"origin": "origin",
"sku": "sku",
"existing_code": "hts_code"
},
"market": "US",
"dataset_version": "2026-SAMPLE",
"validation": {
"suggested_mapping": {
"description": "description",
"material": "material",
"origin": "origin",
"sku": "sku",
"existing_code": "hts_code"
},
"precheck": {
"total": 3,
"empty": 0,
"examples": 0,
"invalid": 0,
"duplicates": 0,
"valid": 3,
"warnings": 0,
"issues": []
},
"final": {
"total": 3,
"empty": 0,
"examples": 0,
"invalid": 0,
"duplicates": 0,
"valid": 3,
"warnings": 0,
"issues": []
},
"lang": "en"
},
"total_rows": 3,
"processed_rows": 0,
"failed_rows": 0,
"error": null,
"save_to_catalog": false,
"counts": {
"pending": 3
},
"preview": []
}
GET /api/batches/{batch_id}/progress
The status, the counters and version, a token that changes whenever the batch or its rows changed. Poll this and read the rows again only when version differs from the one last seen. The token is opaque: compare it, do not parse it.
Path parameters
| Name | Type | Description |
|---|---|---|
batch_id |
string | - |
Returns 200 with BatchProgressOut.
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.
curl "https://htspilot.com/api/batches/505324244bd449b68bdf62d6e2ab15a8/progress" \
-H "X-API-Key: hts_EXAMPLE_KEY_REPLACE_ME"import json
import os
import urllib.request
request = urllib.request.Request(
"https://htspilot.com/api/batches/505324244bd449b68bdf62d6e2ab15a8/progress",
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/batches/505324244bd449b68bdf62d6e2ab15a8/progress", {
headers: { "X-API-Key": process.env.HTS_PILOT_API_KEY },
});
console.log(await response.json());200{
"id": "505324244bd449b68bdf62d6e2ab15a8",
"status": "completed",
"updated_at": "2026-10-09T03:17:01.572253",
"total_rows": 3,
"processed_rows": 3,
"failed_rows": 0,
"error": null,
"counts": {
"done": 3
},
"version": "d6ca5f2f9e469a46"
}
GET /api/batches/{batch_id}
Path parameters
| Name | Type | Description |
|---|---|---|
batch_id |
string | - |
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
preview |
boolean | No | Default false |
Returns 200 with BatchOut.
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.
curl "https://htspilot.com/api/batches/505324244bd449b68bdf62d6e2ab15a8" \
-H "X-API-Key: hts_EXAMPLE_KEY_REPLACE_ME"import json
import os
import urllib.request
request = urllib.request.Request(
"https://htspilot.com/api/batches/505324244bd449b68bdf62d6e2ab15a8",
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/batches/505324244bd449b68bdf62d6e2ab15a8", {
headers: { "X-API-Key": process.env.HTS_PILOT_API_KEY },
});
console.log(await response.json());200{
"id": "505324244bd449b68bdf62d6e2ab15a8",
"created_at": "2026-10-09T03:17:01.126388",
"updated_at": "2026-10-09T03:17:01.126897",
"filename": "products.csv",
"status": "uploaded",
"columns": [
"description",
"material"
],
"column_mapping": {
"description": "description",
"material": "material",
"origin": "origin",
"sku": "sku",
"existing_code": "hts_code"
},
"market": "",
"dataset_version": null,
"validation": {
"suggested_mapping": {
"description": "description",
"material": "material",
"origin": "origin",
"sku": "sku",
"existing_code": "hts_code"
},
"precheck": {
"total": 3,
"empty": 0,
"examples": 0,
"invalid": 0,
"duplicates": 0,
"valid": 3,
"warnings": 0,
"issues": []
}
},
"total_rows": 3,
"processed_rows": 0,
"failed_rows": 0,
"error": null,
"save_to_catalog": false,
"counts": {
"pending": 3
},
"preview": []
}
GET /api/batches
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
limit |
integer | No | Minimum 1, maximum 100, default 20 |
Returns 200 with BatchOut[].
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.
curl "https://htspilot.com/api/batches" \
-H "X-API-Key: hts_EXAMPLE_KEY_REPLACE_ME"import json
import os
import urllib.request
request = urllib.request.Request(
"https://htspilot.com/api/batches",
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/batches", {
headers: { "X-API-Key": process.env.HTS_PILOT_API_KEY },
});
console.log(await response.json());200[
{
"id": "505324244bd449b68bdf62d6e2ab15a8",
"created_at": "2026-10-09T03:17:01.126388",
"updated_at": "2026-10-09T03:17:01.572253",
"filename": "products.csv",
"status": "completed",
"columns": [
"description",
"material"
],
"column_mapping": {
"description": "description",
"material": "material",
"origin": "origin",
"sku": "sku",
"existing_code": "hts_code"
},
"market": "US",
"dataset_version": "2026-SAMPLE",
"validation": {
"suggested_mapping": {
"description": "description",
"material": "material",
"origin": "origin",
"sku": "sku",
"existing_code": "hts_code"
},
"precheck": {
"total": 3,
"empty": 0,
"examples": 0,
"invalid": 0,
"duplicates": 0,
"valid": 3,
"warnings": 0,
"issues": []
},
"final": {
"total": 3,
"empty": 0,
"examples": 0,
"invalid": 0,
"duplicates": 0,
"valid": 3,
"warnings": 0,
"issues": []
},
"lang": "en"
},
"total_rows": 3,
"processed_rows": 3,
"failed_rows": 0,
"error": null,
"save_to_catalog": false,
"counts": {
"done": 3
},
"preview": []
}
]
GET /api/batches/{batch_id}/rows
Path parameters
| Name | Type | Description |
|---|---|---|
batch_id |
string | - |
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
status |
string or null | No | - |
offset |
integer | No | Minimum 0, default 0 |
limit |
integer | No | Minimum 1, maximum 2000, default 200 |
Returns 200 with BatchRowOut[].
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.
curl "https://htspilot.com/api/batches/505324244bd449b68bdf62d6e2ab15a8/rows" \
-H "X-API-Key: hts_EXAMPLE_KEY_REPLACE_ME"import json
import os
import urllib.request
request = urllib.request.Request(
"https://htspilot.com/api/batches/505324244bd449b68bdf62d6e2ab15a8/rows",
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/batches/505324244bd449b68bdf62d6e2ab15a8/rows", {
headers: { "X-API-Key": process.env.HTS_PILOT_API_KEY },
});
console.log(await response.json());200[
{
"row_index": 2,
"raw": {
"description": "Men's T-shirt, knitted, 100% cotton, short sleeves",
"material": "cotton",
"origin": "VN",
"sku": "EXAMPLE-TSH-001",
"hts_code": "6109.10.00.12"
},
"status": "done",
"issues": [],
"duplicate_of": null,
"lookup_id": "05d1ada813e44a48a1d17b36903c48ef",
"attempts": 1,
"error": null,
"result_status": "proposed",
"recommended_code": "6109.10.00.14",
"confidence": 0.75,
"code_check": {
"status": "valid",
"code": "6109.10.00.12",
"description": "Chapter 61: Articles of apparel and clothing accessories, knitted or crocheted > T-shirts, singlets, tank tops and similar garments, knitted or crocheted > Of cotton > Men's or boys' > T-shirts, all white, short hemmed sleeves, hemmed bottom, crew or round neckline, or V-neck, without pockets, trim or embroidery",
"detail": "Valid declarable code",
"comparison": "same_hs6"
},
"final_code": null
},
{
"row_index": 3,
"raw": {
"description": "Cotton terry bath towel, 70 x 140 cm",
"material": "cotton",
"origin": "IN",
"sku": "EXAMPLE-TWL-014",
"hts_code": ""
},
"status": "done",
"issues": [],
"duplicate_of": null,
"lookup_id": "55751240263640bb9d7d52dfa52fa5ba",
"attempts": 1,
"error": null,
"result_status": "proposed",
"recommended_code": "6302.60.00.10",
"confidence": 0.74,
"code_check": {},
"final_code": null
}
]
PATCH /api/batches/{batch_id}/rows/{row_index}
Changes data in your account when executed. values maps column names of the file to their new text. row_index is the row number in the file (the first data row is 2).
Path parameters
| Name | Type | Description |
|---|---|---|
batch_id |
string | - |
row_index |
integer | - |
Request body (application/json)
| Name | Type | Required | Description |
|---|---|---|---|
values |
object | Yes | - |
Returns 200 with BatchOut.
Errors: 401 No valid API key was sent; 402 The free trial of the account has ended and the account is read-only: trial_ended. The batch belongs to another account, whose free trial has ended: owner_trial_ended; 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.
curl -X PATCH "https://htspilot.com/api/batches/505324244bd449b68bdf62d6e2ab15a8/rows/2" \
-H "X-API-Key: hts_EXAMPLE_KEY_REPLACE_ME" \
-H "Content-Type: application/json" \
-d '{
"values": {
"description": "Men'\''s T-shirt, knitted, 100% cotton, short sleeves"
}
}'import json
import os
import urllib.request
request = urllib.request.Request(
"https://htspilot.com/api/batches/505324244bd449b68bdf62d6e2ab15a8/rows/2",
data=json.dumps({
"values": {"description": "Men's T-shirt, knitted, 100% cotton, short sleeves"},
}).encode(),
headers={"X-API-Key": os.environ["HTS_PILOT_API_KEY"], "Content-Type": "application/json"},
method="PATCH",
)
with urllib.request.urlopen(request) as response:
print(json.load(response))const response = await fetch("https://htspilot.com/api/batches/505324244bd449b68bdf62d6e2ab15a8/rows/2", {
method: "PATCH",
headers: { "X-API-Key": process.env.HTS_PILOT_API_KEY, "Content-Type": "application/json" },
body: JSON.stringify({
"values": {
"description": "Men's T-shirt, knitted, 100% cotton, short sleeves"
}
}),
});
console.log(await response.json());200{
"id": "505324244bd449b68bdf62d6e2ab15a8",
"created_at": "2026-10-09T03:17:01.126388",
"updated_at": "2026-10-09T03:17:01.478913Z",
"filename": "products.csv",
"status": "queued",
"columns": [
"description",
"material"
],
"column_mapping": {
"description": "description",
"material": "material",
"origin": "origin",
"sku": "sku",
"existing_code": "hts_code"
},
"market": "US",
"dataset_version": "2026-SAMPLE",
"validation": {
"suggested_mapping": {
"description": "description",
"material": "material",
"origin": "origin",
"sku": "sku",
"existing_code": "hts_code"
},
"precheck": {
"total": 3,
"empty": 0,
"examples": 0,
"invalid": 0,
"duplicates": 0,
"valid": 3,
"warnings": 0,
"issues": []
},
"final": {
"total": 3,
"empty": 0,
"examples": 0,
"invalid": 0,
"duplicates": 0,
"valid": 3,
"warnings": 0,
"issues": []
},
"lang": "en"
},
"total_rows": 3,
"processed_rows": 3,
"failed_rows": 0,
"error": null,
"save_to_catalog": false,
"counts": {
"done": 2,
"pending": 1
},
"preview": []
}
POST /api/batches/{batch_id}/retry
Changes data in your account when executed.
Path parameters
| Name | Type | Description |
|---|---|---|
batch_id |
string | - |
Returns 200 with BatchOut.
Errors: 401 No valid API key was sent; 402 The free trial of the account has ended and the account is read-only: trial_ended. The batch belongs to another account, whose free trial has ended: owner_trial_ended; 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.
curl -X POST "https://htspilot.com/api/batches/505324244bd449b68bdf62d6e2ab15a8/retry" \
-H "X-API-Key: hts_EXAMPLE_KEY_REPLACE_ME"import json
import os
import urllib.request
request = urllib.request.Request(
"https://htspilot.com/api/batches/505324244bd449b68bdf62d6e2ab15a8/retry",
headers={"X-API-Key": os.environ["HTS_PILOT_API_KEY"]},
method="POST",
)
with urllib.request.urlopen(request) as response:
print(json.load(response))const response = await fetch("https://htspilot.com/api/batches/505324244bd449b68bdf62d6e2ab15a8/retry", {
method: "POST",
headers: { "X-API-Key": process.env.HTS_PILOT_API_KEY },
});
console.log(await response.json());200{
"id": "505324244bd449b68bdf62d6e2ab15a8",
"created_at": "2026-10-09T03:17:01.126388",
"updated_at": "2026-10-09T03:17:01.572253",
"filename": "products.csv",
"status": "completed",
"columns": [
"description",
"material"
],
"column_mapping": {
"description": "description",
"material": "material",
"origin": "origin",
"sku": "sku",
"existing_code": "hts_code"
},
"market": "US",
"dataset_version": "2026-SAMPLE",
"validation": {
"suggested_mapping": {
"description": "description",
"material": "material",
"origin": "origin",
"sku": "sku",
"existing_code": "hts_code"
},
"precheck": {
"total": 3,
"empty": 0,
"examples": 0,
"invalid": 0,
"duplicates": 0,
"valid": 3,
"warnings": 0,
"issues": []
},
"final": {
"total": 3,
"empty": 0,
"examples": 0,
"invalid": 0,
"duplicates": 0,
"valid": 3,
"warnings": 0,
"issues": []
},
"lang": "en",
"retried_rows": 0
},
"total_rows": 3,
"processed_rows": 3,
"failed_rows": 0,
"error": null,
"save_to_catalog": false,
"counts": {
"done": 3
},
"preview": []
}
GET /api/batches/{batch_id}/export
Path parameters
| Name | Type | Description |
|---|---|---|
batch_id |
string | - |
Returns 200 with a file (application/vnd.openxmlformats-officedocument.spreadsheetml.sheet).
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.
The file is an Excel workbook in the language of the request (Languages).
curl "https://htspilot.com/api/batches/505324244bd449b68bdf62d6e2ab15a8/export" \
-H "X-API-Key: hts_EXAMPLE_KEY_REPLACE_ME" \
-o "products_hts_results.xlsx"import json
import os
import urllib.request
request = urllib.request.Request(
"https://htspilot.com/api/batches/505324244bd449b68bdf62d6e2ab15a8/export",
headers={"X-API-Key": os.environ["HTS_PILOT_API_KEY"]},
method="GET",
)
with urllib.request.urlopen(request) as response, open("products_hts_results.xlsx", "wb") as out:
out.write(response.read())import { writeFile } from "node:fs/promises";
const response = await fetch("https://htspilot.com/api/batches/505324244bd449b68bdf62d6e2ab15a8/export", {
headers: { "X-API-Key": process.env.HTS_PILOT_API_KEY },
});
await writeFile("products_hts_results.xlsx", Buffer.from(await response.arrayBuffer()));200{
"file": true,
"content_type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
"content_disposition": "attachment; filename=\"products_hts_results.xlsx\"",
"bytes": 6843
}