Hotels

Search hotels from one sentence, with follow-ups

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.

post/v1/hotel_ai_search

Request

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

Headers

Idempotency-Keystring

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.

Preferstring

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.

Example:wait=0

Request body

textstring required

The traveller's request in one sentence, or the answer to the question asked in the previous turn.

context_idstring

The conversation to continue, from an earlier answer. Omit to start a new conversation.

task_idstring

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.

currencystring

Currency of the prices (ISO 4217).

guest_nationalitystring

Nationality of the guests (ISO 3166-1 alpha-2).

timezonestring required

The traveller's IANA time zone. Relative dates such as "next weekend" or "tonight" are computed in it.

Example request

{
  "text": "A hotel in Paris next weekend for 2 adults with breakfast included",
  "context_id": "ctx_example",
  "task_id": "atk_example",
  "currency": "EUR",
  "guest_nationality": "FR",
  "timezone": "Europe/Paris"
}

Response

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

context_idstring nullable required

The conversation; send it with the next message to continue.

task_idstring 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.

messagestring

The reply to show the traveller.

questionstring

What the reply asks for, when status is input_required.

criteriaobject

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.

notesobject[]

Assumptions and adjustments made while understanding the request.

has_moreboolean

More hotels are available; ask for more in the same conversation.

referenceboolean

The hotels are a 1-night reference search shown while the check-out date is asked.

superseded_bystring

The task that replaced this one, when status is canceled.

Changes

No recorded changes to this operation across all 1 revision of this API.