# What Kind of Input Does the TREK Server Expect?

> Discover the input TREK server expects including multipart form data for uploads, JSON for APIS, and URL-encoded params for auth. Learn how TREK processes requests.

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

---

**The TREK server expects HTTP requests with specific content types—`multipart/form-data` for file uploads, `application/json` for REST API and OAuth token exchanges, and URL-encoded query parameters for authorization flows—routed through Express middleware that enforces CORS, security headers, and authentication validation.**

The mauriceboe/TREK backend is built on Express wrapped by NestJS, exposing a RESTful interface that handles everything from image uploads to OAuth 2.0 flows. Understanding the exact input format is critical for client integration, as the server strictly validates content types, authentication tokens, and request bodies before routing to controllers.

## Input Categories and Expected Formats

The server organizes input handling into four distinct categories, each with strict requirements for HTTP method, path, and payload format.

### Static File Uploads and Retrieval

Upload endpoints accept binary data via `POST` requests with `multipart/form-data` encoding. These routes are defined in [`server/src/nest/platform/platform.routes.ts`](https://github.com/mauriceboe/TREK/blob/main/server/src/nest/platform/platform.routes.ts) and include:

- `/uploads/avatars` – User avatar images
- `/uploads/covers` – Cover images  
- `/uploads/journey` – Journey-related files

Static file retrieval uses `GET` requests to `/uploads/photos/:filename`, but requires authentication via either a valid **JWT** or a **share-token** that authorizes access to the specific trip.

### Health Checks and Discovery Metadata

Metadata endpoints use simple `GET` requests with no request body:

- `/api/health` – Returns `{ status: "ok" }` to verify server availability
- `/.well-known/openid-configuration` – Exposes OAuth discovery data for OpenID Connect clients
- `/.well-known/oauth-protected-resource` – Provides OAuth resource indicators

### OAuth 2.0 and MCP Protocol Flows

The OAuth implementation expects different input formats depending on the endpoint:

- **Authorization requests** (`GET /oauth/authorize`) require URL-encoded query parameters including `response_type`, `client_id`, `redirect_uri`, `scope`, `code_challenge`, and `code_challenge_method`
- **Token exchange** (`POST /oauth/token`) expects an `application/json` body containing `grant_type`, `code`, `redirect_uri`, and `code_verifier`
- **Registration and consent** (`POST /oauth/register`, `POST /oauth/consent`) accept JSON payloads
- **UserInfo** (`GET /oauth/userinfo`) requires a valid Bearer token in the Authorization header

The server also supports Model-Context-Protocol (MCP) specific metadata routes via the MCP SDK.

### RESTful Application API

Domain-specific resources under `/api/*` (such as `/api/trips`, `/api/places`, `/api/reservations`) accept standard REST methods:

- **GET** – For retrieval (query parameters for filtering)
- **POST**, **PUT**, **PATCH** – For creation and updates with `application/json` bodies
- **DELETE** – For resource removal

All application endpoints consume and return JSON, with validation handled by NestJS controllers.

## Global Request Processing Pipeline

Before reaching any route handler, every request passes through global middleware defined in [`server/src/middleware/globalMiddleware.ts`](https://github.com/mauriceboe/TREK/blob/main/server/src/middleware/globalMiddleware.ts). This pipeline configures the Express app to expect:

- **CORS** enabled for cross-origin requests (`app.use(cors({ origin, credentials: true }))`)
- **Security headers** via Helmet
- **JSON bodies** parsed with `express.json({ limit: '100kb' })`
- **URL-encoded bodies** parsed with `express.urlencoded({ extended: true })`
- **Cookies** parsed via `cookieParser()`
- **Global MFA enforcement** via the `enforceGlobalMfaPolicy` function

If a request violates these expectations—such as exceeding the 100kb JSON limit, missing required headers, or failing authentication—the server responds with standard HTTP status codes (`400`, `401`, `403`, or `404`) before reaching controller logic.

## Required Headers and Authentication

Successful requests must include appropriate headers:

- **Content-Type**: `multipart/form-data` for uploads, `application/json` for API endpoints, or `application/x-www-form-urlencoded` where specified
- **Authorization**: `Bearer <token>` for protected routes, or a valid share-token as a query parameter for photo access
- **Accept**: `application/json` for API responses

The authentication schema is defined in [`shared/src/auth/auth.schema.ts`](https://github.com/mauriceboe/TREK/blob/main/shared/src/auth/auth.schema.ts), which validates JWT payloads and password-version gates for protected endpoints.

## Code Examples

The following examples demonstrate the exact input format expected by the TREK server.

Health check requires no authentication or body:

```http
GET /api/health HTTP/1.1
Host: trek.example.com

```

Avatar upload uses multipart encoding:

```http
POST /uploads/avatars HTTP/1.1
Host: trek.example.com
Content-Type: multipart/form-data; boundary=----WebKitBoundary

------WebKitBoundary
Content-Disposition: form-data; name="file"; filename="avatar.png"
Content-Type: image/png

<binary data>
------WebKitBoundary--

```

OAuth authorization requests use query parameters:

```http
GET /oauth/authorize?response_type=code&client_id=trek-client&redirect_uri=https%3A%2F%2Fapp.example.com%2Fcallback&scope=read%20write&code_challenge=xyz&code_challenge_method=S256 HTTP/1.1
Host: trek.example.com

```

Token exchange requires JSON:

```http
POST /oauth/token HTTP/1.1
Host: trek.example.com
Content-Type: application/json

{
  "grant_type": "authorization_code",
  "code": "SplxlOBeZQQYbYS6WxSbIA",
  "redirect_uri": "https://app.example.com/callback",
  "code_verifier": "xyz"
}

```

## Summary

- **TREK** is an Express/NestJS server that strictly validates incoming HTTP requests through global middleware before routing to controllers.
- **File uploads** to `/uploads/*` require `multipart/form-data` POST requests, while photo retrieval requires JWT or share-token authentication.
- **OAuth flows** expect URL-encoded query parameters for authorization and JSON bodies for token exchanges.
- **Application APIs** under `/api/*` consume `application/json` with a 100kb size limit enforced by `express.json()` in [`server/src/middleware/globalMiddleware.ts`](https://github.com/mauriceboe/TREK/blob/main/server/src/middleware/globalMiddleware.ts).
- **Key files** controlling input expectations include [`server/src/nest/platform/platform.routes.ts`](https://github.com/mauriceboe/TREK/blob/main/server/src/nest/platform/platform.routes.ts) for route definitions and [`shared/src/auth/auth.schema.ts`](https://github.com/mauriceboe/TREK/blob/main/shared/src/auth/auth.schema.ts) for authentication validation.

## Frequently Asked Questions

### What Content-Type should I use for file uploads to TREK?

Upload endpoints such as `/uploads/avatars` and `/uploads/covers` expect `multipart/form-data` with the file included as a form field. The server parses these using standard Express middleware before storing the binary data.

### How do I authenticate requests to retrieve photos from the server?

Requests to `/uploads/photos/:filename` must include either a valid JWT in the Authorization header (`Bearer <token>`) or a share-token as a query parameter that authorizes access to the specific trip. Without one of these, the server returns a 401 or 403 response.

### Is there a request body size limit for JSON payloads?

Yes. According to the middleware configuration in [`server/src/middleware/globalMiddleware.ts`](https://github.com/mauriceboe/TREK/blob/main/server/src/middleware/globalMiddleware.ts), the server limits JSON bodies to 100kb via `express.json({ limit: '100kb' })`. Requests exceeding this limit receive a 413 Payload Too Large error.

### Does TREK support form-urlencoded request bodies?

Yes. The server explicitly configures `express.urlencoded({ extended: true })` in the global middleware to parse URL-encoded bodies. This is primarily used for OAuth endpoints and traditional form submissions, while the REST API prefers `application/json`.