Skip to content
Tilecast Docs

applyPackageUpdate

POST
/api/v1/packages/{packageId}/update
curl --request POST \
  --url https://example.com/api/v1/packages/example/update \
  --header 'Content-Type: application/json' \
  --cookie tilecast_session=<tilecast_session> \
  --data '{ "digest": "example" }'

Requires the Owner or Administrator role with the admin scope. Cookie requests additionally require the X-CSRF-Token header. Activates the digest an update check approved. The check re-resolves fresh, so a stale digest answers update_check_expired instead of installing old bytes. Audited.

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.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
digest
required

Pinned artifact digest as sha256 colon hex.

string
Examplegenerated
{
  "digest": "example"
}

Responses

Section titled “ Responses ”

200

Section titled “200”

Update result

Media typeapplication/json
object
data
required
object
package
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
updated
required
boolean
Example
{
  "data": {
    "package": {
      "capabilities": {
        "services": [
          {
            "category": "read"
          }
        ]
      }
    }
  }
}

400

Section titled “400”

Invalid_request — a digest is required

401

Section titled “401”

Dashboard authentication required

403

Section titled “403”

Owner or Administrator role required

404

Section titled “404”

Package_not_installed

409

Section titled “409”

Update_check_expired, package_mismatch, contribution_collision, source_conflict, or package_in_use — the update drops a contribution persisted content still uses; remaining resources are listed in error.details

Media typeapplication/json

A 409 from applying a package update. Only package_in_use carries details, listing the content the update would strand.

object
error
required
object
code
required
string
Allowed values: update_check_expired package_mismatch contribution_collision source_conflict package_in_use
message
required
string
details

The package and the contributed content that blocks the operation.

object
packageId
required
string
resources
required
Array<object>
object
kind
required
string
count
required
integer
>= 1
label
required
string
resolution
required
string
Example
{
  "error": {
    "code": "update_check_expired"
  }
}

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_incompatible, or namespace_violation

502

Section titled “502”

Upstream_unavailable — GitHub, the registry, or Sigstore is unreachable