--- name: ancilair-integration description: Integrate Ancilair into your own product. One token for the ancillary shelf, supplier credentials held server-side, a tag per customer, and an invoice from the usage rollup. HTTP, MCP, and CLI. --- # Integrating Ancilair into your product You are a coding agent. A human has pointed you at this file because they want Ancilair inside their product. Read this whole file, and https://ancilair.com/llms.txt, before writing code. The billing section changes how you write the plumbing. **What Ancilair is.** One base URL and one token for the travel shelf after the ticket: insurance, eSIM, lounges, bag protection, fast track, transfers, hotels, visas and entry rules, disruption, and seats and bags beside a ticket. Supplier credentials stay on the server. Calls on Ancilair's own supplier account are metered at the supplier's rate, 0% markup. The price is quoted on the call. This file has no rate card. **What this file is for.** Your product is the caller. Your users are customers of you. You pay the call fee. Your margin is yours. The supplier price is the traveller price. Base URL: https://api.ancilair.com MCP: https://mcp.ancilair.com Contract: https://ancilair.com/llms.txt Flights stay with the air API the product already uses. A quote, a search, a plan list, a seat map, a hotel rate, or a requirements check is not a booking. --- ## 1. Pick an integration method Three doors, same token, same behaviour. | Method | Use when | Shape | |---|---|---| | **HTTP** `POST https://api.ancilair.com/call/` | your backend already makes HTTP calls | you build the request, Ancilair injects the credential and relays | | **MCP** `https://mcp.ancilair.com` | your agent runtime speaks MCP | `catalog_search`, then `catalog_get`, then `call` | | **CLI** `anc` | scripts and a devbox | thin client over the same API | ### HTTP ```bash curl "https://api.ancilair.com/call/anc.lounge.search" \ -H "X-Anc-Token: $ANC_TOKEN" \ -H "Content-Type: application/json" \ -d '{"airport":"CDG","terminal":"2E","date":"2026-10-14","adults":1}' ``` Find the tool first. This file does not list partner endpoints. ``` anc catalog search "find a lounge" anc catalog get ``` `anc catalog get ` is the parameter schema and the price for that one tool. The settled call fee is the response header, not a number you copy from a page. Headers on every response: - **`X-Anc-Cost-Micro`** — the call fee, in integer micro-euros. It is not a markup on the traveller's price. An idempotent replay reports `0`. - **`X-Anc-Call-Id`** — store it. It joins your ledger to this call. - **`X-Anc-Served-By`** — who answered a routed call. A failed supplier call (4xx/5xx), a timeout, an empty result, a 422, a saturation 503, and an idempotent replay cost nothing. Out of balance is **402** with `balance_micro`, `estimated_cost_micro`, and `topup_url`. Do not forward that body to your end user. It describes your account. `X-Anc-Route-Max-Cost` refuses the call with nothing charged if the reserve would exceed it. ### MCP Point the client at `https://mcp.ancilair.com` with `Authorization: Bearer` or `X-Anc-Token`. Tools: `catalog_search`, `catalog_get`, `call`, `balance`, `my_tools`, `catalog_request`, `review`, `feedback`. ### CLI ```bash curl -fsSL https://ancilair.com/install.sh | sh -s -- --token $ANC_TOKEN anc catalog search "insure a trip" anc catalog get anc.insurance.quote anc call anc.insurance.quote --data '{"destination":"JP","departure_date":"2026-11-02","return_date":"2026-11-12","travellers":2}' ``` ### Auth An agent token is scoped to one team. Send it as `X-Anc-Token` or `Authorization: Bearer`. Use that token in a product. --- ## 2. Tag every call with your customer Send `X-Anc-Meta` from your backend on every call. Up to five `key=value` pairs: ``` X-Anc-Meta: customer=agency_8123, workspace=brand_fr ``` A malformed tag is a **422** before the call is relayed, so it costs nothing. Do not expose the tag as an argument your model fills in. Your backend already knows which user a request belongs to. Set the tag at the same place you set `X-Anc-Token`. ```ts async function ancilairCall(id: string, body: unknown, ctx: { customerId: string; workspaceId?: string }) { const tags = [`customer=${ctx.customerId}`]; if (ctx.workspaceId) tags.push(`workspace=${ctx.workspaceId}`); const response = await fetch(`https://api.ancilair.com/call/${id}`, { method: "POST", headers: { "X-Anc-Token": process.env.ANC_TOKEN!, "X-Anc-Meta": tags.join(", "), "Content-Type": "application/json", }, body: JSON.stringify(body), }); await db.usage.insert({ customerId: ctx.customerId, callId: response.headers.get("X-Anc-Call-Id"), costMicro: Number(response.headers.get("X-Anc-Cost-Micro") ?? 0), }); return response; } ``` Route every call through one function like this. --- ## 3. Limit what a customer can spend `PUT https://api.ancilair.com/orgs//budgets/customer/` The contract's example ceiling is `{"daily_cap_micro": 5000000}` on `customer/agency_8123`. That figure is an example cap in micro-euros, not a supplier price. Caps stack. The refusal names which one hit. The team balance is the hard stop. --- ## 4. Invoice your customers `GET https://api.ancilair.com/orgs//usage/by-tag?key=customer&days=30` That rollup is the invoice. Store `X-Anc-Call-Id` on your own rows. Do not invent a price for a tool this file does not quote. --- ## 5. Isolation, when a tag is not enough A tag is a label your backend asserts. A token pinned to one tag can bill and read only that tag: ```bash anc org agent-new agency-bot --pin customer=agency_8123 ``` --- ## 6. Before you ship - [ ] One function wraps every call, and it sets `X-Anc-Meta` from request context. - [ ] `X-Anc-Call-Id` is stored on your usage rows. - [ ] The invoice reads `usage/by-tag`. - [ ] A team-level 402 is handled by you, never forwarded to a user. - [ ] Retries of a booking send the same `Idempotency-Key`. A replay returns the stored answer and charges nothing. - [ ] Book, bind, order, purchase, add, or apply only after an explicit yes. - [ ] The code does not shop flights through this shelf. A quote is not a booking. Not legal, immigration, telecom, or insurance advice.