> ## 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.

# Promoting prompts across environments via API

export const plans_0 = "Any"

export const deployments_0 = "Any"

export const data_plane_version_0 = undefined

export const use_case_0 = undefined

<Note>
  **Applies to:**

  * Plan - {plans_0}
  * Deployment - {deployments_0}
  * {data_plane_version_0}
  * {use_case_0}
</Note>

## 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`](/api-reference/prompts/create-prompt) or [`PUT /v1/prompt`](/api-reference/prompts/create-or-replace-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.

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
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.

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

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
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.

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
#!/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\"}"
```