# Roamline > Trip planner at https://roamline.lbyte.app. An agent holding the traveler's personal access token can read and edit their trips: places, dates, route order, alternative routes, notes, links and comments. What it saves shows up in the traveler's planner at https://roamline.lbyte.app/app the next time a page loads. All endpoints are JSON under https://roamline.lbyte.app/api. Request and response fields are camelCase. Ids are opaque strings: take them from responses, never guess them. ## Auth - Every call needs the traveler's token: `Authorization: Bearer rl_...` (`rl_` plus 43 characters). Only the header counts; cookies are ignored when it is present. - The traveler creates one at https://roamline.lbyte.app/app/agents, picks how long it lasts (30 or 90 days), and can revoke it there. If you do not have one, ask the traveler for it. Never log, store, or repeat the token. - A token acts as the traveler, so do only what the traveler asked for, and ask before deleting anything. - A malformed, revoked, or expired token is 401 `unauthenticated`. Retrying will not help: ask the traveler for a new token. - These answer 403 `session-required` to any token; the traveler does them in the app: - managing tokens - inviting companions - creating or editing share links (revoking one works with a token) - `GET /api/me` confirms the token works and returns `{id, email, displayName}`. ## What Roamline stores Travel the traveler authored: trip names, places, dates, route order, alternative routes, availability, votes, notes, links. A trip has no fields for prices, schedules, accommodation, weather, visa rules or coordinates, and you should not smuggle reference data in as bulk text. Visa rules have their own public directory, apart from trips (see "Visa directory"), what a place is usually like in a month has its own read (see "Usual climate"), and so does how people get around there (see "Getting around"). A short reminder the traveler wants on a stop ("biometrics appointment Nov 25, apply for the visa before then") is a note. A link to the source is a link. ## Planning loop: build a trip 1. `GET /api/trips`: the traveler's named trips, newest edit first. Reuse one when the traveler means an existing trip. 2. `POST /api/trips` with `{"name": "Southeast Asia"}`: 201 with the trip. It starts with one route (a "variant") named `Main`, already selected. 3. `POST /api/trips/{tripId}/stops` with `{"name": "Hanoi"}` once per place: 201 with `{id, name, place}`. A stop is a candidate place in the trip's pool. It is on no route yet and has no dates. To put it on the trip map, first `GET /api/geo/places?q=Hanoi` (towns, regions and countries, each with a `kind` and `placeId`; add the country to tell same-named towns apart, as in `q=Flores Guatemala`), then add `"place": {"kind": "", "id": ""}` to the body. Without `place` the stop still saves and is just not drawn. 4. `GET /api/trips/{tripId}`: the trip with `stops` and `variants`. Read the `Main` variant's `id` and `updatedAt`. 5. `PUT /api/variants/{variantId}/stops`: set the route. The body replaces the whole list; array order is the route order. ```json { "stops": [ { "stopId": "...", "arrivalDate": "2026-12-01", "departureDate": "2026-12-06" }, { "stopId": "...", "arrivalDate": "2026-12-06", "departureDate": "2026-12-12" }, { "stopId": "..." } ], "expectedUpdatedAt": "" } ``` Dates are `YYYY-MM-DD` and optional. A stop can also carry a planned stay with `minNights` and `maxNights` (whole nights, 0 to 999, both or neither; equal for an exact stay, different for a range such as 3 to 5). A stay needs no dates, so a route can be planned by nights before it has a start. When a stop has both dates and a stay, the nights between the dates must fall inside it or the save is 400 `invalid-body`. The body replaces every field: a stop sent without `minNights`/`maxNights` loses its stay. Leave a stop out of the list to drop it from this route; it stays in the pool. Send `expectedUpdatedAt` so you do not overwrite an edit the traveler made meanwhile: 409 `variant-changed` means read the trip again and redo the change. 6. `GET /api/variants/{variantId}/schedule`: nights per stop (`minNights`, `maxNights`), `estimatedArrivalDate`/`estimatedDepartureDate` for a stop with nights and no dates that follows a dated one, or for a stop with an arrival and nights but no departure, `totalNights` and `totalNightsMax`, `lastDate` and `lastDateMax` (the last date if every ranged stay ran to its longest; both count stays with no dates that follow the last dated stop, and a stop dated only by its arrival and nights counts from that estimate), and `issues` (`gap`, `overlap`, `out-of-order`, `invalid-range`, `missing-dates`, each naming the `stopId`). Fix what it reports and save again. Each route also has `legs`, one per pair of neighbouring stops (`id`, `fromStopId`, `toStopId`, `method`). `PATCH /api/legs/{legId}` with `{"method": "train"}` records how the traveler plans to cover a leg: `plane`, `train`, `bus`, `car`, `ferry`, `bike`, `walk`, `other`, or `null` to clear it. It returns the route; `updatedAt` does not change. Record only what the traveler told you; do not look up or guess transport. A leg belongs to its pair of stops, so a reorder makes new legs for new pairs: read the route again after step 5. 7. `POST /api/stops/{stopId}/notes` with `{"body": "..."}` (up to 4000 characters) and `POST /api/stops/{stopId}/links` with `{"url": "https://...", "label": "..."}` for what the traveler should remember at that stop. The same pair exists per route: `/api/variants/{variantId}/notes` and `/links`. A note or a comment may hold `\n` and `\t`; no text field takes a NUL or any other control character, and a carriage return is one (400 `invalid-note`, `invalid-comment`, `invalid-link` or `invalid-body`). 8. Tell the traveler the trip is at `https://roamline.lbyte.app/app/trips/{tripId}`. ## Alternative routes A trip can hold several routes over the same pool of stops, to compare orders or date ranges. - `POST /api/trips/{tripId}/variants` with `{"name": "Wet season first"}`: a new, empty route. Fill it with step 5. - `PATCH /api/variants/{variantId}` with `{"name": "..."}` to rename, or `{"isSelected": true}` to make it the one the traveler is going with. A trip always has exactly one selected route. - `DELETE /api/variants/{variantId}`: 409 `last-route` on the only route. - `GET /api/variants/{variantId}/shift-preview?stopId=...&days=3`: what later dates become if that stop moves by a number of days. Nothing is saved; apply the result with step 5. ## Editing - `PATCH /api/trips/{tripId}` and `PATCH /api/stops/{stopId}` with `{"name": "..."}`. Names are 1 to 120 characters. A stop also takes `"place": {"kind", "id"}` to put it on the map or `"place": null` to take it off; leaving `place` out keeps it. - `DELETE /api/stops/{stopId}`: removes the place from every route of the trip. - `DELETE /api/trips/{tripId}`: owner only. Ask the traveler first. - `POST /api/trips/{tripId}/duplicate`: a full copy named ` (copy)`. Use it before a large rework the traveler may want to undo. - Notes, links and comments: `GET` lists them under the same paths as step 7 (`{notes: [...]}`, `{links: [...]}`, `{comments: [...]}`); `PATCH` and `DELETE` at `/api/notes/{noteId}`, `/api/links/{linkId}`, `/api/comments/{commentId}`. ## A single place, no trip For "add Lisbon in March" with no trip in mind, skip the trip: `POST /api/plan/places`. - `{"name": "Lisbon", "arrivalDate": "2027-03-04", "departureDate": "2027-03-09"}`: a dated place. Roamline groups it with the traveler's other places near those dates. - `{"name": "Patagonia", "roughWindow": {"from": "2027-11", "to": "2028-02"}}`: roughly when, by month. Do not send it together with `arrivalDate`. - `{"name": "Kyoto"}`: someday, no dates. It returns `{stopId, tripId, isSomeday}`. `GET /api/timeline` lists these under `planned` and `someday`, next to `entries`, the traveler's record of where they have actually been. `GET /api/plan/stops` returns `{stops: [...]}`: every stop with a place across the traveler's trips, each with `tripId`, `position` on its trip's route (null off the route) and `place` (`lat`, `lon`). Use it to see the whole plan on one read. ## The traveler's history `GET /api/timeline` `entries` and `GET /api/visited` (countries and regions, with `stats` for stays and nights; add `?year=2026` for one year) are the traveler's private record. Read them when it helps the plan (where they have been, where they are now). Do not add, edit or share history unless the traveler asks: `POST /api/timeline` takes `{"placeName": "...", "arrivedOn": "YYYY-MM-DD", "departedOn": "YYYY-MM-DD"}`. ## Companions and sharing Read-only for a token. Inviting someone or publishing a link gives access that outlives your token, so the traveler does those in the app. - `GET /api/trips/{tripId}/members` lists who is on the trip. - `GET /api/trips/{tripId}/votes` and `GET /api/trips/{tripId}/availability` show how the group rated each route and when everyone is free. - `GET /api/trips/{tripId}/share` shows whether a read-only public link exists (`createdAt` is set, or null), `options`: what it shows besides names (`dates`, `stays`, `methods`, `map`, `otherRoutes`), and `title`: the link's own headline, or null for the trip name. - Share links and invite codes are only shown to a signed-in person. With a token, `token` and `url` are always null on `GET /api/trips/{tripId}/share`, `GET /api/trips/{tripId}/invites`, `GET /api/timeline/share`, `GET /api/status/share`, `GET /api/visited/share` and `GET /api/journeys`; the other fields still say whether sharing is on. If the traveler wants the link, they copy it in the app. - `POST /api/trips/{tripId}/invites`, `POST` and `PATCH /api/trips/{tripId}/share`, `POST` and `PATCH /api/timeline/share`, `POST /api/status/share`, `POST` and `PATCH /api/visited/share`, and `POST /api/journeys` and `PATCH /api/journeys/{journeyId}` are 403 `session-required`. When the traveler wants one, send them to `https://roamline.lbyte.app/app/trips/{tripId}`. ## Usual climate What a stop's place is usually like in each month, so you can tell the traveler what to expect or which month suits better. Long-run averages over the years `source.period` names, never a forecast. Temperatures are for the place's own height where we know it. Do not copy them into notes or trip names. - `GET /api/guide/climate?stopIds={stopId},{stopId}` (up to 50): for each stop, `status` `ready` with twelve `months` (January first: `rainDays`, `heavyRainDays`, `sunnyDays`, `snowDays`, `precipMm` per month; `sunshineH`, `daylightH`, `tempMaxC`, `tempMinC` per day; `wetHours`, `rainPeakHour`, `rainPeakShare` for when rain falls) and a `source` to credit (its `name`, `url` and `period`; it can differ from stop to stop); or `pending` with `retryAfterSeconds` while the place is looked up for the first time (ask again after that wait, not sooner); or `unavailable` with `reason` `no-place` (pick a place for the stop), `area-too-large` (a big region or country: pick a town), `failed` or `not-found`. - `GET /api/guide/places?stopIds={stopId},{stopId}` (up to 50): for each stop, `status` `ready` with `page` (the public destination page for its town, or the nearest region or country that has one: `kind`, `name`, `path` on this site; null when none does) and `nextStops` (up to three cities Nomads.com members logged a trip to next: `name`, `travels`, `path` or null), with `nextStopsSource` to credit whenever you mention them; or `unavailable` with `reason` `no-place` or `not-found`. ## Getting around, tourist season and advisories What travelers and named sources say about a stop's place: which ride-hailing apps work, how people travel and book (taxis by app or phone, motorbike taxis, buses, ferries), which months are peak, shoulder or off season, and the current government travel advisory level for its country. Each claim says where it is true (the town, its region or its country), who says so (a traveler or a named source with its date), whether an admin has verified it, and how many travelers vouched. Never copy claims into notes or trip names. - `GET /api/guide/claims?stopIds={stopId},{stopId}` (up to 50): for each stop, `status` `ready` with `scopes` (the stop's town, region and country, most precise first) and `claims`, or `unavailable` with `reason` `no-place` or `not-found`. Each claim has `facts`, `scope`, `month` (null: all year), `note`, `origin`, `status`, `vouches`, and `mine`. - `facts` is one of `{"topic": "ride-hailing", "app": "Grab", "modes": ["car", "motorbike"]}` (modes: `car`, `motorbike`, `taxi`, `tuk-tuk`) or `{"topic": "transport", "mode": "taxi", "booking": ["app", "phone"]}` (mode: `walk`, `bicycle`, `scooter-rental`, `car-rental`, `taxi`, `motorbike-taxi`, `tuk-tuk`, `bus`, `minibus`, `metro`, `tram`, `train`, `ferry`; booking: `app`, `phone`, `street`, `rank`, or empty). - Tourist season: `{"topic": "season", "peak": [12, 1, 2], "shoulder": [3, 11], "off": [5, 6, 7, 8]}`, month numbers, each month in at most one list, months the source does not cover left out. One claim covers the whole year, so never send `month` with it. - Advisory: `{"topic": "advisory", "issuer": "US", "level": 2, "issuedOn": "YYYY-MM-DD"}`. `issuer` is `US` (travel.state.gov), `CA` (travel.gc.ca) or `AU` (smartraveller.gov.au), `level` 1 to 4 on that government's scale, `issuedOn` the date on the advisory. It is always about a country, and needs `sourceUrl` on the issuer's own site and `observedOn`, the day you read the level there. A level read more than 30 days ago is shown as possibly out of date: file it again after checking. Quote the level and link the advisory; never summarise its safety text. - `POST /api/guide/claims` with `{"stopId": "...", "facts": {...}}` to add what the traveler told you. Add `"level": "region"` or `"country"` when it is true more widely than the town. Without a stop, use `"place": {"kind": "", "id": ""}` from `GET /api/geo/places`. Optional: `month` (1-12), `note` (up to 500 characters, no web addresses), `sourceUrl` (https), `observedOn` (YYYY-MM-DD). It shows to other travelers at once, marked unverified. 201 with the claim. - `GET /api/guide/claims/mine` lists the traveler's own claims with every status; `DELETE /api/guide/claims/{claimId}` withdraws one. Claims are never edited: withdraw and add again. - Only an admin registers a source (`POST /api/guide/sources`, same body as the visa directory's) or files a claim with `sourceId`. Vouching and review need the traveler in person: a token gets 403 there. ## Visa directory A public record of what travelers and named sources say about entering a country on a given passport. It is separate from trips: never copy a claim into a trip, and a visa reminder on a stop is still a note. A claim is one statement with its origin and date. Several claims about the same passport and destination sit side by side, so add what you found even when it disagrees with what is there. Use of this data: it is for the traveler you act for, to plan their own travel. Look up the countries and the passport their plan needs. Do not export the directory, mirror it, or feed it into another product, dataset or service; the Latent Byte terms (https://latentbyte.com/products/roamline/terms, sections 2 and 6) forbid extracting or reusing service data. What may be shared is a link to a page: `https://roamline.lbyte.app/visa/{code}` for a destination, `https://roamline.lbyte.app/visa/passport/{code}` for a passport. Add `?passport=IR&hold=residence:US,visa:SCHENGEN` to open a destination page on the traveler's own documents. Give the traveler the link instead of pasting lists of claims. Reading needs no token: - `GET /api/public/visa/countries/{code}`: official links and every claim about entering that country. Add `?passport=IR` for one passport. - `GET /api/public/visa/passports/{code}`: the destinations with a claim for the traveler's passport. Codes are ISO 3166-1 alpha-2 (`XK` for Kosovo). A claim is `unverified` until an admin verifies it; say so when you quote one, and send the traveler to the official link before they rely on it. Contributing, as the traveler: - `POST /api/visa/claims` with `{"destination": "MX", "passport": "IR", "category": "visa-free"}`: 201 with the claim. `category` is one of `visa-free`, `on-arrival`, `eta`, `e-visa`, `visa-required`, `refused`, or `no-advance-visa` (the source says only that nothing is needed before travel). - Optional: `maxStayDays`, `note` (your own words, up to 500 characters), `sourceUrl` (the official https page behind it), `observedOn` (`YYYY-MM-DD`, only when the traveler crossed that border themselves). - `holding` is a document that changes the answer: `{"kind": "residence", "issuer": "US"}` for a green card, `{"kind": "visa", "issuer": "SCHENGEN"}` for a Schengen visa. `issuer` is a country code or `SCHENGEN`. On a visa, add `"multipleEntry": true` when the destination wants a multiple-entry visa and `"used": true` when it must already have been used; send `false` when the source says it is not needed, and leave them out when it does not say. Leave `passport` out for a claim about that document on any passport; then `holding` is required. - A claim is never edited. `DELETE /api/visa/claims/{claimId}` retracts your own, then post the corrected one. - `POST /api/visa/links` with `{"country": "RS", "kind": "foreign-ministry", "url": "https://...", "label": "Visa regime"}` proposes an official page. `kind` is `immigration`, `e-visa`, `foreign-ministry`, `embassies` or `other`. It appears once an admin verifies it. `DELETE /api/visa/links/{linkId}` retracts your own. - `GET /api/visa/mine`: everything the traveler submitted, with its status. - `GET /api/visa/preferences`: `{passports, holdings}`, the passports (alpha-2 codes, up to 6) and documents the traveler picked on the visa pages (`holdings` like `residence:US`, `visa:SCHENGEN`); empty until they pick. Use it instead of asking again. `PUT` the same shape only when the traveler tells you what they hold. It is private to the traveler: do not repeat it to anyone else. - Vouching for a claim and reviewing claims are 403 `session-required`: a person does those in the app. Claims read from a published list carry that list as their source: - `GET /api/visa/sources` lists the registered sources. Reuse one when the page is already there. - `POST /api/visa/sources` with `{"kind": "page", "name": "...", "url": "https://...", "retrievedOn": "YYYY-MM-DD"}`: admin travelers only (403 `admin-only` otherwise). 201, or 200 with the existing source when the url is already registered. - Then one claim per row of the list (admin travelers only, like the source itself), each with `sourceId` and the list's own wording in `sourceLabel` (up to 80 characters). Take the fact and attribute it; do not copy the page's text into `note`, and skip a site whose terms forbid reuse. - Posting again for the same source, destination, passport and holding replaces the earlier claim. `multipleEntry` and `used` are not part of that key, so a changed condition replaces too. - `note` and `sourceLabel` take no web addresses (`://`, `www.`): 400 `invalid-claim`. A link goes in `sourceUrl`. ## Public destination pages The site has public pages for places, no token needed: https://roamline.lbyte.app/places lists the countries that have one, then `/places///`. A page shows monthly climate averages (a year chart, then the table), getting around and tourist season reports with their sources, travel advisories, a map of where travelers logged going next and coming from as two ranked lists, and for a country or region its logged cities ranked by trips, again with the credit and its link. Pages exist only where we hold a fact, so a URL that is not linked is a 404. Use a page to read reference detail for a place the traveler is planning around. Cite the page URL when you use it. - `GET /api/public/places/map`: every published country, the 5,000 largest published cities (`name`, `region`, `country`, `path`, `lat`, `lon`, `rank`), largest first, and `cityCount`, the total. - `GET /api/public/places/search?q={text}`: up to ten published countries, regions and cities whose name matches, best first, as `results` of `kind` (`country`, `region` or `city`), `name` and `path`; a region also has `country`, a city `region`, `country` and `city` (the map entry with `id`, `lat`, `lon`). Accents and case do not matter. Add the region or country after the name to tell same-named towns apart, as in `q=flores guatemala`. Under two characters or no match: an empty `results`. 120 reads a minute. Use this to find one place rather than reading the map. - `GET /api/public/places/map/tiles/{z}/{x}/{y}` (web mercator tile, `z` 2 to 7): the other published cities in that tile, largest first; at `z` 7 all of them, below it the largest 1,000. Read the tile around a place rather than walking the grid. - `GET /api/public/places/climate?paths={path},{path}` (up to 50 city paths from the map): for each, `status` `ready` with `name`, `region`, `country`, `period`, its own `source` and twelve `months` (the shape of "Usual climate"); `pending` with `retryAfterSeconds`; or `unavailable` with `reason` `not-found`, `failed` or `not-fetched`. Credit each ready city's own `source`; the top-level `source` names the on-demand one. No token is needed, but anonymous callers get 30 reads an hour; with the traveler's token you get 600 and a read looks up to three missing cities (`pending`, ask again after the wait). Pace by the `RateLimit-*` headers and stop on 429. Use these to answer about places the traveler is considering. Copying the dataset, by pages or by the JSON, is not allowed. ## Errors Every error is `{"error": ""}` with a matching status. - 400: the body failed validation (`invalid-body`, `invalid-json`, `invalid-note`, `invalid-url`, `unknown-stop`, `duplicate-stop`, `invalid-claim`, `invalid-link`, `invalid-source`, `invalid-preferences`). - 401 `unauthenticated`: missing, mistyped or revoked token. Ask the traveler for a new one. - 403: the traveler lacks the role (`owner-only`, or `admin-only` for visa sources and sourced claims), or the route is closed to tokens (`session-required`: invites, creating or editing share links, token management, vouching for and reviewing visa claims). - 404 `not-found`: no such thing, or the traveler is not on that trip. The visa directory names what is missing: `claim-not-found`, `link-not-found`, `source-not-found`, `country-not-found` (not an assigned country code). - 409: `variant-changed` (someone saved first; read again), `conflict`, `last-route`, `selected-route`, `link-exists`. - 429 `too-many-claims`: the traveler has 50 unverified visa claims waiting. Stop and tell them.