# Kiwi.com API

> Every Kiwi.com endpoint on Cotlet: inputs, JSON Schema, cURL, Python and Node.js examples and an example response for each call.

Source: https://cotlet.dev/docs/api/kiwi-com

Docs sections: [Get started](https://cotlet.dev/docs.md) · [REST API](https://cotlet.dev/docs/api.md) · [MCP](https://cotlet.dev/docs/mcp.md) · [SDKs & CLI](https://cotlet.dev/docs/sdks.md) · [Integrations](https://cotlet.dev/docs/integrations.md)

13 endpoints for Kiwi.com. Each one is a POST with a JSON body, called with your API key.

- Base URL: `https://cotlet.dev/api/v1/kiwi-com`
- Connects with: Your own Kiwi.com account (the one that holds your bookings)
- Integration page: https://cotlet.dev/integrations/kiwi-com-api-mcp-server

## Endpoints

| Endpoint | Access | Description |
|---|---|---|
| `search_flights` | read | Flights between two places for set dates, with price, duration and a booking link. |
| `list_trips` | read | Trips on your account with booking number, route, dates and whether travel documents are missing. |
| `get_trip` | read | One trip: flights, passengers, bags, seats, check-in status and which travel documents are still needed. |
| `get_boarding_passes` | read | Boarding passes Kiwi.com received after checking you in, as download links. |
| `get_baggage_options` | read | Bags you can still add to a trip, with the price of each. |
| `get_seat_map` | read | Seats you can pick on one flight of a trip, where the airline offers seat selection. |
| `get_cancellation_options` | read | What you get back if you cancel this trip now, under its ticket type. |
| `get_invoice` | read | Invoice of a booking as a PDF download link. |
| `get_credit_balance` | read | Your Kiwi.com Credit balance and its expiration date. |
| `add_travel_documents` | write | Add the passport or ID details Kiwi.com needs to check a passenger in. |
| `add_baggage` | write | Buy a bag from get_baggage_options for the price shown there. |
| `select_seat` | write | Pick a seat for a passenger on one flight, where the airline offers it. |
| `cancel_trip` | write | Cancel a trip and request the refund you picked from get_cancellation_options. |

## Search flights

`POST https://cotlet.dev/api/v1/kiwi-com/search_flights`

Access: read.

Searches Kiwi.com flights for one-way or round trips and returns the flights Kiwi.com finds, each with a link to book on Kiwi.com. Date flexibility goes up to 3 days either side. It does not need your trips, so it works before you book anything.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `from` | string | yes | City or airport, name or IATA code. |
| `to` | string | yes | City or airport, name or IATA code. |
| `departure_date` | date | yes | Outbound date. |
| `return_date` | date | no | Leave out for one-way. |
| `flex_days` | integer | no | Search this many days either side, 0 to 3. Default: 0. |
| `adults` | integer | no | Default: 1. |
| `cabin_class` | enum | no | economy, premium_economy, business or first. Default: economy. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/kiwi-com/search_flights \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"from":"from","to":"to","departure_date":"2026-10-01"}'
```

**Python**

```python
result = client.call("kiwi-com", "search_flights", {"from":"from","to":"to","departure_date":"2026-10-01"})
```

**Node.js**

```js
const result = await cotlet.call('kiwi-com', 'search_flights', {"from":"from","to":"to","departure_date":"2026-10-01"});
```

**CLI**

```bash
cotlet call kiwi-com search_flights --data '{"from":"from","to":"to","departure_date":"2026-10-01"}'
```

### Example response

```json
{
  "flights": [
    {
      "price": {
        "amount": 128,
        "currency": "EUR"
      },
      "route": "PRG-LIS",
      "departs": "2026-11-12T06:40:00+01:00",
      "arrives": "2026-11-12T09:10:00+00:00",
      "duration": "4h 30m",
      "stops": 0,
      "booking_url": "https://www.kiwi.com/en/booking?token=example1"
    },
    {
      "price": {
        "amount": 112,
        "currency": "EUR"
      },
      "route": "PRG-LIS",
      "departs": "2026-11-13T13:55:00+01:00",
      "arrives": "2026-11-13T18:20:00+00:00",
      "duration": "5h 25m",
      "stops": 1,
      "booking_url": "https://www.kiwi.com/en/booking?token=example2"
    }
  ]
}
```

## List trips

`POST https://cotlet.dev/api/v1/kiwi-com/list_trips`

Access: read.

Returns the trips on your account. Each trip shows the booking number, route, departure, passenger count and documents_missing. Use trip_id in every other trip tool.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `when` | enum | no | upcoming, past or all. Default: upcoming. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/kiwi-com/list_trips \
  -H "Authorization: Bearer $COTLET_API_KEY"
```

**Python**

```python
result = client.call("kiwi-com", "list_trips")
```

**Node.js**

```js
const result = await cotlet.call('kiwi-com', 'list_trips');
```

**CLI**

```bash
cotlet call kiwi-com list_trips
```

### Example response

```json
{
  "trips": [
    {
      "trip_id": "512834907",
      "route": "PRG-BCN-PRG",
      "departs": "2026-11-14T07:20:00+01:00",
      "passengers": 1,
      "documents_missing": true
    },
    {
      "trip_id": "734120655",
      "route": "PRG-BER",
      "departs": "2026-12-02T09:05:00+01:00",
      "passengers": 2,
      "documents_missing": false
    }
  ]
}
```

## Get trip

`POST https://cotlet.dev/api/v1/kiwi-com/get_trip`

Access: read.

Returns the full trip as shown on its booking page: each flight with its flight_id, each passenger with passenger_id, bags and seats already booked, check-in status, and the travel documents Kiwi.com still needs per passenger. Use the IDs in the write tools.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `trip_id` | string | yes | Booking number from list_trips. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/kiwi-com/get_trip \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"trip_id":"trip_8c41d2"}'
```

**Python**

```python
result = client.call("kiwi-com", "get_trip", {"trip_id":"trip_8c41d2"})
```

**Node.js**

```js
const result = await cotlet.call('kiwi-com', 'get_trip', {"trip_id":"trip_8c41d2"});
```

**CLI**

```bash
cotlet call kiwi-com get_trip --data '{"trip_id":"trip_8c41d2"}'
```

### Example response

```json
{
  "trip_id": "512834907",
  "status": "confirmed",
  "flights": [
    {
      "flight_id": "f1",
      "route": "PRG-BCN",
      "departs": "2026-11-14T07:20:00+01:00",
      "carrier": "Example Air"
    },
    {
      "flight_id": "f2",
      "route": "BCN-PRG",
      "departs": "2026-11-17T18:45:00+01:00",
      "carrier": "Example Air"
    }
  ],
  "passengers": [
    {
      "passenger_id": "p1",
      "name": "Ana Lopez",
      "bags": [
        "Cabin bag"
      ],
      "seats": {},
      "documents_needed": [
        "document number",
        "expiry date"
      ]
    }
  ],
  "check_in": "waiting for the airline to open"
}
```

## Get boarding passes

`POST https://cotlet.dev/api/v1/kiwi-com/get_boarding_passes`

Access: read.

Returns one download link per passenger and flight once Kiwi.com has checked you in. Before that the list is empty and check_in says what is pending. If you checked in with the airline yourself, the airline sent the pass and Kiwi.com has none.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `trip_id` | string | yes | Booking number from list_trips. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/kiwi-com/get_boarding_passes \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"trip_id":"trip_8c41d2"}'
```

**Python**

```python
result = client.call("kiwi-com", "get_boarding_passes", {"trip_id":"trip_8c41d2"})
```

**Node.js**

```js
const result = await cotlet.call('kiwi-com', 'get_boarding_passes', {"trip_id":"trip_8c41d2"});
```

**CLI**

```bash
cotlet call kiwi-com get_boarding_passes --data '{"trip_id":"trip_8c41d2"}'
```

### Example response

```json
{
  "trip_id": "512834907",
  "passes": [
    {
      "passenger_id": "p1",
      "flight_id": "f1",
      "url": "https://cotlet.dev/api/v1/files/example/boarding-pass-f1.pdf"
    },
    {
      "passenger_id": "p1",
      "flight_id": "f2",
      "url": "https://cotlet.dev/api/v1/files/example/boarding-pass-f2.pdf"
    }
  ]
}
```

## Get baggage options

`POST https://cotlet.dev/api/v1/kiwi-com/get_baggage_options`

Access: read.

Returns the bag options Kiwi.com offers for the itinerary, each with its price and the passenger it is for. Options are sold for the whole itinerary. The list is empty when Kiwi.com no longer sells bags for the trip, which is the case from 36 hours before departure, and for self-transfer itineraries with short layovers.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `trip_id` | string | yes | Booking number from list_trips. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/kiwi-com/get_baggage_options \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"trip_id":"trip_8c41d2"}'
```

**Python**

```python
result = client.call("kiwi-com", "get_baggage_options", {"trip_id":"trip_8c41d2"})
```

**Node.js**

```js
const result = await cotlet.call('kiwi-com', 'get_baggage_options', {"trip_id":"trip_8c41d2"});
```

**CLI**

```bash
cotlet call kiwi-com get_baggage_options --data '{"trip_id":"trip_8c41d2"}'
```

### Example response

```json
{
  "trip_id": "512834907",
  "options": [
    {
      "bag_option_id": "bo_chk20_p1",
      "passenger_id": "p1",
      "description": "Checked bag, 20 kg",
      "price": {
        "amount": 64,
        "currency": "EUR"
      }
    },
    {
      "bag_option_id": "bo_cab_p1",
      "passenger_id": "p1",
      "description": "Cabin bag, 10 kg",
      "price": {
        "amount": 38,
        "currency": "EUR"
      }
    }
  ]
}
```

## Get seat map

`POST https://cotlet.dev/api/v1/kiwi-com/get_seat_map`

Access: read.

Returns the seat map Kiwi.com shows for one flight, with each free seat and its price if there is one. Seat selection is open up to 48 hours before departure. If the airline does not offer it, the list is empty and the airline assigns your seat at check-in at no extra cost.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `trip_id` | string | yes | Booking number from list_trips. |
| `flight_id` | string | yes | Flight ID from get_trip. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/kiwi-com/get_seat_map \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"trip_id":"trip_8c41d2","flight_id":"flight_8c41d2"}'
```

**Python**

```python
result = client.call("kiwi-com", "get_seat_map", {"trip_id":"trip_8c41d2","flight_id":"flight_8c41d2"})
```

**Node.js**

```js
const result = await cotlet.call('kiwi-com', 'get_seat_map', {"trip_id":"trip_8c41d2","flight_id":"flight_8c41d2"});
```

**CLI**

```bash
cotlet call kiwi-com get_seat_map --data '{"trip_id":"trip_8c41d2","flight_id":"flight_8c41d2"}'
```

### Example response

```json
{
  "trip_id": "512834907",
  "flight_id": "f1",
  "seats": [
    {
      "seat": "14C",
      "price": {
        "amount": 9,
        "currency": "EUR"
      }
    },
    {
      "seat": "14D",
      "price": {
        "amount": 9,
        "currency": "EUR"
      }
    }
  ]
}
```

## Get cancellation options

`POST https://cotlet.dev/api/v1/kiwi-com/get_cancellation_options`

Access: read.

Returns the refund options Kiwi.com offers for this trip, each with a refund_option_id, where the money goes and the amount. Requests follow the rules of each airline and the ticket type: Saver and Standard tickets allow cancelling single flights, Flexi only the whole booking. The call changes nothing.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `trip_id` | string | yes | Booking number from list_trips. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/kiwi-com/get_cancellation_options \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"trip_id":"trip_8c41d2"}'
```

**Python**

```python
result = client.call("kiwi-com", "get_cancellation_options", {"trip_id":"trip_8c41d2"})
```

**Node.js**

```js
const result = await cotlet.call('kiwi-com', 'get_cancellation_options', {"trip_id":"trip_8c41d2"});
```

**CLI**

```bash
cotlet call kiwi-com get_cancellation_options --data '{"trip_id":"trip_8c41d2"}'
```

### Example response

```json
{
  "trip_id": "734120655",
  "ticket_type": "Standard",
  "options": [
    {
      "refund_option_id": "rf_credit",
      "refund_as": "Kiwi.com Credit",
      "amount": 112.5,
      "currency": "EUR"
    },
    {
      "refund_option_id": "rf_original",
      "refund_as": "Original payment",
      "amount": 98,
      "currency": "EUR"
    }
  ]
}
```

## Get invoice

`POST https://cotlet.dev/api/v1/kiwi-com/get_invoice`

Access: read.

Returns the invoice Kiwi.com shows at the bottom of the booking page, as a PDF link. Billing details on it cannot be changed after booking, as Kiwi.com reports them to local tax authorities.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `trip_id` | string | yes | Booking number from list_trips. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/kiwi-com/get_invoice \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"trip_id":"trip_8c41d2"}'
```

**Python**

```python
result = client.call("kiwi-com", "get_invoice", {"trip_id":"trip_8c41d2"})
```

**Node.js**

```js
const result = await cotlet.call('kiwi-com', 'get_invoice', {"trip_id":"trip_8c41d2"});
```

**CLI**

```bash
cotlet call kiwi-com get_invoice --data '{"trip_id":"trip_8c41d2"}'
```

### Example response

```json
{
  "trip_id": "512834907",
  "invoice_url": "https://cotlet.dev/api/v1/files/example/invoice-512834907.pdf",
  "issued_on": "2026-09-02"
}
```

## Get Credit balance

`POST https://cotlet.dev/api/v1/kiwi-com/get_credit_balance`

Access: read.

Returns the Kiwi.com Credit shown in your account, with the expiration date of each part. Credit is what Kiwi.com often issues when it refunds a cancellation.

### Parameters

No parameters.

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/kiwi-com/get_credit_balance \
  -H "Authorization: Bearer $COTLET_API_KEY"
```

**Python**

```python
result = client.call("kiwi-com", "get_credit_balance")
```

**Node.js**

```js
const result = await cotlet.call('kiwi-com', 'get_credit_balance');
```

**CLI**

```bash
cotlet call kiwi-com get_credit_balance
```

### Example response

```json
{
  "balance": {
    "amount": 112.5,
    "currency": "EUR"
  },
  "parts": [
    {
      "amount": 112.5,
      "currency": "EUR",
      "expires_on": "2028-09-18"
    }
  ]
}
```

## Add travel documents

`POST https://cotlet.dev/api/v1/kiwi-com/add_travel_documents`

Access: write. Confirm: waits for the user's OK before it runs.

Saves the travel document details for one passenger, which Kiwi.com passes to the airline for check-in. It accepts them up to 24 hours before departure; later you check in with the airline. Send the fields get_trip lists under documents_needed. By default you confirm each call; you can switch that off for this tool.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `trip_id` | string | yes | Booking number from list_trips. |
| `passenger_id` | string | yes | Passenger ID from get_trip. |
| `details` | object | yes | The fields listed in documents_needed by get_trip, e.g. document_number and expiry_date. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/kiwi-com/add_travel_documents \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"trip_id":"512834907","passenger_id":"p1","details":{"document_number":"XK1234567","expiry_date":"2031-04-18"}}'
```

**Python**

```python
result = client.call("kiwi-com", "add_travel_documents", {"trip_id":"512834907","passenger_id":"p1","details":{"document_number":"XK1234567","expiry_date":"2031-04-18"}})
```

**Node.js**

```js
const result = await cotlet.call('kiwi-com', 'add_travel_documents', {"trip_id":"512834907","passenger_id":"p1","details":{"document_number":"XK1234567","expiry_date":"2031-04-18"}});
```

**CLI**

```bash
cotlet call kiwi-com add_travel_documents --data '{"trip_id":"512834907","passenger_id":"p1","details":{"document_number":"XK1234567","expiry_date":"2031-04-18"}}'
```

### Example response

```json
{
  "trip_id": "512834907",
  "passenger_id": "p1",
  "status": "saved",
  "check_in": "waiting for the airline to open"
}
```

## Add baggage

`POST https://cotlet.dev/api/v1/kiwi-com/add_baggage`

Access: write. Confirm: waits for the user's OK before it runs.

Adds one bag option to the booking and charges the price from get_baggage_options. The bag cannot be removed or moved to another passenger afterwards, and Kiwi.com may add a processing fee depending on your service package. By default you confirm each call; you can switch that off for this tool.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `trip_id` | string | yes | Booking number from list_trips. |
| `bag_option_id` | string | yes | Option ID from get_baggage_options. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/kiwi-com/add_baggage \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"trip_id":"512834907","bag_option_id":"bo_chk20_p1"}'
```

**Python**

```python
result = client.call("kiwi-com", "add_baggage", {"trip_id":"512834907","bag_option_id":"bo_chk20_p1"})
```

**Node.js**

```js
const result = await cotlet.call('kiwi-com', 'add_baggage', {"trip_id":"512834907","bag_option_id":"bo_chk20_p1"});
```

**CLI**

```bash
cotlet call kiwi-com add_baggage --data '{"trip_id":"512834907","bag_option_id":"bo_chk20_p1"}'
```

### Example response

```json
{
  "trip_id": "512834907",
  "status": "added",
  "bag": {
    "bag_option_id": "bo_chk20_p1",
    "description": "Checked bag, 20 kg",
    "passenger_id": "p1"
  },
  "price": {
    "amount": 64,
    "currency": "EUR"
  }
}
```

## Select seat

`POST https://cotlet.dev/api/v1/kiwi-com/select_seat`

Access: write. Confirm: waits for the user's OK before it runs.

Reserves one seat from get_seat_map for one passenger on one flight, up to 48 hours before departure. The seat then shows on the e-ticket and in the trip. A seat with a price charges your payment method. By default you confirm each call; you can switch that off for this tool.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `trip_id` | string | yes | Booking number from list_trips. |
| `flight_id` | string | yes | Flight ID from get_trip. |
| `passenger_id` | string | yes | Passenger ID from get_trip. |
| `seat` | string | yes | Seat from get_seat_map, e.g. 14C. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/kiwi-com/select_seat \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"trip_id":"trip_8c41d2","flight_id":"flight_8c41d2","passenger_id":"passenger_8c41d2","seat":"seat"}'
```

**Python**

```python
result = client.call("kiwi-com", "select_seat", {"trip_id":"trip_8c41d2","flight_id":"flight_8c41d2","passenger_id":"passenger_8c41d2","seat":"seat"})
```

**Node.js**

```js
const result = await cotlet.call('kiwi-com', 'select_seat', {"trip_id":"trip_8c41d2","flight_id":"flight_8c41d2","passenger_id":"passenger_8c41d2","seat":"seat"});
```

**CLI**

```bash
cotlet call kiwi-com select_seat --data '{"trip_id":"trip_8c41d2","flight_id":"flight_8c41d2","passenger_id":"passenger_8c41d2","seat":"seat"}'
```

### Example response

```json
{
  "trip_id": "512834907",
  "flight_id": "f1",
  "passenger_id": "p1",
  "seat": "14C",
  "status": "reserved",
  "price": {
    "amount": 9,
    "currency": "EUR"
  }
}
```

## Cancel trip

`POST https://cotlet.dev/api/v1/kiwi-com/cancel_trip`

Access: write. Confirm: waits for the user's OK before it runs.

Sends the cancellation request to Kiwi.com, which handles it under the airline rules for your ticket type. Pass refund_option_id from get_cancellation_options. On Saver and Standard tickets you can name single flights in flight_ids; on Flexi tickets the whole booking is cancelled. By default you confirm each call; you can switch that off for this tool.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `trip_id` | string | yes | Booking number from list_trips. |
| `refund_option_id` | string | yes | Option ID from get_cancellation_options. |
| `flight_ids` | string[] | no | Cancel only these flights (Saver and Standard tickets). Default: whole trip. |

### Request

**cURL**

```bash
curl -X POST https://cotlet.dev/api/v1/kiwi-com/cancel_trip \
  -H "Authorization: Bearer $COTLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"trip_id":"734120655","refund_option_id":"rf_credit"}'
```

**Python**

```python
result = client.call("kiwi-com", "cancel_trip", {"trip_id":"734120655","refund_option_id":"rf_credit"})
```

**Node.js**

```js
const result = await cotlet.call('kiwi-com', 'cancel_trip', {"trip_id":"734120655","refund_option_id":"rf_credit"});
```

**CLI**

```bash
cotlet call kiwi-com cancel_trip --data '{"trip_id":"734120655","refund_option_id":"rf_credit"}'
```

### Example response

```json
{
  "trip_id": "734120655",
  "status": "cancellation requested",
  "refund": {
    "refund_option_id": "rf_credit",
    "refund_as": "Kiwi.com Credit",
    "amount": 112.5,
    "currency": "EUR"
  }
}
```