For people and agents

External Agent API

Let something else read your travels, and add to them.

Dear Travel is a travel record with an agent living inside it. This API lets an agent running somewhere else — on your own machine, in a chat app, anywhere that can make an HTTPS request — read that record, add to it, and talk to the agent that keeps it.

Three rules

Read these first. They are not configuration, and no key changes them.

1. The agent’s mind is read-only from outside. Dear Travel’s agent keeps a mind — a graph of what it has concluded about the traveller. You can read it. Nothing outside Dear Travel can write it, and there is no endpoint that would. The reason is mechanical: the whole mind is loaded into the agent’s prompt every turn, so anything written from outside would come back to the agent as its own recollection, indistinguishable from what it worked out for itself. If you have something the mind should hold, say so through /chat and let the agent decide.
2. Nothing deletes. The tool surface is adds and edits. 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.

Getting a key

Each traveller issues their own keys, in Settings → External agent. A key acts as exactly one account — the account of whoever issued it — so there is no way to issue one on someone else’s behalf, and no way for a key to issue another key.

The key is shown once. Dear Travel stores only a hash of it, so a lost key is re-issued, never recovered. It can be renamed and re-scoped at any time, and turned off immediately — that is why it is an opaque random string looked up in a table rather than a signed token that would stay valid until it expired.

Authorization: Bearer dt_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Permissions

A key carries a set of permissions. They only ever subtract: a key acts as one account and can never reach outside it.

There is no write counterpart to mind:read, and no delete permission at all. Those absences are the two rules above, expressed in the vocabulary.

Endpoints

What an agent can reach

6 reads and 5 adds or edits. This table is generated from the allowlist the gateway actually enforces.

Notice what is absent. No delete tool, and none of the mind’s write tools. The catalog is an allowlist, so a tool added inside Dear Travel stays unreachable from outside until someone puts it on the list on purpose.

Sending files

Understanding a document and storing it are different questions, and the answers differ. You almost certainly have your own model — extract the fields where you are, rather than relaying bytes to Dear Travel so it can spend the traveller’s AI budget re-reading what you already read. But a summary is not a receipt, so the bytes still have to land.

So it is one call: send the structured fields and the file. The file is filed onto whatever that call creates — a photo onto the trip, a scan onto the journal entry. Up to 5 files per call, 10 MB each, base64-encoded. Images, video, audio and PDF; SVG is refused. Sending files needs files:write on top of the tool’s own permission — creating a journal entry and putting a scanned visa in the traveller’s media are different grants.

POST /api/agent/external/tools
Authorization: Bearer dt_…
Content-Type: application/json

{
  "tool": "create_journal_entry",
  "args": {
    "body": "Landed in Lisbon. The taxi queue was 40 minutes.",
    "trip_id": "…",
    "entry_type": "note"
  },
  "attachments": [
    {
      "filename": "boarding-pass.pdf",
      "mimeType": "application/pdf",
      "data": "JVBERi0xLjQK…",
      "caption": "TP1234 LIS"
    }
  ]
}

A filing miss never fails the write, and is never silent either. If the entry saved but the file did not, result says so — you can retry the file alone.

A worked example

Read the catalog, then read the traveller’s upcoming trips.

curl -s https://dear.travel/api/agent/external/tools \
  -H "Authorization: Bearer $DEAR_TRAVEL_KEY"

curl -s https://dear.travel/api/agent/external/tools \
  -H "Authorization: Bearer $DEAR_TRAVEL_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tool":"list_trips","args":{"scope":"upcoming"}}'

Add a trip, then ask the agent about it in its own words.

curl -s https://dear.travel/api/agent/external/tools \
  -H "Authorization: Bearer $DEAR_TRAVEL_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tool":"create_trip","args":{"name":"Lisbon in spring","city":"Lisbon","start_date":"2027-04-02","end_date":"2027-04-09"}}'

curl -s https://dear.travel/api/agent/external/chat \
  -H "Authorization: Bearer $DEAR_TRAVEL_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message":"What should I pack for Lisbon in April?"}'

Rate limits and errors

• 60 calls per minute per key, and a separate hourly ceiling on /chat because that one spends the account’s AI budget. Over the line is a 429 with Retry-After.
• 401 — the key is missing, malformed, unknown, turned off or expired. One answer for all of them on purpose: which of your guesses was close is not something an unauthenticated caller has earned.
• 403 — authenticated, but the key lacks a permission. The response names which one, so the fix is “ask for files:write” rather than a bare refusal.
• 404 on a tool call — that tool is not in the catalog. It may exist inside Dear Travel; it is not reachable from outside.
• 200 with ok: false — the tool ran and declined, or failed. Relay result. Do not retry: a permission decision will not change on the second attempt.

Want a capability that is not here? The tool surface grows deliberately — each entry is a decision, not an export. Machine-readable spec: /api/agent/external/openapi.