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

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

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