> ## Documentation Index
> Fetch the complete documentation index at: https://cloud-docs.mentra.glass/llms.txt
> Use this file to discover all available pages before exploring further.

# Photos

> REST endpoints for photo upload and management

## Upload Photo

Upload a photo from smart glasses to the cloud.

### Endpoint

<CodeGroup>
  ```bash Production theme={null}
  POST https://api.mentra.glass/api/photos/upload
  ```

  ```bash Development theme={null}
  POST https://devapi.mentra.glass/api/photos/upload
  ```

  ```bash Local theme={null}
  POST http://localhost:8002/api/photos/upload
  ```
</CodeGroup>

### Headers

```
Authorization: Bearer <glassesJwt>
Content-Type: multipart/form-data
```

<Note>
  This endpoint requires glasses authentication, not regular user authentication.
</Note>

### Request Body

Multipart form data with:

* `file`: The image file (JPEG, PNG, etc.)
* `metadata`: JSON string containing request metadata

Metadata format:

```json theme={null}
{
  "requestId": "photo-request-123"
}
```

### Response

Success (200):

```json theme={null}
{
  "success": true,
  "photoUrl": "https://api.mentra.glass/uploads/2024-01-20T10-30-00-000Z_uuid.jpg",
  "requestId": "photo-request-123"
}
```

Error (400):

```json theme={null}
{
  "error": "Request ID is required" // or "No photo uploaded", "Invalid metadata format", "Invalid file data - no buffer"
}
```

Error (404):

```json theme={null}
{
  "error": "User session not found"
}
```

Error (500):

```json theme={null}
{
  "error": "Failed to process photo upload" // or "Failed to save photo"
}
```

### Implementation

* **File**: `packages/cloud/src/routes/photos.routes.ts:109-198`
* **Middleware**: `validateGlassesAuth` - Validates glasses JWT token
* **File Limits**: 10MB maximum file size
* **Storage**: Memory storage with file system persistence

### Upload Process

1. Validates glasses authentication
2. Parses metadata from request body
3. Validates file is an image
4. Saves photo to disk in `uploads/photos` directory
5. Broadcasts to apps subscribed to `PHOTO_TAKEN` events
6. Returns public URL for the photo

### File Validation

* Only accepts files with `image/*` mimetype
* Maximum file size: 10MB
* Requires valid `requestId` in metadata
* File must have a buffer

### Automatic Cleanup

Photos older than 5 minutes are automatically deleted from the upload directory when new photos are uploaded.

### Broadcast Event

Apps subscribed to `PHOTO_TAKEN` stream receive the photo data via WebSocket:

* Photo buffer data
* MIME type

## Test Endpoint

Simple test endpoint to verify photo routes are working.

### Endpoint

<CodeGroup>
  ```bash Production theme={null}
  GET https://api.mentra.glass/api/photos/test
  ```

  ```bash Development theme={null}
  GET https://devapi.mentra.glass/api/photos/test
  ```

  ```bash Local theme={null}
  GET http://localhost:8002/api/photos/test
  ```
</CodeGroup>

### Response

```json theme={null}
{
  "message": "Photo routes are working"
}
```

## Error Codes

| Code | Description                                                      |
| ---- | ---------------------------------------------------------------- |
| 400  | Invalid request (missing file, invalid metadata, wrong mimetype) |
| 401  | Unauthorized - invalid glasses token                             |
| 404  | User session not found                                           |
| 500  | Internal server error                                            |

## Notes

* Photos are saved to the file system in `uploads/photos` directory
* Files are named with timestamp and UUID for uniqueness
* Old photos are automatically cleaned up after 5 minutes
* The photo URL is constructed using `CLOUD_PUBLIC_URL` environment variable
* Apps receive photo data through WebSocket broadcast, not via REST
* The endpoint handles multipart form data uploads

<Warning>
  The current implementation has a hardcoded user email ("[loriamistadi75@gmail.com](mailto:loriamistadi75@gmail.com)") at line 148 which should be replaced with proper user identification from the request.
</Warning>