Complete Guide to TREK API Endpoints: NestJS REST API Reference

TREK exposes a comprehensive REST API built on NestJS, grouping HTTP routes under /api/* with feature-specific controllers handling trips, reservations, weather, and 20+ additional functional domains.

The TREK travel planning platform (mauriceboe/TREK) organizes its backend as a modular NestJS application where each @Controller decorator defines a base path and standard CRUD verbs. All endpoints are rooted at /api/ (with rare public exceptions under /oauth and /public/), making the API contract predictable for client integrations.

Core Trip Management Endpoints

The trip lifecycle is managed through the primary api/trips hierarchy defined in server/src/nest/trips/trips.controller.ts.

Base Path: api/trips

• GET /api/trips – List all user trips
• POST /api/trips – Create a new trip with metadata (name, dates)
• GET /api/trips/:tripId – Retrieve specific trip details
• PATCH /api/trips/:tripId – Update trip metadata
• DELETE /api/trips/:tripId – Remove a trip
• POST /api/trips/:tripId/invite-link – Generate shareable invite links

Invite links are handled separately via server/src/nest/trip-invite/trip-invite.controller.ts under api/trip-invites.

Reservations and accommodations live under the trip namespace:

• GET /api/trips/:tripId/reservations – List all reservations (source: server/src/nest/reservations/reservations.controller.ts)
• POST /api/trips/:tripId/reservations – Add flight, hotel, or activity bookings
• GET /api/trips/:tripId/accommodations – Accommodation-specific queries (source: server/src/nest/reservations/accommodations.controller.ts)

Itinerary & Daily Planning Endpoints

Day-by-day planning uses nested resources under api/trips/:tripId/days implemented in server/src/nest/days/days.controller.ts.

Base Path: api/trips/:tripId/days

• GET /api/trips/:tripId/days – Retrieve itinerary days
• POST /api/trips/:tripId/days/:dayId/notes – Attach notes to specific days (source: server/src/nest/days/day-notes.controller.ts)

Task assignments are managed via:

• GET /api/trips/:tripId/assignments – List assigned tasks
• POST /api/trips/:tripId/days/:dayId/assignments – Create tasks for specific days (source: server/src/nest/assignments/assignments.controller.ts)

Budget tracking shares the trip namespace:

• GET /api/trips/:tripId/budget – Retrieve expense summary
• POST /api/trips/:tripId/budget – Add budget items (source: server/src/nest/budget/budget.controller.ts)

Content & Media Endpoints

TREK separates media handling from trip data to support file uploads and external integrations.

Photos (server/src/nest/photos/photos.controller.ts):

• POST /api/photos – Upload image assets via multipart/form-data
• GET /api/photos – Retrieve photo metadata
• DELETE /api/photos/:id – Remove photo assets

Files (server/src/nest/files/files.controller.ts):

• GET /api/trips/:tripId/files – List file attachments
• POST /api/trips/:tripId/files – Upload arbitrary documents

Places & Search (server/src/nest/places/places.controller.ts):

• GET /api/places – Search locations
• POST /api/trips/:tripId/places – Add discovered places to a trip

Utility & Service Endpoints

Standalone utility endpoints provide real-time data without trip-scoped resources.

Weather (server/src/nest/weather/weather.controller.ts):

fetch('/api/weather?lat=48.8566&lon=2.3522')
  .then(r => r.json())
  .then(weather => console.log('Forecast:', weather));

Transit (server/src/nest/transit/transit.controller.ts):

• GET /api/transit – Query public transport routes and schedules

Maps (server/src/nest/maps/maps.controller.ts):

• GET /api/maps – Route calculations and OSRM utilities

Airports (server/src/nest/airports/airports.controller.ts):

• GET /api/airports – Airport code lookup and IATA data

Administrative & System Endpoints

System-wide configuration and monitoring endpoints support user preferences and operational health.

Settings & Configuration (server/src/nest/settings/settings.controller.ts):

• GET /api/settings – User configuration values
• PATCH /api/settings – Update preferences

Notifications (server/src/nest/notifications/notifications.controller.ts):

• GET /api/notifications – Push notification history
• PATCH /api/notifications – Update notification preferences

System Notices (server/src/nest/system-notices/system-notices.controller.ts):

• GET /api/system-notices – Global announcements and maintenance alerts

Feeds (server/src/nest/feeds/feeds.controller.ts):

• GET /api/feed/:tripId – Trip activity streams
• GET /api/feed/user – User-specific activity feeds

Health & Backup:

• GET /api/health and GET /api/_nest – Liveness/readiness checks
• GET /api/backup – System export/import operations

Authentication & Public Access

Authentication follows OAuth 2.0 and OIDC standards with passkey support.

Primary Auth (server/src/nest/auth/auth.controller.ts):

• POST /api/auth/login – Credential exchange
• POST /api/auth/refresh – Token refresh
• POST /api/auth/passkey – WebAuthn registration

Public OAuth (server/src/nest/oauth/oauth-public.controller.ts):

• POST /oauth/token – Public token exchange (unlike /api/* routes)

OIDC (server/src/nest/oidc/oidc.controller.ts):

• GET /api/auth/oidc – OpenID Connect configuration endpoints

MFA is enforced via middleware at api/mfa (mfaPolicy middleware) rather than a dedicated controller.

Public Sharing (server/src/nest/public-journey/public-journey.controller.ts):

• GET /api/public/journey – Read-only public trip data for shareable URLs

Add-ons & Extensions

TREK supports optional features under the api/addons/* namespace, implemented as thin controller wrappers delegating to service layers.

Collections (api/addons/collections) – User-defined item collections
Atlas (api/addons/atlas) – Geographic atlas data
Vacay (api/addons/vacay) – Vacation-specific utilities

Plugins (server/src/nest/plugins/):

• GET /api/plugins – List installed plugins
• GET /api/plugins/:pluginId – Proxy to sandboxed iframe
• POST /api/admin/plugins – Plugin management (admin only)

MCP (Model-Context-Protocol) (api/admin/llm/local) – Internal LLM tooling for AI-assisted features.

Integrations (api/integrations/memories/*):

• GET /api/integrations/memories/unified – Unified photo memory sync
• GET /api/integrations/memories/synologyphotos – Synology Photos connector
• GET /api/integrations/memories/immich – Immich photo server integration

Implementation Details

According to the mauriceboe/TREK source code, endpoint routing relies on NestJS decorators. The @Controller('api/trips') class in trips.controller.ts defines the base path, while method decorators like @Get(), @Post(), and @Param('tripId') handle dynamic segments.

Dynamic IDs (:tripId, :dayId, :pluginId) are resolved by NestJS param decorators and validated by service layers (tripService, dayService). The concrete HTTP verbs and JSON schemas are defined within each controller file under server/src/nest/, wired into the application at startup via server/src/bootstrap.ts.

Summary

• TREK API endpoints are organized under /api/* with feature-specific controllers in server/src/nest/
• Trip management uses api/trips with nested resources for days, reservations, budget, and files
• Media handling separates photos (api/photos) and files (api/trips/:tripId/files) from trip data
• Utility endpoints provide weather, transit, maps, and airport data without authentication requirements
• Add-ons extend functionality via api/addons/* and api/plugins/* namespaces
• Authentication supports OAuth 2.0, OIDC, and passkeys under api/auth and /oauth

Frequently Asked Questions

What is the base URL for TREK API endpoints?

All TREK API endpoints are prefixed with /api/ (e.g., https://trek.example.com/api/trips). The only exceptions are public OAuth routes (/oauth/token) and health checks (/api/_nest or /api/health), which are configured at the root level.

How does TREK handle authentication for API endpoints?

According to the source code in server/src/nest/auth/auth.controller.ts, TREK uses Bearer token authentication for most endpoints. Clients must include an Authorization: Bearer {accessToken} header. Public endpoints like /api/public/journey and /oauth endpoints do not require authentication.

What are the dynamic path parameters in TREK API endpoints?

Dynamic segments use colon-prefixed parameters such as :tripId, :dayId, and :pluginId. These are resolved by NestJS @Param() decorators and validated by service layers (e.g., tripService.validateTripId()). Example: GET /api/trips/12345/days retrieves days for trip ID 12345.

How are add-ons accessed via the TREK API?

Optional features are namespaced under api/addons/* (e.g., api/addons/collections, api/addons/vacay). These controllers are thin wrappers that delegate to specific services and can be enabled or disabled via the admin UI without affecting core trip endpoints.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}