Skip to main content
Applies to:


​
Use case

In order to use Braintrust as a central prompt registry for production agentic workflows, enabling developers to save prompts in Braintrust and automatically make them available in external systems, with environment-based deployment controls and update notifications.

​
Features used

Prompts API: The REST API endpoints (/v1/prompt) allow you to programmatically query, list, and retrieve prompt objects with filtering by project, slug, version, and other parameters. SDK loadPrompt(): The Braintrust SDK provides a loadPrompt() function that enables loading prompts directly in production code with support for version pinning and environment tags, eliminating the need for manual API calls. Environment Tags: Tags (production, staging, development) allow you to associate prompt versions with specific environments and promote prompts through your deployment pipeline in a controlled manner. Environment Update Alerts: Webhook-based alerts that trigger when environment tags are added or removed from prompts, providing a user-initiated workflow for syncing prompt updates to external systems.

​
Steps

​
Step 1: Query prompts using the API

Use the Prompts API to list or retrieve specific prompt objects. The API supports filtering by project, slug, version, and other parameters. List prompts: 
curl -X GET "https://api.braintrustdata.com/v1/prompt?project_name=my-project&slug=my-prompt" \
  -H "Authorization: Bearer YOUR_API_KEY"
Get a specific prompt by ID: 
curl -X GET "https://api.braintrustdata.com/v1/prompt/{prompt_id}" \
  -H "Authorization: Bearer YOUR_API_KEY"
API Documentation:

​
Step 2: Load prompts directly in production code using the SDK

For production workflows, use the SDK’s loadPrompt() function to load prompts directly in your code. This approach supports version pinning and environment tags, allowing you to control which prompt version is used in different environments. 
const prompt = await loadPrompt({
  projectId: "your-project-id",
  slug: "your-prompt-slug",
  environment: "production",  // or "staging", "development"
  version: "8c1dbaf225d7540b",  // optional: pin to specific version
});
Note: You can omit theversion parameter to always load the latest version tagged with the specified environment.

​
Step 3: Configure environment tags for prompt deployment

Environment tags allow you to promote prompt versions through your deployment pipeline (e.g., development → staging → production). To add an environment tag to a prompt:
  1. Navigate to your prompt in the Braintrust UI
  2. Click the dropdown button in the top right of the prompt view
  3. Select or create an environment tag (production, staging, development, etc.)
  4. The tag is now associated with the current prompt version
This ensures the correct version is used in your application code through either the SDK or API calls to the /v1/prompt endpoint with the environment filter.

​
Step 4: Set up environment update alerts for webhook notifications

While Braintrust doesn’t currently provide a webhook that fires on every prompt change, you can set up environment update alerts to receive notifications when prompts are promoted to specific environments. This provides a controlled, user-initiated workflow for syncing prompt updates. To configure an environment update alert:
  1. Click Settings on the left-hand navigation bar of your project
  2. Click Alerts on the left-hand side of the Settings page
  3. Click the + Alert button in the top right
  4. Enter an Alert name (e.g., “Production Prompt Update”)
  5. Select “Environment update” as the Event Type
  6. Select either “All environments” or specify the specific environment tag (e.g., “production”)
  7. Select “Webhook URL” as the Action type
  8. Enter your webhook endpoint URL
  9. Click Create alert

​
Step 5: Handle webhook payloads and sync prompts

When your webhook endpoint receives an environment update notification, call the /v1/prompt API endpoint to fetch the latest prompt version and update your external system. 
// Example webhook handler
app.post('/braintrust-webhook', async (req, res) => {
  const { project_id, slug, environment } = req.body;

  // Fetch the latest prompt with the environment tag
  const response = await fetch(
    `https://api.braintrustdata.com/v1/prompt?project_id=${project_id}&slug=${slug}&environment=${environment}`,
    {
      headers: {
        'Authorization': `Bearer ${YOUR_API_KEY}`
      }
    }
  );

  const prompts = await response.json();

  // Update your system with the latest prompt
  await updatePromptInYourSystem(prompts[0]);

  res.status(200).send('OK');
});
Complete

​
Summary

This configuration enables Braintrust to serve as a centralized prompt registry with controlled deployment workflows. Developers can save prompts in Braintrust, promote them through environments using tags, and external systems receive webhook notifications to sync updates. While there’s no real-time webhook for all prompt changes, the environment tag alert system provides a production-ready workflow with explicit promotion gates.