Nebula Cloud API

Nebula Cloud provides a REST API for managing miniapps, versions, publishing, and authentication. The service listens on port 3001 by default, with the API root path at /api.

Authentication

All APIs except publicly accessible endpoints require a Bearer Token in the request header:

Authorization: Bearer <accessToken>

Register

POST /api/auth/register

Returns: { id, email, accessToken, displayName }

Login CLI Required

POST /api/auth/login

Returns:

{
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "user": {
    "id": "user-uuid",
    "email": "[email protected]",
    "displayName": "User Name"
  }
}

Get Current User

GET /api/auth/me

Returns: { id, email, displayName, role, status }

CLI Device Authorization Flow CLI Required

The CLI uses the device authorization flow for login (recommended method):

1. Create CLI Session

POST /api/auth/cli/sessions

No authentication required, no request body.

Returns:

{
  "code": "ABCD-1234",
  "verificationUrl": "https://your-server.com/cli/verify?code=ABCD-1234",
  "expiresAt": "2025-01-15T10:45:00Z",
  "intervalSeconds": 5
}

The CLI prints the verificationUrl and automatically opens a browser. The user logs in and confirms authorization in the browser.

2. Poll Session Status

GET /api/auth/cli/sessions/{code}

The CLI polls this endpoint at intervalSeconds intervals until the status becomes approved.

Returns:

{
  "status": "pending | approved | expired",
  "accessToken": "eyJhbGci... (returned when status is approved)",
  "user": { "id": "...", "email": "...", "displayName": "..." }
}

3. Approve Session (user action in browser)

POST /api/auth/cli/sessions/{code}/approve
Authorization: Bearer <accessToken>

Runtime API Contract (Public Access)

The following interfaces are core dependencies for Nebula runtime to download and update miniapps. No user login authentication is required; they use query token authentication.

Get Installation Info Runtime Required

GET /api/mini-apps/access/versions/{versionId}/install?token={accessToken}

Returns installation metadata for the miniapp. The runtime uses this interface to obtain download URLs for the bundle and manifest.

Returns:

{
  "appId": "com.example.weather",
  "appName": "Weather",
  "versionId": "version-uuid",
  "version": "1.2.0",
  "releaseType": "RELEASE",
  "routeUrl": "nebula://com.example.weather",
  "bundleUrl": "https://your-server.com/api/mini-apps/access/versions/{versionId}/bundle?token=...",
  "bundles": {
    "ios": "https://your-server.com/api/mini-apps/access/versions/{versionId}/bundles/ios?token=...",
    "android": "https://your-server.com/api/mini-apps/access/versions/{versionId}/bundles/android?token=..."
  },
  "assetsUrl": {
    "ios": "https://your-server.com/api/mini-apps/access/versions/{versionId}/assets/ios?token=...",
    "android": "https://your-server.com/api/mini-apps/access/versions/{versionId}/assets/android?token=..."
  },
  "manifestUrl": "https://your-server.com/api/mini-apps/access/versions/{versionId}/manifest?token=..."
}

Download Bundle Runtime Required

GET /api/mini-apps/access/versions/{versionId}/bundle?token={accessToken}

Returns the JavaScript bundle file. Content-Type is application/javascript.

This is the Metro build output main.jsbundle. The runtime saves it to the sandbox directory /Documents/MiniApps/{appId}/.

Download Manifest Runtime Required

GET /api/mini-apps/access/versions/{versionId}/manifest?token={accessToken}

Returns the miniapp's manifest file (app.json). Content-Type is application/json.

The runtime uses this interface to check for version updates by comparing the locally installed version with the version field in the remote manifest.

Download Assets Runtime Required

GET /api/mini-apps/access/versions/{versionId}/assets/{platform}?token={accessToken}

Returns the miniapp's assets archive (zip) for the specified platform. Content-Type is application/zip.

The platform parameter accepts ios or android. The runtime downloads this zip, extracts it into the miniapp's sandbox directory, and places assets alongside the bundle file so React Native can resolve require('./image.png') references correctly.

URL Derivation Rules

URL Resolution Rules

The runtime resolves relative paths using serverBaseURL (configured in NebulaAPI.wrap()):

export default NebulaAPI.wrap({
  serverBaseURL: 'https://your-api.example.com/api',
  // ...
})(App);

Miniapp Management

List Miniapps

GET /api/mini-apps

Returns: MiniApp[]

Create Miniapp

POST /api/mini-apps

Returns: MiniApp

Get Miniapp Details

GET /api/mini-apps/{miniAppId}

Update Miniapp

PATCH /api/mini-apps/{miniAppId}

Get Workspace

GET /api/mini-apps/{miniAppId}/workspace

Returns miniapp details and all its versions.

Version Management

Upload Version CLI Required

POST /api/mini-apps/by-app-id/{appId}/versions/upload
Content-Type: multipart/form-data

The CLI's nebula miniapp upload command calls this interface.

Returns:

{
  "id": "version-id",
  "version": "1.0.0",
  "buildNumber": 1,
  "releaseType": "RELEASE",
  "status": "DRAFT"
}

After successful upload, this version automatically becomes the current experience version.

Submit for Review

POST /api/mini-apps/{miniAppId}/versions/{versionId}/review

Submits the current experience version or a historical version to the review process and updates currentReviewVersionId.

Publish Version

POST /api/mini-apps/{miniAppId}/versions/{versionId}/publish

After publishing: the version status updates to PUBLISHED, and the current release version updates to this version.

Rollback Version

POST /api/mini-apps/{miniAppId}/rollback

Delete Version

DELETE /api/mini-apps/{miniAppId}/versions/{versionId}

Admin Interfaces

List Users

GET /api/admin/users
Authorization: Bearer <admin-token>

Returns: { users: User[], auditLogs: AuditLog[] }

Create User

POST /api/admin/users
Authorization: Bearer <admin-token>

Update User

PATCH /api/admin/users/{userId}
Authorization: Bearer <admin-token>

Self-Hosted Backend Minimal Implementation Checklist

If you choose to build your own backend, here is the priority order for a minimal viable implementation:

For Runtime to Work Properly (Required)

1. GET .../install — Returns bundleUrl, bundles, assetsUrl, and manifestUrl
2. GET .../bundle — Returns JS bundle file
3. GET .../bundles/{platform} — Returns platform-specific JS bundle file
4. GET .../manifest — Returns manifest JSON
5. GET .../assets/{platform} — Returns platform-specific assets archive (zip)

For CLI to Work Properly (Recommended)

4. POST /api/auth/login or POST /api/auth/cli/sessions — Authentication
5. POST .../versions/upload — Accepts multipart file uploads (including assets)

For Complete Management Features (Optional)

6. Miniapp CRUD, version publish/rollback, admin panel, etc.

See Nebula Cloud Deployment for self-hosted backend guidance and recommended production architecture.