# Dear Travel > A personal travel record — trips, plans, packing lists, a wishlist, a travel > wallet and a journal — with an agent living inside it. This file is for agents. > Everything below describes the External Agent API, which lets an agent running > somewhere else read that record, add to it, and talk to the agent that keeps it. ## Start here - Machine-readable contract (no key needed): https://dear.travel/api/agent/external/openapi Full JSON-schema parameters for every tool. Fetch this first. - Human reference: https://dear.travel/docs/api - Your key's own catalog (needs a key): GET https://dear.travel/api/agent/external/tools ## Three rules that do not bend 1. The agent's mind is READ-ONLY from outside. You can read it; nothing outside Dear Travel can write it, and no endpoint exists that would. The whole mind is loaded into the agent's prompt every turn, so anything written from outside would return to the agent as its own recollection. If you have something the mind should hold, say it through /api/agent/external/chat and let the agent decide what to remember. 2. Nothing deletes. Adds and edits only. There is no delete tool and no permission that could authorize one. 3. Nothing reaches settings. No key can change the traveller's preferences, their account, or issue another key. ## Authentication One opaque bearer key per traveller, issued by that traveller in Settings -> External agent. Send it as: Authorization: Bearer dt_... A key acts as exactly one account. It is shown once (only a hash is stored), can be re-scoped or turned off at any time, and cannot issue another key. ## Permissions - travel:read: Read trips, plans, packing lists and the wishlist. - travel:write: Create and update trips, packing lists, items and journal entries. Never delete. - wallet:read: Read the travel wallet — passports, visas, trusted-traveler and elite status, card names (never numbers). - mind:read: Read the agent's mind — the rendered index, and one page in full. Read only. - files:write: Send files along with a write, to be filed onto what it creates. - agent:chat: Hold a conversation with the in-app agent and act on the traveller’s behalf. Permissions only ever subtract. There is no write counterpart to mind:read, and no delete permission at all — those absences are rules 1 and 2 above. ## Endpoints - GET /api/agent/external/tools The catalog for your key, with parameters. - POST /api/agent/external/tools Run one tool. Body: {tool, args, attachments?, correlationId?, ownerConfirmed?} - GET /api/agent/external/mind The agent's mind index. Needs mind:read. No POST exists. - POST /api/agent/external/chat Hand the agent a whole turn. Needs agent:chat. Body: {message, conversationId?} - GET /api/agent/external/openapi This contract as JSON. No key needed. ## Reads (6) - list_trips (travel:read): List the traveller's trips with dates, location and plan counts. Use scope to focus: 'upcoming' (active/future), 'past', or 'all'. - get_trip (travel:read): Get one trip in detail: its plans (flights, lodging, activities, …) and packing lists. Pass the trip id (with or without the trip: prefix). - list_packing (travel:read): List the traveller's packing lists with packed/total counts. - list_wishlist (travel:read): List the traveller's saved Wishlist — places AND activities they want to do, including bucket-list items, each with status and any target timing. Use for "what's on my wishlist", planning ideas, or matching a trip to something they wanted to do. - list_wallet (wallet:read): List the traveller's travel wallet — passports, residency/visa status, Global Entry / trusted-traveler programs, airline & hotel elite status, the credit cards they carry (names only, never numbers), lounge access, insurance. Use for visa/entry, lounge, best-card, alliance-perk, and document-validity questions. - read_memory (mind:read): Read one page of the agent's mind in full by node_id, plus its directly-connected pages. Ids come from the index at GET /api/agent/external/mind. Read only — nothing outside Dear Travel can write the mind. ## Adds and edits (5) - create_trip (travel:write, accepts files): Create a new trip for the traveller. Use when they ask you to start/plan a trip. Dates are optional (they fill in as plans land). For the destination pass a plain city name in `city` (e.g. 'Lisbon'); the server resolves it. This WRITES immediately when called on this endpoint — there is no approval step here, so confirm with the traveller yourself before calling it. - update_trip (travel:write, accepts files): Edit an existing trip (rename, change dates, destination, or type). Pass `trip_id` and only the fields to change. To clear a date pass it as null. This WRITES immediately when called on this endpoint — there is no approval step here, so confirm with the traveller yourself before calling it. - create_packing_list (travel:write): Create a new packing list, optionally pre-filled with items and linked to a trip. Use when the traveller asks you to make them a list. (For an AI-generated list from a trip's specifics, the traveller can also use the trip's “Create Packing List” button.) This WRITES immediately when called on this endpoint — there is no approval step here, so confirm with the traveller yourself before calling it. - add_packing_item (travel:write): Add one item to an existing packing list. Pass `list_id` and the item `label`. Use `list_packing` first to find the list id. This WRITES immediately when called on this endpoint — there is no approval step here, so confirm with the traveller yourself before calling it. - create_journal_entry (travel:write, accepts files): Write a journal entry on the traveller's behalf — a note, reflection, or record of something that happened. Optionally pin it to a trip. This WRITES immediately when called on this endpoint — there is no approval step here, so confirm with the traveller yourself before calling it. Nothing that deletes, and nothing that writes the mind, appears above. The catalog is an allowlist: a tool added inside Dear Travel is unreachable from outside until someone lists it deliberately. ## Files Send bytes along with a write and they are filed onto whatever that call creates. Up to 5 per call, 10 MB each, base64, as {filename, mimeType, data, caption?}. Images, video, audio and PDF; SVG is refused. Needs files:write ON TOP OF the tool's own permission. Extract the document's fields wherever you are rather than relaying bytes for Dear Travel to re-read — but do send the bytes, because a summary is not a receipt. ## Responses - 200 with ok:true It worked. 'result' is a sentence to relay. - 200 with ok:false The tool ran and declined, or failed. Relay 'result'. DO NOT RETRY — a permission decision will not change. - 401 Key missing, malformed, unknown, turned off or expired. - 403 Authenticated, but the key lacks a permission. The response names which one; ask your owner to re-scope the key. - 404 on a tool call Not in the catalog. It may exist inside Dear Travel; it is not reachable from outside. - 429 60 calls/minute per key. Honour Retry-After.