GOgojinko
Discovery

Search flights from one sentence, with follow-ups

Send the traveller's request in one sentence. The answer comes within about 20 seconds with 200: the options, 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.

Every option is priced live and carries fares: book one by adding its trip_item_token with POST /v1/trip add_item before its expires_at. The JSON answer of an ended turn carries its charge; the event stream does not.

post/v1/flight_ai_search

Request

  • Base URL
    https://api.gojinko.com
  • URL
    https://api.gojinko.com/v1/flight_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).

timezonestring required

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

Example request

{
  "text": "Paris to Tokyo 3–17 October 2027 for 4, at most one stop",
  "context_id": "ctx_example",
  "task_id": "atk_example",
  "currency": "EUR",
  "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 options are in the answer. failed: see error. canceled: a later message or a cancel replaced it.

messagestring

The reply to show the traveller, in English.

question'origin' | 'which_place' | 'dates' | 'passengers' | 'group_too_large' | 'contradiction' | 'out_of_scope'

What the reply asks for, when status is input_required.

criteriaobject

The search the request was understood as: trip_type, origins, destinations, departure, return, passengers, priority (only when the request says how to rank the options), currency, and the filters, in the flight_search field names. Each place of origins and destinations has code, type, name and country_code; code is null for a country, a region or a kind of trip, whose airports searched are on each option's legs.

has_moreboolean

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

superseded_bystring

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

Example response

{
  "context_id": "ctx_example",
  "task_id": "atk_example",
  "message": "Three round-trip options Paris–Tokyo, 3–17 Oct 2027, for 4 adults with at most one stop.",
  "question_options": [
    {
      "value": "SJO",
      "label": "San José, Costa Rica",
      "detail": "1 airport"
    }
  ],
  "notes": [
    {
      "kind": "passengers_assumed_adults"
    }
  ],
  "options": [
    {
      "option_id": "s1_1",
      "legs": [
        {
          "index": 1,
          "origin": {
            "code": "PAR",
            "name": "Paris",
            "airport": "CDG"
          },
          "destination": {
            "code": "PAR",
            "name": "Paris",
            "airport": "CDG"
          },
          "departure": "2027-10-03T10:20:00",
          "arrival": "2027-10-03T10:20:00",
          "duration_minutes": 975,
          "stops": 1,
          "segments": [
            {
              "marketing_carrier": "AF",
              "operating_carrier": "KL",
              "flight_number": "AF1240",
              "origin": "CDG",
              "destination": "AMS",
              "departure": "2027-10-03T10:20:00",
              "arrival": "2027-10-03T10:20:00",
              "duration_minutes": 80,
              "layover_minutes": 140
            }
          ]
        }
      ],
      "fares": [
        {
          "trip_item_token": "offer_7f3a9c21_1b2c3d4e:trip_item_0",
          "brand_name": "Economy Light",
          "cabin_class": "economy",
          "total": {
            "amount": 3412,
            "currency": "EUR"
          },
          "price_per_person": {
            "amount": 3412,
            "currency": "EUR"
          },
          "priced_for": {
            "adults": 4
          },
          "expires_at": "2026-10-27T10:58:12Z",
          "carry_on_baggage": "1 × 12 kg",
          "included_baggage": "1 × 23 kg"
        }
      ],
      "score": 100,
      "why": "Cheapest total for 4; one stop each way in Amsterdam."
    }
  ],
  "groups": [
    {
      "group_id": "g_1",
      "route": {
        "origin": "PAR",
        "destination": "TYO"
      },
      "dates": {
        "departure": "2027-10-03",
        "return": "2027-10-03"
      }
    }
  ],
  "charge": {
    "turn": 1,
    "llm_usd": 0.0195,
    "api_usd": 0.01,
    "total_usd": 0.0295
  }
}

Changes

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