Version prompts

Every change to a prompt creates a new version, and by default your application uses the latest one. A prompt you edit in the UI takes effect immediately, with no redeploy. To control when a change reaches production, pin a version in code or assign versions to environments. As each prompt change creates a new version automatically, you can:

Compare performance across versions.
Roll back to previous versions.
Pin experiments to specific versions.
Track which version is used in production.

View version history in the prompt editor and select any version to restore or compare. When saving prompt changes, the update dialog shows a Preview changes section that displays the diff between your changes and the previous version. Large text and object diffs are truncated by default for performance. Click Show more to view the complete diff. Expand Version comment in the update dialog to describe what changed, up to 5,000 characters. The comment is saved with that version. The field isn’t available if your organization has disabled comments, since the comment wouldn’t be visible afterward. The prompt’s Activity tab lists version history alongside any comments. Each entry that created a version shows the version it replaced next to the new one, and you can select either to view or compare it.

Pin a specific version

Every prompt save creates a new version with a unique ID. Pin a version in production code so later saves don’t affect your application until you update the pin. Both ways of using a prompt in code accept a version parameter. To pin a version you invoke on Braintrust:

import { invoke } from "braintrust";

const result = await invoke({
  projectName: "My Project",
  slug: "summarizer",
  version: "5878bd218351fb8e", // Pin to specific version
  input: { text: "Long text to summarize..." },
});

from braintrust import invoke

result = invoke(
    project_name="My Project",
    slug="summarizer",
    version="5878bd218351fb8e",  # Pin to specific version
    input={"text": "Long text to summarize..."},
)

To pin a version you load and run with your own LLM client:

const prompt = await loadPrompt({
  projectName: "My Project",
  slug: "summarizer",
  version: "5878bd218351fb8e", // Pin to specific version
});

require "braintrust"

prompt = Braintrust::Prompt.load(
  project: "My Project",
  slug: "summarizer",
  version: "5878bd218351fb8e" # Pin to specific version
)

params = prompt.build(text: "Long text to summarize...")

Without a version parameter, every one of these uses the latest version.

Use bt prompts versions to look up a prompt’s version IDs from the terminal. Both short and decimal transaction IDs are accepted.

Use environments

Environments separate dev, staging, and production configurations. Assign a prompt version to an environment, then load the version assigned to that environment from your code. To assign a prompt to an environment:

Go to Prompts.
Open the prompt.
Click the icon.
Select an environment.

List the prompt’s versions, then assign one to an environment:

bt prompts versions my-prompt
bt prompts assign my-prompt --version 1234 --environment production

To remove the prompt from the environment:

bt prompts unassign my-prompt --environment production

Use POST /v1/prompt or PUT /v1/prompt and pass environment_slugs to assign the prompt to one or more environments in a single atomic request. If any slug doesn’t exist, the entire request fails and no prompt is created.

curl -X POST https://api.braintrust.dev/v1/prompt \
  -H "Authorization: Bearer $BRAINTRUST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "your-project-id",
    "name": "My prompt",
    "slug": "my-prompt-slug",
    "environment_slugs": ["dev", "staging"],
    "prompt_data": {
      "prompt": {
        "type": "chat",
        "messages": [{"role": "system", "content": "You are a helpful assistant"}]
      },
      "options": {
        "model": "gpt-5-mini"
      }
    }
  }'

Once assigned, load prompts for that environment in your code:

import { loadPrompt } from "braintrust";

// Load from specific environment
const prompt = await loadPrompt({
  projectName: "My Project",
  slug: "my-prompt",
  environment: "production",
});

// Use conditional versioning
const prompt = await loadPrompt({
  projectName: "My Project",
  slug: "my-prompt",
  version: process.env.NODE_ENV === "production" ? "5878bd218351fb8e" : undefined,
});

from braintrust import load_prompt
import os

# Load from specific environment
prompt = load_prompt(
    project="My Project",
    slug="my-prompt",
    environment="production"
)

# Use conditional versioning
prompt = load_prompt(
    "My Project",
    "my-prompt",
    version="5878bd218351fb8e" if os.environ.get("NODE_ENV") == "production" else None,
)

# Load by project ID and slug
curl "https://api.braintrust.dev/v1/prompt?slug=my-prompt-slug&project_id=PROJECT_ID&environment=production" \
  -H "Authorization: Bearer $BRAINTRUST_API_KEY"

# Load by prompt ID
curl "https://api.braintrust.dev/v1/prompt/PROMPT_ID?environment=production" \
  -H "Authorization: Bearer $BRAINTRUST_API_KEY"

Invoke an environment-pinned prompt with invoke()

invoke() does not accept an environment parameter. To execute an environment-pinned prompt server-side via invoke(), resolve the version with loadPrompt() first and pass it to invoke():

const prompt = await loadPrompt({
  projectName: "My Project",
  slug: "summarizer",
  environment: "production",
});

const result = await invoke({
  projectName: "My Project",
  slug: "summarizer",
  version: prompt.version,
  input: { text: "Long text to summarize..." },
});

This pins the call to the version that was assigned to the environment when loadPrompt() ran. Re-call loadPrompt() if you need to pick up environment reassignments.

Assigning versions to environments is how you manage different versions of a prompt across your development lifecycle. See Manage environments for details on creating and using environments.

Next steps

Manage environments to separate dev, staging, and production across prompts, datasets, and functions.
Use prompts in code to invoke pinned or environment-scoped prompts.
Manage prompts to duplicate prompts and customize the Prompts page.
Monitor deployments to track prompt performance in production.

Start

Instrument

Observe

Annotate

Evaluate

Deploy

Admin

Best practices

Pin a specific version

Use environments

Next steps

​Pin a specific version

​Use environments

​Next steps

Pin a specific version

Use environments

Next steps