Skip to content
Tilecast Docs

installStorePackage

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

Requires the Owner or Administrator role with the admin scope. Cookie requests additionally require the X-CSRF-Token header. Installs the store entry. A marketplace entry installs from its listing with an empty body; a custom entry installs when the body names its repository. The package ID must match the resolved manifest. 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 Body

Section titled “Request Body”
Media typeapplication/json
object
repository

Custom repository URL. Omit for marketplace listings.

string format: uri
Examplegenerated
{
  "repository": "https://example.com"
}

Responses

Section titled “ Responses ”

201

Section titled “201”

Package installed

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

401

Section titled “401”

Dashboard authentication required

403

Section titled “403”

Owner or Administrator role required

404

Section titled “404”

Repository_not_found or plugin_not_found

409

Section titled “409”

Package_mismatch, package_installed, contribution_collision, or source_conflict

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