Promoting prompts across environments via API

Applies to:

Plan -
Deployment -

Summary

Automate prompt promotion across environments (local → dev → staging → production) using Braintrust API calls in CI/CD pipelines to eliminate manual environment assignments in the UI. The workflow uses prompt versioning via _xact_id transaction IDs and environment-specific assignments through idempotent PUT operations to programmatically manage prompt deployments.

Configuration Steps

Step 1: Configure environments in Braintrust UI

Create your environments (dev, staging, production) in Braintrust UI under Configuration > Environments before using the API.

Step 2: Create or update prompt and assign to environments

Use POST /v1/prompt or PUT /v1/prompt and pass environment_slugs to create the prompt and assign it to one or more environments in a single atomic request. The response includes a _xact_id (transaction ID) identifying the created version.

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",
    "slug": "my-prompt-slug",
    "environment_slugs": ["dev"],
    "prompt_data": {
      "prompt": {
        "type": "chat",
        "messages": [
          {"role": "system", "content": "You are a helpful assistant"}
        ]
      },
      "model": "gpt-5-mini"
    }
  }'

All environments are validated before the prompt is created — if any slug doesn’t exist, the entire request fails with no prompt created.

Step 3: Assign prompt version to additional environments

Use the environment-object API to promote the prompt version (using _xact_id from Step 2) to additional environments.

The environment-object endpoint is not yet documented in the API reference. Contact support if you need details on this endpoint.

curl -X PUT https://api.braintrust.dev/environment-object/prompt/{prompt_id}/{environment_slug} \
  -H "Authorization: Bearer $BRAINTRUST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "object_version": "1234567890123456789"
  }'

Step 4: Automate promotion workflow

Chain API calls to promote prompts through your SDLC pipeline.

#!/bin/bash
# Update prompt and assign to dev in one step
RESPONSE=$(curl -s -X PUT "https://api.braintrust.dev/v1/prompt" \
  -H "Authorization: Bearer $BRAINTRUST_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"id\": \"$PROMPT_ID\",
    \"project_id\": \"$PROJECT_ID\",
    \"slug\": \"$PROMPT_SLUG\",
    \"environment_slugs\": [\"dev\"],
    \"prompt_data\": $(cat prompt-config.json)
  }")

VERSION=$(echo $RESPONSE | jq -r '._xact_id')

# Promote to staging
curl -X PUT "https://api.braintrust.dev/environment-object/prompt/$PROMPT_ID/staging" \
  -H "Authorization: Bearer $BRAINTRUST_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"object_version\": \"$VERSION\"}"

# Promote to production
curl -X PUT "https://api.braintrust.dev/environment-object/prompt/$PROMPT_ID/production" \
  -H "Authorization: Bearer $BRAINTRUST_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"object_version\": \"$VERSION\"}"

​Summary

​Configuration Steps

​Step 1: Configure environments in Braintrust UI

​Step 2: Create or update prompt and assign to environments

​Step 3: Assign prompt version to additional environments

​Step 4: Automate promotion workflow

Summary

Configuration Steps

Step 1: Configure environments in Braintrust UI

Step 2: Create or update prompt and assign to environments

Step 3: Assign prompt version to additional environments

Step 4: Automate promotion workflow