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.
Each page has a Markdown copy at the same address with .md: this page is at /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 | The index: every page with a one-line description, and the OpenAPI document |
| /llms-full.txt | The whole documentation as one Markdown file, in reading order |
| /openapi.json | Every operation with its parameters and schemas |
| /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:
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.
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.
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.
{
"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:
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_operationreturns 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.
- 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
Originof another site answers403, and no answer carries a CORS header. - There is no file under
/.well-known/for it: revision2026-07-28of the protocol defines none. The address is in /llms.txt.
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
- 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
- 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.
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). Give the agent a key with the lowest role that works.
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.