> ## 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.

# App Management

> REST endpoints for managing apps and installations

## Get All Apps

Get all apps, including running state for authenticated users.

### Endpoint

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

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

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

### Headers

```
Authorization: Bearer <coreToken>
```

### Query Parameters

Can also authenticate with API key:

* `apiKey`: API key for allowed packages
* `packageName`: Package name (must be in allowed list)
* `userId`: User email

### Response

```json theme={null}
{
  "success": true,
  "data": [
    {
      "_id": "app123",
      "packageName": "com.example.app",
      "name": "Example App",
      "description": "An example app",
      "logoURL": "https://cdn.example.com/icon.png",
      "appType": "STANDARD",
      "featured": false,
      "published": true,
      "minHardwareVersion": "1.0.0",
      "requiredHardware": ["CAMERA", "DISPLAY"],
      "is_running": false,
      "is_foreground": false,
      "lastActiveAt": "2024-01-20T10:30:00Z",
      "compatibility": {
        "isCompatible": true,
        "missingRequired": [],
        "missingOptional": [],
        "message": "Compatible with your device"
      }
    }
  ]
}
```

### Implementation

* **File**: `packages/cloud/src/routes/apps.routes.ts:336-478`
* **Middleware**: `unifiedAuthMiddleware` - Allows core token or API key auth
* **Service**: Enhances apps with hardware compatibility and running state

## Get Public Apps

Get all published apps without authentication requirements.

### Endpoint

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

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

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

### Headers

```
Authorization: Bearer <coreToken> (optional)
```

### Response

```json theme={null}
{
  "success": true,
  "data": [
    {
      "_id": "app123",
      "packageName": "com.example.app",
      "name": "Example App",
      "description": "An example app",
      "logoURL": "https://cdn.example.com/icon.png",
      "appType": "STANDARD",
      "featured": false,
      "published": true
    }
  ]
}
```

### Implementation

* **File**: `packages/cloud/src/routes/apps.routes.ts:483-509`
* **Middleware**: `authWithOptionalSession` - Works with or without auth
* **Service**: Filters by hardware compatibility if user session exists

## Search Apps

Search apps by name or description.

### Endpoint

<CodeGroup>
  ```bash Production theme={null}
  GET https://api.mentra.glass/api/apps/search?q=<query>
  ```

  ```bash Development theme={null}
  GET https://devapi.mentra.glass/api/apps/search?q=<query>
  ```

  ```bash Local theme={null}
  GET http://localhost:8002/api/apps/search?q=<query>
  ```
</CodeGroup>

### Query Parameters

| Parameter        | Type   | Description                       |
| ---------------- | ------ | --------------------------------- |
| `q`              | string | Search query (required)           |
| `organizationId` | string | Filter by organization (optional) |

### Response

```json theme={null}
{
  "success": true,
  "data": [
    {
      "_id": "app123",
      "packageName": "com.example.app",
      "name": "Example App",
      "description": "Matches your search query"
    }
  ]
}
```

### Implementation

* **File**: `packages/cloud/src/routes/apps.routes.ts:514-571`
* **Service**: Searches by name and description

## Get Available Apps

Get apps marked as available, with organization profiles.

### Endpoint

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

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

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

### Query Parameters

| Parameter        | Type   | Description                       |
| ---------------- | ------ | --------------------------------- |
| `organizationId` | string | Filter by organization (optional) |

### Response

```json theme={null}
{
  "success": true,
  "data": [
    {
      "_id": "app123",
      "packageName": "com.example.app",
      "name": "Example App",
      "developerProfile": {
        "company": "Example Company",
        "website": "https://example.com",
        "contactEmail": "contact@example.com",
        "description": "We build amazing apps",
        "logo": "https://example.com/logo.png"
      },
      "orgName": "Example Org"
    }
  ]
}
```

### Implementation

* **File**: `packages/cloud/src/routes/apps.routes.ts:1418-1497`
* **Service**: Enhances with organization profiles

## Get Installed Apps

Get apps installed by the current user.

### Endpoint

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

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

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

### Headers

```
Authorization: Bearer <coreToken>
```

### Response

```json theme={null}
{
  "success": true,
  "data": [
    {
      "_id": "app123",
      "packageName": "com.example.app",
      "name": "Example App",
      "installedDate": "2024-01-15T08:00:00Z",
      "compatibility": {
        "isCompatible": true,
        "missingRequired": [],
        "missingOptional": [],
        "message": "Compatible with your device"
      }
    }
  ]
}
```

### Implementation

* **File**: `packages/cloud/src/routes/apps.routes.ts:1273-1340`
* **Enhancement**: Includes installation date and hardware compatibility

## Get App Details

Get detailed information about a specific app.

### Endpoint

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

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

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

### Parameters

| Parameter     | Type   | Description               |
| ------------- | ------ | ------------------------- |
| `packageName` | string | App package name (in URL) |

### Response

```json theme={null}
{
  "success": true,
  "data": {
    "_id": "app123",
    "packageName": "com.example.app",
    "name": "Example App",
    "description": "Detailed app description",
    "logoURL": "https://cdn.example.com/icon.png",
    "appType": "STANDARD",
    "permissions": [
      {
        "type": "CAMERA",
        "description": "Take photos to analyze visual content"
      },
      {
        "type": "MICROPHONE",
        "description": "Listen to conversations for transcription"
      }
    ],
    "uninstallable": true,
    "developerProfile": {
      "company": "Example Company",
      "website": "https://example.com",
      "contactEmail": "contact@example.com",
      "description": "We build amazing apps",
      "logo": "https://example.com/logo.png"
    },
    "orgName": "Example Org"
  }
}
```

### Implementation

* **File**: `packages/cloud/src/routes/apps.routes.ts:576-661`
* **Service**: Includes organization profile and uninstallable flag

## Install App

Install an app for the current user.

### Endpoint

<CodeGroup>
  ```bash Production theme={null}
  POST https://api.mentra.glass/api/apps/install/:packageName
  ```

  ```bash Development theme={null}
  POST https://devapi.mentra.glass/api/apps/install/:packageName
  ```

  ```bash Local theme={null}
  POST http://localhost:8002/api/apps/install/:packageName
  ```
</CodeGroup>

### Headers

```
Authorization: Bearer <coreToken>
```

### Parameters

| Parameter     | Type   | Description               |
| ------------- | ------ | ------------------------- |
| `packageName` | string | App package name (in URL) |

### Response

Success (200):

```json theme={null}
{
  "success": true,
  "message": "App com.example.app installed successfully"
}
```

Error (400/404):

```json theme={null}
{
  "success": false,
  "message": "App is already installed" // or "App not found"
}
```

### Implementation

* **File**: `packages/cloud/src/routes/apps.routes.ts:1106-1195`
* **Validation**: Checks if app exists and not already installed
* **Service**: Updates user's installed apps list and broadcasts state

## Uninstall App

Remove an app from user's installed apps.

### Endpoint

<CodeGroup>
  ```bash Production theme={null}
  POST https://api.mentra.glass/api/apps/uninstall/:packageName
  ```

  ```bash Development theme={null}
  POST https://devapi.mentra.glass/api/apps/uninstall/:packageName
  ```

  ```bash Local theme={null}
  POST http://localhost:8002/api/apps/uninstall/:packageName
  ```
</CodeGroup>

### Headers

```
Authorization: Bearer <coreToken>
```

### Parameters

| Parameter     | Type   | Description               |
| ------------- | ------ | ------------------------- |
| `packageName` | string | App package name (in URL) |

### Response

Success (200):

```json theme={null}
{
  "success": true,
  "message": "App com.example.app uninstalled successfully"
}
```

Error (400/404):

```json theme={null}
{
  "success": false,
  "message": "App is not installed" // or "User not found"
}
```

### Implementation

* **File**: `packages/cloud/src/routes/apps.routes.ts:1200-1268`
* **Service**: Removes from user's installed apps and stops running instance

## Start App

Start an app session (alternative to voice command).

### Endpoint

<CodeGroup>
  ```bash Production theme={null}
  POST https://api.mentra.glass/api/apps/:packageName/start
  ```

  ```bash Development theme={null}
  POST https://devapi.mentra.glass/api/apps/:packageName/start
  ```

  ```bash Local theme={null}
  POST http://localhost:8002/api/apps/:packageName/start
  ```
</CodeGroup>

### Headers

```
Authorization: Bearer <coreToken>
```

### Parameters

| Parameter     | Type   | Description               |
| ------------- | ------ | ------------------------- |
| `packageName` | string | App package name (in URL) |

### Response

Success (200):

```json theme={null}
{
  "success": true,
  "data": {
    "status": "started",
    "packageName": "com.example.app",
    "appState": {
      /* current app state */
    }
  }
}
```

Error (404/500):

```json theme={null}
{
  "success": false,
  "message": "App not found" // or "Error starting app"
}
```

### Implementation

* **File**: `packages/cloud/src/routes/apps.routes.ts:666-877`
* **Middleware**: `unifiedAuthMiddleware` - Requires active session
* **Service**: Validates app exists, starts via AppManager, broadcasts state

## Stop App

Stop a running app session.

### Endpoint

<CodeGroup>
  ```bash Production theme={null}
  POST https://api.mentra.glass/api/apps/:packageName/stop
  ```

  ```bash Development theme={null}
  POST https://devapi.mentra.glass/api/apps/:packageName/stop
  ```

  ```bash Local theme={null}
  POST http://localhost:8002/api/apps/:packageName/stop
  ```
</CodeGroup>

### Headers

```
Authorization: Bearer <coreToken>
```

### Parameters

| Parameter     | Type   | Description               |
| ------------- | ------ | ------------------------- |
| `packageName` | string | App package name (in URL) |

### Response

Success (200):

```json theme={null}
{
  "success": true,
  "data": {
    "status": "stopped",
    "packageName": "com.example.app",
    "appState": {
      /* current app state */
    }
  }
}
```

Error (404/500):

```json theme={null}
{
  "success": false,
  "message": "App not found" // or "Error stopping app"
}
```

### Implementation

* **File**: `packages/cloud/src/routes/apps.routes.ts:882-1101`
* **Service**: Stops via AppManager, broadcasts state change

## Get Cloud Version

Get the current cloud version.

### Endpoint

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

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

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

### Response

```json theme={null}
{
  "version": "2.1.16"
}
```

### Implementation

* **File**: `packages/cloud/src/routes/apps.routes.ts:1518-1520`
* **Note**: Version is hardcoded in the source code

## System Apps

The following apps are marked as non-uninstallable:

* `live.captions.augmentos`
* `com.TeamopenSmartGlasses.SmartGlasses`
* `cloud.mentra.mira`
* `com.mentra.mira`

## Error Codes

| Code | Description                                       |
| ---- | ------------------------------------------------- |
| 400  | Missing required parameters or invalid request    |
| 401  | Unauthorized - invalid token or no active session |
| 403  | Forbidden - unauthorized package name             |
| 404  | App or user not found                             |
| 500  | Internal server error                             |

## Authentication Notes

The app endpoints support two authentication methods:

1. **Bearer Token**: Standard JWT authentication in Authorization header
2. **API Key**: For allowed packages (test.augmentos.mira, cloud.augmentos.mira, com.augmentos.mira) using query parameters:
   * `apiKey`: The API key
   * `packageName`: The package name
   * `userId`: User email

Device-specific operations (start/stop) require an active user session.