Skip to content
Rival Docs

Versions & Publishing

A version is a complete snapshot of your tool at a specific point in time - the code, language, input schema, events, pricing, and configuration. When you publish, Rival captures all of that into an immutable record. Nothing about a published version can be changed. To update the tool, you publish a new version.

This means callers can depend on your tool’s behavior staying the same once they pin a version, and you can iterate freely in the editor without affecting anyone using a live version.

Version numbering

Versions follow semantic versioning: 1.0, 1.1, 2.0, and so on. The first time you publish a tool, it becomes version 1.0. Each subsequent publish increments the version. You choose the increment when you publish:

  • Patch - internal fixes that don’t change behavior callers see.
  • Minor - backwards-compatible improvements (e.g. adding an optional input).
  • Major - breaking changes to the input schema or output shape.

Rival generates the version name automatically based on your choice.

Publishing a tool

Publishing is the final step in the Tool Editor: Publish. You can reach it from the stepper or by flipping the mode toggle at the top of the Code step from Test to Publish.

Before you can publish you need at least one passing test case. If you don’t have one, the Publish step routes you back to the Test panel.

Set visibility

  • Private - the tool is only accessible inside your organization. It does not appear in marketplace search and can only be called by org members or via an API key from your workspace.
  • Public - the tool is submitted to the marketplace, where any Rival user can discover and use it.

Set pricing

For public tools you choose how callers pay:

  • Free - no credit cost to the caller.
  • Paid per run - callers consume credits each time the tool runs. You set the credit cost.

Private tools don’t need pricing - only members of your workspace can run them.

Write release notes

Add a short changelog entry describing what changed in this version. This is shown in the version history and on the marketplace page so users can decide whether to upgrade.

Confirm and publish

Click publish. Rival validates the tool and packages the version. For Private tools this is immediate - the version is live as soon as it’s packaged. For Public tools the version is queued for marketplace review; you’ll receive an email when it’s approved or flagged. Approved versions appear in marketplace search; flagged versions stay private until you address the feedback.

After publishing, the tool gets a stable URL and is callable via the Rival API.

Version history

Every version your tool has ever shipped is listed in the Tool Editor’s version history. From there you can:

  • View the code, schema, and metadata of any past version
  • Roll forward by starting a new draft from an older version
  • Deprecate or delete individual versions (see Deprecating vs Deleting)

The same history appears on the public marketplace page so callers can see the changelog between versions and decide whether to move from a pinned version to the latest.

Updating a published tool

To update a tool, open it in the Tool Editor and make changes - they apply to a draft, not to any live version. When you’re ready, go through the Publish step again to ship a new version alongside the existing ones.

Existing integrations pinned to an older version keep working unchanged. Only callers hitting the “latest” alias will pick up the new version automatically. See APIs for how version pinning works in requests.

Changing visibility

You can change visibility when you publish a new version - for example, develop privately, validate internally, then flip to public on 1.2.

Next steps