Skip to content
Rival Docs

Versions

Overview

Every time you publish a tool on Rival, you create a version. Versions are the unit of deployment - they capture a complete snapshot of your tool at a point in time and make that snapshot permanently accessible to callers.

What a version contains

A version is not just your code. It packages together everything that defines how a tool behaves:

  • The handler code and runtime
  • The input schema (parameter names, types, and validation rules)
  • Any event configuration
  • The pricing model (free, paid per execution, or private)

All of these are frozen together at publish time. This matters because callers who depend on your tool can trust that the version they are calling will never change behavior underneath them.

Immutability

Public versions cannot be edited. Once a version is live, it stays exactly as it was when you published it - no silent changes, no patches, no amendments.

This is intentional. If a caller has integrated your 1.0 tool into their application, they should be able to rely on it indefinitely. If you need to fix a bug, add a parameter, or change the pricing, you create a new version. The old version remains available and callable.

However, a privately published version, which is available for just your organization, is mutable, and you can make changes to it. To update a private version, from the My Tools page, open the respective tool, make your changes in the tool builder after selecting the private version, and publish it.

Version numbers

Rival follows semantic versioning, but version names are generated automatically.

When publishing a new version, you choose the type of update:

  • Patch → bug fixes and small tweaks (0.0.1 → 0.0.2)
  • Minor → new features, backwards compatible (0.0.1 → 0.1.0)
  • Major → breaking changes (0.0.1 → 1.0.0)

Based on your selection, Rival automatically assigns the next version number - you do not manually enter version names.

The version number appears on:

  • The tool’s detail page in the marketplace
  • The API invocation endpoint

This ensures callers can clearly identify and target a specific version.

The changelog

Each tool’s detail page on the marketplace includes a changelog that lists all published versions in order. This gives callers visibility into what has changed over time and helps them decide when to upgrade.

When you publish a new version, you can include a description of what changed. Writing a clear changelog entry is good practice - it helps your users understand what is new and whether they need to update their integration.

Draft vs. published

While you are building or updating a tool, it exists in a Draft state. Draft tools are not versioned and are not accessible via the API. When you are ready to release, publishing creates the first (or next) version and makes the tool callable.

Unpublished changes you make after a tool is already live are also held in draft until you publish again. This lets you work on the next version without affecting anyone currently using the tool.