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

POST /api/entities/{entityId}/versions/upload-url
ParameterTypeRequiredDescription
versionbodyYesVersion string (e.g., 2024.06.10-153042)
source_hashbodyYesSHA hash of the source code
base_version_idbodyNoParent version ID for lineage tracking
forcebodyNoCreate version even if source hash already exists
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

POST /api/entities/{entityId}/versions/confirm
ParameterTypeRequiredDescription
storage_pathbodyYesPath where the package was uploaded
versionbodyYesVersion string
source_hashbodyYesSource code hash
file_size_bytesbodyYesPackage file size
service_dependenciesbodyNoArray of required service slugs
package_jsonbodyNoPackage.json contents
package_lock_pathbodyNoLockfile storage path
set_as_activebodyNoSet this version as active immediately
forcebodyNoForce creation
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.

​
Download version

GET /api/entities/{entityId}/versions/{versionId}/download
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

GET /api/entities/{entityId}/active-version
Returns the currently active version details. Authentication: Entity access required.

​
Set active version

PUT /api/entities/{entityId}/active-version
ParameterTypeRequiredDescription
versionIdbodyYesVersion ID to set as active
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

DELETE /api/entities/{entityId}/versions/{versionId}
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.