Build deployment apps through the REST API
Smart Builder turns an applet version into a deployment app for a device platform. In Box you do this with a form. The REST API does the same from a script, so you can build deployment apps in a CI pipeline, or build many applets and platforms without clicking through Box.
One build request builds one platform. To build for Tizen and webOS, send two requests.
devSpace · Availability: DevSpaceThe flow has four steps:
- Pick a Core App version.
- Optional: upload a branding logo.
- Start the build.
- Wait for the build to finish, then download the app.
The examples call https://api.signageos.io and read your token from a shell variable. Every API request sends it in the X-Auth header:
export SOS_AUTH="TOKEN_ID:TOKEN_SECRET"
Before you start
You need:
- An account token or an organization token. See REST API Authentication.
- DevSpace for your company.
- The build target of every platform you build for, for example
devSpaceTizenfor Tizen. The platform table lists them. See Build Targets. - DevSpace — Branded Apps (
devSpaceBrandedApps) if you brand the app. See Branding and Whitelabel.
The company of the organization the devices get verified into needs these entitlements. The applet must belong to an organization of that same company.
Two more rules can apply:
- DevSpace license. When your company licenses DevSpace per user, the account that starts the build needs a DevSpace user license. With an organization token, that is the account that created the token.
- Monthly build limit. When your company has one, you can start builds until it is used up. Failed builds don't count, and neither does a build still running 24 hours after it started. Months are UTC calendar months. See Check your monthly allowance.
The examples also use jq to read JSON responses.
Step 1: Pick a Core App version
List the Core App versions you can build with. The newest version comes first.
curl -X GET \
"https://api.signageos.io/v1/application/version?applicationType=tizen&limit=5" \
-H "X-Auth: $SOS_AUTH"
[
{
"uid": "c2a7e9f1b4d8a3e6c5f0b9d2e7a4c1f8b3d6",
"applicationType": "tizen",
"version": "2.13.0",
"frontDisplayVersion": "17.4.0",
"createdAt": "2026-10-20T09:12:44.000Z",
"publishedSince": "2026-10-22T08:00:00.000Z"
}
]
Use the version as applicationVersion in step 3. A version with deprecatedSince is deprecated; pick another one.
The list has only published Core App versions. An unpublished version you already know, for example from a device that runs it, isn't listed, but version finds it and you can build with it.
| Parameter | Description |
|---|---|
applicationType | Required. sssp, tizen, webos, android, chrome, brightsign, linux, windows, default (the emulator), chromeos, or ipados. Smart Builder builds only the types in Platforms. |
version | An exact version, for example 2.13.0, published or not. Use it to check that a version exists before you build. |
search | Part of the version, case-insensitive. For example 2.13. Works together with version. |
published | true leaves out unpublished versions, also the one an exact version would find. |
limit | 1 to 1000. The default is 1000. |
lastId | The uid of the last item of the previous page. |
GET /v1/application/version/count takes the same filters and returns the number of matching versions.
This endpoint doesn't need DevSpace. Any account or organization token can call it.
Paging. When more items follow, the response has a Link header with rel="next". Its URL loads the next page. The build list in List your builds pages the same way.
Step 2 (optional): Upload a branding logo
Skip this step to build without a logo. A build with a branding title and no logo uses the applet icon.
The API doesn't resize the logo. Upload a square PNG of exactly the size of the platform, up to 2 MB: 512×512 for Tizen and Android, 200×200 for webOS. The build reads the size from the PNG file itself, so setting size in the request isn't enough. Other platforms aren't branded. To brand a Tizen build and a webOS build, upload two logos, one per size.
Uploading a logo needs DevSpace — Branded Apps.
-
Compute the MD5 checksum of the file, base64-encoded:
MD5=$(openssl md5 -binary icon-512.png | base64) -
Prepare the upload.
sizeis512or200.md5Checksumalso accepts the MD5 as 32 hex digits.curl -X POST \https://api.signageos.io/v1/application/build/branding-icon \-H 'Content-Type: application/json' \-H "X-Auth: $SOS_AUTH" \-d "$(jq -n --arg md5 "$MD5" '{size: 512, md5Checksum: $md5}')" \-o upload.jsonupload.jsonnow holds the key of the logo and the upload form:{"iconKey": "applet/5d41402abc4b2a76b9719d911017c592_512.png","upload": {"url": "https://…","fields": { "…": "…" }}} -
Upload the file. Send a
multipart/form-dataPOST toupload.urlwith every field ofupload.fields, and the file last, in the fieldfile:FIELDS=()while IFS= read -r field; doFIELDS+=(--form-string "$field")done < <(jq -r '.upload.fields | to_entries[] | "\(.key)=\(.value)"' upload.json)curl -fsS "${FIELDS[@]}" -F "file=@icon-512.png" "$(jq -r '.upload.url' upload.json)"--form-stringsends each field value exactly as it is. Don't send yourX-Authheader toupload.url; the upload form authorizes the request. The upload is rejected unless the file matches the MD5 checksum and is 2 MB or smaller.
Keep the iconKey for step 3.
Step 3: Start the build
curl -X POST \
https://api.signageos.io/v1/application/build \
-H 'Content-Type: application/json' \
-H "X-Auth: $SOS_AUTH" \
-d '{
"appletUid": "APPLET_UID",
"appletVersion": "1.0.0",
"applicationType": "tizen",
"applicationVersion": "2.13.0",
"organizationUid": "ORGANIZATION_UID",
"appletConfig": { "apiUrl": "https://example.com/api" },
"branding": { "title": "Lobby screen", "iconKey": "ICON_KEY" }
}'
The API answers 202 Accepted with the UID of the build request:
{ "requestUid": "7c4f1e2d9a8b3c6e5f0a1d2b4c6e8f0a2b4d" }
| Field | Required | Description |
|---|---|---|
appletUid | Yes | The applet to build. |
appletVersion | Yes | The applet version to build. |
applicationType | Yes | The platform. See Platforms. |
applicationVersion | Yes | A Core App version from step 1. |
applicationFlavor | Linux only | The platform variant. Linux needs one: rpi, rpi4, fedora, or ubuntu. Other types: see Platforms. |
applicationSignature | No | Android vendor signature. Only Android Core App versions below 4.2.0 use it. |
appletConfig | No | Applet configuration built into the app. Each value is a string or an array of strings. |
organizationUid | No | The organization devices running the app get verified into. The default is the organization of the applet. |
branding.title | No | The app name shown on the device. 1 to 64 characters, no control characters. |
branding.iconKey | No | The iconKey from step 2: an uploaded square PNG of exactly the size of the platform. It can also be the key of the applet's own multi-size icon, applet/<hash>_50.png; the API then uses its variant of the platform's size. Without iconKey, the applet icon is used. |
Branding applies to Tizen from Core App 2.13.0, to webOS from Core App 2.12.0, and to every Android version. Other builds ignore branding. For how the title and logo show on devices, see Branding and Whitelabel.
Step 4: Wait for the build and download it
Get the build with the requestUid from step 3:
curl -X GET \
https://api.signageos.io/v1/application/build/REQUEST_UID \
-H "X-Auth: $SOS_AUTH"
{
"uid": "7c4f1e2d9a8b3c6e5f0a1d2b4c6e8f0a2b4d",
"status": "completed",
"organizationUid": "ORGANIZATION_UID",
"applicationType": "tizen",
"applicationVersion": "2.13.0",
"applet": {
"uid": "APPLET_UID",
"name": "Lobby screen",
"version": "1.0.0",
"config": { "apiUrl": "https://example.com/api", "apiKey": "*** masked ***" }
},
"createdAt": "2026-11-11T10:00:00.000Z",
"builtAt": "2026-11-11T10:04:12.000Z",
"buildUrl": "https://…",
"directBuildUrl": "https://…"
}
Repeat the request every 5 to 10 seconds until status is completed or failed. A build usually takes a few minutes.
| Field | Description |
|---|---|
uid | The requestUid from step 3. |
status | building, completed, or failed. |
organizationUid | The organization devices running the app get verified into. |
applicationType, applicationFlavor, applicationVersion, applicationSignature | What you built. |
applet | The applet uid, name, version, and config. Secret and encrypted config values come back as *** masked ***. |
frontAppletVersion | The version of the signageOS JS API bundled with the applet. |
createdAt | When the build started. |
builtAt | When the build completed. |
failedAt, error | When and why the build failed. |
buildUrl | Download URL of the deployment app archive. Set once the build completes. |
directBuildUrl | URL of the folder with the app files. Set once the build completes. |
When the build completes, download the archive:
curl -fLO "BUILD_URL"
Deploy the app
Install the app on your devices with the provisioning guides. To compare the ways you can roll it out, see Applet Deployment Options.
List your builds
List the builds of the organizations you can access, newest first:
curl -X GET \
"https://api.signageos.io/v1/application/build?appletUid=APPLET_UID&status=failed&limit=20" \
-H "X-Auth: $SOS_AUTH"
The response is an array of builds, each like the one in step 4.
| Parameter | Description |
|---|---|
status | building, completed, or failed. Repeat the parameter for more values: status=completed&status=failed. |
appletUid, appletVersion | Only builds of this applet or applet version. |
applicationType | Only builds of this type. Same values as in step 1. |
builtSince, builtUntil | Only builds completed in this range. ISO 8601 date-time, for example 2026-11-01T00:00:00Z. |
organizationUids | Only builds of these organizations. |
companyUid | Only builds of this company. |
sortKey | createdAt (default) or applicationType. |
descending | true (default) or false. |
limit | 1 to 100. |
lastId | The uid of the last build of the previous page. The Link header carries the URL of the next page. |
GET /v1/application/build/count takes the same filters and returns the number of builds, for example { "count": 12 }.
To get the newest download of an applet for every platform, ask for its latest builds:
curl -X GET \
"https://api.signageos.io/v1/application/build/latest?appletUid=APPLET_UID" \
-H "X-Auth: $SOS_AUTH"
The response has the latest completed build of the applet for each platform. A platform is an application type plus a flavor.
Check your monthly allowance
curl -X GET \
"https://api.signageos.io/v1/application/build/statistics?companyUid=COMPANY_UID" \
-H "X-Auth: $SOS_AUTH"
{
"buildsTotal": 42,
"buildsThisMonth": 3,
"monthlyBuildLimit": 5,
"platforms": 4,
"platformsThisMonth": 2
}
With an account token, companyUid is required.
| Field | Description |
|---|---|
buildsThisMonth | What the monthly limit counts, for your whole company: builds completed this UTC month, plus builds still running that started in the last 24 hours. Failed builds don't count. It can be higher than buildsTotal. |
monthlyBuildLimit | Builds your company can start per month. null means unlimited. |
buildsTotal | Completed builds. |
platforms | Platforms with a completed build. A platform is an application type plus a flavor. |
platformsThisMonth | Platforms with a build completed this month. |
buildsTotal, platforms, and platformsThisMonth count only the organizations you can access.
Platforms
Each platform is an applicationType, with an applicationFlavor for variants. The entitlement column is the build target the company needs.
| Build target | applicationType | applicationFlavor | Entitlement | Branding logo |
|---|---|---|---|---|
| Android | android | none | devSpaceAndroid | 512×512 |
| Android Legacy | android | legacy | devSpaceAndroidLegacy | 512×512 |
| Sony | android | sony | devSpaceSony | 512×512 |
| Philips | android | philips | devSpacePhilips | 512×512 |
| Elo | android | elo | devSpaceElo | 512×512 |
| Tizen | tizen | none | devSpaceTizen | 512×512, Core App 2.13.0 and newer |
| Tizen TEP | tizen | tep | devSpaceTizenTEP | 512×512, Core App 2.13.0 and newer |
| Tizen EPaper | tizen | epaper | devSpaceTizenEPaper | 512×512, Core App 2.13.0 and newer |
| webOS | webos | none | devSpaceWebOS | 200×200, Core App 2.12.0 and newer |
| webOS IDCap | webos | idcap | devSpaceWebOSIDCap | 200×200, Core App 2.12.0 and newer |
| BrightSign | brightsign | none | devSpaceBrightsign | Not branded |
| BrightSign 9 | brightsign | brightsign9 | devSpaceBrightsign9 | Not branded |
| RaspberryPi | linux | rpi or rpi4 | devSpaceRaspberryPi | Not branded |
| Fedora | linux | fedora | devSpaceLinuxFedora | Not branded |
| Ubuntu | linux | ubuntu | devSpaceLinuxUbuntu | Not branded |
| SSSP | sssp | none | devSpaceSSSP | Not branded |
| Windows | windows | none | devSpaceWindows | Not branded |
| Emulator | default | none | devSpace only | Not branded |
Errors
Errors come back as JSON:
{
"status": 402,
"message": "Feature entitlement required - Monthly build limit reached",
"errorCode": 402400,
"errorName": "APPLICATION_BUILD_MONTHLY_LIMIT_REACHED",
"errorDetail": "The company used 5 of its 5 builds this month. New builds start again next month."
}
| Status | errorCode | errorName | What it means |
|---|---|---|---|
| 400 | 400301 | INVALID_BODY_PROPERTIES | The request body doesn't match the schema, for example a missing required field, an unknown applicationType, or a flavor that doesn't exist, such as debian. message lists the problems. |
| 400 | 400254 | APPLICATION_BUILD_PLATFORM_NOT_SUPPORTED | The flavor doesn't belong to the application type, for example rpi for Tizen, or a Linux build has no flavor. |
| 400 | 400255 | APPLICATION_BUILD_BRANDING_TITLE_INVALID | The branding title is empty, longer than 64 characters, or has control characters. |
| 400 | 400256 | APPLICATION_BUILD_BRANDING_ICON_NOT_UPLOADED | Nothing was uploaded for the iconKey. Finish the upload in step 2. |
| 400 | 400257 | APPLICATION_BUILD_BRANDING_ICON_INVALID | The logo isn't a square PNG of exactly the size of the platform, for example a 512×512 logo for webOS. errorDetail names the size, for example "A webos build needs a 200x200 PNG branding icon." |
| 400 | 400258 | APPLICATION_BUILD_APPLET_OF_ANOTHER_COMPANY | The applet belongs to another company than the organization the app is provisioned into. |
| 401 | 401039 | DEVSPACE_SEAT_REQUIRED | Your company licenses DevSpace per user, and the account has no DevSpace license. |
| 402 | 402300 | INSUFFICIENT_<ENTITLEMENT>_ENTITLEMENT | The company of the organization the app is provisioned into lacks DevSpace, the build target, or Branded Apps, for example INSUFFICIENT_DEV_SPACE_BRIGHTSIGN9_ENTITLEMENT. Listing builds or statistics of a company without DevSpace answers it too. |
| 402 | 402400 | APPLICATION_BUILD_MONTHLY_LIMIT_REACHED | Your company used up its builds for this month. |
| 403 | The X-Auth token is missing or invalid. | ||
| 404 | The applet, the applet version, the organization, or the Core App version doesn't exist, or your token can't access it. A lastId that points to no item answers 404 too. |
End-to-end script
This script runs steps 1 to 4 for one platform. It picks the newest Core App version that isn't deprecated, starts the build, waits for it, and downloads the app. To brand the app, set ICON to a square PNG of exactly the platform's size, and ICON_SIZE=200 for webOS.
#!/usr/bin/env bash
# Usage: SOS_AUTH=TOKEN_ID:TOKEN_SECRET ./build-deployment-app.sh APPLET_UID APPLET_VERSION APPLICATION_TYPE [APPLICATION_FLAVOR]
# Optional: ICON=icon.png ICON_SIZE=512
# Needs curl 7.76 or newer, jq and openssl.
set -euo pipefail
API=https://api.signageos.io
APPLET_UID=$1
APPLET_VERSION=$2
TYPE=$3
FLAVOR=${4:-}
# Calls the API and prints the error body to stderr when the call fails
api() {
local response
if ! response=$(curl -sS --fail-with-body -H "X-Auth: $SOS_AUTH" "$@"); then
echo "$response" >&2
return 1
fi
echo "$response"
}
# 1. The newest Core App version that isn't deprecated
CORE_APP_VERSION=$(api "$API/v1/application/version?applicationType=$TYPE" \
| jq -r 'map(select(.deprecatedSince == null))[0].version // empty')
[ -n "$CORE_APP_VERSION" ] || { echo "No Core App version for $TYPE" >&2; exit 1; }
# 2. Optional branding logo
ICON_KEY=
if [ -n "${ICON:-}" ]; then
MD5=$(openssl md5 -binary "$ICON" | base64)
UPLOAD=$(api -X POST "$API/v1/application/build/branding-icon" -H 'Content-Type: application/json' \
-d "$(jq -n --argjson size "${ICON_SIZE:-512}" --arg md5 "$MD5" '{size: $size, md5Checksum: $md5}')")
FIELDS=()
while IFS= read -r field; do
FIELDS+=(--form-string "$field")
done < <(jq -r '.upload.fields | to_entries[] | "\(.key)=\(.value)"' <<<"$UPLOAD")
curl -sS --fail-with-body "${FIELDS[@]}" -F "file=@$ICON" "$(jq -r '.upload.url' <<<"$UPLOAD")"
ICON_KEY=$(jq -r '.iconKey' <<<"$UPLOAD")
fi
# 3. Start the build
BODY=$(jq -n --arg applet "$APPLET_UID" --arg version "$APPLET_VERSION" --arg type "$TYPE" \
--arg core "$CORE_APP_VERSION" --arg flavor "$FLAVOR" --arg icon "$ICON_KEY" \
'{appletUid: $applet, appletVersion: $version, applicationType: $type, applicationVersion: $core}
+ (if $flavor != "" then {applicationFlavor: $flavor} else {} end)
+ (if $icon != "" then {branding: {iconKey: $icon}} else {} end)')
REQUEST_UID=$(api -X POST "$API/v1/application/build" -H 'Content-Type: application/json' -d "$BODY" \
| jq -r '.requestUid')
echo "Building $TYPE $FLAVOR with Core App $CORE_APP_VERSION: $REQUEST_UID"
# 4. Check every 10 seconds, for up to 30 minutes, then download the app
for _ in $(seq 180); do
BUILD=$(api "$API/v1/application/build/$REQUEST_UID")
STATUS=$(jq -r '.status' <<<"$BUILD")
[ "$STATUS" = building ] || break
sleep 10
done
if [ "$STATUS" != completed ]; then
echo "Build $REQUEST_UID: $STATUS $(jq -r '.error // empty' <<<"$BUILD")" >&2
exit 1
fi
curl -fsSLO "$(jq -r '.buildUrl' <<<"$BUILD")"
The upload and the download go to storage URLs, so the script sends them without your X-Auth header.