Skip to main content
Every entity is versioned. Each push creates a new version with a timestamp identifier and a source hash for deduplication. One version is marked as active — this is what gets installed or deployed by default.

​
Upload version

Version upload is a two-step process: request an upload URL, then confirm the upload after the file is stored.

​
Step 1: Get upload URL

If the source hash matches an existing version (and force is false), the API returns the existing version info instead of generating an upload URL. This prevents duplicate uploads. Returns signed upload URLs for the main package and lockfile. Authentication: Entity access + publisher role required.

​
Step 2: Confirm upload

Creates the version record in the database. If set_as_active is true, this version becomes the active version. Authentication: Entity access + publisher role required.

​
Release notes

Each version can carry free-text notes describing what changed since the previous version, so version history doubles as a changelog. Notes are returned with every version record and are shown in version history in the desktop app and the store.
  • Supplied on confirm only. The upload-url step ignores it — notes belong to the version record, not the upload handshake.
  • Plain text, stored as-is. Anything past 2000 characters is truncated rather than rejected: a bad summary should never be the reason a publish fails.
  • Write-once. There is no endpoint to edit a version’s notes after the fact; versions are immutable. To correct notes, push a new version.
  • Omitted or blank notes are stored as null, and versions created before this field existed have null.
  • Ignored when deduplication short-circuits the push, since no new version is created — see below.
Notes are per-version. The entity’s description is separate and describes the app or service as a whole, not a particular release.

​
Push protection

A push may only extend the current tip: the most recently created version. Both upload endpoints validate base_version_id against it, and reject the push with 409 when the value is stale, or when it’s omitted while the entity already has versions:
latest_version is the current tip to reconcile against before retrying.
  • The first push to an entity needs no base_version_id.
  • force does not bypass this check; it only bypasses source-hash deduplication.
  • On confirm, deduplication runs first, so re-confirming a version you already published returns 200 with the existing version rather than 409.

​
Download version

Returns a signed download URL for the version package. Access is granted to:
  • Entity publishers
  • Users the entity is shared with
  • Organization members if the entity is published to the org store
  • Any authenticated user if the entity is in a public store
Authentication: Entity access required (multiple access paths).

​
Get active version

Returns the currently active version details. Authentication: Entity access required.

​
Set active version

The active version is what gets installed by default from stores or shares, and what gets deployed unless a specific version is specified. Authentication: Entity access + publisher role required.

​
Delete version

Deletes the version record and removes the package from storage. Cannot delete the active version — set a different active version first. Authentication: Entity access + publisher role required.

​
Version identifiers

Versions use a timestamp-based format: YYYY.MM.DD-HHMMSS (e.g., 2024.06.10-153042). This provides chronological ordering without semantic versioning complexity. The source_hash field enables deduplication — if you push the same source code twice, the platform recognizes the duplicate and returns the existing version rather than creating a new one.