> ## 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-05. The service runs the latest version: https://docs.htspilot.com/system.md

# System

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

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

## Service status

`GET /api/health` (no API key needed)

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

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

**Errors**: `500` An unexpected failure.

**Example request**

```bash
curl "https://htspilot.com/api/health"
```

**Example response** `200`

```json
{
  "status": "ok",
  "environment": "development",
  "demo_mode": true,
  "sample_data_markets": [
    "US"
  ],
  "issues": [],
  "background": {
    "query_embedding": "ok",
    "vn_tariff": "disabled"
  },
  "version": null
}
```

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

| `background` | Values | Meaning |
| --- | --- | --- |
| `vn_tariff` | `disabled`, `no_release`, `pending`, `loading`, `loaded`, `failed`, `differs`, `unknown` | The load of the bundled Vietnam tariff release. `differs`: the file of that release is not the one that was loaded, and nothing was loaded over it |
| `query_embedding` | `ok`, `paused` | `paused`: lookups run on text search alone for the moment ([Lookups](/v/2026-10-05/lookups.md#the-lookup-object), `result.retrieval`) |

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

## The account behind a key

`GET /api/auth/me`

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

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

**Example request**

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

**Example response** `200`

```json
{
  "id": "cce3280fe0e040f688065e1bf8dca65c",
  "name": "Administrator (API: Documentation examples)",
  "email": "admin@example.com",
  "role": "admin",
  "role_label": "Admin",
  "via": "api_key",
  "avatar_url": "",
  "credits": 0,
  "unlimited": true
}
```

| Field | Type | Meaning |
| --- | --- | --- |
| `id`, `name`, `email` | string | The account that created the key. `name` carries the name of the key |
| `role`, `role_label` | string | The effective role of the key ([Authentication](/v/2026-10-05/authentication.md#roles)) |
| `via` | string | `api_key` for a request recognised by its key |
| `credits`, `unlimited` | number, boolean | The balance, and whether the account is exempt |

## Request limits

`GET /api/limits`

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

**Returns** `200` with `LimitsOut`.

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

**Example request**

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

**Example response** `200`

```json
{
  "max_upload_mb": 25,
  "max_upload_unpacked_mb": 50,
  "upload_extensions": [
    ".csv",
    ".xlsx"
  ],
  "max_upload_columns": 64,
  "max_upload_cell_chars": 10000,
  "max_batch_rows": 2000,
  "max_description_chars": 2000,
  "max_sku_bulk_items": 5000
}
```

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

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

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

These limits are about what a request may hold. How many uploaded files the service reads at once is not among
them: an upload that finds the service busy is answered `429` ([Batches](/v/2026-10-05/batches.md#an-upload-that-waits-429)).
