Skip to the content

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.

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.

{
  "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_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.
  • 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.

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

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.