Skip to content
Rival Docs

Versions & Publishing

A version is a complete snapshot of your tool at a specific point in time - the code, runtime, 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. If you need to update the tool, you publish a new version.

This design means callers can depend on your tool’s behavior not changing under them. It also means you can iterate freely in the builder without affecting anyone who is already 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 number. You choose the increment - patch, minor, or major - based on the nature of the change.

Use minor increments (e.g. 1.0 → 1.1) for backwards-compatible changes like adding an optional input field or improving performance. Use major increments (e.g. 1.x → 2.0) when you’re making breaking changes to the input schema or the shape of the output.

Publishing a tool

Publishing is the final step in the tool builder - Step 6: Publish. Before you reach this step, you need at least one passing test case. If that requirement isn’t met, the publish step will prompt you to return to Code & Test.

Set pricing

On the publish step, you choose how the tool is priced:

  • Free - anyone can execute the tool at no credit cost to them.
  • Paid per execution - callers consume credits each time the tool runs. You set the credit cost.
  • Private - the tool is only accessible via API key. It does not appear in marketplace search results and cannot be executed by arbitrary users.

Confirm and publish

Once you’ve set pricing, confirm the publish. Rival validates the tool, packages the version, and makes it live. This typically takes a few seconds.

After publishing, your tool receives a stable public URL and is callable via the API. If visibility was set to Public, it also appears in the marketplace at cortexone.rival.io.

What callers see

Callers interact with your tool through its public URL. By default, requests go to the latest published version. Callers who need stability can pin to a specific version by including the version string in the request. This is useful for integrations that depend on a particular input/output contract.

The tool’s detail page on the marketplace shows a changelog that tracks changes between versions. This gives users an at-a-glance view of what changed and when, so they can decide whether to stay on a pinned version or move to the latest.

Updating a tool

To update a published tool, return to the builder and make your changes. The builder always operates on a draft - your edits don’t affect any published version. When you’re ready, go through the publish step again. This creates a new version alongside the existing ones.

Existing integrations that call the previous version by number continue to work. Only callers using the “latest” default will automatically get the new version.

Public vs. private tools

A tool set to Public is listed in the marketplace and discoverable by any Rival user. A tool set to Private is accessible only within your organization via API key - it won’t appear in search results and can’t be executed by unauthenticated users.

You can change a tool’s visibility when publishing a new version. For example, you might develop a tool privately, validate it internally, and then flip it to public in a later version once you’re confident it’s ready for broader use.