Skip to main content
API docs by Redocly

Wallboard API - Customer-owned Apps (2.0)

Create, upload and manage private apps owned by the selected customer. All operations require OWNER access. The customerId selector is available to callers permitted to manage that customer; these operations cannot transfer an app to another customer. Available app types depend on the server version.

Create, upload and enable an app

  1. Create an app with POST /api/customApp/myApps. Supply a nonempty name; type defaults to WIDGET and widgetCategory to CUSTOM_APPS. The new app is disabled and private, with automatic repository updates disabled.
  2. Upload its ZIP with the resumable workflow below, or use POST /api/customApp/myApps/{id}/upload with the multipart field file.
  3. Enable it with PUT /api/customApp/myApps/{id} and {"enabled":true}.
Type ZIP requirements
WIDGET config.json with nonempty name and version, each at most 255 characters; these determine package identity/version
HTML_BUNDLE index.html at the ZIP root; the server generates the manifest and identity

Uploading replaces the package. Identity conflicts in the customer's effective catalog return 409. Missing or invalid required package content returns 400. Downloading an app before its first package upload fails.

Resumable ZIP upload

Use an existing customer app for this workflow. ZIP validation and installation happen at completion.

  1. POST /api/customApp/myApps/{id}/upload/init with JSON name, size, contentType and totalChunks. The response gives an uploadId, relative part URLs, maxChunkSize and expiresAt.
  2. PUT raw ZIP bytes to each returned URL with Content-Type: application/octet-stream and an exact Content-Length. Part numbers start at 1; each successful response returns partNumber and etag.
  3. GET /api/customApp/myApps/{id}/upload/{uploadId}/recover to find uploaded and missing parts. Send missing parts while the status is UPLOADING.
  4. POST /api/customApp/myApps/{id}/upload/{uploadId}/complete without a body to validate and install the ZIP. The response is the updated app; a successful part PUT alone does not establish a valid complete bundle.
  5. DELETE /api/customApp/myApps/{id}/upload/{uploadId} to cancel an upload.

Use the same account, app and selected customer throughout. If using customerId, also add it to each returned part URL. A missing or expired upload requires a new initialization.

Manage existing apps

List the customer's own apps with GET /api/customApp/myApps; this is not the combined platform/customer catalog. Updates accept name, description, enabled and widgetCategory. Ownership, app type and repository-update settings cannot be changed through these operations. Use returned appRootPath, entryPoint and iconPath values when available instead of constructing storage URLs.

custom-app

List private apps

Minimum role: OWNER.

Authorizations:
bearer
query Parameters
customerId
integer <int64>

Select a customer/tenant within the caller's access. When this parameter is optional, omitting it uses the caller's scope: global for ADMIN, owned member customers for a network owner, and the own customer for other callers. Use an explicit customerId for customer-specific operations. Requiredness is declared per endpoint.

page
integer >= 0
Default: 0

Page index (0-based)

size
integer >= 1
Default: 20

Requested page size; server limits and endpoint overrides apply.

sort
string
Example: sort=name,asc

Sort expression. Format: field,direction

  • Directions: asc, desc
  • Multiple sorts: sort=name,asc&sort=lastActivity,desc
  • Nested fields: sort=content.name,asc
search
string

WBQL filter expression. Operators: : (contains), = (equals), ≠, ∉, ^ (starts with), >, ≥, <, ≤, ∈ (in set). Logic: , (AND), | (OR). Special: NULL, !NULL. Example: name:lobby,deviceStatus=ONLINE

select
string

Field projection. * = all primitives, field,field = specific, relation(fields) = nested. Example: select=*,customer(id,name)

Responses

Response samples

Content type
application/json
{
  • "first": true,
  • "last": true,
  • "number": 0,
  • "numberOfElements": 0,
  • "totalElements": 0,
  • "totalPages": 0,
  • "size": 0,
  • "content": [
    ]
}

Create a disabled private app

Minimum role: OWNER.

Authorizations:
bearer
query Parameters
customerId
integer <int64>

Select a customer/tenant within the caller's access. When this parameter is optional, omitting it uses the caller's scope: global for ADMIN, owned member customers for a network owner, and the own customer for other callers. Use an explicit customerId for customer-specific operations. Requiredness is declared per endpoint.

Request Body schema: application/json
required
name
required
string non-empty
description
string
type
string
Default: "WIDGET"
Enum: "WIDGET" "HTML_BUNDLE"
widgetCategory
string
Default: "CUSTOM_APPS"
Enum: "CUSTOM_APPS" "BASIC" "MEDIA" "CHARTS" "INTERACTIONS"

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "type": "WIDGET",
  • "widgetCategory": "CUSTOM_APPS"
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "appId": "string",
  • "description": "string",
  • "storageId": "string",
  • "enabled": true,
  • "availableToAllCustomers": true,
  • "version": "string",
  • "repositoryVersion": "string",
  • "ownershipType": "PLATFORM",
  • "customerId": 0,
  • "sizeBytes": 0,
  • "lastUpdated": 0,
  • "type": "WIDGET",
  • "widgetCategory": "CUSTOM_APPS",
  • "config": null,
  • "appRootPath": "string",
  • "entryPoint": "string",
  • "iconPath": "string",
  • "resourceList": [
    ]
}

Update a private app

Minimum role: OWNER.

Authorizations:
bearer
path Parameters
id
required
integer <int64>
query Parameters
customerId
integer <int64>

Select a customer/tenant within the caller's access. When this parameter is optional, omitting it uses the caller's scope: global for ADMIN, owned member customers for a network owner, and the own customer for other callers. Use an explicit customerId for customer-specific operations. Requiredness is declared per endpoint.

Request Body schema: application/json
required
name
string
enabled
boolean
description
string
widgetCategory
string
Enum: "CUSTOM_APPS" "BASIC" "MEDIA" "CHARTS" "INTERACTIONS"

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "enabled": true,
  • "description": "string",
  • "widgetCategory": "CUSTOM_APPS"
}

Delete a private app

Minimum role: OWNER.

Authorizations:
bearer
path Parameters
id
required
integer <int64>
query Parameters
customerId
integer <int64>

Select a customer/tenant within the caller's access. When this parameter is optional, omitting it uses the caller's scope: global for ADMIN, owned member customers for a network owner, and the own customer for other callers. Use an explicit customerId for customer-specific operations. Requiredness is declared per endpoint.

Responses

Upload a private app ZIP

Multipart field file, Content-Type application/zip or application/x-zip-compressed. WIDGET packages require config.json; HTML_BUNDLE packages require root index.html.

Minimum role: OWNER.

Authorizations:
bearer
path Parameters
id
required
integer <int64>
query Parameters
customerId
integer <int64>

Select a customer/tenant within the caller's access. When this parameter is optional, omitting it uses the caller's scope: global for ADMIN, owned member customers for a network owner, and the own customer for other callers. Use an explicit customerId for customer-specific operations. Requiredness is declared per endpoint.

Request Body schema: multipart/form-data
required
file
required
string <binary>

Responses

Initialize a private app ZIP upload

Start a resumable ZIP upload for an existing customer app.

Minimum role: OWNER.

Authorizations:
bearer
path Parameters
id
required
integer <int64>
query Parameters
customerId
integer <int64>

Select a customer/tenant within the caller's access. When this parameter is optional, omitting it uses the caller's scope: global for ADMIN, owned member customers for a network owner, and the own customer for other callers. Use an explicit customerId for customer-specific operations. Requiredness is declared per endpoint.

Request Body schema: application/json
required
name
required
string [ 1 .. 255 ] characters

Nonblank upload name

size
required
integer <int64> [ 1 .. 1073741824 ]

Declared ZIP size in bytes

contentType
required
string

application/zip or application/x-zip-compressed, case-insensitive

totalChunks
required
integer <int32> [ 1 .. 10000 ]

Declared number of parts

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "size": 1,
  • "contentType": "string",
  • "totalChunks": 1
}

Response samples

Content type
application/json
{
  • "uploadId": "string",
  • "name": "string",
  • "size": 1,
  • "maxChunkSize": 1,
  • "totalChunks": 1,
  • "uploadUrls": {
    },
  • "expiresAt": 0
}

Upload a private app ZIP part

Send raw ZIP bytes with an exact Content-Length for the chosen part number. Completion separately validates the full upload.

Minimum role: OWNER.

Authorizations:
bearer
path Parameters
id
required
integer <int64>
uploadId
required
string
partNumber
required
integer <int32> [ 1 .. 10000 ]

1-based part number within the declared totalChunks

query Parameters
customerId
integer <int64>

Select a customer/tenant within the caller's access. When this parameter is optional, omitting it uses the caller's scope: global for ADMIN, owned member customers for a network owner, and the own customer for other callers. Use an explicit customerId for customer-specific operations. Requiredness is declared per endpoint.

header Parameters
Content-Length
required
integer <int64> [ 1 .. 104857600 ]
Request Body schema: application/octet-stream
required
string <binary>

Responses

Response samples

Content type
application/json
{
  • "partNumber": 0,
  • "etag": "string"
}

Recover a private app ZIP upload

Read the upload status and the part numbers already received or still missing.

Minimum role: OWNER.

Authorizations:
bearer
path Parameters
id
required
integer <int64>
uploadId
required
string
query Parameters
customerId
integer <int64>

Select a customer/tenant within the caller's access. When this parameter is optional, omitting it uses the caller's scope: global for ADMIN, owned member customers for a network owner, and the own customer for other callers. Use an explicit customerId for customer-specific operations. Requiredness is declared per endpoint.

Responses

Response samples

Content type
application/json
{
  • "uploadId": "string",
  • "name": "string",
  • "size": 1,
  • "totalChunks": 1,
  • "uploadedChunks": [
    ],
  • "missingChunks": [
    ],
  • "status": "UPLOADING",
  • "expiresAt": 0
}

Complete a private app ZIP upload

Complete and validate all uploaded parts, then install the ZIP and return the app. Missing parts, a size mismatch or missing required package content return 400.

Minimum role: OWNER.

Authorizations:
bearer
path Parameters
id
required
integer <int64>
uploadId
required
string
query Parameters
customerId
integer <int64>

Select a customer/tenant within the caller's access. When this parameter is optional, omitting it uses the caller's scope: global for ADMIN, owned member customers for a network owner, and the own customer for other callers. Use an explicit customerId for customer-specific operations. Requiredness is declared per endpoint.

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "appId": "string",
  • "description": "string",
  • "storageId": "string",
  • "enabled": true,
  • "availableToAllCustomers": true,
  • "version": "string",
  • "repositoryVersion": "string",
  • "ownershipType": "PLATFORM",
  • "customerId": 0,
  • "sizeBytes": 0,
  • "lastUpdated": 0,
  • "type": "WIDGET",
  • "widgetCategory": "CUSTOM_APPS",
  • "config": null,
  • "appRootPath": "string",
  • "entryPoint": "string",
  • "iconPath": "string",
  • "resourceList": [
    ]
}

Cancel a private app ZIP upload

Cancel an upload that has not completed. A completed or interrupted upload can return 409.

Minimum role: OWNER.

Authorizations:
bearer
path Parameters
id
required
integer <int64>
uploadId
required
string
query Parameters
customerId
integer <int64>

Select a customer/tenant within the caller's access. When this parameter is optional, omitting it uses the caller's scope: global for ADMIN, owned member customers for a network owner, and the own customer for other callers. Use an explicit customerId for customer-specific operations. Requiredness is declared per endpoint.

Responses

Download a private app ZIP

Minimum role: OWNER.

Authorizations:
bearer
path Parameters
id
required
integer <int64>
query Parameters
customerId
integer <int64>

Select a customer/tenant within the caller's access. When this parameter is optional, omitting it uses the caller's scope: global for ADMIN, owned member customers for a network owner, and the own customer for other callers. Use an explicit customerId for customer-specific operations. Requiredness is declared per endpoint.

Responses