# QuickOTA Developer API

The QuickOTA API lets your own software — a website, a mid-office, a CRM, another booking engine — search, book, ticket and service travel through your QuickOTA agency account, exactly as your staff do in the panel.

Version 1 covers **flights**. Other products (hotels, CMS, cart, CRM) will be added under the same rules, keys and conventions.

## Base URL

```
https://quickota.com/api/v1
```

Every path in these docs is relative to it. Keys start with `tam_live_`; bookings are made with the airlines your agency uses and paid from your agency wallet.

Opening the base URL in a browser (no key needed) shows the API name and links to these docs — a quick way to check the address is right.

To build and test without real tickets, ask your platform for access to its **test server**: it runs the same API with simulated airlines. Use a key created on that server and its own base URL.

## Five-minute tour

```bash
# 1. Who am I?
curl https://quickota.com/api/v1/account -H "Authorization: Bearer tam_live_..."

# 2. Search flights
curl -X POST https://quickota.com/api/v1/flights/search \
  -H "Authorization: Bearer tam_live_..." -H "Content-Type: application/json" \
  -d '{"slices":[{"origin":"IKA","destination":"IST","departureDate":"2026-12-01"}],"passengers":{"adults":1}}'
```

Then follow the [Quick start](https://quickota.com/developers/guides/quick-start.md) to hold and ticket a booking.

## Conventions

- **JSON everywhere**, `camelCase` field names, UTF-8.
- **Successful responses** are wrapped:
  ```json
  { "data": { ... }, "meta": { "requestId": "req_7f3a..." } }
  ```
  Lists add `pagination`: `{ "page": 1, "pageSize": 20, "total": 57, "hasMore": true }`.
- **Errors** use real HTTP status codes and a `application/problem+json` body with a stable `code`. See [Errors](https://quickota.com/developers/guides/errors.md).
- **Money** is an object with the amount as a string (no floating-point surprises):
  `{ "amount": "180.00", "currency": "USD" }`.
- **Timestamps** are ISO-8601 in UTC and end with `Z` (`2026-12-01T08:30:00Z`). Flight departure/arrival times are also given as local airport time (`departureLocal`).
- **Dates** are `yyyy-MM-dd`.
- **IDs** are opaque strings. Store them as strings.
- **Your reference**: pass `agencyReference` (your order number) when you book; it is echoed on the booking, in lists and in webhooks, and you can search by it.

## Headers you will see

| Header | Meaning |
|---|---|
| `X-Request-Id` | Unique id of the request. Quote it when you contact support. |
| `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` | Your rate limit. See [Rate limits](https://quickota.com/developers/guides/rate-limits-and-look-to-book.md). |
| `X-Quota-Searches-Remaining` | Searches left today. |
| `Retry-After` | Seconds to wait before retrying (on 429 and 503). |
| `Idempotent-Replayed` | `true` when a response was replayed for a repeated `Idempotency-Key`. |

## Getting a key

Your agency must have the **Developer API** module installed. Then, in your panel, open **Developers → API keys** and choose the permissions (scopes) the key needs. The key is shown **once** — store it in a secret manager, never in a browser or mobile app.

| Scope | Allows |
|---|---|
| `flights:read` | Search, price, fare rules, read bookings and e-tickets |
| `flights:book` | Hold, issue and cancel bookings |
| `flights:post_booking` | Refunds, voids, changes and schedule-change replies |
| `account:read` | Account, balance and usage |
| `webhooks:manage` | Webhook endpoints and deliveries |

## Using this documentation with an AI assistant

Every page is plain Markdown underneath:

- `https://quickota.com/developers/llms.txt` — index of all pages, for AI tools.
- `https://quickota.com/developers/llms-full.txt` — **everything in one file** (guides, full endpoint reference and every error code). Paste it into ChatGPT, Claude or your IDE assistant and ask it to write your integration.
- `https://quickota.com/developers/openapi.json` — OpenAPI 3 description, for code generators and Postman.
- Add `.md` to any guide URL to get its Markdown.

## Versioning

The version is in the URL (`/v1`). Within v1 we only make **additive** changes: new endpoints, new optional request fields, new response fields, new enum values and new error codes. Your code must ignore fields it does not know. Breaking changes get a new version and at least six months' notice. See the [Changelog](https://quickota.com/developers/guides/changelog.md).