Get started
Introduction
Book flights from Uzbekistan programmatically. One JSON API for travel agencies, developers and AI agents.
1fly sells flights out of Uzbekistan, with prices in so‘m. The 1fly API lets your software do what a traveller does on our site: book a chosen flight offer for a group of passengers, follow the booking to a ticket, and explain what went wrong when it does not get there.
What you can do#
- Create orders for an offer the traveller picked, with passengers and a contact. Booking runs on our side: passenger checks, a price and seat re-check, a seat hold at the airline, payment, ticketing and the e-ticket e-mail. See Orders & booking lifecycle.
- Follow every step. Each order has a timeline that records every attempt of every step, with an error code, who must act and a plain-language hint. See Chronology.
- Act when a person must decide: accept or decline a price change, or cancel before payment.
- Measure conversion, step health and errors with the analytics endpoints.
- Debug with request logs: every call made with your keys, including calls from AI agents.
- Connect AI agents through our MCP server, so an assistant such as Claude can book on a traveller’s behalf with the same rules. See MCP.
Environments#
| Mode | Key prefix | What happens | Status |
|---|---|---|---|
| Test | 1fly_test_ |
Orders run end to end against mock airlines and a mock payment provider. Nothing is charged, no ticket is real. You can force failures with test scenarios. | Available |
| Live | 1fly_live_ |
Real airlines and real payments (Click, Payme, Stripe). | Not yet available |
Test and live are separated by the key, not by the URL. Until real suppliers are connected, creating an order with a live key returns 403 LIVE_MODE_UNAVAILABLE. Build and test your whole integration in test mode now; switching to live will mean changing the key.
Base URL#
http://localhost:4000Release v0.0.1 of the API is served under the /v1 path; /v1 is the stable route prefix and is independent of the release number. Requests and responses are JSON (Content-Type: application/json). Timestamps are ISO 8601 in UTC. The production base URL will be published here when live mode opens.
Note
Money is always an integer in minor units: so‘m × 100 for UZS (tiyin), cents for USD and EUR. A fare of 3 980 000 so‘m is "amountMinor": 398000000. Never send floats.
Conventions#
- Every response has an
x-request-idheader. The same id appears in error bodies, the request log and the order timeline. Quote it when you contact us. - Errors always have the same shape:
{ "error": { "code", "message", "requestId", "issues"? } }. Match oncode, showmessage. See Errors. - Ids are prefixed:
ord_orders,pay_payments,acc_accounts,key_API keys.
Next steps#
- Follow the Quickstart to book a test flight in five requests.
- Read Authentication & scopes before you put a key in production code.
- Browse the API reference, generated from the same schemas the API validates with.