Search hotels from one sentence, with follow-ups
curl --request POST \
--url https://api.gojinko.com/v1/hotel_ai_search \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"text": "A hotel in Paris next weekend for 2 adults with breakfast included",
"timezone": "Europe/Paris",
"context_id": "ctx_example",
"task_id": "atk_example",
"currency": "EUR",
"guest_nationality": "FR",
"effort": "medium"
}
'import requests
url = "https://api.gojinko.com/v1/hotel_ai_search"
payload = {
"text": "A hotel in Paris next weekend for 2 adults with breakfast included",
"timezone": "Europe/Paris",
"context_id": "ctx_example",
"task_id": "atk_example",
"currency": "EUR",
"guest_nationality": "FR",
"effort": "medium"
}
headers = {
"X-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
text: 'A hotel in Paris next weekend for 2 adults with breakfast included',
timezone: 'Europe/Paris',
context_id: 'ctx_example',
task_id: 'atk_example',
currency: 'EUR',
guest_nationality: 'FR',
effort: 'medium'
})
};
fetch('https://api.gojinko.com/v1/hotel_ai_search', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.gojinko.com/v1/hotel_ai_search",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'text' => 'A hotel in Paris next weekend for 2 adults with breakfast included',
'timezone' => 'Europe/Paris',
'context_id' => 'ctx_example',
'task_id' => 'atk_example',
'currency' => 'EUR',
'guest_nationality' => 'FR',
'effort' => 'medium'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-API-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.gojinko.com/v1/hotel_ai_search"
payload := strings.NewReader("{\n \"text\": \"A hotel in Paris next weekend for 2 adults with breakfast included\",\n \"timezone\": \"Europe/Paris\",\n \"context_id\": \"ctx_example\",\n \"task_id\": \"atk_example\",\n \"currency\": \"EUR\",\n \"guest_nationality\": \"FR\",\n \"effort\": \"medium\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-API-Key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.gojinko.com/v1/hotel_ai_search")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"text\": \"A hotel in Paris next weekend for 2 adults with breakfast included\",\n \"timezone\": \"Europe/Paris\",\n \"context_id\": \"ctx_example\",\n \"task_id\": \"atk_example\",\n \"currency\": \"EUR\",\n \"guest_nationality\": \"FR\",\n \"effort\": \"medium\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.gojinko.com/v1/hotel_ai_search")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"text\": \"A hotel in Paris next weekend for 2 adults with breakfast included\",\n \"timezone\": \"Europe/Paris\",\n \"context_id\": \"ctx_example\",\n \"task_id\": \"atk_example\",\n \"currency\": \"EUR\",\n \"guest_nationality\": \"FR\",\n \"effort\": \"medium\"\n}"
response = http.request(request)
puts response.read_body{
"context_id": "ctx_example",
"task_id": "atk_example",
"status": "working",
"message": "Found 37 hotels in Paris for Oct 24–25 (1 night, 2 adults, 1 room).",
"question": "dates",
"criteria": {},
"notes": [
{}
],
"hotels": [
{
"hotel_id": "lp1d2c3",
"hotel_ref": "h1:lp1d2c3",
"name": "Hôtel Le Marais",
"address": "12 Rue de Rivoli",
"city": "Paris",
"country": "fr",
"star_rating": 4,
"category": "4 KEYS",
"lodging_type": "Aparthotel",
"rating": 8.6,
"review_count": 1243,
"main_photo": "https://images.example.com/hotels/main.jpg",
"thumbnail": "https://images.example.com/hotels/thumb.jpg",
"latitude": 48.8566,
"longitude": 2.3522,
"distance_km": 1,
"recommendation_score": 0.5,
"rooms": [
{
"room_id": "rm_1",
"room_name": "Superior Double",
"description": "<string>",
"requested_occupancy": 2,
"room_capacity": 2,
"max_occupancy": 2,
"images": [
"<string>"
],
"amenities": [
"<string>"
],
"beds": [
{
"bed_type": "<string>",
"count": 2
}
],
"rates": [
{
"offer_id": "htl_2d67a7441c60e5de",
"board_type": "RO",
"board_name": "Room Only",
"total_amount": 1818.4,
"total_amount_display": "EUR 606.13",
"currency": "EUR",
"total_amount_money": {
"value": 41250,
"currency": "USD",
"decimal_places": 2,
"display": "USD 412.50"
},
"is_refundable": false,
"free_cancellation_until": "2026-08-18T10:00:00+02:00",
"cancellation_schedule": [
{
"cancel_time": "2026-08-18T10:00:00+02:00",
"amount": 606.13,
"currency": "EUR",
"type": "amount",
"display": "EUR 606.13",
"amount_money": {
"value": 41250,
"currency": "USD",
"decimal_places": 2,
"display": "USD 412.50"
},
"percent": 50,
"nights": 1
}
],
"taxes_breakdown": [
{
"amount": 164.49,
"currency": "EUR",
"amount_money": {
"value": 41250,
"currency": "USD",
"decimal_places": 2,
"display": "USD 412.50"
},
"description": "19, VAT National taxes on accommodation",
"included": true,
"display": "EUR 164.49"
}
],
"payment_types": [
"pay_now"
],
"promotions": [
{
"code": "<string>",
"name": "<string>",
"remark": "<string>"
}
],
"booking_scope": "room_bundle",
"num_rooms": 2,
"rooms": [
{
"occupancy_number": 1,
"occupancy": {
"adults": 2,
"children_ages": [
8
]
},
"room_id": "<string>",
"mapped_room_id": 123,
"room_name": "Superior Double",
"rate_id": "<string>",
"board_type": "BB",
"board_name": "Breakfast Included",
"max_occupancy": 123,
"taxes_and_fees": [
{
"amount": 164.49,
"currency": "EUR",
"amount_money": {
"value": 41250,
"currency": "USD",
"decimal_places": 2,
"display": "USD 412.50"
},
"description": "19, VAT National taxes on accommodation",
"included": true,
"display": "EUR 164.49"
}
],
"policies": [
{
"type": "<string>",
"description": "<string>",
"fee_amount": 123,
"fee_currency": "<string>",
"fee_amount_money": {
"value": 41250,
"currency": "USD",
"decimal_places": 2,
"display": "USD 412.50"
}
}
],
"is_refundable": true,
"cancellation_policy": [
{
"cancel_time": "2026-08-18T10:00:00+02:00",
"amount": 606.13,
"currency": "EUR",
"type": "amount",
"display": "EUR 606.13",
"amount_money": {
"value": 41250,
"currency": "USD",
"decimal_places": 2,
"display": "USD 412.50"
},
"percent": 50,
"nights": 1
}
],
"free_cancellation_until": "<string>",
"payment_types": [
"pay_now"
],
"remarks": "<string>"
}
]
}
]
}
],
"offers": [
{
"offer_id": "htl_2d67a7441c60e5de",
"total_amount": 1818.4,
"currency": "EUR",
"is_refundable": true,
"taxes_breakdown": [
{
"amount": 164.49,
"currency": "EUR",
"amount_money": {
"value": 41250,
"currency": "USD",
"decimal_places": 2,
"display": "USD 412.50"
},
"description": "19, VAT National taxes on accommodation",
"included": true,
"display": "EUR 164.49"
}
],
"trip_item_token": "htl_2d67a7441c60e5de",
"room_rates": [
{
"room_id": "<string>",
"occupancy_number": 2,
"occupancy": {
"adults": 2,
"children_ages": [
8
]
},
"taxes_and_fees": [
{
"amount": 164.49,
"currency": "EUR",
"amount_money": {
"value": 41250,
"currency": "USD",
"decimal_places": 2,
"display": "USD 412.50"
},
"description": "19, VAT National taxes on accommodation",
"included": true,
"display": "EUR 164.49"
}
],
"is_refundable": true,
"room_name": "<string>",
"board_type": "<string>",
"board_name": "<string>",
"max_occupancy": 123,
"policies": [
{
"type": "<string>",
"description": "<string>",
"fee_amount": 123,
"fee_currency": "<string>",
"fee_amount_money": {
"value": 41250,
"currency": "USD",
"decimal_places": 2,
"display": "USD 412.50"
}
}
],
"cancellation_policy": [
{
"cancel_time": "2026-08-18T10:00:00+02:00",
"amount": 606.13,
"currency": "EUR",
"type": "amount",
"display": "EUR 606.13",
"amount_money": {
"value": 41250,
"currency": "USD",
"decimal_places": 2,
"display": "USD 412.50"
},
"percent": 50,
"nights": 1
}
],
"free_cancellation_until": "<string>",
"payment_types": [
"pay_now"
],
"remarks": "<string>"
}
],
"board_type": "RO",
"board_name": "Room Only",
"total_amount_display": "EUR 606.13",
"total_amount_money": {
"value": 41250,
"currency": "USD",
"decimal_places": 2,
"display": "USD 412.50"
},
"free_cancellation_until": "2026-08-18T10:00:00+02:00",
"cancellation_schedule": [
{
"cancel_time": "2026-08-18T10:00:00+02:00",
"amount": 606.13,
"currency": "EUR",
"type": "amount",
"display": "EUR 606.13",
"amount_money": {
"value": 41250,
"currency": "USD",
"decimal_places": 2,
"display": "USD 412.50"
},
"percent": 50,
"nights": 1
}
],
"payment_types": [
"pay_now"
],
"promotions": [
{
"name": "<string>",
"remark": "<string>"
}
]
}
],
"match_score": 87
}
],
"has_more": true,
"reference": true,
"error": {
"code": "<string>",
"message": "<string>"
},
"superseded_by": "<string>",
"charge": {
"turn": 1,
"llm_usd": 0.0165,
"api_usd": 0.0645,
"total_usd": 0.081,
"currency": "USD"
}
}{
"context_id": "ctx_example",
"task_id": "atk_example",
"status": "working",
"message": "Found 37 hotels in Paris for Oct 24–25 (1 night, 2 adults, 1 room).",
"question": "dates",
"criteria": {},
"notes": [
{}
],
"hotels": [
{
"hotel_id": "lp1d2c3",
"hotel_ref": "h1:lp1d2c3",
"name": "Hôtel Le Marais",
"address": "12 Rue de Rivoli",
"city": "Paris",
"country": "fr",
"star_rating": 4,
"category": "4 KEYS",
"lodging_type": "Aparthotel",
"rating": 8.6,
"review_count": 1243,
"main_photo": "https://images.example.com/hotels/main.jpg",
"thumbnail": "https://images.example.com/hotels/thumb.jpg",
"latitude": 48.8566,
"longitude": 2.3522,
"distance_km": 1,
"recommendation_score": 0.5,
"rooms": [
{
"room_id": "rm_1",
"room_name": "Superior Double",
"description": "<string>",
"requested_occupancy": 2,
"room_capacity": 2,
"max_occupancy": 2,
"images": [
"<string>"
],
"amenities": [
"<string>"
],
"beds": [
{
"bed_type": "<string>",
"count": 2
}
],
"rates": [
{
"offer_id": "htl_2d67a7441c60e5de",
"board_type": "RO",
"board_name": "Room Only",
"total_amount": 1818.4,
"total_amount_display": "EUR 606.13",
"currency": "EUR",
"total_amount_money": {
"value": 41250,
"currency": "USD",
"decimal_places": 2,
"display": "USD 412.50"
},
"is_refundable": false,
"free_cancellation_until": "2026-08-18T10:00:00+02:00",
"cancellation_schedule": [
{
"cancel_time": "2026-08-18T10:00:00+02:00",
"amount": 606.13,
"currency": "EUR",
"type": "amount",
"display": "EUR 606.13",
"amount_money": {
"value": 41250,
"currency": "USD",
"decimal_places": 2,
"display": "USD 412.50"
},
"percent": 50,
"nights": 1
}
],
"taxes_breakdown": [
{
"amount": 164.49,
"currency": "EUR",
"amount_money": {
"value": 41250,
"currency": "USD",
"decimal_places": 2,
"display": "USD 412.50"
},
"description": "19, VAT National taxes on accommodation",
"included": true,
"display": "EUR 164.49"
}
],
"payment_types": [
"pay_now"
],
"promotions": [
{
"code": "<string>",
"name": "<string>",
"remark": "<string>"
}
],
"booking_scope": "room_bundle",
"num_rooms": 2,
"rooms": [
{
"occupancy_number": 1,
"occupancy": {
"adults": 2,
"children_ages": [
8
]
},
"room_id": "<string>",
"mapped_room_id": 123,
"room_name": "Superior Double",
"rate_id": "<string>",
"board_type": "BB",
"board_name": "Breakfast Included",
"max_occupancy": 123,
"taxes_and_fees": [
{
"amount": 164.49,
"currency": "EUR",
"amount_money": {
"value": 41250,
"currency": "USD",
"decimal_places": 2,
"display": "USD 412.50"
},
"description": "19, VAT National taxes on accommodation",
"included": true,
"display": "EUR 164.49"
}
],
"policies": [
{
"type": "<string>",
"description": "<string>",
"fee_amount": 123,
"fee_currency": "<string>",
"fee_amount_money": {
"value": 41250,
"currency": "USD",
"decimal_places": 2,
"display": "USD 412.50"
}
}
],
"is_refundable": true,
"cancellation_policy": [
{
"cancel_time": "2026-08-18T10:00:00+02:00",
"amount": 606.13,
"currency": "EUR",
"type": "amount",
"display": "EUR 606.13",
"amount_money": {
"value": 41250,
"currency": "USD",
"decimal_places": 2,
"display": "USD 412.50"
},
"percent": 50,
"nights": 1
}
],
"free_cancellation_until": "<string>",
"payment_types": [
"pay_now"
],
"remarks": "<string>"
}
]
}
]
}
],
"offers": [
{
"offer_id": "htl_2d67a7441c60e5de",
"total_amount": 1818.4,
"currency": "EUR",
"is_refundable": true,
"taxes_breakdown": [
{
"amount": 164.49,
"currency": "EUR",
"amount_money": {
"value": 41250,
"currency": "USD",
"decimal_places": 2,
"display": "USD 412.50"
},
"description": "19, VAT National taxes on accommodation",
"included": true,
"display": "EUR 164.49"
}
],
"trip_item_token": "htl_2d67a7441c60e5de",
"room_rates": [
{
"room_id": "<string>",
"occupancy_number": 2,
"occupancy": {
"adults": 2,
"children_ages": [
8
]
},
"taxes_and_fees": [
{
"amount": 164.49,
"currency": "EUR",
"amount_money": {
"value": 41250,
"currency": "USD",
"decimal_places": 2,
"display": "USD 412.50"
},
"description": "19, VAT National taxes on accommodation",
"included": true,
"display": "EUR 164.49"
}
],
"is_refundable": true,
"room_name": "<string>",
"board_type": "<string>",
"board_name": "<string>",
"max_occupancy": 123,
"policies": [
{
"type": "<string>",
"description": "<string>",
"fee_amount": 123,
"fee_currency": "<string>",
"fee_amount_money": {
"value": 41250,
"currency": "USD",
"decimal_places": 2,
"display": "USD 412.50"
}
}
],
"cancellation_policy": [
{
"cancel_time": "2026-08-18T10:00:00+02:00",
"amount": 606.13,
"currency": "EUR",
"type": "amount",
"display": "EUR 606.13",
"amount_money": {
"value": 41250,
"currency": "USD",
"decimal_places": 2,
"display": "USD 412.50"
},
"percent": 50,
"nights": 1
}
],
"free_cancellation_until": "<string>",
"payment_types": [
"pay_now"
],
"remarks": "<string>"
}
],
"board_type": "RO",
"board_name": "Room Only",
"total_amount_display": "EUR 606.13",
"total_amount_money": {
"value": 41250,
"currency": "USD",
"decimal_places": 2,
"display": "USD 412.50"
},
"free_cancellation_until": "2026-08-18T10:00:00+02:00",
"cancellation_schedule": [
{
"cancel_time": "2026-08-18T10:00:00+02:00",
"amount": 606.13,
"currency": "EUR",
"type": "amount",
"display": "EUR 606.13",
"amount_money": {
"value": 41250,
"currency": "USD",
"decimal_places": 2,
"display": "USD 412.50"
},
"percent": 50,
"nights": 1
}
],
"payment_types": [
"pay_now"
],
"promotions": [
{
"name": "<string>",
"remark": "<string>"
}
]
}
],
"match_score": 87
}
],
"has_more": true,
"reference": true,
"error": {
"code": "<string>",
"message": "<string>"
},
"superseded_by": "<string>",
"charge": {
"turn": 1,
"llm_usd": 0.0165,
"api_usd": 0.0645,
"total_usd": 0.081,
"currency": "USD"
}
}{
"error": {
"code": "BAD_REQUEST",
"message": "Malformed JSON in request body"
}
}{
"error": {
"code": "AUTH_REQUIRED",
"message": "Invalid or expired API key.",
"doc_url": "https://docs.gojinko.com/authentication/api-keys"
}
}{
"error": {
"code": "PAYMENT_REQUIRED",
"message": "Insufficient balance — a hotel AI search turn needs at least $0.20 and your organization has $0.0500 available. Top up at https://dashboard.gojinko.com/developers/billing/topup"
}
}{
"error": {
"code": "FORBIDDEN",
"message": "This API key is not granted the \"search_live\" scope required by this endpoint"
}
}{
"error": {
"code": "NOT_FOUND",
"message": "Resource not found.",
"doc_url": "https://docs.gojinko.com/concepts/errors"
}
}{
"error": {
"code": "GONE",
"message": "The resource no longer exists.",
"doc_url": "https://docs.gojinko.com/concepts/errors"
}
}{
"error": {
"code": "BAD_REQUEST",
"message": "A required field is missing or invalid.",
"doc_url": "https://docs.gojinko.com/concepts/errors"
}
}{
"error": {
"code": "RATE_LIMITED",
"message": "Too many requests. Retry after the Retry-After delay.",
"doc_url": "https://docs.gojinko.com/concepts/errors"
}
}{
"error": {
"code": "UPSTREAM_REJECTED",
"message": "The request was declined for this offer. Try another offer.",
"doc_url": "https://docs.gojinko.com/concepts/errors"
}
}{
"error": {
"code": "UPSTREAM_UNAVAILABLE",
"message": "The service is temporarily unavailable. Retry after the Retry-After delay.",
"doc_url": "https://docs.gojinko.com/concepts/errors"
}
}{
"error": {
"code": "UPSTREAM_TIMEOUT",
"message": "The request timed out before a result was available. Retry the request.",
"doc_url": "https://docs.gojinko.com/concepts/errors"
}
}Hotel search
hotel-ai-search
Search hotels from one sentence, with follow-ups
POST
/
v1
/
hotel_ai_search
Search hotels from one sentence, with follow-ups
curl --request POST \
--url https://api.gojinko.com/v1/hotel_ai_search \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"text": "A hotel in Paris next weekend for 2 adults with breakfast included",
"timezone": "Europe/Paris",
"context_id": "ctx_example",
"task_id": "atk_example",
"currency": "EUR",
"guest_nationality": "FR",
"effort": "medium"
}
'import requests
url = "https://api.gojinko.com/v1/hotel_ai_search"
payload = {
"text": "A hotel in Paris next weekend for 2 adults with breakfast included",
"timezone": "Europe/Paris",
"context_id": "ctx_example",
"task_id": "atk_example",
"currency": "EUR",
"guest_nationality": "FR",
"effort": "medium"
}
headers = {
"X-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
text: 'A hotel in Paris next weekend for 2 adults with breakfast included',
timezone: 'Europe/Paris',
context_id: 'ctx_example',
task_id: 'atk_example',
currency: 'EUR',
guest_nationality: 'FR',
effort: 'medium'
})
};
fetch('https://api.gojinko.com/v1/hotel_ai_search', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.gojinko.com/v1/hotel_ai_search",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'text' => 'A hotel in Paris next weekend for 2 adults with breakfast included',
'timezone' => 'Europe/Paris',
'context_id' => 'ctx_example',
'task_id' => 'atk_example',
'currency' => 'EUR',
'guest_nationality' => 'FR',
'effort' => 'medium'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-API-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.gojinko.com/v1/hotel_ai_search"
payload := strings.NewReader("{\n \"text\": \"A hotel in Paris next weekend for 2 adults with breakfast included\",\n \"timezone\": \"Europe/Paris\",\n \"context_id\": \"ctx_example\",\n \"task_id\": \"atk_example\",\n \"currency\": \"EUR\",\n \"guest_nationality\": \"FR\",\n \"effort\": \"medium\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-API-Key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.gojinko.com/v1/hotel_ai_search")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"text\": \"A hotel in Paris next weekend for 2 adults with breakfast included\",\n \"timezone\": \"Europe/Paris\",\n \"context_id\": \"ctx_example\",\n \"task_id\": \"atk_example\",\n \"currency\": \"EUR\",\n \"guest_nationality\": \"FR\",\n \"effort\": \"medium\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.gojinko.com/v1/hotel_ai_search")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"text\": \"A hotel in Paris next weekend for 2 adults with breakfast included\",\n \"timezone\": \"Europe/Paris\",\n \"context_id\": \"ctx_example\",\n \"task_id\": \"atk_example\",\n \"currency\": \"EUR\",\n \"guest_nationality\": \"FR\",\n \"effort\": \"medium\"\n}"
response = http.request(request)
puts response.read_body{
"context_id": "ctx_example",
"task_id": "atk_example",
"status": "working",
"message": "Found 37 hotels in Paris for Oct 24–25 (1 night, 2 adults, 1 room).",
"question": "dates",
"criteria": {},
"notes": [
{}
],
"hotels": [
{
"hotel_id": "lp1d2c3",
"hotel_ref": "h1:lp1d2c3",
"name": "Hôtel Le Marais",
"address": "12 Rue de Rivoli",
"city": "Paris",
"country": "fr",
"star_rating": 4,
"category": "4 KEYS",
"lodging_type": "Aparthotel",
"rating": 8.6,
"review_count": 1243,
"main_photo": "https://images.example.com/hotels/main.jpg",
"thumbnail": "https://images.example.com/hotels/thumb.jpg",
"latitude": 48.8566,
"longitude": 2.3522,
"distance_km": 1,
"recommendation_score": 0.5,
"rooms": [
{
"room_id": "rm_1",
"room_name": "Superior Double",
"description": "<string>",
"requested_occupancy": 2,
"room_capacity": 2,
"max_occupancy": 2,
"images": [
"<string>"
],
"amenities": [
"<string>"
],
"beds": [
{
"bed_type": "<string>",
"count": 2
}
],
"rates": [
{
"offer_id": "htl_2d67a7441c60e5de",
"board_type": "RO",
"board_name": "Room Only",
"total_amount": 1818.4,
"total_amount_display": "EUR 606.13",
"currency": "EUR",
"total_amount_money": {
"value": 41250,
"currency": "USD",
"decimal_places": 2,
"display": "USD 412.50"
},
"is_refundable": false,
"free_cancellation_until": "2026-08-18T10:00:00+02:00",
"cancellation_schedule": [
{
"cancel_time": "2026-08-18T10:00:00+02:00",
"amount": 606.13,
"currency": "EUR",
"type": "amount",
"display": "EUR 606.13",
"amount_money": {
"value": 41250,
"currency": "USD",
"decimal_places": 2,
"display": "USD 412.50"
},
"percent": 50,
"nights": 1
}
],
"taxes_breakdown": [
{
"amount": 164.49,
"currency": "EUR",
"amount_money": {
"value": 41250,
"currency": "USD",
"decimal_places": 2,
"display": "USD 412.50"
},
"description": "19, VAT National taxes on accommodation",
"included": true,
"display": "EUR 164.49"
}
],
"payment_types": [
"pay_now"
],
"promotions": [
{
"code": "<string>",
"name": "<string>",
"remark": "<string>"
}
],
"booking_scope": "room_bundle",
"num_rooms": 2,
"rooms": [
{
"occupancy_number": 1,
"occupancy": {
"adults": 2,
"children_ages": [
8
]
},
"room_id": "<string>",
"mapped_room_id": 123,
"room_name": "Superior Double",
"rate_id": "<string>",
"board_type": "BB",
"board_name": "Breakfast Included",
"max_occupancy": 123,
"taxes_and_fees": [
{
"amount": 164.49,
"currency": "EUR",
"amount_money": {
"value": 41250,
"currency": "USD",
"decimal_places": 2,
"display": "USD 412.50"
},
"description": "19, VAT National taxes on accommodation",
"included": true,
"display": "EUR 164.49"
}
],
"policies": [
{
"type": "<string>",
"description": "<string>",
"fee_amount": 123,
"fee_currency": "<string>",
"fee_amount_money": {
"value": 41250,
"currency": "USD",
"decimal_places": 2,
"display": "USD 412.50"
}
}
],
"is_refundable": true,
"cancellation_policy": [
{
"cancel_time": "2026-08-18T10:00:00+02:00",
"amount": 606.13,
"currency": "EUR",
"type": "amount",
"display": "EUR 606.13",
"amount_money": {
"value": 41250,
"currency": "USD",
"decimal_places": 2,
"display": "USD 412.50"
},
"percent": 50,
"nights": 1
}
],
"free_cancellation_until": "<string>",
"payment_types": [
"pay_now"
],
"remarks": "<string>"
}
]
}
]
}
],
"offers": [
{
"offer_id": "htl_2d67a7441c60e5de",
"total_amount": 1818.4,
"currency": "EUR",
"is_refundable": true,
"taxes_breakdown": [
{
"amount": 164.49,
"currency": "EUR",
"amount_money": {
"value": 41250,
"currency": "USD",
"decimal_places": 2,
"display": "USD 412.50"
},
"description": "19, VAT National taxes on accommodation",
"included": true,
"display": "EUR 164.49"
}
],
"trip_item_token": "htl_2d67a7441c60e5de",
"room_rates": [
{
"room_id": "<string>",
"occupancy_number": 2,
"occupancy": {
"adults": 2,
"children_ages": [
8
]
},
"taxes_and_fees": [
{
"amount": 164.49,
"currency": "EUR",
"amount_money": {
"value": 41250,
"currency": "USD",
"decimal_places": 2,
"display": "USD 412.50"
},
"description": "19, VAT National taxes on accommodation",
"included": true,
"display": "EUR 164.49"
}
],
"is_refundable": true,
"room_name": "<string>",
"board_type": "<string>",
"board_name": "<string>",
"max_occupancy": 123,
"policies": [
{
"type": "<string>",
"description": "<string>",
"fee_amount": 123,
"fee_currency": "<string>",
"fee_amount_money": {
"value": 41250,
"currency": "USD",
"decimal_places": 2,
"display": "USD 412.50"
}
}
],
"cancellation_policy": [
{
"cancel_time": "2026-08-18T10:00:00+02:00",
"amount": 606.13,
"currency": "EUR",
"type": "amount",
"display": "EUR 606.13",
"amount_money": {
"value": 41250,
"currency": "USD",
"decimal_places": 2,
"display": "USD 412.50"
},
"percent": 50,
"nights": 1
}
],
"free_cancellation_until": "<string>",
"payment_types": [
"pay_now"
],
"remarks": "<string>"
}
],
"board_type": "RO",
"board_name": "Room Only",
"total_amount_display": "EUR 606.13",
"total_amount_money": {
"value": 41250,
"currency": "USD",
"decimal_places": 2,
"display": "USD 412.50"
},
"free_cancellation_until": "2026-08-18T10:00:00+02:00",
"cancellation_schedule": [
{
"cancel_time": "2026-08-18T10:00:00+02:00",
"amount": 606.13,
"currency": "EUR",
"type": "amount",
"display": "EUR 606.13",
"amount_money": {
"value": 41250,
"currency": "USD",
"decimal_places": 2,
"display": "USD 412.50"
},
"percent": 50,
"nights": 1
}
],
"payment_types": [
"pay_now"
],
"promotions": [
{
"name": "<string>",
"remark": "<string>"
}
]
}
],
"match_score": 87
}
],
"has_more": true,
"reference": true,
"error": {
"code": "<string>",
"message": "<string>"
},
"superseded_by": "<string>",
"charge": {
"turn": 1,
"llm_usd": 0.0165,
"api_usd": 0.0645,
"total_usd": 0.081,
"currency": "USD"
}
}{
"context_id": "ctx_example",
"task_id": "atk_example",
"status": "working",
"message": "Found 37 hotels in Paris for Oct 24–25 (1 night, 2 adults, 1 room).",
"question": "dates",
"criteria": {},
"notes": [
{}
],
"hotels": [
{
"hotel_id": "lp1d2c3",
"hotel_ref": "h1:lp1d2c3",
"name": "Hôtel Le Marais",
"address": "12 Rue de Rivoli",
"city": "Paris",
"country": "fr",
"star_rating": 4,
"category": "4 KEYS",
"lodging_type": "Aparthotel",
"rating": 8.6,
"review_count": 1243,
"main_photo": "https://images.example.com/hotels/main.jpg",
"thumbnail": "https://images.example.com/hotels/thumb.jpg",
"latitude": 48.8566,
"longitude": 2.3522,
"distance_km": 1,
"recommendation_score": 0.5,
"rooms": [
{
"room_id": "rm_1",
"room_name": "Superior Double",
"description": "<string>",
"requested_occupancy": 2,
"room_capacity": 2,
"max_occupancy": 2,
"images": [
"<string>"
],
"amenities": [
"<string>"
],
"beds": [
{
"bed_type": "<string>",
"count": 2
}
],
"rates": [
{
"offer_id": "htl_2d67a7441c60e5de",
"board_type": "RO",
"board_name": "Room Only",
"total_amount": 1818.4,
"total_amount_display": "EUR 606.13",
"currency": "EUR",
"total_amount_money": {
"value": 41250,
"currency": "USD",
"decimal_places": 2,
"display": "USD 412.50"
},
"is_refundable": false,
"free_cancellation_until": "2026-08-18T10:00:00+02:00",
"cancellation_schedule": [
{
"cancel_time": "2026-08-18T10:00:00+02:00",
"amount": 606.13,
"currency": "EUR",
"type": "amount",
"display": "EUR 606.13",
"amount_money": {
"value": 41250,
"currency": "USD",
"decimal_places": 2,
"display": "USD 412.50"
},
"percent": 50,
"nights": 1
}
],
"taxes_breakdown": [
{
"amount": 164.49,
"currency": "EUR",
"amount_money": {
"value": 41250,
"currency": "USD",
"decimal_places": 2,
"display": "USD 412.50"
},
"description": "19, VAT National taxes on accommodation",
"included": true,
"display": "EUR 164.49"
}
],
"payment_types": [
"pay_now"
],
"promotions": [
{
"code": "<string>",
"name": "<string>",
"remark": "<string>"
}
],
"booking_scope": "room_bundle",
"num_rooms": 2,
"rooms": [
{
"occupancy_number": 1,
"occupancy": {
"adults": 2,
"children_ages": [
8
]
},
"room_id": "<string>",
"mapped_room_id": 123,
"room_name": "Superior Double",
"rate_id": "<string>",
"board_type": "BB",
"board_name": "Breakfast Included",
"max_occupancy": 123,
"taxes_and_fees": [
{
"amount": 164.49,
"currency": "EUR",
"amount_money": {
"value": 41250,
"currency": "USD",
"decimal_places": 2,
"display": "USD 412.50"
},
"description": "19, VAT National taxes on accommodation",
"included": true,
"display": "EUR 164.49"
}
],
"policies": [
{
"type": "<string>",
"description": "<string>",
"fee_amount": 123,
"fee_currency": "<string>",
"fee_amount_money": {
"value": 41250,
"currency": "USD",
"decimal_places": 2,
"display": "USD 412.50"
}
}
],
"is_refundable": true,
"cancellation_policy": [
{
"cancel_time": "2026-08-18T10:00:00+02:00",
"amount": 606.13,
"currency": "EUR",
"type": "amount",
"display": "EUR 606.13",
"amount_money": {
"value": 41250,
"currency": "USD",
"decimal_places": 2,
"display": "USD 412.50"
},
"percent": 50,
"nights": 1
}
],
"free_cancellation_until": "<string>",
"payment_types": [
"pay_now"
],
"remarks": "<string>"
}
]
}
]
}
],
"offers": [
{
"offer_id": "htl_2d67a7441c60e5de",
"total_amount": 1818.4,
"currency": "EUR",
"is_refundable": true,
"taxes_breakdown": [
{
"amount": 164.49,
"currency": "EUR",
"amount_money": {
"value": 41250,
"currency": "USD",
"decimal_places": 2,
"display": "USD 412.50"
},
"description": "19, VAT National taxes on accommodation",
"included": true,
"display": "EUR 164.49"
}
],
"trip_item_token": "htl_2d67a7441c60e5de",
"room_rates": [
{
"room_id": "<string>",
"occupancy_number": 2,
"occupancy": {
"adults": 2,
"children_ages": [
8
]
},
"taxes_and_fees": [
{
"amount": 164.49,
"currency": "EUR",
"amount_money": {
"value": 41250,
"currency": "USD",
"decimal_places": 2,
"display": "USD 412.50"
},
"description": "19, VAT National taxes on accommodation",
"included": true,
"display": "EUR 164.49"
}
],
"is_refundable": true,
"room_name": "<string>",
"board_type": "<string>",
"board_name": "<string>",
"max_occupancy": 123,
"policies": [
{
"type": "<string>",
"description": "<string>",
"fee_amount": 123,
"fee_currency": "<string>",
"fee_amount_money": {
"value": 41250,
"currency": "USD",
"decimal_places": 2,
"display": "USD 412.50"
}
}
],
"cancellation_policy": [
{
"cancel_time": "2026-08-18T10:00:00+02:00",
"amount": 606.13,
"currency": "EUR",
"type": "amount",
"display": "EUR 606.13",
"amount_money": {
"value": 41250,
"currency": "USD",
"decimal_places": 2,
"display": "USD 412.50"
},
"percent": 50,
"nights": 1
}
],
"free_cancellation_until": "<string>",
"payment_types": [
"pay_now"
],
"remarks": "<string>"
}
],
"board_type": "RO",
"board_name": "Room Only",
"total_amount_display": "EUR 606.13",
"total_amount_money": {
"value": 41250,
"currency": "USD",
"decimal_places": 2,
"display": "USD 412.50"
},
"free_cancellation_until": "2026-08-18T10:00:00+02:00",
"cancellation_schedule": [
{
"cancel_time": "2026-08-18T10:00:00+02:00",
"amount": 606.13,
"currency": "EUR",
"type": "amount",
"display": "EUR 606.13",
"amount_money": {
"value": 41250,
"currency": "USD",
"decimal_places": 2,
"display": "USD 412.50"
},
"percent": 50,
"nights": 1
}
],
"payment_types": [
"pay_now"
],
"promotions": [
{
"name": "<string>",
"remark": "<string>"
}
]
}
],
"match_score": 87
}
],
"has_more": true,
"reference": true,
"error": {
"code": "<string>",
"message": "<string>"
},
"superseded_by": "<string>",
"charge": {
"turn": 1,
"llm_usd": 0.0165,
"api_usd": 0.0645,
"total_usd": 0.081,
"currency": "USD"
}
}{
"error": {
"code": "BAD_REQUEST",
"message": "Malformed JSON in request body"
}
}{
"error": {
"code": "AUTH_REQUIRED",
"message": "Invalid or expired API key.",
"doc_url": "https://docs.gojinko.com/authentication/api-keys"
}
}{
"error": {
"code": "PAYMENT_REQUIRED",
"message": "Insufficient balance — a hotel AI search turn needs at least $0.20 and your organization has $0.0500 available. Top up at https://dashboard.gojinko.com/developers/billing/topup"
}
}{
"error": {
"code": "FORBIDDEN",
"message": "This API key is not granted the \"search_live\" scope required by this endpoint"
}
}{
"error": {
"code": "NOT_FOUND",
"message": "Resource not found.",
"doc_url": "https://docs.gojinko.com/concepts/errors"
}
}{
"error": {
"code": "GONE",
"message": "The resource no longer exists.",
"doc_url": "https://docs.gojinko.com/concepts/errors"
}
}{
"error": {
"code": "BAD_REQUEST",
"message": "A required field is missing or invalid.",
"doc_url": "https://docs.gojinko.com/concepts/errors"
}
}{
"error": {
"code": "RATE_LIMITED",
"message": "Too many requests. Retry after the Retry-After delay.",
"doc_url": "https://docs.gojinko.com/concepts/errors"
}
}{
"error": {
"code": "UPSTREAM_REJECTED",
"message": "The request was declined for this offer. Try another offer.",
"doc_url": "https://docs.gojinko.com/concepts/errors"
}
}{
"error": {
"code": "UPSTREAM_UNAVAILABLE",
"message": "The service is temporarily unavailable. Retry after the Retry-After delay.",
"doc_url": "https://docs.gojinko.com/concepts/errors"
}
}{
"error": {
"code": "UPSTREAM_TIMEOUT",
"message": "The request timed out before a result was available. Retry the request.",
"doc_url": "https://docs.gojinko.com/concepts/errors"
}
}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.
New to hotel AI search? The Hotel AI search guide walks through the whole flow: the first call, the questions it asks, follow-ups,
202 and streaming, and booking a result.Authorizations
ApiKeyAuthBearerAuth
Headers
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.
Required string length:
1 - 200wait=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.
Maximum string length:
200Example:
"wait=0"
Body
application/json
The traveller's request in one sentence, or the answer to the question asked in the previous turn.
Required string length:
1 - 2000Example:
"A hotel in Paris next weekend for 2 adults with breakfast included"
The traveller's IANA time zone. Relative dates such as "next weekend" or "tonight" are computed in it.
Example:
"Europe/Paris"
The conversation to continue, from an earlier answer. Omit to start a new conversation.
Required string length:
1 - 100Example:
"ctx_example"
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.
Required string length:
1 - 100Example:
"atk_example"
Currency of the prices (ISO 4217).
Pattern:
^[A-Za-z]{3}$Example:
"EUR"
Nationality of the guests (ISO 3166-1 alpha-2).
Pattern:
^[A-Za-z]{2}$Example:
"FR"
How much the search may do before it answers. low answers soonest; high checks the most and searches the most options. Defaults to medium.
Available options:
low, medium, high Example:
"medium"
Response
The task ended this turn; or, with Accept: text/event-stream, the turn as it happens.
The conversation; send it with the next message to continue.
Example:
"ctx_example"
Example:
"atk_example"
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.
Available options:
working, input_required, completed, failed, canceled The reply to show the traveller.
Example:
"Found 37 hotels in Paris for Oct 24–25 (1 night, 2 adults, 1 room)."
What the reply asks for, when status is input_required.
Example:
"dates"
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.
Show child attributes
Show child attributes
Assumptions and adjustments made while understanding the request.
Show child attributes
Show child attributes
Show child attributes
Show child attributes
More hotels are available; ask for more in the same conversation.
The hotels are a 1-night reference search shown while the check-out date is asked.
Why the task failed, when status is failed.
Show child attributes
Show child attributes
The task that replaced this one, when status is canceled.
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}.
Show child attributes
Show child attributes