Documentation Index Fetch the complete documentation index at: https://braintrust.dev/docs/llms.txt
Use this file to discover all available pages before exploring further.
Environments let you maintain different versions of prompts, datasets, and parameters across your development lifecycle. This enables you to:
Maintain version control : Pin stable versions to production while testing new versions in developmentEnable staged deployments : Promote versions through dev/staging/production pipelinesSupport A/B testing : Compare different versions across environmentsIsolate changes : Test modifications without affecting production systems
Create an environment Environments are defined at the organization level:
Go to
Click + Environment .
Enter a name (e.g., “production”, “staging”, “dev”).
Click Create environment .
Assign to environments Prompts To assign a prompt to an environment:
Go to
Open the prompt.
Click the
Select an environment.
Use POST /v1/promptPUT /v1/promptenvironment_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 , });
# 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 "
Datasets Environments are attached to dataset snapshots , not datasets directly. To assign a snapshot to an environment:
Go to
Open the dataset.
Click Snapshots in the toolbar.
Find the snapshot you want to assign, then select Environments .
Toggle the environments in the submenu.
You can also tag and untag environments from Loop when working on a dataset page. # 1. Create a snapshot curl -X POST https://api.braintrust.dev/v1/dataset_snapshot \ -H "Authorization: Bearer $BRAINTRUST_API_KEY " \ -H "Content-Type: application/json" \ -d '{ "dataset_id": "DATASET_ID", "name": "prod snapshot", "xact_id": "DATASET_VERSION_OR_XACT_ID" }' # 2. Upsert the environment association curl -X PUT https://api.braintrust.dev/environment-object/dataset/DATASET_ID/ENVIRONMENT \ -H "Authorization: Bearer $BRAINTRUST_API_KEY " \ -H "Content-Type: application/json" \ -d '{ "object_version": "SNAPSHOT_XACT_ID" }'
Once assigned, load the dataset for that environment in your evals:
import { Eval, initDataset } from "braintrust" ; // Load by environment Eval ( "My App" , { data: initDataset ({ project: "My App" , dataset: "My Dataset" , environment: "production" }), task : async ( input ) => { /* ... */ }, scores: [], }); // Load by version name Eval ( "My App" , { data: initDataset ({ project: "My App" , dataset: "My Dataset" , version_name: "version 1" }), task : async ( input ) => { /* ... */ }, scores: [], }); // Load by xact_id (less readable, but precise) Eval ( "My App" , { data: initDataset ({ project: "My App" , dataset: "My Dataset" , version: "8234923849293849..." }), task : async ( input ) => { /* ... */ }, scores: [], });
Parameters To assign a specific parameter version to an environment:
Go to
Open the parameter.
Click the
Select an environment.
Once assigned, load parameters for that environment in your code:
import { loadParameters } from "braintrust" ; const params = await loadParameters ({ projectName: "My Project" , slug: "eval-config" , environment: "production" , });
Move tested versions from development to production:
Test a new prompt or parameter version in the “dev” environment.
Run experiments to validate performance.
Once satisfied, assign the same version to “staging”.
After final validation, assign to “production”.
This workflow ensures changes are validated before reaching production users.
Monitor environment changes Set up environment alerts to get notified via webhook or Slack when prompt, dataset, or parameter versions are assigned to or removed from environments. Use these to track deployments, maintain audit trails, or trigger downstream CI/CD workflows.
Common patterns Three-tier deployment Maintain dev, staging, and production environments:
dev : Latest changes, frequent updates, used by developers.staging : Pre-release testing, stable versions.production : Customer-facing, only validated versions.
Feature flags Use environments to control feature rollouts:
Create an environment for each feature flag.
Assign different prompt, dataset, or parameter versions based on flag state.
Gradually roll out by changing environment assignments.
A/B testing Test variations by environment:
Create environments for each variant (e.g., “variant-a”, “variant-b”).
Assign different prompt, dataset, or parameter versions to each.
Route users to different environments based on A/B test assignment.
Compare performance using environment filters.
Next steps 
