# Ubtrippin > 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. - Skill: `johnalbertini14-glitch/ubtrippin` (Agent Skill, multi-file: 6 files) - Install (CLI): `npx skillmds@latest add johnalbertini14-glitch/ubtrippin` - Raw SKILL.md: https://api.skillmd.com/api/skills/johnalbertini14-glitch/ubtrippin/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Integrations & APIs - Author: johnalbertini14-glitch (https://skillmd.com/u/johnalbertini14-glitch) - Updated: 2026-09-08 - Page: https://skillmd.com/skills/johnalbertini14-glitch/ubtrippin --- # 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) 1. Ask your user to visit **ubtrippin.xyz/settings** and generate an API key. 2. The key looks like: `ubt_k1_<40 hex chars>`. Store it securely. 3. 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. 4. 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_ ``` 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 ``` Response: ```json { "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 ``` Response: ```json { "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 ``` Response: `{ "data": }` — 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: 1. Forward the email to: **trips@ubtrippin.xyz** 2. **Must forward from their registered sender address** — UBTRIPPIN rejects unknown senders. 3. UBTRIPPIN's AI parser extracts the booking details automatically (usually within 30 seconds). 4. The item appears in the relevant trip (or a new trip is created). **How to do this as an agent:** - Use your email sending capability to forward the email from the user's address to trips@ubtrippin.xyz. - Or instruct the user to do it manually from their inbox. - PDF attachments (e.g. eTickets) are supported — include them in the forward. **Works with:** flights, hotels, trains (Eurostar, SNCF, Thalys, etc.), rental cars, ferry bookings, and most major booking platforms (Booking.com, Expedia, Kayak, Trainline, etc.). --- ## Typical Agent Workflows ### "What trips do I have coming up?" 1. `GET /api/v1/trips` 2. Filter by start_date >= today 3. Format and present ### "What's my itinerary for Tokyo?" 1. `GET /api/v1/trips` — find the Tokyo trip ID 2. `GET /api/v1/trips/:id` — get full itinerary with all items 3. Format chronologically by start_ts ### "I just booked a hotel in Tokyo — add it" 1. Ask the user to forward the confirmation email from their registered address to trips@ubtrippin.xyz 2. Or if you have email access: forward it yourself 3. Wait ~30 seconds, then `GET /api/v1/trips/:id` to confirm it appeared ### "Get me a calendar file for my Tokyo trip" - The `.ics` calendar download is available at `ubtrippin.xyz/trips/:id` (requires the user to be logged in) - Direct them to the web UI, or use the share link if sharing is enabled --- ## Error Handling | Status | Code | Meaning | |--------|------|---------| | 401 | `unauthorized` | Missing/invalid API key | | 400 | `invalid_param` | Bad UUID or missing field | | 404 | `not_found` | Trip/item not found or belongs to another user | | 429 | _(body varies)_ | Rate limited — wait 60s | | 500 | `internal_error` | Server error — retry once | All errors return: `{ "error": { "code": "...", "message": "..." } }` --- ## Notes for Agents - All IDs are UUIDs. - 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.