Extensions

Extension Versioning

Extension versions are immutable snapshots of a manifest. Published versions cannot be changed. Installs are always pinned to a specific version, so rolling out a change requires publishing a new version and upgrading each install explicitly.

After publishing an upgrade, follow the operations guide to monitor adoption, compatibility, and incidents.

Version lifecycle

A version starts as draft and becomes published when you publish it. Once published, the version record is frozen — its scopes, iframeUrl, webhookUrl, and eventSubscriptions never change.

stateDiagram-v2
  [*] --> draft: POST /extensions/:id/versions
  draft --> published: POST .../publish
  published --> [*]: (immutable — never changed)
Extension version lifecycle. Published versions are immutable.

In the dashboard you never number a version by hand. Once an extension is private or public, Publish a new version on its Publish tab snapshots the saved settings as the next patch version (for example 1.0.3 after 1.0.2) and publishes it. The Versions tab lists every version and marks the one new installs get as Live. The API calls below do the same thing.

Create version
# Create a new version (snapshots the current manifest)
curl -X POST https://api.usethrottle.dev/api/v1/extensions/ext_xxx/versions \
  -H "Authorization: Bearer <dashboard-session>" \
  -H "content-type: application/json" \
  -d '{
    "version": "1.1.0",
    "notes": "Added customers:read scope for contact lookup feature"
  }'
# Response:
# {
#   "data": {
#     "id": "ver_new...",
#     "version": "1.1.0",
#     "status": "draft",
#     "scopes": ["orders:read", "customers:read"],
#     "notes": "...",
#     "createdAt": "..."
#   }
# }
Publish version
# Publish a draft version (makes it installable)
curl -X POST https://api.usethrottle.dev/api/v1/extensions/ext_xxx/versions/ver_new/publish \
  -H "Authorization: Bearer <dashboard-session>" \
  -H "content-type: application/json" \
  -d '{}'
List versions
# List all versions for an extension
GET /api/v1/extensions/ext_xxx/versions
# Response: { data: { versions: [ { id, version, status, scopes, ... }, ... ] } }

Which versions can be pinned

An install that names a versionId and an upgrade or rollback that names a targetVersionId follow the same rule:

  • The version must belong to the extension. Any other id, including a version of a different extension, returns 404 not_found.
  • A draft version is never pinned in production, which returns 422 draft_not_installable_in_live. Outside production, only the workspace that owns the extension may pin a draft.
  • The workspace that owns the extension may pin any of its other versions, including published versions still awaiting marketplace review and older versions.
  • Any other workspace may pin only the version a fresh install would get: the approved version of a public extension, or its latest published version if it has never been approved. Anything else returns 422 version_not_approved.

An install with no versionId pins that same default version.

Installs are pinned

When an extension is installed, the install row records the exact versionId. Publishing a new version has no effect on existing installs — they continue running on the pinned version indefinitely. This provides stability: a breaking manifest change cannot affect installs that have not opted in to the upgrade.

The dashboard may surface an "upgrade available" indicator when a newer published version exists for an installed extension. The installer decides when and whether to upgrade.

Upgrading

Use POST /api/v1/installations/:id/upgrade to move an install to a different published version. The install's API key is updated to reflect the new version's scopes; the config is preserved.

Upgrade with consent
# Attempt to upgrade to a new version
curl -X POST https://api.usethrottle.dev/api/v1/installations/inst_xxx/upgrade \
  -H "Authorization: Bearer <dashboard-session>" \
  -H "X-Throttle-Application-Id: <applicationId>" \
  -H "content-type: application/json" \
  -d '{ "targetVersionId": "ver_new..." }'
# If the new version requests scopes not in the current install:
# HTTP 409
# {
#   "error": {
#     "code": "new_scopes_require_consent",
#     "newScopes": ["customers:read"]
#   }
# }
# Retry with explicit consent:
curl -X POST https://api.usethrottle.dev/api/v1/installations/inst_xxx/upgrade \
  -H "Authorization: Bearer <dashboard-session>" \
  -H "X-Throttle-Application-Id: <applicationId>" \
  -H "content-type: application/json" \
  -d '{
    "targetVersionId": "ver_new...",
    "acknowledgedNewScopes": true
  }'
# → { data: { id: "inst_xxx", versionId: "ver_new...", ... } }
  • Only an active installation can be upgraded or rolled back. A suspended or uninstalled installation returns 409 installation_not_active and is left unchanged.
  • If the new version's scopes are a subset of the current version's scopes (scope reduction), no consent is required and the upgrade proceeds immediately.
  • If the new version requests additional scopes, the endpoint returns 409 new_scopes_require_consent with the delta. Retry with acknowledgedNewScopes: true to confirm.
  • The target must be a version this workspace may pin (see Which versions can be pinned). Installers of another workspace's public extension can move to a new version once it is approved.
Re-consent gates production installs
The consent requirement protects against a malicious extension publisher silently acquiring new scopes. The installer must explicitly acknowledge each new scope — the 409 lists exactly which scopes are being added so the operator can make an informed decision.

Rollback

Rolling back to an older version uses the same upgrade endpoint — just target an earlier versionId. Because older versions have fewer or equal scopes, rollback typically does not require consent. After rollback, the install runs the older version's manifest (including its iframeUrl and event subscriptions). Rollback follows the same pinning rule as an upgrade: the owning workspace can roll back to any of its versions, while installers of another workspace's public extension can only target its approved version.

Roll back
# Roll back to an older published version by upgrading to it.
# "Rollback" and "upgrade" use the same endpoint — just target an earlier versionId.
# No consent required if the older version's scopes are a subset of the current scopes.
curl -X POST https://api.usethrottle.dev/api/v1/installations/inst_xxx/upgrade \
  -H "Authorization: Bearer <dashboard-session>" \
  -H "X-Throttle-Application-Id: <applicationId>" \
  -H "content-type: application/json" \
  -d '{ "targetVersionId": "ver_old..." }'
Config is preserved across upgrades and rollbacks
The installation's config object is not changed by an upgrade or rollback. If the new version requires different config keys, update config separately via PATCH /api/v1/installations/:id/config.

Versioning strategy

  • Use semantic versioning (e.g. 1.0.0) — it is stored as a string, not parsed.
  • Additive changes (new UI features within the same scopes, bug fixes, updated iframeUrl) can be shipped as a new version without requiring install consent.
  • New scopes always require explicit upgrader consent.
  • Removing scopes does not require consent — it is a reduction.
  • Keep at least the previous published version available to allow rollback without republishing.

See also: Security model for how scope ceilings are enforced at the version level, and Installing extensions for the full install lifecycle.