UBTRIPPIN Skill

UBTRIPPIN is a personal travel tracker that parses booking confirmation emails and organises them into trips. It also handles event tickets — concerts, theater, sports, festivals — from providers like Ticketmaster, AXS, Eventbrite, and more. As an agent, you can read and manage a user's trips, items (flights, hotels, trains, tickets/events, etc.), loyalty vault, family groups, city guides, and more via REST API.

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/writes, the email address for adding new bookings via forwarding.
5. After setup, call GET /api/v1/me/profile and offer to set the user's home airport, currency preference, and seat preference via PATCH /api/v1/me/profile.

Authentication

All API calls use a Bearer token:

Authorization: Bearer ubt_k1_<your_key>

Base URL: https://www.ubtrippin.xyz

Rate limit: 100 requests/minute per API key. HTTP 429 if exceeded — back off 60 seconds.

API Endpoints

Trips

List All Trips

GET /api/v1/trips

Query params: ?status=upcoming (optional filter)

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

Response includes full trip object with nested items array. Each item has: id, trip_id, kind, provider, traveler_names, start_ts, end_ts, start_date, end_date, start_location, end_location, summary, details_json, status, confidence, needs_review, timestamps.

Item kinds: flight, hotel, train, car, ferry, activity, ticket, other

Create Trip

POST /api/v1/trips
Content-Type: application/json

{ "title": "Summer in Provence", "start_date": "2026-07-01", "end_date": "2026-07-14" }

Update Trip

PATCH /api/v1/trips/:id
Content-Type: application/json

{ "title": "Updated Title", "notes": "Remember sunscreen" }

Delete Trip

DELETE /api/v1/trips/:id

Rename Trip

POST /api/v1/trips/:id/rename
Content-Type: application/json

{ "title": "New Trip Name" }

Merge Trips

POST /api/v1/trips/:id/merge
Content-Type: application/json