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#

text
http://localhost:4000

Release 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-id header. 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 on code, show message. See Errors.
  • Ids are prefixed: ord_ orders, pay_ payments, acc_ accounts, key_ API keys.

Next steps#

  1. Follow the Quickstart to book a test flight in five requests.
  2. Read Authentication & scopes before you put a key in production code.
  3. Browse the API reference, generated from the same schemas the API validates with.
API version v0.0.1 · Spec generated from source on 2026-11-22Changelog · Prices in so‘m (UZS)