# Complete Guide to TREK API Endpoints: NestJS REST API Reference

> Explore TREK API endpoints in this complete guide to the NestJS REST API reference. Discover routes for trips, reservations, weather, and more under api.*.

- Repository: [Maurice/TREK](https://github.com/mauriceboe/TREK)
- Tags: api-reference
- Published: 2026-07-10

---

**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`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/server/src/nest/weather/weather.controller.ts)):

```javascript
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`](https://github.com/mauriceboe/TREK/blob/main/server/src/nest/transit/transit.controller.ts)):

- **GET /api/transit** – Query public transport routes and schedules

**Maps** ([`server/src/nest/maps/maps.controller.ts`](https://github.com/mauriceboe/TREK/blob/main/server/src/nest/maps/maps.controller.ts)):

- **GET /api/maps** – Route calculations and OSRM utilities

**Airports** ([`server/src/nest/airports/airports.controller.ts`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/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.