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

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.