# Use these docs with AI

> Open any page in ChatGPT or Claude, copy it as Markdown, or give an assistant llms.txt and the OpenAPI file.

Source: https://fx-port.com/docs/ai-tools

These docs are written to be read by developers **and** by AI assistants and agents. Every page is available as Markdown, the whole API is described in an OpenAPI 3.1 file, and the names the API uses are published as data. This page lists what exists and how to use it.

## Give an assistant the docs

| What | Where | Use it to |
|---|---|---|
| **Any page as Markdown** | Add `.md` to its address: `https://fx-port.com/docs/flights/book.md`. The home page is `https://fx-port.com/docs/introduction.md`. | Paste one page, or let an assistant fetch it. |
| **Page index** | [`https://fx-port.com/llms.txt`](https://fx-port.com/llms.txt) | A short index (title, address, one-line description of every page) for tools that follow the `llms.txt` convention. |
| **Everything in one file** | [`https://fx-port.com/llms-full.txt`](https://fx-port.com/llms-full.txt) | Load the whole documentation into a long-context model. |
| **OpenAPI 3.1** | [`https://fx-port.com/openapi.json`](https://fx-port.com/openapi.json) | Generate clients, tool definitions and tests. Every operation has an `operationId`, examples and its error codes. |
| **Postman collections** | [Environments and Postman](https://fx-port.com/docs/environments.md#postman-collections) | Try every endpoint by hand. |
| **The names of the API** | `GET https://api.fx-port.com/api/v1/conventions/naming` (no key) | Every previous spelling and snake_case twin as JSON. |

Every page has a **Use with AI** menu next to its title: it opens ChatGPT or Claude on the Markdown of that page, copies the page as Markdown, or links the `llms.txt` and OpenAPI files.

## A prompt for a coding assistant

Paste this at the start of a conversation, or into the instructions file of your assistant, then add what you want to build:

~~~text
You are integrating the FX-Port travel API (flights, hotels, eSIMs). Documentation: https://fx-port.com/llms-full.txt
and the OpenAPI file https://fx-port.com/openapi.json. Follow these rules.
- Base URL https://api.fx-port.com/api/v1. Auth: Authorization: Bearer <key>. Keys start with fxp_test_ (sandbox) or
  fxp_live_ (live). Use the sandbox key while developing. Keep the key on the server, in an environment variable.
- Names: send snake_case (search_id, offer_id, booking_type). Read the snake_case twin of a response key when it exists
  (search_id next to searchId), or add ?naming=snake.
- Flights: search -> price_flight -> book_flight -> get_booking. Always price right before you book. Send send_email=false while testing.
- Hotels: in the sandbox you can search and price any hotel but you can only BOOK the test hotels test_hotel_do_not_book
  (any residency) and test_hotel (residency dz, ru or us). Cancel every sandbox booking. Use the mini hotel data for result
  lists and the full data only for one hotel's details page.
- Errors: a call failed when the status is 4xx/5xx OR the body has success=false. Parse errors[0].code and branch on it, never
  on the message. Log request_id. Retry only 429 and 5xx with exponential backoff and jitter, honour Retry-After.
- Never retry book/pay/cancel calls blindly: read the booking back first. There is no Idempotency-Key header.
- Send a User-Agent of your own. Ask for gzip. Cache airports, suppliers, hotel content and eSIM packages.
- Never print or log API keys or traveler documents.
~~~

## Building an agent on top of the API

An AI agent that searches and books for people needs a few habits that the API supports:

1. **Generate tools from the OpenAPI file.** Each `operationId` (`getFlights`, `priceFlight`, `bookFlight` ...) becomes a tool; the descriptions and examples are written to be read by a model. Give an agent only the read operations unless a human confirms the booking.
2. **Use a Read key for exploration and a Read+Write key only for the step that books.** A read key cannot book, pay or cancel: it fails with `403 read_write_permission_required`.
3. **Separate "price" from "book".** Show the priced offer to the user (or to your policy engine), then book with the same `search_id` and `offer_id`. Fares move: price again if the user waits.
4. **Treat `errors[].type` as the control flow.** `validation_error` means fix the arguments, `supplier_error` means search again or retry, `rate_limit_error` means wait for `Retry-After`. See [Errors](https://fx-port.com/docs/errors.md).
5. **Keep a trace.** Store the `request_id` of every call next to the booking it created.
6. **Stay in the sandbox until a human says go.** The same code runs on live by changing the key; make that switch explicit and reviewed.

## Keep the answers small

Flight searches can be megabytes of JSON. When an agent reads them, let your code filter the answer (cheapest offers, duration, stops) before it reaches the model, and use [streaming](https://fx-port.com/docs/streaming.md) when you want results to appear as they arrive. For hotels, use the compact [mini data](https://fx-port.com/docs/hotels/hotel-data.md) for lists.