Koko

Manually re-pull Google ratings/reviews/hours + photos on an EXISTING Koko list or plan. This happens automatically on send_to_koko, so ONLY call it when the user explicitly asks to refresh an existing list. confirm=false estimates the cost; confirm=true spends and starts the refresh in the background (it returns at once; the data lands over a minute or two).

refresh_details

Save what you just made to the user's Koko account — a LIST or a PLAN, decided automatically from the shape. A PLAN has a schedule (stops with times grouped into days) → pass `days`. A LIST is just places in rank order → pass `places`. Pass EXACTLY ONE. region = 'City, Country'. Whenever the plan includes FREE TIME (a break, downtime, 'explore on your own'), encode that stop as a free-time block ({free_time: true, duration_min, neighborhood?}) — never as a place. Any SIDE NOTE the user gives about a particular stop ('Thursdays only', 'book the counter seat') goes in that stop's `note` — it is kept per-stop and shown on the stop itself, and is a different field from `reason`, which is the one-line pitch on the card. Geocoding is free; ratings/photos fill in afterward. Returns a quick ack + a view link.

send_to_koko

Set the signed-in user's default transport for new plans.

update_koko_settings

Update an EXISTING Koko list or plan — a FULL REPLACE of its contents from the edited structure you got from get_koko. Pass the WHOLE new version, not a diff: stops you omit are removed, new ones are added, and the order/notes/durations you send win. The list's link and id stay the same; unchanged places keep their pins & photos (only new names are geocoded). TO CORRECT A WRONG PIN, send that stop a more specific `query` (exact name + ward/neighbourhood + city + country): a query that differs from the one the stop was resolved with re-geocodes it, and the old pin is kept only if nothing better is found. Changing `name` or `reason` does NOT move a pin. Drop the `resolved` block or send it back untouched — it is ignored either way. Pass `places` for a list or `days` for a plan (match the kind from get_koko). Keep free-time blocks as {free_time: true, duration_min, neighborhood?} stops — and a JOURNEY (a flight, a train leg) as the one get_koko gave you, transport_mode and its transport_start/transport_end/transport_note intact: drop those and the leg comes back as anonymous downtime. KEEP EACH STOP'S `note` — this call re-creates every stop, so a note you drop from the payload is deleted from the list. Send back the `note` get_koko gave you (edited if the user asked), and add one to any stop they just told you something about. title/region/description/start_date/day_start are optional — omitted ones keep their current values. A plan stop can carry `travel` — the transport into it from the stop before. SEND IT WHENEVER YOU KNOW BETTER THAN A HEURISTIC: our estimate has no timetable and no geo for JR or any private railway, so it mis-routes real journeys and will sometimes choose a car over an obvious train. A `travel` you send is used as given and survives every later edit; get_koko marks those legs `source: "you"`. The expected input is the structure get_koko returns for this job_id with the edits applied, so that the replacement is built from the current version. ATOMIC, AND ASYNCHRONOUS WHEN BIG: the payload is validated first (an error changes nothing), and the new version is built off to the side and swapped in whole. A rebuild that takes more than ~20 s (a long trip, many new places) answers that it is still rebuilding: poll check_koko_status with this job_id until it says the update is in, and send nothing else to this job meanwhile.

update_koko

Identify the authenticated Koko account: returns JSON with username (stable), email, name, username, is_operator, auto_publish_as and creator_handle. No arguments. Call it to confirm which account this connection acts on — e.g. before a send, or when the user asks who they are logged in as. koko_account is the same information as prose.

whoami

Who the connected Koko account is: display name, username, email, whether it is an operator account, the creator storefront it publishes to (if any), how many lists and plans it holds, and — critically — whether sends AUTO-PUBLISH to the public Discover shelf. Call this when the user asks who they are logged in as, when a send is about to go somewhere public, or when anything about the account is ambiguous. Returns only the caller's own account.

koko_account