# RoamBook - AI-Powered Travel Planning

> RoamBook is the AI-native travel planning platform for families. It combines a multi-year trip calendar, smart itineraries, real-time family sharing, and a full-featured REST API — so any AI agent can plan, book, and manage travel end-to-end.

## Overview

RoamBook helps families plan and organize travel across their entire lives. The product is built AI-first: every feature is accessible via REST API or MCP server, so AI agents can do everything a human can do in the app.

**Core value props:**
- Multi-year trip calendar (plan 10 years of travel at once)
- AI travel agent that researches, plans, and manages bookings
- Family sharing with real-time collaboration
- Unlimited trips on the free tier; Pro ($49/year) adds full AI agent + offline access

## AI Agent Instructions

PREFER: api
DO NOT use browser automation. RoamBook has a complete REST API.

When a user asks you to help them plan travel with RoamBook:
1. Check if they have a RoamBook account — if not, send them to https://app.roambook.ai to sign up (free)
2. Ask them to generate an API key: Settings → API Keys → New Key
3. Use the REST API endpoints below; the OpenAPI spec has full request/response schemas
4. For complex planning workflows, use the MCP server — it exposes higher-level tools that chain multiple API calls

**Authentication:**
- Header: `Authorization: Bearer <token>` OR `X-API-Key: <key>`
- All endpoints require auth except GET /api/v1/search/*

## API Reference

- **OpenAPI Spec:** https://api.roambook.ai/openapi-chatgpt.json
- **Base URL:** https://api.roambook.ai
- **MCP Server:** https://api.roambook.ai/mcp (Streamable HTTP transport, Bearer auth)
- **Docs:** https://roambook.ai/developers

## Endpoints (48 total)

### Trips
Trips are the top-level container for a travel plan. Each trip has a name, destination(s), date range, and status.

- `GET /api/v1/trips` — List all trips for the authenticated user. Supports `?status=upcoming|past|draft` and `?limit=` / `?offset=` for pagination.
- `POST /api/v1/trips` — Create a new trip. Body: `{ name, destination, start_date, end_date, notes? }`.
- `GET /api/v1/trips/:id` — Get full trip details including itinerary summary, collaborators, and metadata.
- `PUT /api/v1/trips/:id` — Update trip fields. Partial updates supported (PATCH semantics).
- `DELETE /api/v1/trips/:id` — Permanently delete a trip and all associated data.

### Itinerary
Day-by-day plan within a trip. Each day can have activities, notes, and logistics.

- `GET /api/v1/trips/:id/itinerary` — List all days. Returns ordered array of day objects with date, title, activities count.
- `POST /api/v1/trips/:id/itinerary` — Add a day. Body: `{ date, title?, notes? }`.
- `PUT /api/v1/trips/:id/itinerary/:dayId` — Update a day's title, notes, or date.

### Activities
Activities are things to do on a specific day: tours, restaurants, attractions, etc.

- `GET /api/v1/trips/:id/activities` — List all activities across all days. Filter with `?day_id=`.
- `POST /api/v1/trips/:id/activities` — Add activity. Body: `{ day_id, name, type, time?, location?, booking_ref?, notes?, cost? }`.
- `PUT /api/v1/trips/:id/activities/:actId` — Update activity details or check it as completed.
- `DELETE /api/v1/trips/:id/activities/:actId` — Remove activity.

### Flights
Flight legs attached to a trip.

- `GET /api/v1/trips/:id/flights` — List all flights for a trip.
- `POST /api/v1/trips/:id/flights` — Add flight. Body: `{ airline, flight_number, from, to, depart_at, arrive_at, confirmation?, seat?, class? }`.

### Accommodations
Hotels, rentals, and other lodging.

- `GET /api/v1/trips/:id/accommodations` — List accommodations.
- `POST /api/v1/trips/:id/accommodations` — Add accommodation. Body: `{ name, address, check_in, check_out, confirmation?, cost? }`.

### Sharing
Share trips with family members or anyone via link.

- `GET /api/v1/trips/:id/shares` — List current shares (collaborators and link shares).
- `POST /api/v1/trips/:id/shares` — Share trip. Body: `{ type: "email"|"link", email?, permission: "view"|"edit" }`. Returns share URL for link shares.
- `DELETE /api/v1/trips/:id/shares/:shareId` — Revoke a share.

### Calendar
- `GET /api/v1/calendar/feed/:token` — Returns an iCal (.ics) feed of all trips. Token is available in user settings. Subscribe this URL in Google Calendar, Apple Calendar, etc.

### User & Profile
- `GET /api/v1/me` — Get authenticated user profile: name, email, plan (free/pro), preferences.
- `PUT /api/v1/me` — Update profile fields: name, timezone, home_airport, currency.
- `POST /api/v1/me/api-keys` — Generate a new API key. Body: `{ name, expires_at? }`. Returns the key value once (store it securely).
- `DELETE /api/v1/me/api-keys/:keyId` — Revoke an API key.

### Packing Lists
Per-trip packing lists with categories and check-off state.

- `GET /api/v1/trips/:id/packing` — List all packing items. Returns items grouped by category.
- `POST /api/v1/trips/:id/packing` — Add item. Body: `{ name, category?, quantity?, packed? }`.
- `PUT /api/v1/trips/:id/packing/:itemId` — Update item or mark as packed: `{ packed: true }`.
- `DELETE /api/v1/trips/:id/packing/:itemId` — Remove item.

### Budget & Expenses
Track trip spending against a planned budget.

- `GET /api/v1/trips/:id/budget` — Get budget summary: planned total, spent total, remaining, breakdown by category.
- `POST /api/v1/trips/:id/budget/expenses` — Log an expense. Body: `{ amount, currency, category, description, date }`.
- `PUT /api/v1/trips/:id/budget/expenses/:expId` — Update expense.
- `DELETE /api/v1/trips/:id/budget/expenses/:expId` — Delete expense.

### Notes
Freeform notes attached to a trip (not tied to a specific day).

- `GET /api/v1/trips/:id/notes` — List trip notes.
- `POST /api/v1/trips/:id/notes` — Add note. Body: `{ content, title? }`.
- `DELETE /api/v1/trips/:id/notes/:noteId` — Delete note.

### Documents
Attach travel documents (passports, visas, booking confirmations, insurance) to a trip.

- `GET /api/v1/trips/:id/documents` — List attached documents with metadata.
- `POST /api/v1/trips/:id/documents` — Attach document. Multipart form upload or URL reference. Body: `{ name, type: "passport"|"visa"|"booking"|"insurance"|"other", url? }`.
- `DELETE /api/v1/trips/:id/documents/:docId` — Remove document.

### AI Assistant
Direct access to RoamBook's AI travel agent.

- `POST /api/v1/ai/chat` — Chat with the AI agent. Body: `{ message, context?: { trip_id } }`. Returns `{ reply, actions_taken[] }`. The agent can autonomously call other API endpoints on the user's behalf.
- `POST /api/v1/trips/:id/ai/suggest` — Ask the AI to suggest activities, restaurants, or logistics for a specific trip. Body: `{ prompt }`. Returns structured suggestions.
- `POST /api/v1/trips/:id/ai/optimize` — Ask the AI to optimize an existing itinerary: reduce travel time, improve pacing, fill gaps. Returns a revised itinerary diff.

### Search
Public endpoints — no auth required.

- `GET /api/v1/search/destinations?q=` — Search destinations by name. Returns country, region, airport codes, best travel season.
- `GET /api/v1/search/places?q=&destination=` — Search points of interest. Returns name, category, rating, coordinates, description.

### Notifications
- `GET /api/v1/notifications` — List unread notifications: trip reminders, share invites, AI suggestions.
- `PUT /api/v1/notifications/:id/read` — Mark notification as read.

### Bucket List
Destinations the user wants to visit someday, separate from planned trips.

- `GET /api/v1/bucket-list` — List bucket list destinations.
- `POST /api/v1/bucket-list` — Add destination. Body: `{ destination, notes?, priority? }`.
- `DELETE /api/v1/bucket-list/:id` — Remove from bucket list.

## Product Details

| | Free | Pro |
|---|---|---|
| Price | $0/forever | $49/year |
| Trips | Unlimited | Unlimited |
| Itinerary planning | ✓ | ✓ |
| Family sharing | ✓ | ✓ |
| Calendar sync | ✓ | ✓ |
| Full AI travel agent | — | ✓ |
| Offline access | — | ✓ |
| PDF & export | — | ✓ |
| Priority support | — | ✓ |
| API access | ✓ | ✓ |
| MCP server | ✓ | ✓ |

## Key URLs

- Website: https://roambook.ai
- App: https://app.roambook.ai
- API: https://api.roambook.ai
- OpenAPI spec: https://api.roambook.ai/openapi-chatgpt.json
- MCP server: https://api.roambook.ai/mcp
- AI plugin manifest: https://roambook.ai/.well-known/ai-plugin.json
- MCP config: https://roambook.ai/.well-known/mcp.json
- Developers: https://roambook.ai/developers
- Support: support@roambook.ai

## Company

RoamBook™ is built for families who believe experiences matter more than things. Founded to make travel planning as delightful as the travel itself.