Manages travel for your user via UBTRIPPIN — reads trips, items, and booking details. Use when the user asks about their trips, upcoming travel, flights, hotels, train bookings, or wants to add a new booking to their travel tracker. Requires a UBTRIPPIN API key from ubtrippin.xyz/settings.
Manages travel for your user via UBTRIPPIN — reads trips, items, and booking details. Use when the user asks about their trips, upcoming travel, flights, hotels, train bookings, or wants to add a new booking to their travel tracker. Requires a UBTRIPPIN API key from ubtrippin.xyz/settings.
UBTRIPPIN Skill
UBTRIPPIN is a personal travel tracker that parses booking confirmation emails and organises them into trips. As an agent, you can read a user's trips and items via REST API, and add new bookings by forwarding confirmation emails on their behalf.
Setup (First Time)
Ask your user to visit ubtrippin.xyz/settings and generate an API key.
The key looks like: ubt_k1_<40 hex chars>. Store it securely.
Ask for their registered sender email — the email address they use to forward bookings (typically their personal inbox). This is their "allowed sender" in UBTRIPPIN.
You'll need both to operate: the API key for reads, the email address for adding new bookings.
Authentication
All API calls use a Bearer token:
Authorization: Bearer ubt_k1_<your_key>
Base URL: https://ubtrippin.xyz
Rate limit: 100 requests/minute per API key. HTTP 429 if exceeded — back off 60 seconds.
API Endpoints
List All Trips
GET /api/v1/trips
Authorization: Bearer <key>
Response:
{"data":[{"id":
"uuid"
,
"title"
:
"Tokyo Spring 2026"
,
"start_date"
:
"2026-04-01"
,
"end_date"
:
"2026-04-14"
,
"primary_location"
:
"Tokyo, Japan"
,
"travelers"
:
[
"Ian Rogers"
]
,
"notes"
:
null
,
"cover_image_url"
:
"https://..."
,
"share_enabled"
:
false
,
"created_at"
:
"2026-02-15T10:00:00Z"
,
"updated_at"
:
"2026-02-15T10:00:00Z"
}
]
,
"meta"
:
{
"count"
:
1
}
}
Ordered by start_date descending (soonest upcoming / most recent first).
Get Trip with All Items
GET /api/v1/trips/:id
Authorization: Bearer <key>
Response:
{"data":{"id":"uuid","title":"Tokyo Spring 2026","start_date":"2026-04-01","end_date":"2026-04-14","primary_location":"Tokyo, Japan","travelers":["Ian Rogers"],"items":[{"id":"uuid","trip_id":"uuid","kind":"flight","provider":"Air France","traveler_names":["Ian Rogers"],"start_ts":"2026-04-01T08:30:00Z","end_ts":"2026-04-01T18:45:00Z","start_date":"2026-04-01","end_date":"2026-04-01","start_location":"Paris CDG","end_location":"Tokyo NRT","summary":"Flight AF276 Paris → Tokyo","details_json":{"flight_number":"AF276","seat":"12A","confirmation":"XYZ123"},"status":"confirmed","confidence":0.98,"needs_review":false,"created_at":"2026-02-15T10:00:00Z","updated_at":"2026-02-15T10:00:00Z"}]},"meta":{"item_count":1}}
Item kinds:flight, hotel, train, car, ferry, activity, other
Get Single Item
GET /api/v1/items/:id
Authorization: Bearer <key>
Response: { "data": <item> } — same Item shape as above.
Adding New Bookings (Email Forwarding)
The primary way to add bookings is email forwarding. When your user receives a booking confirmation:
Dates are ISO 8601 (YYYY-MM-DD for dates, YYYY-MM-DDTHH:MM:SSZ for timestamps).
details_json contains raw parsed data — useful for confirmation numbers, seat assignments, loyalty numbers, etc.
confidence (0–1): how confident the AI parser was. Items with needs_review: true may have errors.
API keys are read-only — you cannot create, edit, or delete trips/items via the API (v1). Use email forwarding to add bookings.
The API key is the user's — never share it, log it, or store it beyond the session unless the user explicitly asks.
Managing API Keys
Users manage keys at ubtrippin.xyz/settings. Each key has a name and a masked preview. If a key is compromised, the user can revoke it from the settings page and generate a new one.
