Skip to content
Tilecast Docs

checkPackageUpdate

POST
/api/v1/packages/{packageId}/update-check
curl --request POST \
  --url https://example.com/api/v1/packages/example/update-check \
  --cookie tilecast_session=<tilecast_session>

Requires the Owner or Administrator role with the admin scope. Cookie requests additionally require the X-CSRF-Token header. Resolves the latest artifact for an installed package without activating anything. A custom package re-resolves its repository; a marketplace package refreshes the catalog first.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “Path Parameters”
packageId
required
string
/^[a-z][a-z0-9_.:-]{0,127}$/

Store package identifier such as countdown_bar.

Header Parameters

Section titled “Header Parameters”
X-CSRF-Token
string

Cookie-backed browser requests only, and only on unsafe methods. Bearer grants never send it.

Responses

Section titled “ Responses ”

200

Section titled “200”

Update check

Media typeapplication/json
object
data
required

The latest artifact for an installed package, resolved without activating anything. latest is present when available.

object
installed
required

One installed extension package with its contributions and, for custom packages, the repository binding.

object
packageId
required
string
version
required
string
manifest
required

The human-readable face of an installed or resolved package manifest.

object
name
required
string
description
required
string
publisherId
required
string
publisherName
required
string
license
required
string
tilecastRange
required
string
digest
required

Pinned artifact digest as sha256 colon hex.

string
sourceKind
required
string
sourceReference
required
string
registryReference
required
string
signerIdentity
string
trust
required
string
installedAt
required
string format: date-time
installedBy
required
string | null format: uuid
activatedAt
required
string format: date-time
hasRollback
required
boolean
contributions
required
Array<object>

One activated contribution: its kind, its package-qualified identity, and its path inside the package.

object
kind
required
string
id
required
string
path
required
string
runtime

External server behavior module (manifest version 2 only).

object
module
required

Package-relative WebAssembly module path.

string
capabilities

Bounded capabilities the package requests. Every entry is a request the host reviews before installation; nothing here grants itself.

object
network

Approved outbound HTTPS origins.

object
hosts
required
Array<string>
background

Package-owned background jobs the host runs.

object
jobs
required
Array<object>
object
id
required
string
intervalMinutes
required
integer
realtime

One bounded high-frequency background job, separately reviewed.

object
jobs
required
Array<object>
>= 1 items <= 1 items
object
id
required
string
intervalSeconds
required
integer
>= 5 <= 60
storage

Request plugin-owned key/value storage.

boolean
studioUI

Sandboxed Studio UI entry.

object
entry
required
string
services

Requested Tilecast service grants with registry-resolved display metadata.

Array<object>
object
id
required
string
version
required
integer
name
required
string
description
required
string
category
required
string
Allowed values: read directory manage audit
operations
required
Array<object>
object
name
required
string
title
required
string
description
required
string
mutating
required
boolean
source

The custom repository binding behind an installed custom package.

object
owner
required
string
name
required
string
repositoryUrl
required
string format: uri
resolvedDigest
required

Last verified artifact digest as sha256 colon hex.

string
resolvedAt
required
string format: date-time
addedAt
required
string format: date-time
available
required
boolean
upToDate
required
boolean
lastChecked
required
string format: date-time
latest

The install review for a resolved repository: identity, version, provenance, and installed state. Resolving persists nothing.

object
packageId
required
string
version
required
string
manifest
required

The human-readable face of an installed or resolved package manifest.

object
name
required
string
description
required
string
publisherId
required
string
publisherName
required
string
license
required
string
tilecastRange
required
string
compatible
required
boolean
contributions
required
Array<object>
object
type
required
string
path
required
string
id

Package-qualified contribution ID read from the artifact’s nested manifest. Present on update checks, which read the artifact; absent when the review resolved only the published manifest.

string
playerRuntime

Verified external Player surface permissions. Present for executable plugin contributions.

object
surfaces
required
Array<string>
>= 1 items <= 7 items unique items
Allowed values: strip.top strip.bottom corner.top-left corner.top-right corner.bottom-left corner.bottom-right overlay
tier
required
string
Allowed values: emergency live scheduled ambient
runtime

External server behavior module (manifest version 2 only).

object
module
required

Package-relative WebAssembly module path.

string
capabilities

Bounded capabilities the package requests. Every entry is a request the host reviews before installation; nothing here grants itself.

object
network

Approved outbound HTTPS origins.

object
hosts
required
Array<string>
background

Package-owned background jobs the host runs.

object
jobs
required
Array<object>
object
id
required
string
intervalMinutes
required
integer
realtime

One bounded high-frequency background job, separately reviewed.

object
jobs
required
Array<object>
>= 1 items <= 1 items
object
id
required
string
intervalSeconds
required
integer
>= 5 <= 60
storage

Request plugin-owned key/value storage.

boolean
studioUI

Sandboxed Studio UI entry.

object
entry
required
string
services

Requested Tilecast service grants with registry-resolved display metadata.

Array<object>
object
id
required
string
version
required
integer
name
required
string
description
required
string
category
required
string
Allowed values: read directory manage audit
operations
required
Array<object>
object
name
required
string
title
required
string
description
required
string
mutating
required
boolean
digest
required

Pinned artifact digest as sha256 colon hex.

string
registry
required
string
releaseTag
required
string
releaseName
string
publishedAt
string format: date-time
owner
required
string
repo
required
string
repositoryUrl
required
string format: uri
signer
string
trust
required
string
installed
required
boolean
installedVersion
string
Example
{
  "data": {
    "installed": {
      "capabilities": {
        "services": [
          {
            "category": "read"
          }
        ]
      }
    },
    "latest": {
      "contributions": [
        {
          "playerRuntime": {
            "surfaces": [
              "strip.top"
            ],
            "tier": "emergency"
          }
        }
      ],
      "capabilities": {
        "services": [
          {
            "category": "read"
          }
        ]
      }
    }
  }
}

401

Section titled “401”

Dashboard authentication required

403

Section titled “403”

Owner or Administrator role required

404

Section titled “404”

Package_not_installed

422

Section titled “422”

Repository_private, no_published_release, manifest_not_found, manifest_invalid, release_tag_unusable, no_published_package, package_unsigned, artifact_invalid, package_mismatch, or package_incompatible

502

Section titled “502”

Upstream_unavailable — GitHub, the registry, or Sigstore is unreachable