Skip to main content

Apps

Use the apps endpoints to discover content that can be installed on a device and to manage releases for apps owned by your account.

List available apps​

GET/v1/apps

Return all apps currently available to install as a flat, uncategorized list.

Request
GET /v1/apps
Authorization: Bearer <API key>
200 response
[
  {
    "id": "app-id",
    "name": "Weather",
    "description": "Current conditions and forecast for your location.",
    "version": "1.3.0",
    "author": {
      "name": "SolidPixels"
    }
  }
]

The response is a JSON array and does not group apps by category. If no apps are available, the endpoint returns 200 [].

App version lifecycle​

An app has an editable draft and a separately deployed version. Saving changes updates the draft only. Uploading a version creates an immutable snapshot with a PENDING status and submits it for review; it does not publish the draft.

The review can have one of three outcomes:

  • Approval changes the version to APPROVED and publishes it immediately.
  • A change request changes the version to CHANGES_REQUESTED and includes feedback you can address in a new submission.
  • Rejection changes the version to REJECTED without affecting the currently deployed release.

Only one version per app can await review at a time. An app's first submission puts the app in pending status. Later submissions leave an active app and its current release live throughout review. A new app is not listed or installable until its first version is approved.

Installations automatically use the app's currently deployed version. Deploying a previous approved version therefore rolls every installation back without requiring you to update those installations individually. Draft, pending, changes-requested, and rejected versions cannot be deployed.

App identifiers

appId can be the app ID returned by SolidPixels or its slug. Your API key can manage apps owned by the same account.

List versions​

GET/v1/apps/{appId}/versions

List a private app's immutable versions, newest first. This endpoint is available only for private apps.

Request
GET /v1/apps/{appId}/versions
Authorization: Bearer <API key>
200 response
[
  {
    "id": "version-id",
    "version": "1.1.0",
    "scriptLanguage": "STARLARK",
    "checksum": "6e409...",
    "status": "APPROVED",
    "reviewedAt": "2026-09-08T16:00:00.000Z",
    "rejectionReason": null,
    "reviewSummary": null,
    "reviewComments": [],
    "createdAt": "2026-09-08T15:30:00.000Z",
    "deployed": true
  },
  {
    "id": "previous-version-id",
    "version": "1.0.0",
    "scriptLanguage": "STARLARK",
    "checksum": "826a1...",
    "status": "REJECTED",
    "reviewedAt": "2026-09-01T14:00:00.000Z",
    "rejectionReason": "The app fails when the location is omitted.",
    "reviewSummary": null,
    "reviewComments": [],
    "createdAt": "2026-09-01T12:00:00.000Z",
    "deployed": false
  }
]

A public app—or a legacy app without the private attribute—returns 403. A private app without uploaded versions returns 200 [].

Upload an app version​

POST/v1/apps/{appId}/upload

Create an immutable app snapshot and submit it for review.

Request
POST /v1/apps/{appId}/upload
Authorization: Bearer <API key>
Content-Type: application/json
Request body
{
  "version": "1.1.0",
  "scriptContent": "def main():\n  return render.Text(\"Hello\")",
  "scriptLanguage": "STARLARK"
}

version must be 1–64 characters and may contain letters, numbers, dots, dashes, and underscores. scriptLanguage must be STARLARK or TYPESCRIPT. Unknown fields are rejected.

Uploading does not change the currently deployed version.

201 response
{
  "id": "version-id",
  "version": "1.1.0",
  "scriptLanguage": "STARLARK",
  "checksum": "6e409...",
  "status": "PENDING",
  "reviewedAt": null,
  "rejectionReason": null,
  "reviewSummary": null,
  "reviewComments": [],
  "createdAt": "2026-09-08T15:30:00.000Z",
  "deployed": false
}

Uploading a version name that already exists, or submitting while another version of the app is awaiting review, returns 409. Invalid bodies return 400.

Deploy or roll back an app​

POST/v1/apps/{appId}/deploy

Deploy an approved version. Selecting an older version rolls the app back.

Request
POST /v1/apps/{appId}/deploy
Authorization: Bearer <API key>
Content-Type: application/json
Request body
{
  "version": "1.1.0"
}

Every installation uses the selected version on its next render.

200 response
{
  "id": "version-id",
  "version": "1.1.0",
  "scriptLanguage": "STARLARK",
  "checksum": "6e409...",
  "status": "APPROVED",
  "reviewedAt": "2026-09-08T16:00:00.000Z",
  "rejectionReason": null,
  "reviewSummary": null,
  "reviewComments": [],
  "createdAt": "2026-09-08T15:30:00.000Z",
  "deployed": true
}

Missing apps or versions return 404; attempting to deploy a version that has not been approved returns 409; requests without permission to manage the app return 403.

Was this helpful?