App Management - MentraOS Cloud

Get All Apps

Get all apps, including running state for authenticated users.

Endpoint

GET https://api.mentra.glass/api/apps

GET https://devapi.mentra.glass/api/apps

GET http://localhost:8002/api/apps

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

{
  "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

GET https://api.mentra.glass/api/apps/public

GET https://devapi.mentra.glass/api/apps/public

GET http://localhost:8002/api/apps/public

Headers

Authorization: Bearer <coreToken> (optional)

Response

{
  "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

GET https://api.mentra.glass/api/apps/search?q=<query>

GET https://devapi.mentra.glass/api/apps/search?q=<query>

GET http://localhost:8002/api/apps/search?q=<query>

Query Parameters

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

Response

{
  "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

GET https://api.mentra.glass/api/apps/available

GET https://devapi.mentra.glass/api/apps/available

GET http://localhost:8002/api/apps/available

Query Parameters

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

Response

{
  "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

GET https://api.mentra.glass/api/apps/installed

GET https://devapi.mentra.glass/api/apps/installed

GET http://localhost:8002/api/apps/installed

Headers

Authorization: Bearer <coreToken>

Response

{
  "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

GET https://api.mentra.glass/api/apps/:packageName

GET https://devapi.mentra.glass/api/apps/:packageName

GET http://localhost:8002/api/apps/:packageName

Parameters

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

Response

{
  "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

POST https://api.mentra.glass/api/apps/install/:packageName

POST https://devapi.mentra.glass/api/apps/install/:packageName

POST http://localhost:8002/api/apps/install/:packageName

Headers

Authorization: Bearer <coreToken>

Parameters

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

Response

Success (200):

{
  "success": true,
  "message": "App com.example.app installed successfully"
}

Error (400/404):

{
  "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

POST https://api.mentra.glass/api/apps/uninstall/:packageName

POST https://devapi.mentra.glass/api/apps/uninstall/:packageName

POST http://localhost:8002/api/apps/uninstall/:packageName

Headers

Authorization: Bearer <coreToken>

Parameters

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

Response

Success (200):

{
  "success": true,
  "message": "App com.example.app uninstalled successfully"
}

Error (400/404):

{
  "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

POST https://api.mentra.glass/api/apps/:packageName/start

POST https://devapi.mentra.glass/api/apps/:packageName/start

POST http://localhost:8002/api/apps/:packageName/start

Headers

Authorization: Bearer <coreToken>

Parameters

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

Response

Success (200):

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

Error (404/500):

{
  "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

POST https://api.mentra.glass/api/apps/:packageName/stop

POST https://devapi.mentra.glass/api/apps/:packageName/stop

POST http://localhost:8002/api/apps/:packageName/stop

Headers

Authorization: Bearer <coreToken>

Parameters

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

Response

Success (200):

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

Error (404/500):

{
  "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

GET https://api.mentra.glass/api/apps/version

GET https://devapi.mentra.glass/api/apps/version

GET http://localhost:8002/api/apps/version

Response

{
  "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:

Bearer Token: Standard JWT authentication in Authorization header
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.

​Get All Apps

​Endpoint

​Headers

​Query Parameters

​Response

​Implementation

​Get Public Apps

​Endpoint

​Headers

​Response

​Implementation

​Search Apps

​Endpoint

​Query Parameters

​Response

​Implementation

​Get Available Apps

​Endpoint

​Query Parameters

​Response

​Implementation

​Get Installed Apps

​Endpoint

​Headers

​Response

​Implementation

​Get App Details

​Endpoint

​Parameters

​Response

​Implementation

​Install App

​Endpoint

​Headers

​Parameters

​Response

​Implementation

​Uninstall App

​Endpoint

​Headers

​Parameters

​Response

​Implementation

​Start App

​Endpoint

​Headers

​Parameters

​Response

​Implementation

​Stop App

​Endpoint

​Headers

​Parameters

​Response

​Implementation

​Get Cloud Version

​Endpoint

​Response

​Implementation

​System Apps

​Error Codes

​Authentication Notes

Get All Apps

Endpoint

Headers

Query Parameters

Response

Implementation

Get Public Apps

Endpoint

Headers

Response

Implementation

Search Apps

Endpoint

Query Parameters

Response

Implementation

Get Available Apps

Endpoint

Query Parameters

Response

Implementation

Get Installed Apps

Endpoint

Headers

Response

Implementation

Get App Details

Endpoint

Parameters

Response

Implementation

Install App

Endpoint

Headers

Parameters

Response

Implementation

Uninstall App

Endpoint

Headers

Parameters

Response

Implementation

Start App

Endpoint

Headers

Parameters

Response

Implementation

Stop App

Endpoint

Headers

Parameters

Response

Implementation

Get Cloud Version

Endpoint

Response

Implementation

System Apps

Error Codes

Authentication Notes