Publish

Model versioning

How versions work today, and how to give consumers a predictable upgrade path with the primitives that exist.

There is no revision history

A listing carries one version string and one artifact. Previous versions are not retained, and there is no /revisions endpoint, no version pinning in the API, no yank flag, and no diff between versions. This page previously described all of those as if they existed. What follows is how to get the same guarantees with what is real.

Semantic versioning

version is a free-form string up to 40 characters, defaulting to 1.0.0. Nothing enforces a format, so the convention is yours to keep — use MAJOR.MINOR.PATCH and bump:

  • MAJOR when inputs, outputs, or preprocessing change in a way that breaks existing callers
  • MINOR when behaviour improves compatibly — better accuracy, same interface
  • PATCH for fixes that change nothing about the interface

Recording a new version

http
PATCH /v1/models/{id_or_slug}
Authorization: Bearer <key>

{ "version": "2.0.1" }

Requires listings:write. Bumping version updates the string; if the weights changed, upload the new artifact first and pass its storage_path in the same call.

Artifacts are not immutable — plan for that

Replacing the artifact on a listing overwrites what consumers download. Anyone who validated the old file gets the new one on their next call, with no way to ask for what they tested against. That is a real hazard, and it is the reason for the pattern below.

One listing per version consumers must pin

If people run your model in production, publish each significant version as its own listing. It costs you a second listing and gives them an address that cannot change underneath them.
http
# Publish each version consumers must be able to pin to as its own listing.
POST /v1/uploads          → storage_path for the new artifact
POST /v1/models           { "title": "Grasp Policy v2", "version": "2.0.0", … }

# A patch everyone should take can replace the artifact on the same listing.
POST /v1/uploads          → storage_path
PATCH /v1/models/{id}     { "version": "2.0.1" }

Pinning, from the consumer side

The API cannot resolve a version constraint for you, so pin on your side: record both the listing id and the version you validated, and compare before trusting a fresh download.

http
# Resolve a listing and record exactly what you consumed.
GET /v1/models/{id_or_slug}
→ { "id": "cm5x9…", "version": "2.0.1", "file": { "size": 184320042, … } }

# Store the id AND the version you validated against, then re-check before
# trusting a later download — if version moved, re-run your evaluation.

Checking file.size alongside version also catches the case where an artifact was replaced without the version being bumped.

Withdrawing a bad version

There is no yank flag. To withdraw a version, unpublish the listing:

http
POST /v1/listings/{id_or_slug}/unpublish

That removes it from the marketplace immediately. Existing buyers keep their access — purchase history and download rights are preserved deliberately, so unpublishing is not a recall. If a version is dangerous rather than merely superseded, contact the buyers; the platform will not do it for you.

Comparing versions

Not available — there is no diff endpoint. Put a changelog in the listing description, which is the field consumers actually read before upgrading.

Retention

A published listing and its artifact are retained until you unpublish it, and unpublishing keeps both so existing buyers can still download — it only removes the listing from the marketplace. A superseded artifact on a listing whose file you replaced is not retained.