Public API v1 Reference

+ More

Table of Contents

Basics Base URL Authentication Conventions Typical workflows Errors Installing and Updating Packages POST /packages/{packageId}/latest GET /packages/{packageId}/published GET /packages/{packageId}/published/{releaseId} GET /packages/{packageId}/published/{releaseId}/installation POST /packages/{packageId}/published/{releaseId}/provisioning POST /packages/{packageId}/published/{releaseId}/failures Uploading and Publishing Releases GET /packages/{packageId}/releases POST /packages/{packageId}/releases GET /packages/{packageId}/releases/{releaseId} GET /packages/{packageId}/releases/{releaseId}/logs POST /packages/{packageId}/releases/{releaseId}/publish PUT /packages/{packageId}/releases/{releaseId}/publish Environments GET /environments/{installationEnvironment}/installed-packages POST /environments/{installationEnvironment}/installed-packages Release Notes GET /packages/{packageId}/release-notes GET /packages/{packageId}/published/{releaseId}/release-note GET /packages/{packageId}/releases/{releaseId}/release-note PUT /packages/{packageId}/releases/{releaseId}/release-note Responses FailedInstallationResponse InstallationPlanResponse InstalledPackagesResponse LatestReleaseResponse ListResponse ProvisioningResponse PublishedReleaseDetailResponse PublishedReleaseResponse ReleaseNoteResponse UploadedReleaseResponse Response Parts InstalledPackage Prerequisite ReleaseConflict ReleaseNoteLink SkippedRelease Request Parts InstallationLogEntry ReleaseNoteLinkInput ReportedPackage Error ErrorResponse ErrorData ValidationError

Version 0.1.0-alpha – a preview, not released yet: endpoints and contracts may still change without notice.

The Matrix42 Extensions Public API lets pipelines, scripts and other automation work with Extensions without the Matrix42 DevOps Portal: find the release to install or update a package to on an environment, get its installation plan and download, and, as vendor, upload and publish releases and edit their release notes.

Basics

Base URL

https://extensions.matrix42.com/api/v1

All paths in this article are relative to it.

Authentication

Every request needs an access token of your Matrix42 account in the Authorization header. For pipelines and scripts, create a personal access token (PAT) at the bottom of your account page on accounts.matrix42.com.

Authorization: Bearer <token>

Vendor endpoints (uploading, publishing, release note drafts) need the "Contributor" permission on the Extension.

Conventions

  • Packages are identified by their package id, the Id in package.json. Releases are identified by the releaseId the API returns; a version alone is not unique, as releases of the same version can differ in their product version requirement.
  • Requests and responses are JSON (application/json); release logs are text, errors application/problem+json.
  • Values of fixed sets, e.g. a status, are lowercase strings such as available-with-issues.
  • Times are UTC in ISO 8601.
  • List endpoints return one page: items and count (all items), paged with skip (default 0) and take (1 to 100, default 20).

Typical workflows

Installing or updating a package on an environment

  1. POST /packages/{packageId}/latest with the environment, its product version and its installed packages: returns the release to install, whether an update is available, and its installation plan.
  2. POST /packages/{packageId}/published/{releaseId}/provisioning for each package of the plan's installationOrder: returns the download.
  3. After installing, POST /environments/{installationEnvironment}/installed-packages reports the new state of the environment; a failed installation is reported with POST /packages/{packageId}/published/{releaseId}/failures.

Publishing a release as vendor

  1. POST /packages/{packageId}/releases uploads the signed package; the first upload of a package needs createExtension=true.
  2. GET /packages/{packageId}/releases/{releaseId}?waitSeconds=45 until the release is validated (available, available-with-issues or failed); GET …/logs shows the validation log.
  3. POST /packages/{packageId}/releases/{releaseId}/publish publishes it.
  4. PUT /packages/{packageId}/releases/{releaseId}/release-note writes its release note.

Errors

Every error is an ErrorResponse (RFC 9457 problem details, application/problem+json) with a stable code, also given as URI in type; each endpoint below lists its status codes and error codes. Check code (or type), not title or detail: the texts may change.

{
  "type": "https://extensions.matrix42.com/problems/release-already-uploaded",
  "status": 409,
  "code": "release-already-uploaded",
  "title": "Conflict",
  "detail": "A release with version 1.2.0 and the same product version requirement exists already.",
  "instance": "/api/v1/packages/9720d1e9-65f1-4897-b850-2a5bdb72cfcc/releases",
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-00",
  "data": {
    "packageId": "9720d1e9-65f1-4897-b850-2a5bdb72cfcc",
    "version": "1.2.0"
  }
}

Every endpoint can also answer with:

Status Description
401 unauthorized: no or an invalid access token.
500 internal-error: unexpected server error, without details; traceId identifies the request, please include it when contacting support.

Installing and Updating Packages

Automated installation and update of packages: the release to install, the published releases, the installation plan, the download, and reports of failed installations.

POST /packages/{packageId}/latest

The release to install or update a package to on an environment.

Given installed packages are stored for the environment first (updated, or replaced with replace, like POST environments/{installationEnvironment}/installed-packages); without them the stored ones are used.

The answer is the newest release that supports the product version, is newer than the installed version (see allowDowngrade), has resolvable dependencies and doesn't break another installed package: no installed package loses a version it requires. Installed dependencies that suffice are kept. Obsolete releases are left out; among releases sharing a version the one with the stricter product version requirement wins. Newer releases that can't be installed are listed in skippedReleases with the reasons.

Parameters

Name Type Required Description
packageId path string yes The package id, as in package.json.

Request body

application/json: The environment to find the release to install or update to for.

Field Type Required Description
installationEnvironment string yes Host (or URL) of the environment; the installed packages are stored for it.
productVersion string yes Product (ESM) version of the environment, e.g. 12.1.0.1234.
installedPackages array of ReportedPackage (9.3) no Packages installed in the environment, incl. the requested one when it is installed. When given, they are stored for the environment first (see replace); when left out, the stored ones are used.
replace boolean no The installed packages replace all stored ones, so uninstalled packages drop out. By default only the given packages are added or set to their version and all others are kept.
allowPreviewReleases boolean no Considers preview releases too; they are left out by default.
allowDowngrade boolean no Offers the newest release supporting the product version even when the installed version is newer (e.g. after a product downgrade). Dependencies are never downgraded.

Responses

Status Body Description
200 LatestReleaseResponse (7.4) The release and the update status; isUpdateAvailable tells whether to install release, then following installationPlan.
400 ErrorResponse (10.1) installation-environment-required, product-version-required, invalid-product-version, invalid-installed-package (an installed package lacks its GUID id or a valid version, is given twice, or its releaseId is no release of the package in that version; errors names the field, nothing is stored), invalid-request.
404 ErrorResponse (10.1) not-found: unknown package; no-compatible-release: no release supports the product version (data.releases).
409 ErrorResponse (10.1) no-installable-release: the package is not installed and no release supporting the product version can be installed next to the installed packages (data.skippedReleases, data.unknownInstalledPackageIds).

GET /packages/{packageId}/published

The published releases of a package the caller may see, highest version first.

With a product version only the releases supporting it are listed (see includeIncompatible); without one all, with isCompatible null. A version can exist in several releases, differing in their product version requirement: filter by version to find the release id of a version. Among releases of the same version the stricter requirement comes first, then the newer one, as latest picks them.

Parameters

Name Type Required Description
packageId path string yes The package id, as in package.json.
version query string no Only releases of this version, e.g. 1.2.0; 1.2 equals 1.2.0.
productVersion query string no Product (ESM) version to check the releases against; takes precedence over installationEnvironment.
installationEnvironment query string no Host whose known product version is used when productVersion is not given.
includeIncompatible query boolean no Lists releases not supporting the product version too, with isCompatible false.
includeObsolete query boolean no Lists obsolete releases too; they are left out by default.
includePreview query boolean no Lists preview releases too; they are left out by default.
skip query integer no Number of items to skip; default 0.
take query integer no Number of items to return, 1 to 100; default 20.

Responses

Status Body Description
200 list page (7.5) of PublishedReleaseResponse (7.8) A page of the releases; an empty list when no release matches.
400 ErrorResponse (10.1) invalid-product-version, invalid-request (invalid version or paging).
404 ErrorResponse (10.1) not-found: unknown package.
502 ErrorResponse (10.1) installation-environment-unreachable: the product version of the environment could not be queried; pass productVersion instead.

GET /packages/{packageId}/published/{releaseId}

A published release of a package.

Information only: obsolete, preview and incompatible releases are returned too, see isObsolete, isPreview and isCompatible. Installation plan and provisioning refuse them unless allowed.

Parameters

Name Type Required Description
packageId path string yes The package id, as in package.json.
releaseId path string yes The id of the release.
productVersion query string no Product (ESM) version to check the release against; takes precedence over installationEnvironment.
installationEnvironment query string no Host whose known product version is used when productVersion is not given.

Responses

Status Body Description
200 PublishedReleaseDetailResponse (7.7) The release, checked against the product version when one is known.
400 ErrorResponse (10.1) invalid-product-version.
404 ErrorResponse (10.1) not-found: unknown package or release.
502 ErrorResponse (10.1) installation-environment-unreachable: the product version of the environment could not be queried; pass productVersion instead.

GET /packages/{packageId}/published/{releaseId}/installation

The installation plan of a published release: what to install in which order.

Parameters

Name Type Required Description
packageId path string yes The package id, as in package.json.
releaseId path string yes The id of the release.
installationEnvironment query string no Host (or URL) of the environment; its installed packages are taken into account, and its known product version is used when productVersion is not given.
productVersion query string no Product (ESM) version to install on; takes precedence over installationEnvironment.
allowPreviewReleases query boolean no Allows preview releases for the dependencies.
allowIncompatible query boolean no Plans the release although it doesn't support the product version (409 without it).
allowObsolete query boolean no Plans an obsolete release too (409 without it); its dependencies are still never resolved to obsolete releases.

Responses

Status Body Description
200 InstallationPlanResponse (7.2) The plan: install installationOrder in this order; uninstallablePrerequisites must be provided by the environment.
400 ErrorResponse (10.1) invalid-product-version.
404 ErrorResponse (10.1) not-found: unknown or revoked package or release.
409 ErrorResponse (10.1) release-obsolete: the release is obsolete and allowObsolete is not set; incompatible-release: the release does not support the product version and allowIncompatible is not set.
502 ErrorResponse (10.1) installation-environment-unreachable: the product version of the environment could not be queried; pass productVersion instead.

POST /packages/{packageId}/published/{releaseId}/provisioning

The download of a published release to install it on an environment, incl. the license check.

Revoked releases (invalid content signature) are never handed out. Without productVersion the known product version of the environment is checked.

Parameters

Name Type Required Description
packageId path string yes The package id, as in package.json.
releaseId path string yes The id of the release.

Request body

application/json: Asks for the download of a release to install it on an environment.

Field Type Required Description
installationEnvironment string yes Host (or URL) of the environment the release is installed on.
productVersion string no Product (ESM) version of the environment, which the release must support; without it the known product version of the environment is used.
allowObsolete boolean no Hands out an obsolete release too; without it an obsolete release is answered with 409.
allowIncompatible boolean no Hands out the release although it doesn't support the product version; without it such a release is answered with 409.

Responses

Status Body Description
200 ProvisioningResponse (7.6) The time-limited downloadUrl of the package (ZIP) incl. its license; download it right away.
400 ErrorResponse (10.1) installation-environment-required, invalid-product-version, invalid-request (e.g. no body).
404 ErrorResponse (10.1) not-found: unknown, revoked or not licensed release.
409 ErrorResponse (10.1) release-obsolete: the release is obsolete and allowObsolete is not set; incompatible-release: the release does not support the product version and allowIncompatible is not set.
502 ErrorResponse (10.1) installation-environment-unreachable: the product version of the environment could not be queried; pass productVersion instead.

POST /packages/{packageId}/published/{releaseId}/failures

Reports a failed installation of a published release.

The error message and the log are stored for the vendor, who sees them in the installation analytics of the package. Only releases the caller may install can be reported. Successful installations are not reported.

Parameters

Name Type Required Description
packageId path string yes The package id, as in package.json.
releaseId path string yes The id of the release.

Request body

application/json: A failed installation of a release on an environment.

Field Type Required Description
installationEnvironment string yes Host (or URL) of the environment the installation failed on.
errorMessage string yes The error message (e.g. the exception) the installation failed with.
logs array of InstallationLogEntry (9.1) no The log of the installation; stored for the vendor next to the error message.

Responses

Status Body Description
200 FailedInstallationResponse (7.1) The stored failure.
400 ErrorResponse (10.1) installation-environment-required, invalid-request (e.g. no errorMessage).
404 ErrorResponse (10.1) not-found: unknown or inaccessible release.

Uploading and Publishing Releases

The uploaded releases of a package, as its vendor sees them: upload, status, validation log, publishing.

GET /packages/{packageId}/releases

All uploaded releases of a package, published or not, newest upload first.

Parameters

Name Type Required Description
packageId path string yes The package id, as in package.json.
version query string no Only releases of this version, e.g. 1.2.0; 1.2 equals 1.2.0.
skip query integer no Number of items to skip; default 0.
take query integer no Number of items to return, 1 to 100; default 20.

Responses

Status Body Description
200 list page (7.5) of UploadedReleaseResponse (7.10) A page of the releases.
400 ErrorResponse (10.1) invalid-request: invalid version or paging.
403 ErrorResponse (10.1) forbidden: the caller lacks the contributor permission on the package.
404 ErrorResponse (10.1) not-found: unknown package, or the caller is no contributor of it.

POST /packages/{packageId}/releases

Uploads a new release of a package.

The package id in the route must be the one in the package's package.json. The first upload of a package needs createExtension=true, which creates its extension; without it an unknown package is rejected and nothing is created, so a wrong package id never creates an extension by accident.

The release is validated asynchronously: wait for its final status with GET releases/{releaseId}.

Parameters

Name Type Required Description
packageId path string yes The package id, as in package.json.

Request body

multipart/form-data

Field Type Required Description
package file yes The signed package (ZIP) incl. its package.json.
createExtension boolean no Creates the extension (the entry the package is managed under in the Extensions portal) when none exists for the package yet. Without it, an upload for an unknown package is rejected, so a wrong package id never creates an extension by accident.

Responses

Status Body Description
201 UploadedReleaseResponse (7.10) The release is done already, e.g. it failed right away; see its status.
202 UploadedReleaseResponse (7.10) The release is being validated; Location points to it, Retry-After says when to ask again.
400 ErrorResponse (10.1) invalid-package: no ZIP, no package.json at its root, or no valid JSON in it; package-id-mismatch: the package id in the route differs from package.json; invalid-version: the package version is invalid; invalid-request (e.g. no Package).
403 ErrorResponse (10.1) no-package-access: the caller is no contributor of the package.
404 ErrorResponse (10.1) package-not-found: no extension exists for the package and createExtension is not set; nothing is created (data.packageId).
409 ErrorResponse (10.1) package-name-exists: with createExtension, the caller already has an extension with the package's name; detail says what to do (data.packageName, data.existingPackageId, data.uploadedPackageId). release-already-uploaded: a release with the same version and product version requirement exists (data.packageId, data.releaseId, data.version). package-already-uploaded: the package id is used by another vendor or contributor. package-deleted: the package is deleted and must be restored first.

GET /packages/{packageId}/releases/{releaseId}

An uploaded release incl. its status, e.g. to wait for the validation after an upload. While the release is in progress (pending, validating, publishing, ...) the response carries a Retry-After header.

Parameters

Name Type Required Description
packageId path string yes The package id, as in package.json.
releaseId path string yes The id of the release.
waitSeconds query integer no Waits up to this long (at most 45) for the release to leave its in-progress status and answers as soon as it does; without it the current status is returned at once.

Responses

Status Body Description
200 UploadedReleaseResponse (7.10) The release; carries Retry-After while it is in progress.
400 ErrorResponse (10.1) invalid-request: waitSeconds out of range.
403 ErrorResponse (10.1) forbidden: the caller lacks the contributor permission on the package.
404 ErrorResponse (10.1) not-found: unknown package or release, or the caller is no contributor of the package.

GET /packages/{packageId}/releases/{releaseId}/logs

The validation log of an uploaded release (text/plain).

Read it when the release status is failed, to learn why.

Parameters

Name Type Required Description
packageId path string yes The package id, as in package.json.
releaseId path string yes The id of the release.

Responses

Status Body Description
200 text (text/plain) The log as a text file.
403 ErrorResponse (10.1) forbidden: the caller lacks the contributor permission on the package.
404 ErrorResponse (10.1) not-found: unknown package or release, the caller is no contributor of the package, or the release has no log (yet).

POST /packages/{packageId}/releases/{releaseId}/publish

Publishes an uploaded release.

The release must be available or available-with-issues. Publishing runs on: the release is publishing first and published when done (wait with GET releases/{releaseId}).

Parameters

Name Type Required Description
packageId path string yes The package id, as in package.json.
releaseId path string yes The id of the release.

Request body

application/json: Publishes an available release.

Field Type Required Description
name string yes The name the package is published under. 1 to 50 characters.
description string yes The description the package is published with. 1 to 700 characters.
visibility string yes public, vendor or contributors.
versionTag string no none (default), release-candidate, technical-preview or unstable.
publishToCommunity boolean no Publishes to the community; only Matrix42 and partners may choose, everybody else always does.
termsAndConditionsAccepted boolean no Required for every vendor but Matrix42.

Responses

Status Body Description
200 UploadedReleaseResponse (7.10) The release with its status after the request; carries Retry-After while publishing.
400 ErrorResponse (10.1) terms-and-conditions-not-accepted, invalid-request (e.g. no body, or an invalid visibility).
403 ErrorResponse (10.1) forbidden: the caller lacks the publisher permission on the package.
404 ErrorResponse (10.1) not-found: unknown package or release, or the caller is no contributor of the package.
409 ErrorResponse (10.1) invalid-dependency-tree: the dependencies of the release can't be published (data.conflicts).

PUT /packages/{packageId}/releases/{releaseId}/publish

Changes the visibility, version tag or obsolete flag of a published release.

Parameters

Name Type Required Description
packageId path string yes The package id, as in package.json.
releaseId path string yes The id of the release.

Request body

application/json: Changes how a published release is offered.

Field Type Required Description
visibility string yes public, vendor or contributors.
versionTag string no none (default), release-candidate, technical-preview or unstable.
isObsolete boolean no Obsolete releases are no longer offered for automated installation.
upgradeFromCommunity boolean no Moves a community package to the vendor's own category; only Matrix42 and partners.

Responses

Status Body Description
200 UploadedReleaseResponse (7.10) The release.
400 ErrorResponse (10.1) invalid-request (e.g. no body, or an invalid visibility).
403 ErrorResponse (10.1) forbidden: the caller lacks the publisher permission on the package.
404 ErrorResponse (10.1) not-found: unknown package or release, the release is not published, or the caller is no contributor of the package.

Environments

The environments packages are installed on, as the server knows them: their installed packages and last reported product version. POST latest plans against the installed packages, and endpoints given only the environment use its product version.

GET /environments/{installationEnvironment}/installed-packages

The installed packages stored for an environment and its last reported product version.

Parameters

Name Type Required Description
installationEnvironment path string yes Host of the environment, e.g. customer.m42cloud.com.
skip query integer no Number of items to skip; default 0.
take query integer no Number of items to return, 1 to 100; default 20.

Responses

Status Body Description
200 InstalledPackagesResponse (7.3) A page of the packages; an empty list when none are known for the environment.
400 ErrorResponse (10.1) invalid-request: no valid host, or invalid paging.

POST /environments/{installationEnvironment}/installed-packages

Reports the installed packages of an environment.

By default the given packages are added or set to their version and all others are kept; with replace they replace all stored ones, so uninstalled packages drop out.

Parameters

Name Type Required Description
installationEnvironment path string yes Host of the environment, e.g. customer.m42cloud.com.

Request body

application/json: The installed packages an environment reports.

Field Type Required Description
productVersion string no Product (ESM) version of the environment, e.g. 12.1.0.1234; when given, it is stored as the known one of the environment (used by endpoints given only the environment). When left out, the stored one is kept.
installedPackages array of ReportedPackage (9.3) yes The installed packages, each at most once; with replace all of them, so an empty list means nothing is installed.
replace boolean no The packages replace all stored ones, so uninstalled packages drop out. By default only the given packages are added or set to their version and all others are kept.

Responses

Status Body Description
200 InstalledPackagesResponse (7.3) All installed packages stored for the environment afterwards.
400 ErrorResponse (10.1) invalid-product-version, invalid-installed-package (an installed package lacks its GUID id or a valid version, is given twice, or its releaseId is no release of the package in that version; errors names the field, nothing is stored), invalid-request (e.g. no valid host, no body).

Release Notes

Release notes: the published ones of a package, and the draft of each release for its vendor.

GET /packages/{packageId}/release-notes

The published release notes of a package, newest first.

Parameters

Name Type Required Description
packageId path string yes The package id, as in package.json.
version query string no Only the notes of this version, e.g. the installed one; 2.0 equals 2.0.0. A version can exist in several releases (differing in their product version requirement), so this can still be several notes.
skip query integer no Number of items to skip; default 0.
take query integer no Number of items to return, 1 to 100; default 20.

Responses

Status Body Description
200 list page (7.5) of ReleaseNoteResponse (7.9) A page of the notes; an empty list when the package has none.
400 ErrorResponse (10.1) invalid-request: invalid version or paging.
404 ErrorResponse (10.1) not-found: unknown package.

GET /packages/{packageId}/published/{releaseId}/release-note

The release note of a published release.

Parameters

Name Type Required Description
packageId path string yes The package id, as in package.json.
releaseId path string yes The id of the release.

Responses

Status Body Description
200 ReleaseNoteResponse (7.9) The published note.
404 ErrorResponse (10.1) not-found: unknown release, or it has no published note.

GET /packages/{packageId}/releases/{releaseId}/release-note

The release note of an uploaded release incl. an unpublished draft.

Parameters

Name Type Required Description
packageId path string yes The package id, as in package.json.
releaseId path string yes The id of the release.

Responses

Status Body Description
200 ReleaseNoteResponse (7.9) The note, published or not.
403 ErrorResponse (10.1) forbidden: the caller lacks the contributor permission on the package.
404 ErrorResponse (10.1) not-found: unknown package or release, the release has no note, or the caller is no contributor of the package.

PUT /packages/{packageId}/releases/{releaseId}/release-note

Creates (201) or replaces (200) the release note of an uploaded release.

Write the note as a draft any time; publish it (isPublished) once the release is published.

Parameters

Name Type Required Description
packageId path string yes The package id, as in package.json.
releaseId path string yes The id of the release.

Request body

application/json: Creates or updates the release note of a release.

Field Type Required Description
title string yes The title, e.g. the version; must not be empty.
content string no The text of the note, in the format of contentType.
contentType string no plaintext, markdown or html.
links array of ReleaseNoteLinkInput (9.2) no The links of the note, each name at most once.
isPublished boolean no Publishes the note; only possible for a published release.

Responses

Status Body Description
200 ReleaseNoteResponse (7.9) The note was replaced.
201 ReleaseNoteResponse (7.9) The note was created.
400 ErrorResponse (10.1) release-note-title-required, invalid-request (e.g. no body, a link without name or URL, or a link name given twice).
403 ErrorResponse (10.1) forbidden: the caller lacks the contributor permission on the package.
404 ErrorResponse (10.1) not-found: unknown package or release, or the caller is no contributor of the package.
409 ErrorResponse (10.1) release-not-published: isPublished for a release that is not published (yet); release-package-not-found: no published package exists for the release.

Responses

What the endpoints answer with (or a page of it, see ListResponse).

FailedInstallationResponse

A stored failed installation; the vendor sees it in the installation analytics of the package.

Field Type Description
packageId string The package id, as in package.json.
releaseId string The id of the release.
version string The version of the package.
installationEnvironment string The environment, as host.
failedAt string (date-time, UTC) When the failure was stored (UTC).
logEntryCount integer Number of stored log entries.

InstallationPlanResponse

How to install a release: what to install in which order and what the environment must provide.

Field Type Description
packageId string The package id, as in package.json.
releaseId string The id of the release.
version string The version of the package.
requiresMaintenanceMode boolean Whether the environment must be in maintenance mode for the installation.
installationOrder array of Prerequisite (8.2) The packages to install, in this order; the release itself is the last one.
dependencies array of Prerequisite (8.2) All package dependencies of the release, installed already or not.
uninstallablePrerequisites array of Prerequisite (8.2) What the environment must provide and the API can't install: the product version and software.

InstalledPackagesResponse

The installed packages stored for an environment, with its last reported product version.

Field Type Description
items array of InstalledPackage (8.1) The items of the page.
count integer The number of all items matching the request, not only of this page.
skip integer The number of skipped items, as requested.
take integer The page size, as requested.
installationEnvironment string The environment, as host.
productVersion string The product (ESM) version last reported for the environment; null when none is known.

LatestReleaseResponse

The release to install or update a package to on an environment.

Field Type Description
release PublishedReleaseDetailResponse (7.7) The release to install; with up-to-date, installed-version-newer and update-blocked the newest compatible release, which is not to be installed.
installedVersion string The installed version of the package; null when it is not installed.
installedReleaseId string The installed release; null when it is not installed or was reported without its release id.
updateStatus string not-installed, update-available, downgrade, up-to-date, installed-version-newer or update-blocked.
isUpdateAvailable boolean True when release is to be installed (not-installed, update-available, downgrade).
installationPlan InstallationPlanResponse (7.2) The plan to install release; only set when isUpdateAvailable.
skippedReleases array of SkippedRelease (8.5) Newer compatible releases that can't be installed, newest first, with the reasons.
unknownInstalledPackageIds array of string Installed packages unknown to the server; their requirements could not be checked.

ListResponse

The response of every v1 list endpoint: one page of the items.

Field Type Description
items array of object The items of the page.
count integer The number of all items matching the request, not only of this page.
skip integer The number of skipped items, as requested.
take integer The page size, as requested.

ProvisioningResponse

Where to download a release for installation.

Field Type Description
packageId string The package id, as in package.json.
releaseId string The id of the release.
version string The version of the package.
name string The name of the package.
vendorName string The name of the vendor.
downloadUrl string Pre-authorized, time-limited URL of the package (ZIP) incl. its license.
requiresMaintenanceMode boolean Whether the environment must be in maintenance mode to install the release.

PublishedReleaseDetailResponse

A published release of a package with all details, as offered for installation.

Field Type Description
packageId string The package id, as in package.json.
releaseId string The id of the release.
version string The version of the package.
name string The name the release is published under; it can change from release to release.
productVersionRequirement string Product (ESM) version requirement of the release: a minimum (e.g. ">=12.1"), a maximum ("<=13.0") or a range ("12.1-13.0"); null when it has none.
publishedAt string (date-time, UTC) When the release was published (UTC).
isObsolete boolean Whether the vendor marked the release obsolete; obsolete releases are not offered for automated installation and listed only with includeObsolete.
isPreview boolean Whether the release is a preview (unstable, technical preview or release candidate); listed only with includePreview.
isCritical boolean Whether the vendor marked the release as critical update.
isCompatible boolean Whether the release supports the product version; null when none is known. Listed as false only with includeIncompatible.
description string The description the package is published with.
vendorName string The name of the vendor.
vendorId string The id of the vendor.
productVersion string The product version the release was checked against; null when none is known.
isLicensed boolean Whether the caller is licensed to install the release.
isContentSigned boolean Whether the content of the package is signed.
isUninstallSupported boolean Whether the package can be uninstalled.
isSandboxed boolean Whether package.json marks the package as sandboxed.
requiresMaintenanceMode boolean Whether the environment must be in maintenance mode to install the release.
visibility string Who may see the release: public, vendor or contributors.
categories array of string The categories of the package.
logoUrl string URL of the package logo.
launchUrl string Where the installed package opens in the environment (launch URL of package.json), usually relative to the environment's host.

PublishedReleaseResponse

A published release of a package, as listed by GET published.

Field Type Description
packageId string The package id, as in package.json.
releaseId string The id of the release.
version string The version of the package.
name string The name the release is published under; it can change from release to release.
productVersionRequirement string Product (ESM) version requirement of the release: a minimum (e.g. ">=12.1"), a maximum ("<=13.0") or a range ("12.1-13.0"); null when it has none.
publishedAt string (date-time, UTC) When the release was published (UTC).
isObsolete boolean Whether the vendor marked the release obsolete; obsolete releases are not offered for automated installation and listed only with includeObsolete.
isPreview boolean Whether the release is a preview (unstable, technical preview or release candidate); listed only with includePreview.
isCritical boolean Whether the vendor marked the release as critical update.
isCompatible boolean Whether the release supports the product version; null when none is known. Listed as false only with includeIncompatible.

ReleaseNoteResponse

The release note of a release.

Field Type Description
packageId string The package id, as in package.json.
releaseId string The id of the release.
version string The version of the package.
title string The title of the note.
content string The text of the note, in the format of contentType.
contentType string plaintext, markdown or html.
links array of ReleaseNoteLink (8.4) The links of the note.
isPublished boolean Unpublished notes are only visible to the contributors of the package.
createdAt string (date-time, UTC) When the note was created (UTC).
releasePublishedAt string (date-time, UTC) When the release (not the note) was published; null for unpublished notes.
productVersionRequirement string Product (ESM) version requirement of the release: a minimum (e.g. ">=12.1"), a maximum ("<=13.0") or a range ("12.1-13.0"); null when it has none.

UploadedReleaseResponse

An uploaded release as its vendor sees it, published or not.

Field Type Description
packageId string The package id, as in package.json.
releaseId string The id of the release.
version string The version of the package.
status string E.g. pending, validating, available, available-with-issues, failed, publishing, published or revoked. A release can be published once it is available or available-with-issues. Values: failed, pending, published, cloning, compiling, publishing, available, available-with-issues, validating, empty, revoked.
releaseNumber integer Running number of the upload within the package.
uploadedAt string (date-time, UTC) When the release was uploaded (UTC).
uploadedBy string Who uploaded the release.
description string The description from package.json.
productVersionRequirement string Product (ESM) version requirement of the release: a minimum (e.g. ">=12.1"), a maximum ("<=13.0") or a range ("12.1-13.0"); null when it has none.
isCritical boolean Whether the release is marked as critical update.

Response Parts

Objects within the responses.

InstalledPackage

A package stored as installed on an environment, in its installed version; the release id is null when the package was reported without one.

Field Type Description
packageId string The package id, as in package.json.
releaseId string The id of the release.
version string The version of the package.

Prerequisite

A package, the product or software an installation needs.

Field Type Description
type string package, product or software.
packageId string The package id, for packages.
releaseId string The release to install, for packages.
name string The name of the package, product or software.
vendorName string The name of the vendor.
version string The version to install or installed (for the product: the environment's product version); null when it can't be resolved, and for software.
requiredVersion string The version (range) required, e.g. by the depending package or for software; null for the release itself.
isInstalled boolean Whether the environment has the package installed already.
isContentSigned boolean Whether the content of the package is signed.
mismatch string Why the prerequisite can't be met as required, e.g. version-mismatch; null when it can. Values: circular-dependency, version-mismatch, accessibility-mismatch, unreachable-due-to-no-access, unreachable-due-to-not-published-or-obsolete, unknown, not-publicly-available, incompatible-version-installed, unreachable-due-to-not-stable, product-version-mismatch.
description string For software: what it is.
downloadUrl string For software: where to get it.
documentationUrl string For software: its documentation.

ReleaseConflict

Why a release can't be installed. The package, release and version are the ones the package in conflict would get; release and version are null when it can't be resolved.

Field Type Description
packageId string The package id, as in package.json.
releaseId string The id of the release.
version string The version of the package.
type string dependency-mismatch (the dependency PackageId can't be resolved as requiredVersion, see mismatch) or breaks-installed-package (installing PackageId in Version violates the requiredVersion of the installed package installedPackageId).
requiredVersion string The version (range) required of the package: by the dependency of the release (dependency-mismatch) or by the installed package (breaks-installed-package).
mismatch string dependency-mismatch: why the dependency can't be resolved, e.g. version-mismatch. Values: circular-dependency, version-mismatch, accessibility-mismatch, unreachable-due-to-no-access, unreachable-due-to-not-published-or-obsolete, unknown, not-publicly-available, incompatible-version-installed, unreachable-due-to-not-stable, product-version-mismatch.
installedPackageId string breaks-installed-package: the installed package whose requirement would be violated.
installedVersion string breaks-installed-package: the installed version of that package.
installedReleaseId string breaks-installed-package: the installed release of that package; null when it was reported without one.

A link of a release note.

Field Type Description
name string The text of the link.
url string The URL of the link.

SkippedRelease

A newer release that can't be installed.

Field Type Description
packageId string The package id, as in package.json.
releaseId string The id of the release.
version string The version of the package.
conflicts array of ReleaseConflict (8.3) Why it can't be installed.

Request Parts

Objects within the request bodies; the bodies themselves are shown at their endpoints.

InstallationLogEntry

An entry of an installation log; time and message are stored as given.

Field Type Required Description
time string no When the entry was written, e.g. 2026-10-29T10:15:07Z.
level string no The log level: debug, trace, info, warning, error or critical; the case doesn't matter.
message string no The log message.

ReleaseNoteLinkInput

A link of a release note.

Field Type Required Description
name string yes The text of the link; unique within the note.
url string yes The URL of the link.

ReportedPackage

A package installed on the environment.

Field Type Required Description
packageId string yes The package id (GUID) as in package.json.
version string yes The installed version, e.g. 1.2.0.
releaseId string no The installed release, when known (e.g. from latest); it must be a release of the package in this version. Versions aren't unique per package, the release id is.

Error

The error every endpoint answers with, see 2. Errors.

ErrorResponse

The error of every v1 endpoint (RFC 9457 problem details, application/problem+json); its HTTP status code is also the response's status code.

Field Type Description
type string Identifies the kind of error as URI (RFC 9457), e.g. https://extensions.matrix42.com/problems/not-found; the same as code, which is easier to compare.
status integer The HTTP status code of the response.
code string Stable error code, e.g. not-found; each endpoint lists its codes with its responses.
title string Short summary of the status, e.g. "Not Found".
detail string What went wrong, for humans.
instance string The path of the request.
traceId string Identifies the request in the server logs.
errors array of ValidationError (10.3) The invalid request values.
data ErrorData (10.2) Further information about the error, depending on the code.

ErrorData

Further information about an error; which values are set depends on the code, each endpoint names them with its responses.

Field Type Description
packageId string The package the error is about.
releaseId string The release the error is about.
version string The version the error is about.
packageName string package-name-exists: the name of the uploaded package.
existingPackageId string package-name-exists: the package id of the existing extension of that name, if it has one.
uploadedPackageId string package-name-exists: the package id of the uploaded package.
productVersion string The product (ESM) version the request was checked against.
productVersionRequirement string incompatible-release: the product version requirement of the release.
releases array of PublishedReleaseResponse (7.8) no-compatible-release: all published releases of the package.
skippedReleases array of SkippedRelease (8.5) no-installable-release: the releases that can't be installed, with the reasons.
unknownInstalledPackageIds array of string no-installable-release: installed packages unknown to the server.
conflicts array of ReleaseConflict (8.3) invalid-dependency-tree: the dependencies that can't be resolved.

ValidationError

An invalid request value; a field with several problems has one entry per problem.

Field Type Description
field string The invalid field as named in the request, e.g. installedPackages[1].releaseId.
pointer string The invalid field in the JSON body as JSON pointer (RFC 6901, as RFC 9457 suggests), e.g. #/installedPackages/1/releaseId; not set for query and route parameters or form fields.
message string What is wrong with it, for humans.

Related Articles