Skip to main content

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.

Feature entitlement: devSpace · Availability: DevSpace

The flow has four steps:

  1. Pick a Core App version.
  2. Optional: upload a branding logo.
  3. Start the build.
  4. 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:

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.

ParameterDescription
applicationTypeRequired. sssp, tizen, webos, android, chrome, brightsign, linux, windows, default (the emulator), chromeos, or ipados. Smart Builder builds only the types in Platforms.
versionAn exact version, for example 2.13.0, published or not. Use it to check that a version exists before you build.
searchPart of the version, case-insensitive. For example 2.13. Works together with version.
publishedtrue leaves out unpublished versions, also the one an exact version would find.
limit1 to 1000. The default is 1000.
lastIdThe 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.

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.

  1. Compute the MD5 checksum of the file, base64-encoded:

    MD5=$(openssl md5 -binary icon-512.png | base64)
  2. Prepare the upload. size is 512 or 200. md5Checksum also 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.json

    upload.json now holds the key of the logo and the upload form:

    {
    "iconKey": "applet/5d41402abc4b2a76b9719d911017c592_512.png",
    "upload": {
    "url": "https://…",
    "fields": { "…": "…" }
    }
    }
  3. Upload the file. Send a multipart/form-data POST to upload.url with every field of upload.fields, and the file last, in the field file:

    FIELDS=()
    while IFS= read -r field; do
    FIELDS+=(--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-string sends each field value exactly as it is. Don't send your X-Auth header to upload.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" }
FieldRequiredDescription
appletUidYesThe applet to build.
appletVersionYesThe applet version to build.
applicationTypeYesThe platform. See Platforms.
applicationVersionYesA Core App version from step 1.
applicationFlavorLinux onlyThe platform variant. Linux needs one: rpi, rpi4, fedora, or ubuntu. Other types: see Platforms.
applicationSignatureNoAndroid vendor signature. Only Android Core App versions below 4.2.0 use it.
appletConfigNoApplet configuration built into the app. Each value is a string or an array of strings.
organizationUidNoThe organization devices running the app get verified into. The default is the organization of the applet.
branding.titleNoThe app name shown on the device. 1 to 64 characters, no control characters.
branding.iconKeyNoThe 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.

FieldDescription
uidThe requestUid from step 3.
statusbuilding, completed, or failed.
organizationUidThe organization devices running the app get verified into.
applicationType, applicationFlavor, applicationVersion, applicationSignatureWhat you built.
appletThe applet uid, name, version, and config. Secret and encrypted config values come back as *** masked ***.
frontAppletVersionThe version of the signageOS JS API bundled with the applet.
createdAtWhen the build started.
builtAtWhen the build completed.
failedAt, errorWhen and why the build failed.
buildUrlDownload URL of the deployment app archive. Set once the build completes.
directBuildUrlURL 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.

ParameterDescription
statusbuilding, completed, or failed. Repeat the parameter for more values: status=completed&status=failed.
appletUid, appletVersionOnly builds of this applet or applet version.
applicationTypeOnly builds of this type. Same values as in step 1.
builtSince, builtUntilOnly builds completed in this range. ISO 8601 date-time, for example 2026-11-01T00:00:00Z.
organizationUidsOnly builds of these organizations.
companyUidOnly builds of this company.
sortKeycreatedAt (default) or applicationType.
descendingtrue (default) or false.
limit1 to 100.
lastIdThe 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.

FieldDescription
buildsThisMonthWhat 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.
monthlyBuildLimitBuilds your company can start per month. null means unlimited.
buildsTotalCompleted builds.
platformsPlatforms with a completed build. A platform is an application type plus a flavor.
platformsThisMonthPlatforms 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 targetapplicationTypeapplicationFlavorEntitlementBranding logo
AndroidandroidnonedevSpaceAndroid512×512
Android LegacyandroidlegacydevSpaceAndroidLegacy512×512
SonyandroidsonydevSpaceSony512×512
PhilipsandroidphilipsdevSpacePhilips512×512
EloandroidelodevSpaceElo512×512
TizentizennonedevSpaceTizen512×512, Core App 2.13.0 and newer
Tizen TEPtizentepdevSpaceTizenTEP512×512, Core App 2.13.0 and newer
Tizen EPapertizenepaperdevSpaceTizenEPaper512×512, Core App 2.13.0 and newer
webOSwebosnonedevSpaceWebOS200×200, Core App 2.12.0 and newer
webOS IDCapwebosidcapdevSpaceWebOSIDCap200×200, Core App 2.12.0 and newer
BrightSignbrightsignnonedevSpaceBrightsignNot branded
BrightSign 9brightsignbrightsign9devSpaceBrightsign9Not branded
RaspberryPilinuxrpi or rpi4devSpaceRaspberryPiNot branded
FedoralinuxfedoradevSpaceLinuxFedoraNot branded
UbuntulinuxubuntudevSpaceLinuxUbuntuNot branded
SSSPssspnonedevSpaceSSSPNot branded
WindowswindowsnonedevSpaceWindowsNot branded
EmulatordefaultnonedevSpace onlyNot 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."
}
StatuserrorCodeerrorNameWhat it means
400400301INVALID_BODY_PROPERTIESThe 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.
400400254APPLICATION_BUILD_PLATFORM_NOT_SUPPORTEDThe flavor doesn't belong to the application type, for example rpi for Tizen, or a Linux build has no flavor.
400400255APPLICATION_BUILD_BRANDING_TITLE_INVALIDThe branding title is empty, longer than 64 characters, or has control characters.
400400256APPLICATION_BUILD_BRANDING_ICON_NOT_UPLOADEDNothing was uploaded for the iconKey. Finish the upload in step 2.
400400257APPLICATION_BUILD_BRANDING_ICON_INVALIDThe 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."
400400258APPLICATION_BUILD_APPLET_OF_ANOTHER_COMPANYThe applet belongs to another company than the organization the app is provisioned into.
401401039DEVSPACE_SEAT_REQUIREDYour company licenses DevSpace per user, and the account has no DevSpace license.
402402300INSUFFICIENT_<ENTITLEMENT>_ENTITLEMENTThe 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.
402402400APPLICATION_BUILD_MONTHLY_LIMIT_REACHEDYour company used up its builds for this month.
403The X-Auth token is missing or invalid.
404The 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.

build-deployment-app.sh
#!/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.