Docs
Roadbook MCP API
See what is included in Premium
New to this? Use Roadbook in Claude or ChatGPT.
Roadbook exposes a Model Context Protocol(MCP) server so an AI agent can plan and manage trips on a user's behalf. The endpoint speaks JSON-RPC 2.0 over a single route.
Connect Roadbook to Claude
- In Claude, add a custom connector with the URL
https://roadbook.us/mcp. - Select Connect. Roadbook opens and asks you to sign in with your email or your Bluesky account.
- Review the consent screen and select Allow access.
- Ask Claude about your trips. Tool calls need an active premium subscription.
Example prompts:
- "List my Roadbook trips and show the stops on my next one."
- "Add Arches National Park as a stop on my Utah trip."
- "Here is my hotel confirmation email. Add the booking to the right stop on my trip."
- "Add a logbook entry for yesterday's drive from my notes."
Endpoint
POST /mcp accepts a JSON-RPC 2.0 request (or a batch array of up to 50) and dispatches on the methodfield - initialize,tools/list, andtools/call are the ones an MCP client needs. The machine-readable request/response envelope is published as OpenAPI at/openapi.json. Every tool and its input fields are listed under Tools.
Authentication
Every request needs a bearer token in the Authorization header. Two ways to get one:
- OAuth 2.0 - discover the authorization server at/.well-known/oauth-authorization-server(RFC 8414) and the protected-resource metadata at/.well-known/oauth-protected-resource(RFC 9728). Dynamic client registration, PKCE (S256), and the
authorization_codeandrefresh_tokengrants are supported. - Personal token - a signed-in user can mint a long-lived token from their account settings for scripting or local MCP clients that don't support OAuth.
Access
Connecting and listing tools is free. Every tool call needs an active premium subscription. Any authenticated, non-banned Roadbook account can run initialize and tools/list. The premium check runs at tools/call time, not at connection time.
Troubleshooting
- "This tool needs a Roadbook Premium account." Your account is on the free plan. Upgrade at /billing, then retry.
- Claude asks you to connect again. Your access was revoked. Generating or regenerating a personal token in Basecamp settingsrevokes every connected assistant. Reconnect from Claude.
- "This account is suspended." Contact us throughsupport.
- Too many requests. Wait, then retry.
- Disconnect. Remove the connector in Claude. To revoke access for every assistant at once, regenerate your personal token in Basecamp settings.
Tools
30 tools, generated from the server's own tools/list response, so every field below is one a client sees. Each badge says what a tool does to your data, not which plan can call it. The badge comes from the tool's MCP annotations: Read-only never changes data, Writes adds or edits, and Destructive can remove data.
list_tripsRead-only
List trips
List the trips you own, most recently updated first. Returns trips: [{id, name, slug, visibility, startDate, updatedAt}] (startDate can be null) and nextCursor, null on the last page. Up to 50 trips per page by default.
| Field | Type | Required | Notes |
|---|---|---|---|
| limit | integer | Optional | Trips per page, 1 to 100 (default 50) |
| cursor | string | Optional | nextCursor of the previous page. Omit for the first page. |
read_tripRead-only
Read trip
Read one of your trips. Returns trip {id, name, slug, visibility, startDate, endDate, journal {hasBody, published}}; stops in order, each with id, role, nights, placeId, name, city, state, the public place lat/lon (not a private stop coordinate), its lodging records and your own chargingReport; drives, the recorded drives with labels, times, distance, duration and energy but no route or exact points (up to 200); lodgingBookingIssues, each night left unbooked (kind "gap") or booked twice (kind "overlap") between consecutive overnight stops, from booked check-in and check-out dates only; vehicle {make, model, trim, rangeKm, rangeKind} or null; and legs, one per pair of consecutive stops, with legKm (a straight-line estimate, not a route; null without place coordinates) and grade (the stored charger-availability letter, or "not graded"; stored grades expire after 24 hours).
| Field | Type | Required | Notes |
|---|---|---|---|
| tripId | string | Required | Id of one of your trips |
create_tripWrites
Create trip
Create a new private trip you own, with no stops. Returns {id, name, slug}. name is required; startDate and endDate (YYYY-MM-DD) are optional, and a malformed date is rejected. Fails when your garage has no vehicle. Each call creates another trip.
| Field | Type | Required | Notes |
|---|---|---|---|
| name | string | Required | Trip name; must not be blank |
| startDate | string | Optional | First day of the trip as YYYY-MM-DD, e.g. 2026-07-14. Omit for an undated trip. |
| endDate | string | Optional | Last day of the trip as YYYY-MM-DD, e.g. 2026-07-21. Omit for an undated trip. |
search_placesRead-only
Search places
Search real places by name. Returns candidates: [{placeId, name, context, lat, lon, type, url, distanceKm?}]. A place Roadbook stores has its placeId and its public page url (null without a page); a geocoder match not stored yet has placeId and url null. With lat/lng, candidates within radiusKm (default 50) are ranked by distanceKm. type narrows to "settlement", "poi" or an exact type. Without sign-in: stored places only, up to 10, and a query of at least 2 characters.
| Field | Type | Required | Notes |
|---|---|---|---|
| query | string | Required | Place name or query, e.g. "Moab, UT" or "Zion campground" |
| lat | number | Optional | Latitude to rank places near (give with lng) |
| lng | number | Optional | Longitude to rank places near (give with lat) |
| radiusKm | number | Optional | With lat/lng: keep only candidates within this many km (default 50) |
| type | string | Optional | Keep only this kind: "settlement" (city, town, village), "poi" (anything else), or an exact candidate type such as "campground", "national-park", "hotel" |
read_placeRead-only
Read place facts
Read the stored facts for one place by placeId or slug: name, location, categories, a summary and quick facts when a listed source backs them, verified claims (charging, camping, seasonal, events, activities) and the list of sources. Every claim has a sourceUrl and checkedAt, the time it was stored; the quoted passage is not returned. Empty arrays mean no claims are stored. Stored data only: no live availability, no charging reports, no nearby-charger lookup.
| Field | Type | Required | Notes |
|---|---|---|---|
| placeProof | object | Optional | |
| placeId | string | Optional | Internal Place id; include the same candidate placeProof or saved membership. Give this or slug. |
| slug | string | Optional | Public place slug, the last part of a roadbook.us/explore/places/<slug> URL. Give this or placeId. |
searchRead-only
Search place pages
Find Roadbook place pages by name. Returns up to 10 results as {id, title, url}; the id reads the place with fetch. Matches stored place names only, with no geocoder call.
| Field | Type | Required | Notes |
|---|---|---|---|
| query | string | Required | Place name to look for, 2 to 100 characters |
fetchRead-only
Fetch place page
Read one place by an id from search. Returns {id, title, text, url, metadata}: text is the JSON of the place facts, the same object read_place returns, with a sourceUrl and checkedAt on every claim; url is the public Roadbook page, left out when the place has none.
| Field | Type | Required | Notes |
|---|---|---|---|
| placeProof | object | Optional | |
| id | string | Required | Public place URL from search; an internal id needs its candidate placeProof or saved membership |
submit_placeWrites
Submit a place
Queue a place that is missing from search for a human moderator. Creates no live place: returns {submitted: true, submissionId, status: "pending"}. When the place already exists or the same submission is pending, nothing is queued and the match comes back with submitted: false. Fails while you have 10 submissions awaiting moderation.
| Field | Type | Required | Notes |
|---|---|---|---|
| name | string | Required | Place name, max 200 characters |
| type | "campground" | "hotel" | "motel" | "inn" | "rental" | "dispersed" | "park" | "trailhead" | "viewpoint" | "charger" | "restaurant" | "other" | Required | Type of place: campground, hotel, motel, inn, rental, dispersed, park, trailhead, viewpoint, charger, restaurant, other |
| city | string | Required | City, max 120 characters |
| state | string | Required | State or region, max 120 characters |
| address | string | Optional | Street address for the moderator, max 300 characters. Not published as a precise coordinate. |
| notes | string | Optional | Notes for the moderator, max 2000 characters |
create_stopWrites
Create stop
Add a stop to one of your trips by place query, by candidateRef, or by exact lat/lng. A coordinate resolves to the city or neighborhood around it: the trip shows that place and the exact point stays on the private stop. An ambiguous query creates nothing and returns candidates, each with a ref, coordinates, type and, when the trip has stops, distanceKm from the last stop; a ref passed as candidateRef adds that exact place. beforeWaypointId inserts the stop before that top-level stop and is not remembered between calls; without it the stop is appended. The lodging fields record one booking in the same call (lodgingName is required once any is set). Returns {created: true, waypointId, placeName, sortOrder}.
| Field | Type | Required | Notes |
|---|---|---|---|
| tripId | string | Required | Id of one of your trips |
| query | string | Optional | Place name or query. Give this, a candidateRef, or lat/lng. |
| lat | number | Optional | Exact latitude of the stop (give with lng), resolved to its city or neighborhood |
| lng | number | Optional | Exact longitude of the stop (give with lat) |
| label | string | Optional | Private label for a coordinate stop, e.g. "Home" or "Trailhead parking" |
| candidateRef | string | Optional | The ref of a candidate from an earlier ambiguous result, to add that exact place |
| role | "departure" | "stop" | "destination" | Optional | Role of the stop (default stop) |
| beforeWaypointId | string | Optional | Insert before this top-level stop. Omit to append at the end. |
| lodgingName | string | null | Optional | Lodging name, max 200 characters. Required when a stop gets its first lodging record; cannot be cleared. |
| lodgingType | "campground" | "hotel" | "motel" | "inn" | "rental" | "dispersed" | "other" | null | Optional | Type of lodging, one of: campground, hotel, motel, inn, rental, dispersed, other. Null clears it. |
| checkIn | string | null | Optional | Check-in date as YYYY-MM-DD, e.g. 2026-07-14. Null clears it. |
| checkOut | string | null | Optional | Check-out date as YYYY-MM-DD, not earlier than checkIn. Null clears it. |
| cost | number | null | Optional | Total cost of the stay, 0 or more, in the units of currency. Null clears it. |
| currency | string | null | Optional | ISO 4217 currency code for cost, e.g. USD or EUR. Null clears it. |
| reservationRef | string | null | Optional | Booking confirmation or reservation reference, max 200 characters. Null clears it. |
| lodgingNotes | string | null | Optional | Notes about the lodging, max 2000 characters. Null clears it. |
update_stopDestructive
Update stop
Change the role, nights, and/or one lodging record of a stop on your trip. lodgingId names the record; it can be left out when the stop has at most one, and a stop with none gets a new record (lodgingName required). Omitted fields stay as they are; null or an empty string clears a lodging field, except lodgingName. Returns {updated: true}.
| Field | Type | Required | Notes |
|---|---|---|---|
| tripId | string | Required | Id of one of your trips |
| waypointId | string | Required | Id of the stop to change |
| role | "departure" | "stop" | "destination" | Optional | New role of the stop. Omit to leave it unchanged. |
| nights | integer | Optional | Nights at this stop, 0 to 365; 0 makes it a day stop |
| lodgingId | string | Optional | Id of the lodging record to change, from read_trip. Needed when the stop has more than one. |
| lodgingName | string | null | Optional | Lodging name, max 200 characters. Required when a stop gets its first lodging record; cannot be cleared. |
| lodgingType | "campground" | "hotel" | "motel" | "inn" | "rental" | "dispersed" | "other" | null | Optional | Type of lodging, one of: campground, hotel, motel, inn, rental, dispersed, other. Null clears it. |
| checkIn | string | null | Optional | Check-in date as YYYY-MM-DD, e.g. 2026-07-14. Null clears it. |
| checkOut | string | null | Optional | Check-out date as YYYY-MM-DD, not earlier than checkIn. Null clears it. |
| cost | number | null | Optional | Total cost of the stay, 0 or more, in the units of currency. Null clears it. |
| currency | string | null | Optional | ISO 4217 currency code for cost, e.g. USD or EUR. Null clears it. |
| reservationRef | string | null | Optional | Booking confirmation or reservation reference, max 200 characters. Null clears it. |
| lodgingNotes | string | null | Optional | Notes about the lodging, max 2000 characters. Null clears it. |
delete_stopDestructive
Delete stop
Delete one top-level stop from your trip, with its sub-stops, and renumber the remaining stops. Cannot be undone. Returns {removed: true}; fails with "Stop not found on this trip" for an unknown id.
| Field | Type | Required | Notes |
|---|---|---|---|
| tripId | string | Required | Id of one of your trips |
| waypointId | string | Required | Id of the top-level stop to delete |
reorder_stopsDestructive
Reorder stops
Set the order of the top-level stops on your trip. waypointIds lists every top-level stop id exactly once, in the new order; a partial or foreign list is rejected and nothing changes. Returns {reordered: true}.
| Field | Type | Required | Notes |
|---|---|---|---|
| tripId | string | Required | Id of one of your trips |
| waypointIds | string[] | Required | Every top-level stop id of the trip, each exactly once, in the new order |
delete_stop_lodgingDestructive
Delete stop lodging
Delete one lodging record from a stop on your trip. The stop keeps its place, position, nights, charging report and logbook entries. lodgingId can be left out when the stop has exactly one record; a stop with several needs it, and a stop with none reports that there was nothing to remove. Cannot be undone. Returns {removed, lodgingId, remaining}.
| Field | Type | Required | Notes |
|---|---|---|---|
| tripId | string | Required | Id of one of your trips |
| waypointId | string | Required | Id of the stop the lodging record is on |
| lodgingId | string | Optional | Id of the lodging record to delete, from read_trip. Can be left out when the stop has exactly one. |
suggest_stop_candidatesRead-only
Suggest stop candidates
Read up to 3 real places for one leg or one night of your trip, for the person to choose from. kind "leg" looks along the way from afterWaypointId to the next top-level stop; kind "night" looks near afterWaypointId. Each candidate has placeId, name, city, state, category, detourKm (a straight-line estimate, not a route) and charging: a stored fact with its source, or "no charging data". A leg also returns legKm (straight-line estimate) and rangeKm, the trip vehicle's rated range, or null without a vehicle. Returns no coordinates and changes nothing.
| Field | Type | Required | Notes |
|---|---|---|---|
| tripId | string | Required | Id of one of your trips |
| afterWaypointId | string | Required | Top-level stop the leg starts at, or the night is near |
| kind | "leg" | "night" | Required | leg = along the way from this stop to the next one; night = near this stop |
propose_stopWrites
Propose stop
File one pending stop proposal on your trip, after afterWaypointId, for a placeId from suggest_stop_candidates. The trip does not change: the proposal waits in Roadbook's planner, labeled as proposed by your assistant, until the owner accepts or dismisses it there. No tool accepts or dismisses a proposal. Refused when the place is unknown or not ready, already a stop or already pending on the trip, when afterWaypointId is not a top-level stop, or at 10 pending assistant proposals on the trip. reason is shown to the owner.
| Field | Type | Required | Notes |
|---|---|---|---|
| placeProof | object | Optional | |
| tripId | string | Required | Id of one of your trips |
| placeId | string | Required | placeId of the candidate the person picked, as suggest_stop_candidates returns it |
| afterWaypointId | string | Required | Top-level stop the new stop would follow |
| reason | string | Optional | Note shown to the owner on why this stop, max 500 characters |
import_driveDestructive
Import recorded drives
Add 1 to 50 recorded drives (roadbook.drive/1 payloads, as a vehicle connector exports them) to a trip. Without tripId it creates a new private trip; tripId must name one of your private trips. Start and end coordinates resolve to their city or neighborhood. Each drive becomes a departure stop, a destination stop and a drive record (distance, duration, max speed, elevation, energy, route); a drive that starts at the trip's last stop continues from it, which can change that stop's role and nights. A drive already imported (same source.system and source.id) is reported as "exists" and changes nothing. Exact points and the route stay on the private drive record; precision "city" keeps nothing finer than the city. Returns the trip, the stops created, each drive's id and status, and quality notes.
| Field | Type | Required | Notes |
|---|---|---|---|
| tripId | string | Optional | One of your private trips to add the drives to. Omit to create a new private trip. |
| tripName | string | Optional | Name for a new trip (default: "<start city> to <end city>") |
| drives | object[] | Required | 1 to 50 drives, each a roadbook.drive/1 payload exactly as exported |
| precision | "exact" | "city" | Optional | "exact" (default) keeps the precise start and end points and the route on the private drive record; "city" stores nothing finer than the city |
read_logbookRead-only
Read logbook
Read the private logbook of one of your trips. Returns tripId, startDate, coverage and one page of entries, newest first, with nextCursor (null on the last page); startDate and coverage come on the first page only. coverage counts words and characters across all entries: trip totals, per-day averages over the planned span (nights + 1), and overnight stops ranked by words per night, thinnest first; it is a count with no judgement of quality. Each entry has id, entryDate, waypointId, scope, visibility, driveLegId and a body cut to 1000 characters (bodyTruncated is true when cut). With entryId it returns {tripId, entry}: that one entry with its full body.
| Field | Type | Required | Notes |
|---|---|---|---|
| tripId | string | Required | Id of one of your trips |
| entryId | string | Optional | Read only this entry, with its full body |
| limit | integer | Optional | Entries per page, 1 to 50 (default 20) |
| cursor | string | Optional | nextCursor of the previous page. Omit for the first page. |
create_logbook_entriesWrites
Create logbook entries
Add 1 to 50 private dated logbook entries (markdown) to one of your trips. Each entry can tag a stop (waypointId) or an imported drive (driveId, which tags the drive's arrival stop with scope "drive"). Entries are created private. Each entry is validated alone: results lists every entry's outcome, its new id or its error. A created entry echoes the tagged stop's recorded lodging (name, type, charger type) as lodging, to compare with its text; an untagged entry carries a warning that it could not be checked. Marks a published journal stale.
| Field | Type | Required | Notes |
|---|---|---|---|
| tripId | string | Required | Id of one of your trips |
| entries | object[] | Required | 1 to 50 entries to create, in order |
update_logbook_entryDestructive
Update logbook entry
Edit one logbook entry: body, entryDate, scope, and/or its stop tag (waypointId, or null to clear it). Omitted fields stay as they are; visibility does not change. Returns the entry with the tagged stop's recorded lodging as lodging, or a warning when it has no stop tag. Marks a published journal stale.
| Field | Type | Required | Notes |
|---|---|---|---|
| tripId | string | Required | Id of one of your trips |
| entryId | string | Required | Id of the entry to change |
| body | string | Optional | Entry text in markdown, max 10,000 characters |
| entryDate | string | Optional | Entry date as YYYY-MM-DD |
| waypointId | string | null | Optional | Stop to tag the entry to, or null to clear the tag. Omit to leave the tag unchanged. |
| scope | "stay" | "drive" | Optional | stay (default) = about the time at the tagged stop; drive = about the leg that arrived at it (needs a stop tag; the first stop has no inbound drive) |
delete_logbook_entryDestructive
Delete logbook entry
Delete one logbook entry from your trip. Cannot be undone. Returns {deleted: true}, or fails with "Entry not found on this trip". Marks a published journal stale.
| Field | Type | Required | Notes |
|---|---|---|---|
| tripId | string | Required | Id of one of your trips |
| entryId | string | Required | Id of the entry to delete |
set_logbook_entry_visibilityDestructive
Set logbook entry visibility
Make one logbook entry public or private. A public entry is shown publicly only while its trip is public; tripVisibility in the result is the trip's current visibility. Returns {id, visibility, tripVisibility}. Marks a published journal stale.
| Field | Type | Required | Notes |
|---|---|---|---|
| tripId | string | Required | Id of one of your trips |
| entryId | string | Required | Id of the entry |
| visibility | "private" | "public" | Required | public = shown publicly while the trip is public; private = only you see it |
read_journalRead-only
Read journal
Read the public trip journal of one of your trips, which is separate from the private logbook. Returns body (live), draftBody (the private pending draft), publishedAt, lastPublishedAt (set on every publish, kept on unpublish, null if never published), source, style, stale (the logbook changed since the last publish) and changedEntryCount (entries created or edited since lastPublishedAt; deletions are not counted, so stale is the reliable change signal).
| Field | Type | Required | Notes |
|---|---|---|---|
| tripId | string | Required | Id of one of your trips |
update_journal_draftDestructive
Update journal draft
Replace the private draft of the public trip journal (markdown). The live body and the publish state do not change, even on a published journal. Each call replaces the whole draft. Returns the journal state.
| Field | Type | Required | Notes |
|---|---|---|---|
| tripId | string | Required | Id of one of your trips |
| body | string | Required | The whole draft in markdown, max 10,000 characters. Replaces the previous draft. |
set_journal_publishedDestructive
Set journal published
Publish or unpublish the public trip journal. published true makes the pending draft the live public body, sets publishedAt and lastPublishedAt, clears the draft and the stale flag, and records the source as an AI assistant; it fails when there is no draft. published false clears publishedAt only; the body, the draft and lastPublishedAt stay. Returns the journal state.
| Field | Type | Required | Notes |
|---|---|---|---|
| tripId | string | Required | Id of one of your trips |
| published | boolean | Required | true publishes the pending draft as the live body; false takes the journal offline |
read_trip_itineraryRead-only
Read trip itinerary
Read the day-view itinerary of one of your trips: each top-level stop's name, city, state, nights, dates and canAddItems, with its items by day. waypointId reads one stop, a sub-stop included; fromWaypointId and toWaypointId (both inclusive) narrow to a range; upcomingOnly keeps stops not yet arrived at. An unknown stop id fails with "Stop not found on this trip"; upcomingOnly with no upcoming stop returns stops: [] and itemCount: 0. Without a trip startDate no dates are derived and upcomingBasis is "no-start-date". The arrived/upcoming boundary uses the server's UTC day.
| Field | Type | Required | Notes |
|---|---|---|---|
| tripId | string | Required | Id of one of your trips |
| waypointId | string | Optional | Read only this stop |
| fromWaypointId | string | Optional | First stop of the range, inclusive. Omit to start at the first stop. |
| toWaypointId | string | Optional | Last stop of the range, inclusive. Omit to run through the last stop. |
| upcomingOnly | boolean | Optional | Keep only stops not yet arrived at (default false) |
create_itinerary_itemWrites
Create itinerary item
Add a day-view item (activity, dining, sightseeing, note, and more) to a stop with at least one night. Takes no coordinates. An invalid dayOffset, type or title is rejected with the app's own validation message. Returns the created item.
| Field | Type | Required | Notes |
|---|---|---|---|
| tripId | string | Required | Id of one of your trips |
| waypointId | string | Required | Stop to add the item to; it needs at least one night |
| dayOffset | integer | Required | Day of the stay, counted from arrival: 0 to 365 |
| type | "sightseeing" | "dining" | "activity" | "lodging" | "charging" | "transit" | "other" | Required | Item type: sightseeing, dining, activity, lodging, charging, transit, other |
| title | string | Required | Short title for the item |
| description | string | null | Optional | Longer description |
| timeOfDay | string | null | Optional | Free-form time, e.g. "9:00am" or "morning" |
| url | string | null | Optional | Link, e.g. a listing or reservation page |
update_itinerary_itemDestructive
Update itinerary item
Edit a day-view item: title, description, url, timeOfDay, type and/or dayOffset; omitted fields stay as they are and null clears description, url or timeOfDay. toWaypointId moves the item to another stop with at least one night on the same trip, at the end of its day: the moved item gets a new id, previousItemId is the old one, and its approval status and author are kept. Returns {moved, item, previousItemId}. An empty change is rejected.
| Field | Type | Required | Notes |
|---|---|---|---|
| tripId | string | Required | Id of one of your trips |
| itemId | string | Required | Id of the item to change |
| toWaypointId | string | Optional | Move the item to this stop on the same trip; it needs at least one night |
| title | string | Optional | Short title for the item |
| description | string | null | Optional | Longer description, or null to clear it |
| url | string | null | Optional | Link, or null to clear it |
| timeOfDay | string | null | Optional | Free-form time, or null to clear it |
| type | "sightseeing" | "dining" | "activity" | "lodging" | "charging" | "transit" | "other" | Optional | Item type: sightseeing, dining, activity, lodging, charging, transit, other |
| dayOffset | integer | Optional | Day of the stay, counted from arrival: 0 to 365 |
delete_itinerary_itemDestructive
Delete itinerary item
Delete one day-view item from your trip. Its stop must have at least one night. Cannot be undone. Returns {deleted: true}.
| Field | Type | Required | Notes |
|---|---|---|---|
| tripId | string | Required | Id of one of your trips |
| itemId | string | Required | Id of the item to delete |
request_stop_photo_uploadWrites
Request stop photo upload
Step 1 of 2 to attach a photo to a stop on your trip. Returns {uploadId, uploadUrl, method, expiresIn, maxSizeBytes}: a one-time URL valid for 15 minutes. Finishing needs a client that can send an HTTP PUT of the raw image bytes (jpeg, png, webp or heic, up to 10 MB) to uploadUrl with a matching Content-Type header, for example Claude Code; image data does not go through a tool call. The stored photo has its embedded date and location metadata stripped.
| Field | Type | Required | Notes |
|---|---|---|---|
| tripId | string | Required | Id of one of your trips |
| waypointId | string | Required | Stop the photo belongs to |
finalize_stop_photo_uploadWrites
Finalize stop photo upload
Step 2 of 2: attach the image sent by HTTP PUT to the uploadUrl of step 1 to the stop. The photo is converted to WebP and stripped of metadata, as in the app; an image over 10 MB decoded, an unknown image type, or a caption over 280 characters is rejected. uploadId expires 15 minutes after step 1 and works once. caption is text the caller writes; the server generates none. Returns {photo}.
| Field | Type | Required | Notes |
|---|---|---|---|
| tripId | string | Required | Id of one of your trips |
| waypointId | string | Required | Stop the photo belongs to, the same as in step 1 |
| uploadId | string | Required | uploadId returned by step 1 |
| caption | string | null | Optional | Caption, up to 280 characters, written by the caller from the photo. It is also the photo alt text. |
Agent2Agent (A2A)
POST /a2a serves the same tools as skills over the A2A protocol, version 1.0, JSON-RPC binding. The agent card is at/.well-known/agent-card.json. Send the headerA2A-Version: 1.0.
- Calling a skill - send
SendMessagewith one data part shaped{"skill": "<skill id>", "arguments": {...}}. The skill id is a tool name from Tools, and the arguments are that tool's input fields. The skill runs before the answer, so the answer is a finished task:TASK_STATE_COMPLETEDwith the tool's result as one artifact, orTASK_STATE_FAILEDwith the error text instatus.message. - Tasks -
GetTaskandListTasksreturn your own tasks for 7 days.CancelTaskanswers-32002, because every task is already finished. Streaming and push notifications are not supported. - Authentication - the same bearer token as
/mcp. When you get a token with OAuth, sendresource=https://roadbook.us/mcpon the authorization request. The token is issued for the MCP URL and both endpoints accept it. A request with another resource, or none, is refused withinvalid_target. - Errors - a skill that fails (not found, not yours, rejected arguments) answers a
TASK_STATE_FAILEDtask. A missing sign-in or plan answers a JSON-RPC error with code-32000and the reasonUNAUTHENTICATEDorPERMISSION_DENIED. Over the request rate limit, the answer is HTTP 429 withRetry-Afterand a JSON-RPC error with code-32000and the reasonRESOURCE_EXHAUSTED. A call stopped by a per-tool limit or the daily lookup limit answers aTASK_STATE_FAILEDtask that is not stored.
Add a booking to your trip from an email
Your booking confirmation stays in your email. Your own assistant, such as Claude, reads it. Roadbook does not read email. Roadbook keeps the trip: its stops, dates and charging details. It shows you any night left unbooked, or booked at both of two stops in a row, when both stops have booked dates. You decide what to change.
The example uses an invented email: "Sample Inn (synthetic). Your stay is confirmed. Inn. Reference REF-000000. Check-in 2026-11-07. Check-out 2026-11-09. 2 nights." The samples below are shortened to the fields this example uses.
- Connect your assistant to Roadbook (see Authentication). Tool calls need an active premium subscription.
- Give your assistant the email text. Tell it which trip and which stop the stay belongs to.
- Your assistant can call
list_tripsto get your trips and their ids. Tell it which trip if two share a name.{ "trips": [ { "id": "trip-4132", "name": "Autumn cabin trip", "startDate": "2026-11-04" } ] } - It calls
read_tripwith that trip'sidto find the stop'sid. - If that stop already has lodging, tell your assistant whether to change it.
update_stopedits the stop's latest booking. It does not add a second one. This example uses a stop with no lodging yet. - It calls
update_stopwith the lodging name, type, check-in date, check-out date and reservation reference from the email.
Roadbook answers:{ "tripId": "trip-4132", "waypointId": "wp-4132-b", "lodgingName": "Sample Inn (synthetic)", "lodgingType": "inn", "checkIn": "2026-11-07", "checkOut": "2026-11-09", "reservationRef": "REF-000000" }{ "updated": true } - It calls
read_tripagain. - You review the stop and the
lodgingBookingIssueslist. Agapis a night between two consecutive overnight stops that both have booked dates, with no booking covering it. Anoverlapis a night booked at both of two consecutive overnight stops. A stop without dates is not checked. Here, the night of 2026-11-06 has no booking. Roadbook changes nothing for you. Tell your assistant what to change, or edit the trip yourself.{ "stops": [ { "id": "wp-4132-a", "name": "Death Valley National Park", "lodging": [ { "lodgingName": "Sample Motel (synthetic)", "checkIn": "2026-11-04", "checkOut": "2026-11-06" } ] }, { "id": "wp-4132-b", "name": "Gateway Arch National Park", "lodging": [ { "lodgingName": "Sample Inn (synthetic)", "lodgingType": "inn", "checkIn": "2026-11-07", "checkOut": "2026-11-09", "reservationRef": "REF-000000" } ] } ], "lodgingBookingIssues": [ { "kind": "gap", "previousStopName": "Death Valley National Park", "nextStopName": "Gateway Arch National Park", "firstNight": "2026-11-06", "lastNight": "2026-11-06" } ] }