# List your API in the Ancilair catalog — instructions for a coding agent

You are helping an API vendor get listed in Ancilair's catalog (https://ancilair.com) of travel
ancillary APIs: insurance, eSIM, lounges, bags, fast track, transfers, hotels, visas, and
disruption. The deliverable is a **pull request to https://github.com/ancilair/ancilair**
containing the listing, plus a way for the maintainers to reach your team.

A call is the supplier's published per-call rate, 0% markup. Ancilair earns on volume pricing
with suppliers, not by marking up the customer. A key the customer already pays for is never
metered and wins over Ancilair's account. A quote is not a booking.

## Before you write anything

Clone the repo and read the README — it is the authority, this page is only the summary:

- `README.md` in https://github.com/ancilair/ancilair — eligibility rules, what the pull request
  includes, and the pricing rules. The catalog file format is not defined yet. Maintainers will
  add the format. The README will name it once it exists. The PR follows the README and does not
  invent catalog files. There is no worked example in the repo. Do not invent a file schema for
  one. If you illustrate with a fictional offer, make it a travel ancillary (an eSIM, a lounge, a
  visa) in prose only.
- The same README is what reviewers follow, including the live bogus-key test. Maintainers run
  their own check. Do not add a separate review-pipeline file.

Confirm eligibility first. Hard requirements: self-serve API keys (no sales call), the key rides
in a **header or query param** (never the URL path), a free or near-free probe endpoint that
**rejects an invalid key** with a distinguishable response, a published pricing page, and docs
with example parameter values. If any of these fail, stop and tell your user which one — a PR
that fails them will be declined.

## What the PR contains

The catalog file format is not defined yet, so the PR follows the README and does not invent
catalog files. Where a listing would name a schema, a registry, or a command, point at the
README of https://github.com/ancilair/ancilair instead.

1. **The offer** — supplier name, base URL, auth (a key in a header or query param, never the
   URL path), a one-line summary, docs URL, the probe, and where a customer gets a self-serve
   key. The README decides which files that becomes. Do not invent them.
2. **Logo** — the supplier's official icon (the favicon or the apple-touch icon). Ancilair does
   not use lettermarks. The README does not name a logo path. Link or attach that official icon
   in the PR, and do not invent a path for it.
3. **Checks** — the README defines no test suite. Do not invent test files or commands.
   Maintainers run their own check.
4. **Catalog file** — the format is not defined yet. Do not invent one. Describe the calls in
   the PR and follow the README.

## Capability first

The README does not define a capability list, and the file format is not defined yet. Do not
invent one. For every call, before you name the job it does:

1. **Reuse.** If the README or an existing listing already names that job, use those words —
   never a near-duplicate.
2. **Propose only when missing.** If another supplier already has a call doing the same job and
   nothing in the repo covers it, say so in the PR and name that call so reviewers attach both.
   Do not add a file for the proposal.
3. **Prefer overlap.** Calls that share a job with other travel ancillary suppliers are the ones
   agents compare and route between. A new job with a single supplier is a shelf of one.

## Map the FULL surface before selecting

List every documented operation your API exposes, then choose which ones you list. The PR
description must carry that map as a short "catalogued / excluded, because…" list — reviewers
check curation against it, and "we didn't know it existed" is the gap this prevents. The README
sets no file schema and no count, so do not invent either. Two rules of thumb: include the
**free or near-free quote, search, preview, and pre-flight routes** that let an agent size a
trip before paying, and include your **cheapest tier** of an operation, not only the default
one. A quote is not a booking. Name which calls only quote, search, or check, and which calls
bind, book, order, or issue.

## Self-verify with your OWN key before opening the PR

Docs drift; meters don't. Before the PR goes up, run every call you are listing live against
your own account and reconcile each price against what the meter actually charged (a per-call
charge field in the response, a rate-card endpoint, or the balance delta). The price you claim
is the supplier's published per-call rate, 0% markup. A price transcribed from a docs page has
been wrong by 5× in a real submission — the live meter is the authority, and a mismatch you
find now is a one-line fix instead of a review round-trip.

While you're there:
- Quote the probe's bad-key behavior **from the wire** (run it with a garbage key; record the
  exact status and body, with the date) — not from memory or docs.
- If a call is a **deliberate miss** (a target chosen so a pay-on-success endpoint charges
  nothing), label it as such in the note — and observe the HIT price once on a real target so
  the number is metered, not assumed.

The catalog file format is not defined yet. There is no validator in the repo. Do not invent
catalog files or commands. Self-check prices against the live meter before opening the PR.

Rebase on the latest `main` of https://github.com/ancilair/ancilair right before opening.

Do NOT stamp `verified` on any call and do NOT commit example responses — those marks mean "the
maintainers watched it", and they run their own verification with an independent credential
regardless of your evidence. And **never put a credential value anywhere in the diff**: no API
keys in the files you add, the PR description, or commit messages.

## The PR description — required

- **A contact email** for your team, stated plainly (e.g. `Contact: you@yourcompany.com`).
  The maintainers reach out on this address to arrange a test credential for live verification —
  a PR without it cannot be verified or merged.
- **The self-verification ledger**: one line per call — HTTP status of your live call, the price
  you claim, and the cost the meter reported, with the date. This is review evidence, not a
  substitute for the maintainers' own run — but a PR that arrives with it merges much faster,
  and a PR whose ledger disagrees with the prices it states will be bounced.
- **The full-surface map** — every documented operation, marked catalogued or excluded-because.
- Your probe endpoint's exact bad-key behavior (status + body, observed on a dated live call).
- Your pricing page URL and billing model; a machine-readable rate-card endpoint if you have one
  (that is the fastest path to Ancilair serving your endpoints on its own key, at your published
  per-call rate, with 0% markup). A key the customer already pays for is never metered and wins
  over Ancilair's account. A quote is not a booking. Do not invent prices.
- Whether you publish an OpenAPI spec at a stable URL (a machine-readable view of your full
  endpoint surface).

## What happens next

Maintainers run their own check: a garbage key at your probe must come back rejected, and every
call you listed is exercised with the test credential you arrange over email. You do not stamp
verified. Then the PR merges and your API is discoverable by every agent using the catalog —
compared side by side with other travel ancillary providers on price, measured success rate, and
speed.