# Add Day Note
Source: https://docs.stardrift.ai/api-reference/mcp-server/add-day-note
/openapi.json post /v1/trips/{trip_id}/days/{day_number}/notes
# Add Event To Trip
Source: https://docs.stardrift.ai/api-reference/mcp-server/add-event-to-trip
/openapi.json post /v1/trips/{trip_id}/events
Record something scheduled that isn't a booking — a wedding, a concert.
add_place_to_guide would make it an attraction, which is what a place the
user might visit is, not something happening at a time they are expected at.
An event carries its own start and end, and its venue is geocoded to a pin
when one resolves. This is the same `add_event` the in-app Add-event flow
calls; only the authentication differs.
# Add Place
Source: https://docs.stardrift.ai/api-reference/mcp-server/add-place
/openapi.json post /v1/trips/{trip_id}/places
# Add Search Result
Source: https://docs.stardrift.ai/api-reference/mcp-server/add-search-result
/openapi.json post /v1/trips/{trip_id}/search-results
# Add Stay To Trip
Source: https://docs.stardrift.ai/api-reference/mcp-server/add-stay-to-trip
/openapi.json post /v1/trips/{trip_id}/stays
Record a booked stay — it lands in Bookings, not as a place card.
A hotel added through add_place_to_guide becomes an attraction: no dates, no
confirmation number, and it never appears alongside the flights and other
reservations. This is the same `add_stay` the in-app Add-stay flow calls, so
the stay is geocoded, canonical-stamped, date-synced and enqueued for
enrichment identically — only the authentication differs.
# Create Trip
Source: https://docs.stardrift.ai/api-reference/mcp-server/create-trip
/openapi.json post /v1/trips
Create a new draft trip with `num_days` blank days, ready for
add_place/add_day_note.
Mirrors the in-app create path: a Trip plus its primary conversation link, then an empty
plan. Returns the trip summary, including the new trip_id.
# Get Forwarding Address
Source: https://docs.stardrift.ai/api-reference/mcp-server/get-forwarding-address
/openapi.json get /v1/forwarding-address
The user's private forward-to address, minted on first request.
Session-or-token so the web/mobile connections screens and the MCP share
one route. Read scope suffices even though the first call writes: the
token is the user's own credential, not booking data.
# Get Plan
Source: https://docs.stardrift.ai/api-reference/mcp-server/get-plan
/openapi.json get /v1/trips/{trip_id}/plan
# Get Search Results
Source: https://docs.stardrift.ai/api-reference/mcp-server/get-search-results
/openapi.json get /v1/search/{search_id}
# Import Social Post
Source: https://docs.stardrift.ai/api-reference/mcp-server/import-social-post
/openapi.json post /v1/saved/import
Import an Instagram post/reel or TikTok video into a new saved list.
The same import the iOS share extension starts; the share extension's own
route takes only its `saved:import` token, which OAuth clients never hold.
# List Bookings
Source: https://docs.stardrift.ai/api-reference/mcp-server/list-bookings
/openapi.json get /v1/bookings
The user's bookings — imported from email (Gmail scan, forwarded
confirmations, in-chat paste) and sold first-party — in the exact shape
the in-app Bookings page renders, so a flight comes back with its
card_data and its editable ExtractedFlight.
# List Trips
Source: https://docs.stardrift.ai/api-reference/mcp-server/list-trips
/openapi.json get /v1/trips
# Move Entry
Source: https://docs.stardrift.ai/api-reference/mcp-server/move-entry
/openapi.json post /v1/trips/{trip_id}/days/{day_number}/entries/{entry_id}/move
Move a place or note without resolving its place again.
# Publish Trip
Source: https://docs.stardrift.ai/api-reference/mcp-server/publish-trip
/openapi.json post /v1/trips/{trip_id}/publish
# Remove Entry
Source: https://docs.stardrift.ai/api-reference/mcp-server/remove-entry
/openapi.json delete /v1/trips/{trip_id}/days/{day_number}/entries/{entry_id}
Remove one entry from a day — the inverse of add_place / add_day_note.
The removal is `apply_plan_actions` + `RemoveEntryAction` — the same pair
the LLM edit path uses (`plan/edit_subagent.py`, `stream_processing.py`),
rather than a second implementation of "filter the day's entries". Note the
web does NOT go through this: it removes client-side in
`lib/plan-mutations.ts` and PUTs the whole plan. What the two share is
`EditablePlan.save`, which mirrors that PUT's validate-then-save.
Nothing else is needed here: `item_refs` is a read-time derived index that
`PlanRepository.assemble_content` reconstitutes as `[]` on every load.
RemoveEntryAction filters, so removing an entry that isn't there succeeds
silently — that would report a deletion which never happened, so a missing
entry_id 404s instead.
The itinerary activity is deliberately left in place: another day may
reference it, and an orphaned activity is invisible rather than wrong.
# Remove Search Result
Source: https://docs.stardrift.ai/api-reference/mcp-server/remove-search-result
/openapi.json delete /v1/trips/{trip_id}/search-results/{item_id}
# Remove Stay From Trip
Source: https://docs.stardrift.ai/api-reference/mcp-server/remove-stay-from-trip
/openapi.json delete /v1/trips/{trip_id}/stays/{stay_id}
Drop a booking from the trip.
# Search Flights
Source: https://docs.stardrift.ai/api-reference/mcp-server/search-flights
/openapi.json post /v1/search/flights
# Search Hotels
Source: https://docs.stardrift.ai/api-reference/mcp-server/search-hotels
/openapi.json post /v1/search/hotels
# Update Entry
Source: https://docs.stardrift.ai/api-reference/mcp-server/update-entry
/openapi.json patch /v1/trips/{trip_id}/days/{day_number}/entries/{entry_id}
Correct a place annotation, note text, or local time in place.
Omitted fields are preserved; null clears note/time. Changing a time also
reorders the entry because a plan is an ordered document.
# Update Stay On Trip
Source: https://docs.stardrift.ai/api-reference/mcp-server/update-stay-on-trip
/openapi.json patch /v1/trips/{trip_id}/stays/{stay_id}
Change a booking in place — dates, price, or its confirmation number.
Without this a stay could be recorded and never corrected: the confirmation
number could only be set at creation, and a booking whose dates moved had no
path back short of leaving a stale one behind, since removing was not
possible either.
# Add Place By Id
Source: https://docs.stardrift.ai/api-reference/saved/add-place-by-id
/openapi.json post /saved/add-place
Save a place by id — optionally to a list. Idempotent per (place, list).
THE contract is a canonical place ULID (`canonical_places.id`) — the
spine identity every surface joins on; saves resolve entirely from the
spine with zero paid fetches, and dedup by canonical place_id.
A Google place_id is also accepted as the LEGACY autocomplete path (the
picker hands us a gpid before any canonical row exists); that path still
ends canonical — the resolver mints/links the row and stamps
`item.place_id` — it just pays the Google fetch to get there.
# Create List
Source: https://docs.stardrift.ai/api-reference/saved/create-list
/openapi.json post /saved/lists
# Create Section
Source: https://docs.stardrift.ai/api-reference/saved/create-section
/openapi.json post /saved/lists/{list_id}/sections
# Delete Section
Source: https://docs.stardrift.ai/api-reference/saved/delete-section
/openapi.json delete /saved/lists/{list_id}/sections/{section_id}
# Get List Contents
Source: https://docs.stardrift.ai/api-reference/saved/get-list-contents
/openapi.json get /saved/lists/{list_id}/contents
# List Lists
Source: https://docs.stardrift.ai/api-reference/saved/list-lists
/openapi.json get /saved/lists
# Place Autocomplete
Source: https://docs.stardrift.ai/api-reference/saved/place-autocomplete
/openapi.json get /saved/place-autocomplete
Google Places autocomplete powering the Saved "Add a place" search.
# Unsave Place
Source: https://docs.stardrift.ai/api-reference/saved/unsave-place
/openapi.json delete /saved/{item_id}
# Update List
Source: https://docs.stardrift.ai/api-reference/saved/update-list
/openapi.json patch /saved/lists/{list_id}
# Update Saved Item
Source: https://docs.stardrift.ai/api-reference/saved/update-saved-item
/openapi.json patch /saved/{item_id}
# Update Section
Source: https://docs.stardrift.ai/api-reference/saved/update-section
/openapi.json patch /saved/lists/{list_id}/sections/{section_id}
# Connect Stardrift to ChatGPT
Source: https://docs.stardrift.ai/clients/chatgpt
Add Stardrift as a custom MCP connector in ChatGPT with developer mode, then sign in with your Stardrift account.
Stardrift's MCP endpoint is `https://stardrift.ai/mcp`. ChatGPT reaches it through a custom connector, which needs developer mode.
Developer mode is available on Plus, Pro, Business, Enterprise and Edu plans, in the ChatGPT web app.
Open **Settings → Connectors**, scroll to **Advanced settings** and turn on **Developer mode**. A **Create** button appears in the Connectors section.
Click **Create** and fill in:
* **Name**: `Stardrift`
* **Description**: `Plan trips, read bookings and organize saved places in my Stardrift account.`
* **MCP server URL**: `https://stardrift.ai/mcp`
* **Authentication**: OAuth
Click **Create**, then sign in to Stardrift in the browser window and approve the permissions.
Click **+** in the composer, open **Developer mode** and select Stardrift for the conversation. Name the tool you want when it helps, for example “use Stardrift to list my trips”.
OpenAI labels developer mode as elevated risk because connectors can write data. Every Stardrift tool declares whether it reads or writes, and nothing in it purchases or cancels a reservation. See [Tools](/tools).
## Try it
* “List my trips in Stardrift.”
* “Add the Museum of Tomorrow to day two of my Rio trip at 14:00.”
* “Create a private saved list called Lisbon cafés.”
# Connect Stardrift to Claude
Source: https://docs.stardrift.ai/clients/claude
Add Stardrift as a custom connector in claude.ai, the Claude desktop app or Claude Code, then sign in with your Stardrift account.
Stardrift is listed in Claude's connector directory, so claude.ai, the Claude desktop and mobile apps and Claude Code all connect from the same listing. Once connected, Claude can read your trips and bookings, build and correct itineraries, and organize your saved places.
Opens the Stardrift listing in Claude. Click **Connect**, sign in to Stardrift and approve the permissions.
## claude.ai and Claude Desktop
Open **Customize → Connectors**, find **Stardrift** in the directory and click **Connect**.
Sign in to Stardrift in the browser window that opens and approve the permissions.
Click **+** in the chat composer, open **Connectors**, and enable Stardrift for the conversation.
On Team and Enterprise, an owner enables Stardrift under **Organization settings → Connectors** and each member clicks **Connect** on their own Connectors page. If the directory is unavailable to you, [add it as a custom connector](https://stardrift.ai/go/claude-custom?utm_source=docs) instead: the server URL is `https://stardrift.ai/mcp`, and the OAuth fields under Advanced settings stay empty because Stardrift registers the client for you.
## Claude Code
```bash theme={null}
claude mcp add --transport http stardrift https://stardrift.ai/mcp
claude mcp login stardrift
```
Sign in and approve the permissions in the browser. Inside a session, `/mcp` shows the connection state and also offers **Authenticate** and sign-out.
## Try it
* “List my trips.”
* “Create a two-day São Paulo trip and add MASP on day one at 10:00.”
* “Move that visit to day two, keeping its time.”
See [Tools](/tools) for the catalog and [what you are granting](/) for the permissions.
# Connect Stardrift to Codex
Source: https://docs.stardrift.ai/clients/codex
Add the Stardrift MCP server to the OpenAI Codex CLI or IDE extension, then sign in with your Stardrift account.
Stardrift's MCP endpoint is `https://stardrift.ai/mcp`.
## Codex CLI
```bash theme={null}
codex mcp add stardrift --url https://stardrift.ai/mcp
codex mcp login stardrift
```
The login command opens your browser: sign in to Stardrift and approve the permissions. Codex registers itself as an OAuth client automatically; Stardrift supports both client ID metadata documents and dynamic client registration, so no client ID is needed.
The same configuration in `~/.codex/config.toml`:
```toml theme={null}
[mcp_servers.stardrift]
url = "https://stardrift.ai/mcp"
```
## Codex IDE extension
Open the extension's MCP servers settings, add `https://stardrift.ai/mcp` as an HTTP server named `stardrift`, and restart the extension. It prompts you to sign in on first use.
## Try it
Ask Codex to “list my Stardrift trips” or “create a private saved list called Kyoto temples and add Kinkaku-ji”. See [Tools](/tools) for the catalog.
# Connect Stardrift to Cursor
Source: https://docs.stardrift.ai/clients/cursor
Add the Stardrift MCP server to Cursor with one click or a short mcp.json entry, then sign in with your Stardrift account.
Stardrift's MCP endpoint is `https://stardrift.ai/mcp`.
Opens Cursor and adds the Stardrift server. Cursor then opens your browser to sign in.
## Manual setup
Add the server to `~/.cursor/mcp.json` for every project, or to `.cursor/mcp.json` inside one project:
```json theme={null}
{
"mcpServers": {
"stardrift": {
"url": "https://stardrift.ai/mcp"
}
}
}
```
Enable the server in Cursor's MCP settings. Cursor detects that Stardrift needs OAuth and opens your browser: sign in to Stardrift and approve the permissions. No client ID or secret is needed.
## Try it
Ask the agent to “list my Stardrift trips” or “add Tsukiji Outer Market to day one of my Tokyo trip at 8:00”. See [Tools](/tools) for the catalog.
# Connect Stardrift to Gemini CLI
Source: https://docs.stardrift.ai/clients/gemini-cli
Add the Stardrift MCP server to Gemini CLI, then sign in with your Stardrift account.
Stardrift's MCP endpoint is `https://stardrift.ai/mcp`.
```bash theme={null}
gemini mcp add --transport http stardrift https://stardrift.ai/mcp
```
The same configuration in `~/.gemini/settings.json`:
```json theme={null}
{
"mcpServers": {
"stardrift": {
"httpUrl": "https://stardrift.ai/mcp"
}
}
}
```
Gemini CLI detects that Stardrift needs OAuth and discovers the endpoints itself. If it does not prompt you, run `/mcp auth stardrift` in a session, then sign in to Stardrift in the browser and approve the permissions.
## Try it
Ask Gemini to “list my Stardrift trips” or “add a note to day one of my Paris trip: buy museum pass”. See [Tools](/tools) for the catalog.
# Connect any MCP client
Source: https://docs.stardrift.ai/clients/other
What a Model Context Protocol client needs to talk to Stardrift: Streamable HTTP, OAuth with dynamic client registration, and the scopes to request.
Any client that speaks MCP over Streamable HTTP and can complete an OAuth sign-in works with Stardrift.
| | |
| - | - |
| Endpoint | `https://stardrift.ai/mcp` |
| Transport | Streamable HTTP |
| Authentication | OAuth 2.1 with PKCE; dynamic client registration and client ID metadata documents are both supported |
| Resource metadata | `https://stardrift.ai/.well-known/oauth-protected-resource` |
| Authorization server | `https://stardrift.ai/api/oauth` |
| Scopes | `guides:read guides:write bookings:read saved:read saved:write` |
An unauthenticated request returns `401` with a `WWW-Authenticate` header that names the resource metadata URL and the scopes to request. Clients that follow the MCP authorization specification discover everything from there and open the browser for sign-in. Tokens go in the `Authorization: Bearer` header.
Clients that cannot run an OAuth flow are not supported yet.
See [what you are granting](/) for what each scope allows and [Tools](/tools) for the catalog.
# Connect Stardrift to VS Code
Source: https://docs.stardrift.ai/clients/vscode
Add the Stardrift MCP server to VS Code for GitHub Copilot agent mode, then sign in with your Stardrift account.
Stardrift's MCP endpoint is `https://stardrift.ai/mcp`. MCP servers in VS Code run inside GitHub Copilot's agent mode.
Opens VS Code and adds the Stardrift server.
## Manual setup
Run **MCP: Add Server** from the Command Palette, choose **HTTP**, enter `https://stardrift.ai/mcp` and name it `stardrift`. Or add it to `.vscode/mcp.json` in a workspace:
```json theme={null}
{
"servers": {
"stardrift": {
"type": "http",
"url": "https://stardrift.ai/mcp"
}
}
}
```
Start the server from the `mcp.json` editor or the Extensions view. VS Code asks to allow authentication, then opens your browser: sign in to Stardrift and approve the permissions.
## Try it
In agent mode, ask Copilot to “list my Stardrift trips” or “move the Louvre visit to day three, same time”. See [Tools](/tools) for the catalog.
# Connect Stardrift to your AI assistant
Source: https://docs.stardrift.ai/index
Let an AI assistant read and edit your Stardrift trips, itineraries, and saved places over MCP.
Stardrift's public MCP endpoint is `https://stardrift.ai/mcp`. Connect it to let an assistant search flights and hotels, save unbooked options, read your travel plans, build and correct itineraries, record stays and events, and organize saved places on your behalf.
## Connect
In the connector directory: claude.ai, Desktop, mobile and Claude Code
Custom connector with developer mode
One-click install or mcp.json
GitHub Copilot agent mode
OpenAI Codex CLI and IDE extension
Google's Gemini CLI
Streamable HTTP with OAuth
Use your Stardrift account and review the permissions before approving. To change accounts, change the account on the website opened by the authorization flow and reconnect the client; signing into a different website or development environment does not change an existing grant.
## What you are granting
| Scope | What it allows |
| - | - |
| `guides:read` | Read your trips and itineraries |
| `guides:write` | Create trips; add, edit, move, and remove entries; record stays/events; change trip visibility |
| `bookings:read` | Read bookings and obtain your private booking-import address |
| `saved:read` | Read your lists and their contents; search place suggestions |
| `saved:write` | Create and publish lists; edit captions/sections; add and remove saved places |
The `guides:*` scope names cover trips and itineraries. Access to private records is limited to the authenticated account; knowing another user's trip ID does not grant access.
## Try it
* “Create a two-day São Paulo trip and add MASP on day one at 10:00.”
* “Move that visit to day two, keeping its time.”
* “Create a private saved list, then add a Museums heading.”
* “Save the places from this TikTok: [https://www.tiktok.com/@…/video/…”](https://www.tiktok.com/@…/video/…”)
* In a new conversation: “Find that list and change MASP's caption.”
See [Tools](/tools) for the complete catalog, editing IDs, pagination, and explicit-null behavior.
## Sharing
Trips start as drafts and saved lists made with `create_saved_list` start private; lists imported from an Instagram or TikTok post start public, as they do in the app. Ask explicitly to publish: `set_trip_visibility` controls a trip; `update_saved_list` controls a saved list. Public content can be shared and indexed. A returned URL does not itself indicate public visibility.
## Bookings
The assistant can read imported bookings and record stays or events. These tools do not purchase or cancel supplier reservations. There is no direct flight-add tool: forward a confirmation email to the address returned by `get_forwarding_address`. Keep that address private because mail sent there can add bookings to your account.
## Daily lookup budget
Paid place lookups have a **daily cap per user**, shared across the user's API tokens and connected clients. It resets at midnight UTC. A `429` response explains when to retry. Cached lookups do not add provider cost. Moving an existing entry does not resolve the place again; reads and itinerary corrections are separate from place discovery.
## Disconnect
On Stardrift, open **Profile → Connected apps → Disconnect**. The server rechecks grants with a cache of up to 60 seconds, so access may persist briefly before calls are rejected. Reconnect through your MCP client to grant access again.
# Tools
Source: https://docs.stardrift.ai/tools
The public Stardrift MCP tools, their permissions, and how to read and correct your travel plans.
Connect to `https://stardrift.ai/mcp` to use these tools. The [API reference](/api-reference/mcp-server/list-trips) documents the underlying HTTP operations; tool names and HTTP routes are not always the same. The API enforces authentication, permissions, and ownership. The MCP wrapper also validates inputs and filters place candidates.
## Trips and itineraries
| Tool | Scope | What it does |
| - | - | - |
| `list_trips` | `guides:read` | List your trips with `id`, title, `start_date`/`end_date` (null while undated), `updated_at`, and visibility. Match a title or dates to get a `trip_id`. |
| `create_trip` | `guides:write` | Create a draft with `num_days` blank days. The returned `id` is the `trip_id`. |
| `get_itinerary` | `guides:read` | Read days, entries, resolved activities, and `plan_version`. |
| `add_place_to_itinerary` | `guides:write` | Resolve and add a place to a day, with optional time and note. Returns both `item_id` and `entry_id`. |
| `add_day_note` | `guides:write` | Add standalone text to a day. Returns its `entry_id`. |
| `update_entry` | `guides:write` | Change an annotation or time, or rewrite a standalone note with `content`. Omitted fields stay unchanged; explicit null clears note/time. |
| `move_entry` | `guides:write` | Move an existing entry to another day without resolving the place again. Preserves its IDs, time, and note. |
| `remove_from_day` | `guides:write` | Remove one entry from a day. |
| `set_trip_visibility` | `guides:write` | Set `draft`, `private`, or `public`, with an optional slug. Publish only when requested. |
Day numbers start at 1 and must already exist. Use `get_itinerary` to inspect them. Use `entry_id` to edit, move, or remove a visit; `item_id` identifies its underlying activity. `plan_version` reports the current revision; it is not an optimistic-lock parameter.
### Correct a visit
After adding a place, keep the returned `entry_id`. For example, move it from day one to day two:
```json theme={null}
{
"trip_id": "",
"day_number": 1,
"entry_id": "",
"to_day_number": 2
}
```
Pass that object to `move_entry`. Then clear its annotation with `update_entry`:
```json theme={null}
{
"trip_id": "",
"day_number": 2,
"entry_id": "",
"note": null
}
```
The omitted time stays unchanged. Read `get_itinerary` afterward to verify the result.
## Flight and hotel search
| Tool | Scope | Purpose |
| - | - | - |
| `search_flights` | `guides:read` | Search one-way, round-trip, or multi-city cash flights. Returns connecting segments and observed prices without a ranking subagent. |
| `search_hotels` | `guides:read` | Search LiteAPI hotel availability and room rates. Users must visit the Stardrift website to book. |
| `get_search_results` | `guides:read` | Page through an existing search without another provider lookup. |
| `add_search_result_to_itinerary` | `guides:write` | Save an exact search result as an unbooked flight or stay; returns its item ID and trip URL. |
| `remove_search_result_from_itinerary` | `guides:write` | Remove an unbooked MCP search selection. Does not cancel reservations. |
Search first, then pass `search_id` and `result_index` to the add tool. These
references belong to your account and last 24 hours; prices may change sooner.
Follow `next_offset` with `get_search_results` to see subsequent pages.
Search results are the underlying provider options, not Stardrift AI picks.
`get_itinerary` returns `journeys` and `stays` alongside activities and days,
including the IDs needed to remove a selection. Each item carries its primary
`booking_link` and a `booking_link_count`; pass `include_booking_links: true`
to get every booking site's link and price. Places carry their rating, review count and one `photo_url`; review texts, photo galleries and map outlines are left out. Saved items remain in the trip
when search references expire. Repeating the same selection in the same trip
returns the existing item.
Hotel prices distinguish nightly amounts from whole-stay totals. Supply child
ages and guest nationality for accurate availability. Save an option, then open
the returned `trip_url` on Stardrift to continue toward booking. Never use
`record_stay` to save an unbooked candidate. No search or add tool purchases,
holds inventory, takes payment, or guarantees an observed rate.
## Bookings and recorded events
| Tool | Scope | What it does |
| - | - | - |
| `list_bookings` | `bookings:read` | Read bookings, optionally filtered by type, trip, or `from_date` (keeps undated bookings). For precise flight segments, read `edit_data`. |
| `get_forwarding_address` | `bookings:read` | Get your private booking-import email address. Keep it private: mail sent there can add bookings to your account. |
| `record_stay` | `guides:write` | Record a hotel or rental with dates. This does not purchase a reservation. |
| `update_stay` | `guides:write` | Correct a recorded stay's dates, price, confirmation number, or other supported fields. |
| `remove_stay` | `guides:write` | Remove a stay from Stardrift; this does not cancel a supplier reservation. |
| `record_event` | `guides:write` | Record a scheduled event, with optional local start/end times and location. Read any returned `warnings`. |
There is no tool to manually record or edit a confirmed flight by number/date; forward its confirmation email to your import address. Event update/removal tools are not currently available. Recording an event does not buy a ticket.
## Saved lists
A saved list is a collection of places, separate from a day-by-day trip. Lists made with `create_saved_list` are **private by default**; lists imported from a post are public, as in the app.
| Tool | Scope | What it does |
| - | - | - |
| `list_saved_lists` | `saved:read` | List your collections with IDs, item counts, and visibility. Route geometry is left out; `get_saved_list` carries it. |
| `get_saved_list` | `saved:read` | Read list metadata, sections, places, captions, and editing IDs. Takes `offset` and `limit`; follow `next_offset` until null. |
| `create_saved_list` | `saved:write` | Create a private list. Explicit `visibility: "public"` publishes it. |
| `import_social_post` | `saved:write` | Read the places an Instagram post/reel or TikTok video features, saved as a new list. Imported lists are public, as in the app; pass `visibility: "private"` to keep one private. Waits up to `wait_seconds` (default 45) and returns the list with its places; if still `importing`, read `get_saved_list` later. Re-importing a post returns its existing list. |
| `update_saved_list` | `saved:write` | Rename, change visibility, or edit the intro. Explicit null clears the intro. |
| `add_place_to_saved_list` | `saved:write` | Save a place. Ambiguous queries return `candidates` without saving; choose a candidate and retry with its `place_id`. Query-based resolution also needs `saved:read`. |
| `update_saved_place` | `saved:write` | Edit a caption or section membership. Omit to preserve; null clears the caption or removes section membership. |
| `remove_from_saved_list` | `saved:write` | Remove a saved item using its `id`. |
| `add_saved_list_section` | `saved:write` | Create a heading, optionally assigning existing item IDs. |
| `set_saved_list_section` | `saved:write` | Update a heading's title/blurb or replace its ordered `item_ids`. |
| `remove_saved_list_section` | `saved:write` | Delete a heading while keeping its places. |
### Edit an existing list in a fresh conversation
1. Find the list by title with `list_saved_lists`.
2. Call `get_saved_list(list_id=…)`. Its `list` contains metadata and sections; `items` contains saved-item IDs. The default page size is 100, with a maximum of 200.
3. Follow `next_offset` until null if you need every item.
4. Use a saved item's `id` for edits, removals, and section membership. Its `place_id` identifies the underlying place and is not the editing ID.
5. Read the list again after edits. Removal tools may return no body.
Publishing requires an explicit visibility change. A populated `public_url` alone does not mean the list is public. After making a list private, anonymous reads return a private-list placeholder without its places.
## Errors and recovery
| Status | Meaning | What to do |
| - | - | - |
| `401` | Missing, expired, invalid, or disconnected credentials | Reconnect through your client. |
| `403` | The grant lacks the required permission | Check the requested scopes and reconnect if needed. |
| `404` | The record or day is missing, or belongs to another account | Read your own trips/list contents and use their returned IDs. |
| `409` | A resolved place's name collides with a different place already in the trip | Read the itinerary and explain the conflict. The new place was not added. |
| `422` | Invalid input or an unresolved place | Follow the error detail; for resolution failures, try a more specific venue, street, and city. |
| `429` | The daily paid-lookup budget is exhausted | Stop new paid lookups until the indicated reset. Reading or moving an existing entry does not resolve a place. |
Adding the same Google place again is not the name-collision error: the existing activity can be reused for another visit. Do not treat a 409 as proof that the requested place is already present.
The tools preserve API error explanations. The wrapper can also return input errors such as `Pass search_query or place_id`, or `No venue matched`, without an HTTP status.