> ## Documentation index
> Fetch the complete documentation index at: https://docs.htspilot.com/llms.txt
> Use this file to discover all available pages before exploring further.

> This page describes the API as of 2026-10-09. The service runs the latest version: https://docs.htspilot.com/batches.md

# 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:

1. Upload the file (`POST /api/batches`). The answer lists the columns found, a suggested mapping and a preview.
   Nothing is classified yet.
2. Optionally check the rows with your column mapping (`POST /api/batches/{batch_id}/validate`).
3. Start it (`POST /api/batches/{batch_id}/start`) with the column mapping. The start can answer `402` with one of
   three codes: `out_of_credits` when the account cannot be charged for the rows, `trial_ended` when the free trial
   of the account has ended, and `owner_trial_ended` when the batch belongs to another account whose trial has
   ended ([A read-only account](#a-read-only-account)).
4. Poll `GET /api/batches/{batch_id}/progress` until the status is `completed` or `completed_with_errors`, or
   wait for the `batch.completed` webhook ([Asynchronous work](/v/2026-10-09/asynchronous-work.md)).
5. 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](/v/2026-10-09/lookups.md)) and can be charged ([Rate limits and quotas](/v/2026-10-09/rate-limits.md#credits)). 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](/v/2026-10-09/rate-limits.md)).

## The file

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](/v/2026-10-09/system.md#request-limits)) 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](#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](#how-the-text-of-a-file-is-counted)), and the column
names have a limit of their own ([The column names](#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](/v/2026-10-09/errors.md#plan-refusals)).

| 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 |

## How the text of a file is counted

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 `.xlsx` file is compressed, so its text can be much larger than the file;
- a `.csv` file 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.

## The column names

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](#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 text of a cell

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](#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.

## The batch object

| 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` |

## The row object

| 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 |

## A read-only account

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](/v/2026-10-09/errors.md#a-read-only-account)).

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.

## Download the template

`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.

**Example request**

```bash
curl "https://htspilot.com/api/batches/template" \
  -H "X-API-Key: hts_EXAMPLE_KEY_REPLACE_ME" \
  -o "hts_lookup_template.xlsx"
```

**Example response** `200`

```json
{
  "file": true,
  "content_type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
  "content_disposition": "attachment; filename=\"hts_lookup_template.xlsx\"",
  "bytes": 11736
}
```

## Upload a file

`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.

**Example request**

```bash
curl -X POST "https://htspilot.com/api/batches" \
  -H "X-API-Key: hts_EXAMPLE_KEY_REPLACE_ME" \
  -F "file=@products.csv"
```

**Example response** `200` (long lists and texts are cut)

```json
{
  "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": ""
    }
  ]
}
```

```bash
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](#an-upload-that-waits-429)). 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.

## When an upload is refused

Besides the answers every operation has ([Errors](/v/2026-10-09/errors.md)), 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](/v/2026-10-09/errors.md#the-error-body)).

| Status | `code` | Meaning | What to do |
| --- | --- | --- | --- |
| `401` | `unauthenticated` | The request names no key, or the key is not accepted ([A request with no key](#a-request-with-no-key-401)). 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](#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](#a-file-that-arrives-too-slowly-408)). 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](#a-body-that-is-not-a-file-415)). 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](#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](#an-upload-that-waits-429)). Nothing was read and no batch was created | Wait the seconds in `Retry-After`, then send the same upload again |

## A file that is too large (413)

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](#the-file) are
answered `422` only.

What to do:

- Read `max_upload_mb` from `GET /api/limits` before 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
  `413` when 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, the `413` is sent when the body has ended, and the connection stays
  usable. A larger body, or one still arriving 60 seconds after the refusal, gets the `413` at once with the header
  `Connection: 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 with
  `max_upload_mb`.
- A client that sends `Expect: 100-continue` is answered at once, before it sends its body.

## A request with no key (401)

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](#an-upload-that-waits-429)). 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](/v/2026-10-09/authentication.md)).

## A body that is not a file (415)

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 file that arrives too slowly (408)

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](#an-upload-that-waits-429)) and reading the file are not on it. Nothing was read and no batch was created.

What to do:

- Do not retry a `408` automatically. 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.

## An upload that waits (429)

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](/v/2026-10-09/rate-limits.md#uploads-read-at-once)).

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 `429` that 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/batches` first. 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](/v/2026-10-09/rate-limits.md#uploads-read-at-once)).

## Check the rows

`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.

**Example request**

```bash
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
}'
```

**Example response** `200` (long lists and texts are cut)

```json
{
  "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": ""
    }
  ]
}
```

## Start a batch

`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.

**Example request**

```bash
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
}'
```

**Example response** `200` (long lists and texts are cut)

```json
{
  "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": []
}
```

A batch can be started once, from the status `uploaded`; a second start answers `409`.

## Follow the progress

`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.

**Example request**

```bash
curl "https://htspilot.com/api/batches/505324244bd449b68bdf62d6e2ab15a8/progress" \
  -H "X-API-Key: hts_EXAMPLE_KEY_REPLACE_ME"
```

**Example response** `200`

```json
{
  "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 a batch

`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.

**Example request**

```bash
curl "https://htspilot.com/api/batches/505324244bd449b68bdf62d6e2ab15a8" \
  -H "X-API-Key: hts_EXAMPLE_KEY_REPLACE_ME"
```

**Example response** `200` (long lists and texts are cut)

```json
{
  "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": []
}
```

## List batches

`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.

**Example request**

```bash
curl "https://htspilot.com/api/batches" \
  -H "X-API-Key: hts_EXAMPLE_KEY_REPLACE_ME"
```

**Example response** `200` (long lists and texts are cut)

```json
[
  {
    "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": []
  }
]
```

## List the rows

`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.

**Example request**

```bash
curl "https://htspilot.com/api/batches/505324244bd449b68bdf62d6e2ab15a8/rows" \
  -H "X-API-Key: hts_EXAMPLE_KEY_REPLACE_ME"
```

**Example response** `200` (long lists and texts are cut)

```json
[
  {
    "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
  }
]
```

## Edit a row

`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.

**Example request**

```bash
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"
  }
}'
```

**Example response** `200` (long lists and texts are cut)

```json
{
  "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": []
}
```

## Retry the failed rows

`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.

**Example request**

```bash
curl -X POST "https://htspilot.com/api/batches/505324244bd449b68bdf62d6e2ab15a8/retry" \
  -H "X-API-Key: hts_EXAMPLE_KEY_REPLACE_ME"
```

**Example response** `200` (long lists and texts are cut)

```json
{
  "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": []
}
```

## Download the results

`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.

**Example request**

```bash
curl "https://htspilot.com/api/batches/505324244bd449b68bdf62d6e2ab15a8/export" \
  -H "X-API-Key: hts_EXAMPLE_KEY_REPLACE_ME" \
  -o "products_hts_results.xlsx"
```

**Example response** `200`

```json
{
  "file": true,
  "content_type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
  "content_disposition": "attachment; filename=\"products_hts_results.xlsx\"",
  "bytes": 6843
}
```

The file is an Excel workbook in the language of the request ([Languages](/v/2026-10-09/languages.md)).
