`POST /api/marketplace/installs/{id}/update` — update an existing install to the latest version. Returns the updated install row.

POST

/api/marketplace/installs/{id}/update

curl --request POST \
  --url https://example.com/api/marketplace/installs/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/update \
  --header 'Content-Type: application/json' \
  --data '{ "resource_mappings": { "mappings": [ { "binding_name": "example", "grant_write": true, "requirement_kind": "example", "resource_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0" } ], "schema": "example" } }'

Parameters

Path Parameters

id

required

string format: uuid

Request Body^required

Media typeapplication/json

object

resource_mappings

One of:

null

null

object

Resource mappings submitted by the caller during install/update.

object

mappings

Array<object>

object

binding_name

#1313 / ADR 0072 — the in-guest binding NAME this mapping supplies authority for, when the installer is filling a hole the ADR 0058 §7 trust gate left in a workflow member (PackageWorkflow:: required_bindings).

None is the pre-#1313 per-KIND mapping and changes nothing: the strip runs, nothing is filled, the installed code node stays hermetic. The STEP is never named here — it comes from the requirement the manifest recorded, so an installer can supply authority but cannot choose which node receives it.

A name matching no requirement in the package is REFUSED by name rather than ignored (#838 B16).

string | null

grant_write

#1313 / ADR 0072 — the installer’s WRITE grant for binding_name.

The effective allow_write on the restored binding is the AND of this grant and the requirement’s write_requested: a publisher may ASK for the ADR 0058 P3 write allowlist, only the installing workspace can GIVE it, and a grant on a hole that never asked stays read-only. None and false are the same, safe answer.

boolean | null

requirement_kind

required

string

resource_id

required

string format: uuid

schema

#1313 / ADR 0072 D4 — the postgresql schema this install applies a per-workspace (schema_per_workspace) listing’s migrations into. The catalog ships a neutral placeholder, so the effective schema is resolved against the INSTALLING workspace: an existing namespace row for the package’s handle always wins, and this field names the schema for a fresh workspace. A value that contradicts the recorded one is refused by name — one handle never owns two schemas.

None is the pre-#1313 shape and changes nothing: a listing that does not opt in still fixes its literal in the manifest.

string | null

Example^generated

{
  "resource_mappings": {
    "mappings": [
      {
        "binding_name": "example",
        "grant_write": true,
        "requirement_kind": "example",
        "resource_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0"
      }
    ],
    "schema": "example"
  }
}

Responses

200

Media typeapplication/json

A marketplace item installed into a workspace. Tracks the installed version, the local resources created (app, scripts, workflows), and the manifest hash for drift detection.

object

auto_update

required

#1060 — when armed, the auto-update tick pulls newer non-withdrawn versions through the SAME service path the Update button uses, so it can skip none of that path’s signature / review-gate / licence checks.

boolean

auto_update_checked_at

Last tick attempt for this install (success or failure), so “never checked” and “checked and found nothing” stay distinguishable.

string | null format: date-time

auto_update_last_error

Why the last auto-update attempt failed; None after a success. Without this a blocked review gate or a lapsed licence would leave the install silently pinned to an old version while the toggle still reads “on”.

string | null

id

required

string format: uuid

install_manifest_sha256

required

string

installed_app_id

string | null format: uuid

installed_at

required

string format: date-time

installed_by

string | null format: uuid

installed_node_type_ids

required

Array<string>

installed_optional_members

#1313 / ADR 0072 D7 — the OPTIONAL bundle-member slugs this install selected. Empty for every install of a manifest that declares no optional members, and for every pre-#1313 install. It is the record of a HUMAN choice: a re-install may add a member to it, an update may never invent one, and the binding refusals read it to know which members are in play.

Array<string>

installed_script_ids

required

Array<string>

installed_workflow_ids

required

Array<string>

item_id

required

string format: uuid

latest_version

string | null

resource_mappings

update_available

Issue #351 — whether a newer NON-withdrawn version than the installed one exists (the “update available” signal), and that latest version string. Populated only by list_installs_by_workspace via correlated subqueries; absent in other projections that select INSTALL_COLUMNS, where #[sqlx(default)] supplies false / None.

boolean

updated_at

required

string format: date-time

version_id

required

string format: uuid

workspace_id

required

string format: uuid

Example^generated

{
  "auto_update": true,
  "auto_update_checked_at": "2026-04-15T12:00:00Z",
  "auto_update_last_error": "example",
  "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "install_manifest_sha256": "example",
  "installed_app_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "installed_at": "2026-04-15T12:00:00Z",
  "installed_by": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "installed_node_type_ids": [
    "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0"
  ],
  "installed_optional_members": [
    "example"
  ],
  "installed_script_ids": [
    "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0"
  ],
  "installed_workflow_ids": [
    "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0"
  ],
  "item_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "latest_version": "example",
  "resource_mappings": "example",
  "update_available": true,
  "updated_at": "2026-04-15T12:00:00Z",
  "version_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "workspace_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0"
}