App instances API

GET/v1/app-instances

List every app configured in the workspace, including its id, appKey, name, configuration, and node. This is the data behind the My apps grid.

curl "https://api.brixsignage.com/v1/app-instances" \
  -H "Authorization: Bearer $BRIX_API_KEY"

Response 200 Success.

{
  "data": [
    {
      "id": "app_3c4d5e6f7a8b9c0d",
      "spaceId": "space_1a2b3c4d5e6f7a8b",
      "appKey": "clock",
      "name": "Lobby clock",
      "config": {
        "format": "24h"
      },
      "nodeId": null,
      "lastSnapshotKey": null,
      "lastSnapshotAt": null,
      "importSourceId": null,
      "createdAt": "2026-09-28T09:00:00.000Z",
      "updatedAt": "2026-09-28T09:00:00.000Z",
      "deletedAt": null
    }
  ]
}

Response 401 Missing, expired or revoked bearer token.

Response 403 The token lacks the permission this operation needs (see `x-brix-permission`).

Response 5XX Server error. The body carries a `requestId` to quote to support.

POST/v1/app-instances

Configure an app for the workspace with an appKey, name, and optional config and nodeId. appKey must match one of the apps offered by the store; list the available keys first with GET /v1/apps/catalog. **Notes.** - The 201 body is the row as written, not re-read from the database, so columns the create does not set (for example lastSnapshotAt) are absent rather than null. GET returns every column.

Request body application/json

curl -X POST "https://api.brixsignage.com/v1/app-instances" \
  -H "Authorization: Bearer $BRIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"appKey":"clock","name":"Lobby clock","config":{"format":"24h"}}'

Response 201 Success.

{
  "data": {
    "id": "app_3c4d5e6f7a8b9c0d",
    "spaceId": "space_1a2b3c4d5e6f7a8b",
    "appKey": "clock",
    "name": "Lobby clock",
    "config": {
      "format": "24h"
    },
    "createdAt": "2026-09-28T09:00:00.000Z",
    "updatedAt": "2026-09-28T09:00:00.000Z",
    "deletedAt": null
  }
}

Response 401 Missing, expired or revoked bearer token.

Response 403 The token lacks the permission this operation needs (see `x-brix-permission`).

Response 422 Missing `appKey`/`name`, invalid JSON config, unknown app (`unknown_app`), or a location outside this workspace.

Response 5XX Server error. The body carries a `requestId` to quote to support.

GET/v1/app-instances/{id}

Retrieve one configured app instance, including its full configuration.

curl "https://api.brixsignage.com/v1/app-instances/{id}" \
  -H "Authorization: Bearer $BRIX_API_KEY"

Response 200 Success.

Response 401 Missing, expired or revoked bearer token.

Response 403 The token lacks the permission this operation needs (see `x-brix-permission`).

Response 404 No such app instance in this workspace.

Response 5XX Server error. The body carries a `requestId` to quote to support.

PATCH/v1/app-instances/{id}

Edit a configured app's name, configuration, or node. config replaces the entire configuration, so read the current value first before submitting changes.

Request body application/json

curl -X PATCH "https://api.brixsignage.com/v1/app-instances/{id}" \
  -H "Authorization: Bearer $BRIX_API_KEY" \
  -H "Content-Type: application/json"

Response 200 Success.

Response 401 Missing, expired or revoked bearer token.

Response 403 The token lacks the permission this operation needs (see `x-brix-permission`).

Response 404 No such app instance in this workspace.

Response 409 `conflict`: the row changed since `baseUpdatedAt`; the body carries `current`.

Response 422 Invalid JSON config or unknown app.

Response 5XX Server error. The body carries a `requestId` to quote to support.

DELETE/v1/app-instances/{id}

Delete a configured app instance. Screens and playlists that reference it stop showing it.

curl -X DELETE "https://api.brixsignage.com/v1/app-instances/{id}" \
  -H "Authorization: Bearer $BRIX_API_KEY"

Response 200 Success.

Response 401 Missing, expired or revoked bearer token.

Response 403 The token lacks the permission this operation needs (see `x-brix-permission`).

Response 404 No such app instance in this workspace.

Response 409 `content_shared`: it is shared into other places; `shareCount`, `crossSpaceShares`, `contentShares` say where. Repeat with `?force=true` to delete it and those shares.

Response 5XX Server error. The body carries a `requestId` to quote to support.

POST/v1/app-instances/{id}/duplicate

Create a copy of a configured app instance, including its configuration and home node, named "<name> copy". Use this to reuse a tuned configuration instead of re-entering it. Requires permission to create app instances at the source instance's node. **Notes.** - The 201 body is the row as written, not re-read from the database, so columns the create does not set (for example lastSnapshotAt) are absent rather than null. GET returns every column.

curl -X POST "https://api.brixsignage.com/v1/app-instances/{id}/duplicate" \
  -H "Authorization: Bearer $BRIX_API_KEY"

Response 201 Success.

Response 401 Missing, expired or revoked bearer token.

Response 403 The token lacks the permission this operation needs (see `x-brix-permission`).

Response 404 No such app instance in this workspace.

Response 5XX Server error. The body carries a `requestId` to quote to support.

POST/v1/app-instances/{id}/restore

Restore an app instance that was deleted within the last 30 days. The shares removed by the delete come back. Playlist items removed by the delete do not come back; add the app to those playlists again.

curl -X POST "https://api.brixsignage.com/v1/app-instances/{id}/restore" \
  -H "Authorization: Bearer $BRIX_API_KEY"

Response 200 Success.

Response 401 Missing, expired or revoked bearer token.

Response 403 The token lacks the permission this operation needs (see `x-brix-permission`).

Response 404 No such app instance in this workspace, or it was purged.

Response 409 `not_deleted`: it is not in the recycle bin.

Response 5XX Server error. The body carries a `requestId` to quote to support.

GET/v1/app-instances/{id}/thumbnail

Retrieve a shared preview image of an app instance. The same image is reused everywhere the app is previewed, so it loads quickly. Add ?fresh=1 to force a new image to be generated after a configuration change. **Notes.** - A cached image is image/jpeg. When there is none yet, the answer is a neutral image/svg+xml placeholder (header x-brix-cache: pending, not cached) while the image is drawn in the background; fetch it again shortly.

curl "https://api.brixsignage.com/v1/app-instances/{id}/thumbnail" \
  -H "Authorization: Bearer $BRIX_API_KEY"

Response 401 Missing, expired or revoked bearer token.

Response 403 The token lacks the permission this operation needs (see `x-brix-permission`).

Response 404 No such app instance in this workspace.

Response 503 `browser_unavailable`: images cannot be drawn in this environment.

Response 5XX Server error. The body carries a `requestId` to quote to support.