Fix “slug already exists” errors for prompts that are not visible

Applies to:

Plan -
Deployment -

Summary

Issue: A prompt slug update fails with a Failed to save prompt. Error: Slug '<your-slug>' already exists error, but GET /v1/prompt?slug=<your-slug> returns {"objects": []} and no prompt appears in the UI. Cause: A slug is reserved by a prompt record that is not currently visible through standard API queries or in the Braintrust UI. Resolution: Use PUT /v1/prompt to upsert the prompt with the desired slug and make it visible again.

Resolution steps

Confirm the issue

Step 1: Search for the slug in the target project

Run the following request, replacing <your-project-id> and <your-slug> with your values:

GET /v1/prompt?project_id=<your-project-id>&slug=<your-slug>

If the response is empty, but saving a prompt with that slug still fails, continue to the next step.

Step 2: Try updating the prompt slug

Attempt to update the prompt with the desired slug:

PATCH /v1/prompt/<prompt_id>
{ "slug": "your-slug" }

If this returns a 400 error for a unique key violation, the slug conflict is confirmed.

Resolve the conflict using PUT

Step 1: Upsert the prompt

Send a PUT /v1/prompt request with the full prompt payload, including the target project_id and slug:

PUT /v1/prompt
{
  "name": "Your Prompt Name",
  "slug": "your-slug",
  "project_id": "<your-project-id>",
  "prompt_data": { ... }
}

The PUT /v1/prompt endpoint performs an upsert that can restore the prompt associated with the slug and make it visible again.

Step 2: Verify the prompt is visible

After the PUT request succeeds, query the slug again in the same project:

GET /v1/prompt?project_id=<your-project-id>&slug=<your-slug>

The prompt should now appear in the response and be visible in the Braintrust UI.

​Summary

​Resolution steps

​Confirm the issue

​Step 1: Search for the slug in the target project

​Step 2: Try updating the prompt slug

​Resolve the conflict using PUT

​Step 1: Upsert the prompt

​Step 2: Verify the prompt is visible

Summary

Resolution steps

Confirm the issue

Step 1: Search for the slug in the target project

Step 2: Try updating the prompt slug

Resolve the conflict using PUT

Step 1: Upsert the prompt

Step 2: Verify the prompt is visible