# Elsewhere Ventures - llms-full

Primary Goals
- Provide safe machine-readable access without exposing private advisor/client data.
- Preserve human UX while enabling bot integrations.

Preferred Endpoints
- https://travel-accounting-production.up.railway.app/api/openapi
- https://travel-accounting-production.up.railway.app/api/v1/capabilities
- https://travel-accounting-production.up.railway.app/api/v1/public/trips/%7BshareToken%7D/itinerary
- https://travel-accounting-production.up.railway.app/api/v1/bot/events?since=%3CISO8601%3E&cursor=%3Ccursor%3E (requires bot key)
- https://travel-accounting-production.up.railway.app/api/v1/bot/whoami (diagnostics for bot identity/scopes)
- https://travel-accounting-production.up.railway.app/api/v1/bot/export/trips?updatedSince=%3CISO8601%3E&cursor=%3Ccursor%3E
- https://travel-accounting-production.up.railway.app/api/v1/mcp (client-scoped read-only MCP discovery + transport)

Intelligence Endpoints
- GET https://travel-accounting-production.up.railway.app/api/v1/bot/stream — SSE real-time event stream. Polls audit log for trip/accounting changes. Supports ?since=<ISO8601> cursor for reconnection. Max 2 concurrent connections per token. Events: heartbeat, timeout, and entity-type events (e.g., trip.created, expense.updated).
- GET https://travel-accounting-production.up.railway.app/api/v1/bot/trips/%7BtripId%7D/insights — Trip intelligence insights. Returns payment alerts, completeness checks, timeline warnings, and accounting observations. Response: { tripId, tripCode, tripName, insights[], generatedAt }.
- POST https://travel-accounting-production.up.railway.app/api/v1/bot/query — Natural language query. Request body: { question: string }. Understands balance, spend, payment, upcoming, and count intents. Response: { question, answer, data, intent, confidence }. Supports client-specific queries (e.g., "What is John's balance?") with per-client allocation.
- GET https://travel-accounting-production.up.railway.app/api/v1/bot/trips/%7BtripId%7D/actions — Next-action suggestions. Returns prioritized actions (critical/high/medium/low): payment reminders, missing data, status updates, commissions review. Actions with advisory=true are suggestions only. Response: { tripId, tripCode, tripName, actions[], generatedAt }.

Bot List & Write Endpoints (GET list endpoints support cursor-based pagination via ?cursor=<id> or offset via ?page=<n>; cursor is recommended for concurrent-safe iteration)
- GET/POST https://travel-accounting-production.up.railway.app/api/v1/bot/trips (requires trips.read or trips.* or mutations.trips or mutations.* or *)
- PUT/DELETE https://travel-accounting-production.up.railway.app/api/v1/bot/trips/%7Bid%7D (requires mutations.trips or mutations.* or *)
- GET/POST https://travel-accounting-production.up.railway.app/api/v1/bot/expenses (requires trips.read or trips.* or mutations.expenses or mutations.* or *)
- PUT/DELETE https://travel-accounting-production.up.railway.app/api/v1/bot/expenses/%7Bid%7D (requires mutations.expenses or mutations.* or *)
- POST https://travel-accounting-production.up.railway.app/api/v1/bot/expenses/bulk (requires mutations.bulk or mutations.* or *)
- GET/POST https://travel-accounting-production.up.railway.app/api/v1/bot/payments (requires trips.read or trips.* or mutations.payments or mutations.* or *)
- PUT/DELETE https://travel-accounting-production.up.railway.app/api/v1/bot/payments/%7Bid%7D (requires mutations.payments or mutations.* or *)
- POST https://travel-accounting-production.up.railway.app/api/v1/bot/payments/bulk (requires mutations.bulk or mutations.* or *)
- GET/POST https://travel-accounting-production.up.railway.app/api/v1/bot/commissions (requires trips.read or trips.* or mutations.commissions or mutations.* or *)
- PUT/DELETE https://travel-accounting-production.up.railway.app/api/v1/bot/commissions/%7Bid%7D (requires mutations.commissions or mutations.* or *)
- GET/POST https://travel-accounting-production.up.railway.app/api/v1/bot/points (requires trips.read or trips.* or mutations.points or mutations.* or *)
- PUT/DELETE https://travel-accounting-production.up.railway.app/api/v1/bot/points/%7Bid%7D (requires mutations.points or mutations.* or *)
- GET/POST https://travel-accounting-production.up.railway.app/api/v1/bot/webhooks (requires webhooks.read or webhooks.* or mutations.webhooks or mutations.* or *)
- PUT/DELETE https://travel-accounting-production.up.railway.app/api/v1/bot/webhooks/%7Bid%7D (requires mutations.webhooks or mutations.* or *)
- GET https://travel-accounting-production.up.railway.app/api/v1/bot/webhooks/deliveries (requires webhooks.read or webhooks.* or mutations.webhooks or mutations.* or *)
- POST https://travel-accounting-production.up.railway.app/api/v1/bot/webhooks/deliveries/%7Bid%7D/replay (requires mutations.webhooks or mutations.* or *)
- GET/POST https://travel-accounting-production.up.railway.app/api/v1/bot/clients/%7BclientId%7D/api-keys (requires client-api-keys.read or client-api-keys.* or mutations.client-api-keys or mutations.* or *)
- DELETE https://travel-accounting-production.up.railway.app/api/v1/bot/clients/%7BclientId%7D/api-keys/%7BkeyId%7D (requires mutations.client-api-keys or mutations.* or *)

Response Expectations
- Successful mutation responses use { success: true, data: ... } envelopes.
- JSON responses include stable identifiers and ISO8601 timestamps.
- Error payload shape: { code, message, retryable, requestId }
- Cache headers and ETags are provided on public read endpoints.

Rate Limits
- Bot Events: 120 requests per 60-second window (configurable via BOT_RATE_LIMIT_EVENTS_PER_WINDOW).
- Trips Export: 60 requests per 60-second window.
- 429 responses include Retry-After header and retryable: true in error payload.

Dashboard Features (authenticated UI only)
- /reconciliation: Payment reconciliation dashboard with aggregated balances and per-trip quick payment recording.
- /trips/[tripId]: Trip command center with sticky metrics, 5-tab navigation, and context-aware speed-dial FAB.
- Global FAB: floating action button on every page for rapid trip, expense, and payment creation.

Privacy and Security
- Never crawl or index authenticated routes.
- Share tokens are unguessable but should still be treated as sensitive.
- Bot keys may be managed in Settings > Bot API Keys or via BOT_API_KEYS env.
- Bot auth accepts either Authorization: Bearer <BOT_API_KEY> or X-API-Key: <BOT_API_KEY>.
- MCP auth uses Authorization: Bearer <CLIENT_API_KEY> with tokens issued per client in the advisor dashboard.
- Managed keys can be scoped to reads only or to specific mutation families.
- Managed bot keys support rotation and optional source-IP allowlists.
- Respect robots.txt and X-Robots-Tag headers.