Project versions

A project version is the exact configuration your project serves: one model, one system prompt, the catalog items you have chosen, and the tools the model may call, gathered into a single bundle. A project serves through a single endpoint, and each client asks it for the version it wants by number.

Like other entities in the portal, a project version is either a draft you are still building or a published version that is immutable.

What it is

A project version pulls together all things your project needs to run:

• A model, chosen from the models your organization has added.
• A system prompt, the instructions for that model. See The system prompt.
• A list of catalog items. Your catalog is shared across the whole organization, so a project version records exactly which version of each catalog item it uses. Two projects can pin different versions of the same catalog item without disturbing each other.
• A list of tools, the endpoints the model may call during a turn. Like catalog items, a tool is versioned, so a project version records exactly which version of each tool it uses, and it uses one version of any given tool. A tool can be shared across your whole organization or scoped to a single project. A project version can pin any of your organization’s tools and its own project’s tools, but not a tool that belongs to a different project.

A version is identified by its number. The number is the identity a client pins and serving resolves, and it never changes. You can also give a version a short name, a human-readable label like “spring launch” or “checkout redesign”, and a longer description to note anything specific about it. Both are optional. Wherever the portal shows a version it shows the name when one is set and the bare number when it is not, so a version without a name is just its number.

The reason to name a version is often learned after it ships, so you can set a name when you publish and change it later without republishing. Renaming changes only the label. It never changes what serves: the number a client pins still resolves to the same model, prompt, and catalog items.

Publishing turns the draft into an immutable numbered version that can never change again. A client that pins a specific project version is guaranteed the same system prompt, model, catalog items, and tools it was built against.

A client can serve the draft too, by pinning its number — the same vN a published version uses. There is no separate “draft” keyword: a client always pins a number, and to reach an unpublished version it uses the draft’s number, which the Versions screen shows as vN (draft). While that version is a draft, pinning its number serves whatever the draft currently holds, so you can exercise unreleased changes before publishing. Keep in mind that a draft changes as you edit it.

Because a version’s number is stable, publishing does not break a client pinned to it. When you publish, that number stops naming a mutable draft and starts naming the frozen published version, so a client pinned to it simply moves from previewing the draft to serving the finished version, with no gap and no re-pin. This is why a client serves a draft by its number rather than a keyword: the number is the same before and after publish.

Publishing a version publishes its pieces too. If the system prompt version, any catalog item, or any tool it pins is still a draft, publishing the version publishes those first, in one step, then freezes the version. You do not have to publish each piece by hand. One thing to know: a catalog item is shared across your whole organization, and a tool can be too, so publishing a version that pins a draft of one freezes it for every project, not just this one. Because that freeze is hard to undo, the dashboard asks you to confirm before it publishes a version that still pins drafts, and it names what will be frozen.

Your client chooses which version it runs. Every serving turn names the version it wants, and the platform serves that exact bundle. Your app pins a number and keeps serving it while you build and publish the next one, so a new version never changes what a running app sees until the app asks for it. When you want an app to move to a newer version, point it at the new number. When you want it back on an older one, point it at the older number. The version each app runs is the app’s decision, made per turn, not a switch the portal flips for you.

A client always pins a version by number, whether that version is published or still a draft. A number that names no version of the project is refused.

How to use it

Open a project and go to its Versions screen. It lists the project’s versions newest first, each showing its number and whether it is a draft or published. A brand-new project has none yet, and this is where you build the first one.

Before you can start a draft, your organization needs a model and at least one catalog item, and the project needs a system prompt. If any of those is missing, the New draft control tells you which and links you straight to it.

Once they are in place, use New draft to begin one. It starts seeded with a model and a system prompt, but no catalog items yet, so you add those next.

Shape the draft. Choose its model, point it at a system prompt version, and optionally give it a name and a description. Add catalog items by pinning a version of each: a project version uses one version of any given catalog item, so choosing a different version of a catalog item you already use swaps it rather than adding a second, and setting a catalog item to “not included” drops it. A catalog item you are still building shows as a draft until you publish it, and as a numbered version afterward. Tools work the same way: pin a version of each tool the model should be able to call, one version per tool, with the same swap-or-drop behaviour and the same draft-until-published labelling. Only your organization’s shared tools and this project’s own tools are offered. Remember: changes only touch the draft, never a published version your app is already serving.

Publish it. When the draft is ready, publish it to freeze it into an immutable version. Its number does not change on publish, so any client already pinned to that number keeps serving, now the frozen version rather than the draft. You can give it a name as you publish, or leave it unnamed and add one later.

Look at a published version. Publishing freezes a version, so opening one shows it read-only: its model, its system prompt version, each catalog item it pins, and each tool it pins, every piece labelled with its own version. You cannot change what a published version serves. The one thing you can still change is its name: rename it whenever the right label becomes clear, and serving does not move, because the number stays the identity. To change anything else, start a new draft.

You can also create and edit drafts through the API and MCP. Agents build drafts but never publish or name a version, which stays a person’s deliberate step.

Failure modes

• “A draft already exists.” A project keeps one draft version at a time. Publish or finish the current draft before starting another.
• The version cannot be changed. You tried to edit, or add or drop a catalog item or a tool on, a version that is already published. Published versions are frozen. Start a new draft and make the change there.
• The tool cannot be pinned. You tried to pin a tool that belongs to a different project. A project version can pin your organization’s shared tools and its own project’s tools, but not another project’s tools. Pin a shared tool instead, or add the tool to this project.
• “Unsupported version.” A client pinned a number that names no version of this project. Point the client at a number the project has: a published version, or the draft’s number (shown as vN (draft) on the Versions screen) to serve the draft.
• The agent says it cannot rename or re-describe the project. The project already has a published version, so relabeling it is a member’s action, not an agent’s. Rename or re-describe it yourself through the API. See Creating and managing projects.
• A model will not delete. A project version still pins that model, and a model in use cannot be removed, so the versions built on it keep serving. Point your draft versions at a different model to free it. A published version’s model is frozen, so a model that any published version pins stays until that is no longer the case.