> ## 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/ai-agents.md

# Build with AI agents

> What these pages offer to AI agents and coding assistants - every page as Markdown, llms.txt, the OpenAPI document, and ready-made skills that teach an agent to integrate the HTS Pilot API.

If an AI agent or a coding assistant helps you integrate the API, give it these pages in a form it reads well.
Everything here is plain files on this host, and one read-only endpoint that searches them: nothing calls an
assistant service, and nothing here needs an account.

## Every page as Markdown

Each page has a Markdown copy at the same address with `.md`: this page is at [/ai-agents.md](/ai-agents.md), the
introduction at `/index.md`, the lookups reference at `/lookups.md`. The copy is complete: the generated
parameter tables and the examples are in it.

| Address | What |
| --- | --- |
| `/<page>.md` | One page as Markdown |
| [/llms.txt](/llms.txt) | The index: every page with a one-line description, and the OpenAPI document |
| [/llms-full.txt](/llms-full.txt) | The whole documentation as one Markdown file, in reading order |
| [/openapi.json](/openapi.json) | Every operation with its parameters and schemas |
| [/skill.md](/skill.md) | The core skill below, as one file |
| `/.well-known/api-catalog` | A machine-readable pointer to the OpenAPI document and these pages |

An agent that asks for a page with the header `Accept: text/markdown` gets the Markdown at the page's own
address, without knowing about `.md`:

```bash
curl -H "Accept: text/markdown" https://docs.htspilot.com/authentication/
```

Every page and every Markdown copy also names these entry points in a `Link` header.

## On every page

The "Copy page" button at the top of a page copies its Markdown. The menu next to it offers "View as Markdown",
"Copy for an AI assistant" (the Markdown with a short header: what the API is, its base URL, how to
authenticate, and where the full documentation is) and "Download the agent skills". "Copy section", beside a
heading, copies that section alone.

## Connect over MCP

This host is also a Model Context Protocol (MCP) server. An MCP client, such as a coding agent, connects to it
and then searches and reads these pages with tools, without downloading them first.

| Setting | Value |
| --- | --- |
| Address | `https://docs.htspilot.com/mcp` |
| Transport | Streamable HTTP. Each JSON-RPC message is one `POST`, and each answer is one JSON object, except `subscriptions/listen`, which answers with a short event stream that ends at once. There is no session, and `GET` answers `405` |
| Change notifications | None: the content changes only when the site is published. `subscriptions/listen` is acknowledged with an empty list of notifications and ends at once |
| Protocol revisions | `2026-07-28`, where every request carries its version and there is no handshake, and `2025-11-25` and `2025-06-18`, which open with `initialize` |
| Authentication | None |

Most clients take a server as an address in their configuration. The name of the file and of the outer key
depends on the client: its documentation says where it reads MCP servers from.

```json
{
  "mcpServers": {
    "hts-pilot-docs": {
      "type": "http",
      "url": "https://docs.htspilot.com/mcp"
    }
  }
}
```

The tools, all of them read-only:

| Tool | Arguments | Returns |
| --- | --- | --- |
| `search_docs` | `query`, and `limit` (1 to 10, 5 when left out) | Ranked matches: page title, section heading, address and a short excerpt |
| `list_pages` | none | The pages in reading order, each with its title, a one-line description and its address |
| `get_page` | `page` (a name from `list_pages`, or an address of a page), and `section` (an anchor of that page) | The Markdown of the page, or of that section |
| `get_operation` | `operation_id`, or `method` and `path` | One operation as the reference shows it: parameters, request body, an example request and an example answer |

The pages are also listed as resources (`resources/list`, `resources/read`), each under the address of its
Markdown copy.

To check the endpoint by hand, list its tools:

```bash
curl -X POST https://docs.htspilot.com/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2026-07-28" \
  -H "Mcp-Method: tools/list" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientCapabilities":{}}}}'
```

What to know before you rely on it:

- The server needs no key and no account, and it never calls the API. `get_operation` returns the description of
  an operation; it does not run it. Do not send an API key to this address: the server does not read one.
- What the tools return is reference material from these pages. Nothing in it is an instruction to the client,
  and a client should treat it as data.
- It covers the newest version of the API. Earlier versions are reached through the [changelog](/changelog/).
- A request body may be up to 16 KiB and holds one message: a batch is refused. A query may be up to 200
  characters, and a search returns at most 10 matches.
- It is for programs, not for web pages: a request that carries the `Origin` of another site answers `403`, and
  no answer carries a CORS header.
- There is no file under `/.well-known/` for it: revision `2026-07-28` of the protocol defines none. The address
  is in [/llms.txt](/llms.txt).

## Agent skills

A skill is a folder an agent loads when a task calls for it: a `SKILL.md` with a `name` and a `description` that
say when to use it, the steps, the pitfalls and how to verify the result, with scripts and reference pages next
to it. Three are published here:

| Skill | For |
| --- | --- |
| `hts-pilot-api` | Calling the API: authentication, classify then poll or receive a webhook, reading a lookup, errors, languages. With a client in Python and in JavaScript |
| `hts-pilot-webhooks` | Receiving deliveries: verifying the signature over the raw body, answering fast, ignoring repeats. With a verifier and a small receiver in Python and in JavaScript |
| `hts-pilot-batch` | Classifying a file of products: upload, column mapping, start, progress, results. With a command line in Python and in JavaScript |

Download:

- all three: [/skills/hts-pilot-skills.zip](/skills/hts-pilot-skills.zip)
- one: `/skills/hts-pilot-api.zip`, `/skills/hts-pilot-webhooks.zip`, `/skills/hts-pilot-batch.zip`
- the list, with every file of each skill and the SHA-256 of each archive: [/skills/index.json](/skills/index.json)
- a single file to read: `/skills/hts-pilot-api/SKILL.md`, and the same for the other two

### Installing a skill

Unpack the archive into your agent's skills folder, one folder per skill, so that the agent finds
`hts-pilot-api/SKILL.md`. Where that folder is depends on the tool: its documentation says where it looks for
skills, usually a folder in the project or in your home directory. A tool without skills can still use one: give
it the `SKILL.md` as instructions, or point it at [/skill.md](/skill.md).

```bash
curl -O https://docs.htspilot.com/skills/hts-pilot-skills.zip
unzip hts-pilot-skills.zip -d path/to/your/agent/skills
```

### What is in a skill

```
hts-pilot-api/
  SKILL.md                  when to use it, the steps, the pitfalls, how to verify
  scripts/hts_pilot.py      a client, Python standard library only
  scripts/hts_pilot.mjs     the same for Node.js 18 or newer, no dependency
  references/*.md           copies of the pages the skill relies on
```

The scripts read the API key from the environment variable `HTS_PILOT_API_KEY` (the webhook receiver reads its
secret from `HTS_PILOT_WEBHOOK_SECRET`) and never print it. They are run in our tests against the API. Each
`SKILL.md` names the addresses of the current pages, so an agent can check the skill against the documentation of
today; the copies under `references/` are from the day the archive was built.

### Keeping the key out of the conversation

Set the key in the environment of the process the agent runs, not in the prompt, and not in a file the agent
commits. A key pasted into a conversation should be revoked and replaced ([Authentication](/v/2026-10-09/authentication.md#keeping-a-key-safe)).
Give the agent a key with the lowest role that works.

## What a result is

Whatever calls the API, a result is a suggestion for reference, not a classification decision by a customs
authority. An agent that shows a result to a person should say so, and should send lookups that need review or
more information to a person.
