---
title: "Search hotels from one sentence, with follow-ups"
method: POST
path: "/v1/hotel_ai_search"
tags: ["Hotels"]
---

# Search hotels from one sentence, with follow-ups

`POST /v1/hotel_ai_search`

## Request

- Base URL: `https://api.gojinko.com`
- URL: `https://api.gojinko.com/v1/hotel_ai_search`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer

Send the traveller's request in one sentence. The answer comes within about 20 seconds with `200`: the hotels, or a question to answer in the same conversation. When the search takes longer, the answer is `202` with the early reply and a `Location` to read until the task ends. Continue the conversation with its `context_id`.

## Headers

- `Idempotency-Key` string: Makes a retried message safe: a retry with the same key answers the first message again instead of sending a second one. Keys are scoped to the caller, not to the conversation, and the retried body is not compared: a different message needs a new key. 1–200 characters.
- `Prefer` string: `wait=N` (RFC 7240): answer after at most N seconds, never more than 20, with `202` and the early reply if the task has not ended by then. `wait=0` answers at once. Without it the wait is 20 seconds. The wait applied is returned in `Preference-Applied`.

## Request body

- HotelAiSearchRequest
  - `text` string, required: The traveller's request in one sentence, or the answer to the question asked in the previous turn.
  - `context_id` string: The conversation to continue, from an earlier answer. Omit to start a new conversation.
  - `task_id` string: The task of that conversation the message answers. Optional: without it, a message continues the task waiting for an answer, or starts a new one.
  - `currency` string: Currency of the prices (ISO 4217).
  - `guest_nationality` string: Nationality of the guests (ISO 3166-1 alpha-2).
  - `timezone` string, required: The traveller's IANA time zone. Relative dates such as "next weekend" or "tonight" are computed in it.

## Response `200`

The task ended this turn; or, with `Accept: text/event-stream`, the turn as it happens.

- HotelAiSearchAnswer
  - `context_id` string, nullable, required: The conversation; send it with the next message to continue.
  - `task_id` string, required
  - `status` 'working' | 'input_required' | 'completed' | 'failed' | 'canceled', required: `working`: the search is still running, read the task again. `input_required`: the message asks a question; answer it in the same conversation. `completed`: the hotels are in the answer. `failed`: see `error`. `canceled`: a later message or a cancel replaced it.
  - `message` string: The reply to show the traveller.
  - `question` string: What the reply asks for, when `status` is `input_required`.
  - `criteria` object: The search the request was understood as, in the `hotel_search` request fields, plus `board_types` and `refundable_only` for the rate filters applied to the results.
  - `notes` object[]: Assumptions and adjustments made while understanding the request.
  - `hotels` HotelAiSearchHotel[]
    - `hotel_id` string: Opaque hotel identifier. Pass it to hotel_details, hotel_reviews and `hotel_ids` exactly as received; do not parse or build it. The value a hotel is known by can change between contract versions, so read it from a fresh hotel_search rather than keeping it.
    - `hotel_ref` string: Deprecated: use `hotel_id` (search) or `id` (details, reviews). The hotel's identifier behind a source prefix, as earlier contract versions returned it; hotel_details and hotel_reviews still accept it. Pass it back exactly as received; do not parse or build it.
    - `name` string
    - `address` string
    - `city` string
    - `country` string: ISO 3166-1 alpha-2 country code, LOWER case as the platform sends it.
    - `star_rating` number
    - `category` string: The provider's own category wording, which `star_rating` cannot express. Free text.
    - `lodging_type` string
    - `rating` number: Guest score out of 10.
    - `review_count` number: Number of guest reviews behind `rating`.
    - `main_photo` string: Full-size hero image URL.
    - `thumbnail` string: Small preview image URL.
    - `latitude` number
    - `longitude` number
    - `distance_km` number: Straight-line distance from the search center, in kilometers.
    - `recommendation_score` number: How well the hotel fits `intent.user_intent`, from 0 to 1, present when the intent re-ranked the results, which are then ordered by it. Without an intent the results keep the order `sort_by` names. Not a guest rating.
    - `rooms` HotelRoom[]
      - `room_id` string
      - `room_name` string
      - `description` string: Free-text room description, when the provider supplied one.
      - `requested_occupancy` integer: The occupancy these rates were priced for — an echo of what you searched, not a property of the room. Pricing a different party size means searching again.
      - `room_capacity` integer: How many the room sleeps, from the provider’s content catalogue. Absent when the catalogue carries no figure — absent means unknown, never zero. Same field as on hotel_details and on a hotel trip item.
      - `max_occupancy` integer: Deprecated: an alias of `requested_occupancy` (same value), never the room’s capacity. Read `requested_occupancy` for the priced party size and `room_capacity` for how many the room sleeps.
      - `images` string[]
      - `amenities` string[]
      - `beds` HotelBed[]
        - `bed_type` string, required
        - `count` integer, required
      - `rates` HotelRate[]: DEPRECATED compatibility projection. Read the hotel-level `offers[]` list for new integrations and add an offer’s `trip_item_token` to the trip. Multi-room searches return this as an empty array.
        - `offer_id` string: Legacy rooms[].rates[] compatibility token. New integrations use the hotel-level `offers[].trip_item_token`; add that token to the trip exactly once.
        - `board_type` string
        - `board_name` string
        - `total_amount` number: Deprecated: use `total_amount_money` instead. Price for the whole stay in `currency`, in MAJOR units at the currency’s own precision.
        - `total_amount_display` string: Deprecated: use `total_amount_money` instead. The rate total as a string ready to show: the ISO 4217 code, a space, then `total_amount` at the currency’s ISO digits, e.g. "EUR 606.13".
        - `currency` string: Deprecated: use `total_amount_money` instead. The currency of `total_amount`.
        - `total_amount_money` object: Price for the whole stay.
          - `value` integer, required: Integer amount in MINOR units at the ISO 4217 digits of `currency`: divide by 10 ** decimal_places to get the amount. Signed where the field says so (a price change delta).
          - `currency` string, required: ISO 4217 currency code.
          - `decimal_places` integer, required: The ISO 4217 digits of `currency` (2 for USD/EUR, 0 for JPY/KRW, 3 for BHD/KWD), and the scale of `value`.
          - `display` string, required: The same figure as a string ready to show: the ISO 4217 code, a space, then the amount at `decimal_places`, e.g. "USD 412.50". Show this; compute with `value`.
        - `is_refundable` boolean
        - `free_cancellation_until` string: Last instant the stay can be cancelled at no charge. RFC 3339 with the supplier’s declared UTC offset. Absent when the supplier declared no timezone — the platform never invents an offset, so a deadline it cannot place on the clock is withheld rather than published ambiguously — and absent when the rate is non-refundable or the provider named no deadline.
        - `cancellation_schedule` CancellationStep[]: The full penalty ladder, chronological. Absent when the provider published none — which is not a statement that cancelling is free.
          - `cancel_time` string: Deadline after which this tier applies. RFC 3339 with the supplier’s declared UTC offset. Steps whose deadline has no declared timezone are omitted from the ladder — the platform never invents an offset — so a schedule can be shorter than the supplier’s own. Tiers are chronological, earliest first, so the first entry is the deadline that matters.
          - `amount` number: Deprecated: use `amount_money` instead. Read `amount_money`, `percent` or `nights`, whichever this step carries. What the guest is charged on or after `cancel_time`: a sum in MAJOR units of `currency`, a percentage or a number of nights, as `type` says.
          - `currency` string: Deprecated: use `amount_money` instead. The currency of `amount`.
          - `type` string: How the charge is expressed — a sum ("amount", "flat_fee"; read `amount_money`), a percentage ("percent", "percentage"; read `percent`) or a number of nights ("nights"; read `nights`).
          - `display` string: Deprecated: use `amount_money` instead. The same figure as a string ready to show: the ISO 4217 code, a space, then the amount, e.g. "USD 159.77". With decimal_places it is written at exactly that scale (value 1561500, JPY, decimal_places 2 is "JPY 15615.00"); without, at the ISO digits of the currency. Show this; compute with the number. Absent when the figure is not money (a cancellation step expressed as a percent or a number of nights) or could not be read unambiguously.
          - `amount_money` object: What the guest is charged on or after `cancel_time`, when this step is a sum. Absent on a percentage or nights step, and when the supplier named no currency.
            - `value` integer, required: Integer amount in MINOR units at the ISO 4217 digits of `currency`: divide by 10 ** decimal_places to get the amount. Signed where the field says so (a price change delta).
            - `currency` string, required: ISO 4217 currency code.
            - `decimal_places` integer, required: The ISO 4217 digits of `currency` (2 for USD/EUR, 0 for JPY/KRW, 3 for BHD/KWD), and the scale of `value`.
            - `display` string, required: The same figure as a string ready to show: the ISO 4217 code, a space, then the amount at `decimal_places`, e.g. "USD 412.50". Show this; compute with `value`.
          - `percent` number: The charge as a percentage of the stay price, when this step is a percentage, on the 0–100 scale the supplier states it in: 50 is half the stay price, 100 the whole of it. Never a 0–1 fraction. Absent otherwise.
          - `nights` number: The charge as a number of nights of the stay, when this step is expressed in nights. Absent otherwise.
        - `taxes_breakdown` TaxLine[]: Taxes and fees on this rate. ALWAYS present, so an empty array means "no tax is known" and can be shown as such; check `included` per line before adding anything to `total_amount_money`.
          - `amount` number: Deprecated: use `amount_money` instead. The tax in MAJOR units of `currency`.
          - `currency` string: Deprecated: use `amount_money` instead. The currency of `amount`.
          - `amount_money` object: The tax. When the supplier named no currency for the line, it is the currency the rate is priced in.
            - `value` integer, required: Integer amount in MINOR units at the ISO 4217 digits of `currency`: divide by 10 ** decimal_places to get the amount. Signed where the field says so (a price change delta).
            - `currency` string, required: ISO 4217 currency code.
            - `decimal_places` integer, required: The ISO 4217 digits of `currency` (2 for USD/EUR, 0 for JPY/KRW, 3 for BHD/KWD), and the scale of `value`.
            - `display` string, required: The same figure as a string ready to show: the ISO 4217 code, a space, then the amount at `decimal_places`, e.g. "USD 412.50". Show this; compute with `value`.
          - `description` string: The provider’s own wording for the tax. Free text, not a code.
          - `included` boolean: True when the amount is ALREADY inside `total_amount_money`; false when the guest pays it at the property on top. Getting this backwards misquotes the trip.
          - `display` string: Deprecated: use `amount_money` instead. The same figure as a string ready to show: the ISO 4217 code, a space, then the amount, e.g. "USD 159.77". With decimal_places it is written at exactly that scale (value 1561500, JPY, decimal_places 2 is "JPY 15615.00"); without, at the ISO digits of the currency. Show this; compute with the number. Absent when the figure is not money (a cancellation step expressed as a percent or a number of nights) or could not be read unambiguously.
        - `payment_types` HotelPaymentType[]: How the rate can be settled. Each value appears at most once.
        - `promotions` HotelRatePromotion[]
          - `code` string
          - `name` string
          - `remark` string
        - `booking_scope` string: LEGACY-ONLY compatibility metadata. Current canonical `offers[]` never returns `booking_scope`; use `room_rates.length` to determine how many rooms an offer covers.
        - `num_rooms` integer: LEGACY-ONLY compatibility metadata. Current canonical `offers[]` represents room count through `room_rates.length` and never returns `num_rooms`.
        - `rooms` HotelBundleRoom[]: LEGACY-ONLY compatibility room details. Current canonical `offers[]` returns `room_rates[]` and never returns this `rooms` field.
          - `occupancy_number` integer, required: Stable one-based room slot within this bundle.
          - `room_id` string
          - `mapped_room_id` integer
          - `room_name` string
          - `rate_id` string
          - `occupancy` Occupancy, required: The party one room is requested or priced for: the number of adults and the age of each child.
            - `adults` integer, required
            - `children_ages` integer[]
          - `board_type` string
          - `board_name` string
          - `max_occupancy` integer
          - `taxes_and_fees` TaxLine[]
            - `amount` number: Deprecated: use `amount_money` instead. The tax in MAJOR units of `currency`.
            - `currency` string: Deprecated: use `amount_money` instead. The currency of `amount`.
            - `amount_money` object: The tax. When the supplier named no currency for the line, it is the currency the rate is priced in.
              - …
            - `description` string: The provider’s own wording for the tax. Free text, not a code.
            - `included` boolean: True when the amount is ALREADY inside `total_amount_money`; false when the guest pays it at the property on top. Getting this backwards misquotes the trip.
            - `display` string: Deprecated: use `amount_money` instead. The same figure as a string ready to show: the ISO 4217 code, a space, then the amount, e.g. "USD 159.77". With decimal_places it is written at exactly that scale (value 1561500, JPY, decimal_places 2 is "JPY 15615.00"); without, at the ISO digits of the currency. Show this; compute with the number. Absent when the figure is not money (a cancellation step expressed as a percent or a number of nights) or could not be read unambiguously.
          - `policies` HotelBundleRoomPolicy[]
            - `type` string
            - `description` string
            - `fee_amount` number: Deprecated: use `fee_amount_money` instead. Customer policy fee in MAJOR units of `fee_currency`.
            - `fee_currency` string: Deprecated: use `fee_amount_money` instead. The currency of `fee_amount`.
            - `fee_amount_money` object: Customer cancellation or policy fee, with exact minor units and currency precision.
              - …
          - `is_refundable` boolean
          - `cancellation_policy` CancellationStep[]
            - `cancel_time` string: Deadline after which this tier applies. RFC 3339 with the supplier’s declared UTC offset. Steps whose deadline has no declared timezone are omitted from the ladder — the platform never invents an offset — so a schedule can be shorter than the supplier’s own. Tiers are chronological, earliest first, so the first entry is the deadline that matters.
            - `amount` number: Deprecated: use `amount_money` instead. Read `amount_money`, `percent` or `nights`, whichever this step carries. What the guest is charged on or after `cancel_time`: a sum in MAJOR units of `currency`, a percentage or a number of nights, as `type` says.
            - `currency` string: Deprecated: use `amount_money` instead. The currency of `amount`.
            - `type` string: How the charge is expressed — a sum ("amount", "flat_fee"; read `amount_money`), a percentage ("percent", "percentage"; read `percent`) or a number of nights ("nights"; read `nights`).
            - `display` string: Deprecated: use `amount_money` instead. The same figure as a string ready to show: the ISO 4217 code, a space, then the amount, e.g. "USD 159.77". With decimal_places it is written at exactly that scale (value 1561500, JPY, decimal_places 2 is "JPY 15615.00"); without, at the ISO digits of the currency. Show this; compute with the number. Absent when the figure is not money (a cancellation step expressed as a percent or a number of nights) or could not be read unambiguously.
            - `amount_money` object: What the guest is charged on or after `cancel_time`, when this step is a sum. Absent on a percentage or nights step, and when the supplier named no currency.
              - …
            - `percent` number: The charge as a percentage of the stay price, when this step is a percentage, on the 0–100 scale the supplier states it in: 50 is half the stay price, 100 the whole of it. Never a 0–1 fraction. Absent otherwise.
            - `nights` number: The charge as a number of nights of the stay, when this step is expressed in nights. Absent otherwise.
          - `free_cancellation_until` string
          - `payment_types` HotelPaymentType[]: How the rate can be settled. Each value appears at most once.
          - `remarks` string
    - `offers` HotelOffer[]: Bookable whole-stay offers. Choose one and add its `trip_item_token` to the trip exactly once.
      - `offer_id` string, required: Deprecated: use `trip_item_token` instead. Same value.
      - `board_type` string
      - `board_name` string
      - `total_amount` number, required: Deprecated: use `total_amount_money` instead. Price for the whole stay in `currency`, in MAJOR units at the currency’s own precision.
      - `total_amount_display` string: Deprecated: use `total_amount_money` instead. The rate total as a string ready to show: the ISO 4217 code, a space, then `total_amount` at the currency’s ISO digits, e.g. "EUR 606.13".
      - `currency` string, required: Deprecated: use `total_amount_money` instead. The currency of `total_amount`.
      - `total_amount_money` object: Price for the whole stay.
        - `value` integer, required: Integer amount in MINOR units at the ISO 4217 digits of `currency`: divide by 10 ** decimal_places to get the amount. Signed where the field says so (a price change delta).
        - `currency` string, required: ISO 4217 currency code.
        - `decimal_places` integer, required: The ISO 4217 digits of `currency` (2 for USD/EUR, 0 for JPY/KRW, 3 for BHD/KWD), and the scale of `value`.
        - `display` string, required: The same figure as a string ready to show: the ISO 4217 code, a space, then the amount at `decimal_places`, e.g. "USD 412.50". Show this; compute with `value`.
      - `is_refundable` boolean, required
      - `free_cancellation_until` string: Last instant the stay can be cancelled at no charge. RFC 3339 with the supplier’s declared UTC offset. Absent when the supplier declared no timezone — the platform never invents an offset, so a deadline it cannot place on the clock is withheld rather than published ambiguously — and absent when the rate is non-refundable or the provider named no deadline.
      - `cancellation_schedule` CancellationStep[]: The full penalty ladder, chronological. Absent when the provider published none — which is not a statement that cancelling is free.
        - `cancel_time` string: Deadline after which this tier applies. RFC 3339 with the supplier’s declared UTC offset. Steps whose deadline has no declared timezone are omitted from the ladder — the platform never invents an offset — so a schedule can be shorter than the supplier’s own. Tiers are chronological, earliest first, so the first entry is the deadline that matters.
        - `amount` number: Deprecated: use `amount_money` instead. Read `amount_money`, `percent` or `nights`, whichever this step carries. What the guest is charged on or after `cancel_time`: a sum in MAJOR units of `currency`, a percentage or a number of nights, as `type` says.
        - `currency` string: Deprecated: use `amount_money` instead. The currency of `amount`.
        - `type` string: How the charge is expressed — a sum ("amount", "flat_fee"; read `amount_money`), a percentage ("percent", "percentage"; read `percent`) or a number of nights ("nights"; read `nights`).
        - `display` string: Deprecated: use `amount_money` instead. The same figure as a string ready to show: the ISO 4217 code, a space, then the amount, e.g. "USD 159.77". With decimal_places it is written at exactly that scale (value 1561500, JPY, decimal_places 2 is "JPY 15615.00"); without, at the ISO digits of the currency. Show this; compute with the number. Absent when the figure is not money (a cancellation step expressed as a percent or a number of nights) or could not be read unambiguously.
        - `amount_money` object: What the guest is charged on or after `cancel_time`, when this step is a sum. Absent on a percentage or nights step, and when the supplier named no currency.
          - `value` integer, required: Integer amount in MINOR units at the ISO 4217 digits of `currency`: divide by 10 ** decimal_places to get the amount. Signed where the field says so (a price change delta).
          - `currency` string, required: ISO 4217 currency code.
          - `decimal_places` integer, required: The ISO 4217 digits of `currency` (2 for USD/EUR, 0 for JPY/KRW, 3 for BHD/KWD), and the scale of `value`.
          - `display` string, required: The same figure as a string ready to show: the ISO 4217 code, a space, then the amount at `decimal_places`, e.g. "USD 412.50". Show this; compute with `value`.
        - `percent` number: The charge as a percentage of the stay price, when this step is a percentage, on the 0–100 scale the supplier states it in: 50 is half the stay price, 100 the whole of it. Never a 0–1 fraction. Absent otherwise.
        - `nights` number: The charge as a number of nights of the stay, when this step is expressed in nights. Absent otherwise.
      - `taxes_breakdown` TaxLine[], required
        - `amount` number: Deprecated: use `amount_money` instead. The tax in MAJOR units of `currency`.
        - `currency` string: Deprecated: use `amount_money` instead. The currency of `amount`.
        - `amount_money` object: The tax. When the supplier named no currency for the line, it is the currency the rate is priced in.
          - `value` integer, required: Integer amount in MINOR units at the ISO 4217 digits of `currency`: divide by 10 ** decimal_places to get the amount. Signed where the field says so (a price change delta).
          - `currency` string, required: ISO 4217 currency code.
          - `decimal_places` integer, required: The ISO 4217 digits of `currency` (2 for USD/EUR, 0 for JPY/KRW, 3 for BHD/KWD), and the scale of `value`.
          - `display` string, required: The same figure as a string ready to show: the ISO 4217 code, a space, then the amount at `decimal_places`, e.g. "USD 412.50". Show this; compute with `value`.
        - `description` string: The provider’s own wording for the tax. Free text, not a code.
        - `included` boolean: True when the amount is ALREADY inside `total_amount_money`; false when the guest pays it at the property on top. Getting this backwards misquotes the trip.
        - `display` string: Deprecated: use `amount_money` instead. The same figure as a string ready to show: the ISO 4217 code, a space, then the amount, e.g. "USD 159.77". With decimal_places it is written at exactly that scale (value 1561500, JPY, decimal_places 2 is "JPY 15615.00"); without, at the ISO digits of the currency. Show this; compute with the number. Absent when the figure is not money (a cancellation step expressed as a percent or a number of nights) or could not be read unambiguously.
      - `payment_types` HotelPaymentType[]: How the rate can be settled. Each value appears at most once.
      - `promotions` HotelOfferPromotion[]
        - `name` string
        - `remark` string
      - `trip_item_token` string, required: The token `trip(add_item)` takes as `trip_item_token`. Add it once even when `room_rates` contains several occupancies.
      - `room_rates` HotelRoomRate[], required: One entry per requested occupancy. One occupancy means one room; multiple occupancies mean a multi-room offer.
        - `room_id` string, required: References one entry in this hotel’s `rooms[]` metadata.
        - `occupancy_number` integer, required: Stable one-based occupancy slot from the search request.
        - `occupancy` Occupancy, required: The party one room is requested or priced for: the number of adults and the age of each child.
          - `adults` integer, required
          - `children_ages` integer[]
        - `room_name` string
        - `board_type` string
        - `board_name` string
        - `max_occupancy` integer
        - `taxes_and_fees` TaxLine[], required
          - `amount` number: Deprecated: use `amount_money` instead. The tax in MAJOR units of `currency`.
          - `currency` string: Deprecated: use `amount_money` instead. The currency of `amount`.
          - `amount_money` object: The tax. When the supplier named no currency for the line, it is the currency the rate is priced in.
            - `value` integer, required: Integer amount in MINOR units at the ISO 4217 digits of `currency`: divide by 10 ** decimal_places to get the amount. Signed where the field says so (a price change delta).
            - `currency` string, required: ISO 4217 currency code.
            - `decimal_places` integer, required: The ISO 4217 digits of `currency` (2 for USD/EUR, 0 for JPY/KRW, 3 for BHD/KWD), and the scale of `value`.
            - `display` string, required: The same figure as a string ready to show: the ISO 4217 code, a space, then the amount at `decimal_places`, e.g. "USD 412.50". Show this; compute with `value`.
          - `description` string: The provider’s own wording for the tax. Free text, not a code.
          - `included` boolean: True when the amount is ALREADY inside `total_amount_money`; false when the guest pays it at the property on top. Getting this backwards misquotes the trip.
          - `display` string: Deprecated: use `amount_money` instead. The same figure as a string ready to show: the ISO 4217 code, a space, then the amount, e.g. "USD 159.77". With decimal_places it is written at exactly that scale (value 1561500, JPY, decimal_places 2 is "JPY 15615.00"); without, at the ISO digits of the currency. Show this; compute with the number. Absent when the figure is not money (a cancellation step expressed as a percent or a number of nights) or could not be read unambiguously.
        - `policies` HotelBundleRoomPolicy[]
          - `type` string
          - `description` string
          - `fee_amount` number: Deprecated: use `fee_amount_money` instead. Customer policy fee in MAJOR units of `fee_currency`.
          - `fee_currency` string: Deprecated: use `fee_amount_money` instead. The currency of `fee_amount`.
          - `fee_amount_money` object: Customer cancellation or policy fee, with exact minor units and currency precision.
            - `value` integer, required: Integer amount in MINOR units at the ISO 4217 digits of `currency`: divide by 10 ** decimal_places to get the amount. Signed where the field says so (a price change delta).
            - `currency` string, required: ISO 4217 currency code.
            - `decimal_places` integer, required: The ISO 4217 digits of `currency` (2 for USD/EUR, 0 for JPY/KRW, 3 for BHD/KWD), and the scale of `value`.
            - `display` string, required: The same figure as a string ready to show: the ISO 4217 code, a space, then the amount at `decimal_places`, e.g. "USD 412.50". Show this; compute with `value`.
        - `is_refundable` boolean, required
        - `cancellation_policy` CancellationStep[]
          - `cancel_time` string: Deadline after which this tier applies. RFC 3339 with the supplier’s declared UTC offset. Steps whose deadline has no declared timezone are omitted from the ladder — the platform never invents an offset — so a schedule can be shorter than the supplier’s own. Tiers are chronological, earliest first, so the first entry is the deadline that matters.
          - `amount` number: Deprecated: use `amount_money` instead. Read `amount_money`, `percent` or `nights`, whichever this step carries. What the guest is charged on or after `cancel_time`: a sum in MAJOR units of `currency`, a percentage or a number of nights, as `type` says.
          - `currency` string: Deprecated: use `amount_money` instead. The currency of `amount`.
          - `type` string: How the charge is expressed — a sum ("amount", "flat_fee"; read `amount_money`), a percentage ("percent", "percentage"; read `percent`) or a number of nights ("nights"; read `nights`).
          - `display` string: Deprecated: use `amount_money` instead. The same figure as a string ready to show: the ISO 4217 code, a space, then the amount, e.g. "USD 159.77". With decimal_places it is written at exactly that scale (value 1561500, JPY, decimal_places 2 is "JPY 15615.00"); without, at the ISO digits of the currency. Show this; compute with the number. Absent when the figure is not money (a cancellation step expressed as a percent or a number of nights) or could not be read unambiguously.
          - `amount_money` object: What the guest is charged on or after `cancel_time`, when this step is a sum. Absent on a percentage or nights step, and when the supplier named no currency.
            - `value` integer, required: Integer amount in MINOR units at the ISO 4217 digits of `currency`: divide by 10 ** decimal_places to get the amount. Signed where the field says so (a price change delta).
            - `currency` string, required: ISO 4217 currency code.
            - `decimal_places` integer, required: The ISO 4217 digits of `currency` (2 for USD/EUR, 0 for JPY/KRW, 3 for BHD/KWD), and the scale of `value`.
            - `display` string, required: The same figure as a string ready to show: the ISO 4217 code, a space, then the amount at `decimal_places`, e.g. "USD 412.50". Show this; compute with `value`.
          - `percent` number: The charge as a percentage of the stay price, when this step is a percentage, on the 0–100 scale the supplier states it in: 50 is half the stay price, 100 the whole of it. Never a 0–1 fraction. Absent otherwise.
          - `nights` number: The charge as a number of nights of the stay, when this step is expressed in nights. Absent otherwise.
        - `free_cancellation_until` string
        - `payment_types` HotelPaymentType[]: How the rate can be settled. Each value appears at most once.
        - `remarks` string
    - `match_score` integer: How well the hotel fits the request, 0–100. The hotels come best first. Relative to this search, not comparable across searches. Absent on some hotels.
  - `has_more` boolean: More hotels are available; ask for more in the same conversation.
  - `reference` boolean: The hotels are a 1-night reference search shown while the check-out date is asked.
  - `error` object: Why the task failed, when `status` is `failed`.
    - `code` string, required
    - `message` string, required
  - `superseded_by` string: The task that replaced this one, when `status` is `canceled`.
  - `charge` HotelAiSearchCharge: What a turn was charged to the organization's balance, once the turn has ended (`completed`, `input_required`, `failed` or `canceled`); every amount is 0 when the turn cost nothing. Absent while the task is `working`. Carried on JSON answers only: an event stream does not carry it, so read it with `GET /v1/hotel_ai_search/tasks/{task_id}`.
    - `turn` integer, required: The turn of the task this charge is for, from 1; a task answering a question is a later turn.
    - `llm_usd` number, required: The language-model part of the charge, in USD.
    - `api_usd` number, required: The hotel search part of the charge, in USD.
    - `total_usd` number, required: `llm_usd` + `api_usd`.
    - `currency` 'USD', required

## Other responses

- `202`: The search is still running: the early reply. Read `Location` after Retry-After.
- `400`: Bad request: malformed JSON, or an invalid header such as a reserved `X-End-User-Id`.
- `401`: Authentication required
- `402`: The organization's balance is below what a search turn needs. The message carries the top-up link. **`PAYMENT_REQUIRED`** — The organization's balance cannot cover this call. Top up at the link in the message. Retrying never fills an empty wallet.
- `403`: The key is valid but is not a tenant API key (`jnk_t_…`), is not granted the `search_live` scope, or Travel AI search is not enabled for this account. **`FORBIDDEN`** — The credential is valid, and this request is refused anyway. Do not rotate the key — it is working. Check that it is entitled to this operation, and on this environment.
- `404`: Resource not found
- `410`: The resource this request names no longer exists
- `422`: Validation error
- `429`: Rate limit or quota exceeded
- `502`: The travel provider rejected the request, or an upstream call failed
- `503`: No travel provider can serve the request right now
- `504`: The travel provider did not answer in time

---

[API](https://skmtc.dev/gojinko/apis/jinko-public-api.md) - [All operations](https://skmtc.dev/gojinko/apis/jinko-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/gojinko/apis/jinko-public-api/revisions/ac5046767e4c?raw)