Skip to main content

​
Prompt Tags

Tags let you label specific prompt versions for different deployment stages. Instead of fetching by version number, you can fetch by tag — so your application always gets the right version for its environment.

​
Built-in Tags

LangWatch provides three built-in tags:
TagBehavior
latestAutomatically assigned to the newest version on every save. Cannot be removed.
productionAssign this to the version you want your production application to use.
stagingAssign this to the version you want your staging environment to use.

​
Assigning Tags via the Deploy Dialog

In the Prompt Playground, click the Deploy button to open the Deploy dialog. From there you can:
  1. Select a version from the version history
  2. Assign it to production, staging, or any custom tag
  3. See which versions currently have each tag assigned
This is the recommended way to promote a prompt version to production — it provides a clear audit trail and prevents accidental changes.

​
Fetching by Tag in Your Application

​
TypeScript SDK

import { LangWatch } from "langwatch";

const langwatch = new LangWatch();

// Fetch the production version
const prompt = await langwatch.prompts.get("pizza-prompt", { tag: "production" });

// Fetch the staging version
const staging = await langwatch.prompts.get("pizza-prompt", { tag: "staging" });

​
Python SDK

import langwatch

# Fetch the production version
prompt = langwatch.prompts.get("pizza-prompt", tag="production")

# Fetch the staging version
staging = langwatch.prompts.get("pizza-prompt", tag="staging")

​
REST API

# Using the tag query parameter
curl -H "X-Auth-Token: $LANGWATCH_API_KEY" \
  "https://app.langwatch.ai/api/prompts/pizza-prompt?tag=production"

# Using shorthand syntax
curl -H "X-Auth-Token: $LANGWATCH_API_KEY" \
  "https://app.langwatch.ai/api/prompts/pizza-prompt:production"

​
MCP Tools

Use platform_get_prompt with the tag parameter to fetch a specific tagged version: 
platform_get_prompt({ idOrHandle: "pizza-prompt", tag: "production" })

​
Shorthand Syntax

LangWatch supports a shorthand syntax for specifying tags in prompt identifiers:
  • pizza-prompt:production → version pointed to by the production tag
  • pizza-prompt:staging → version pointed to by the staging tag
  • pizza-prompt:2 → version 2 (numeric values are treated as version numbers)
  • pizza-prompt:latest → equivalent to the bare slug pizza-prompt
This works anywhere a prompt identifier is accepted: REST API, SDK, and config files.
You cannot use both shorthand syntax and the ?tag= query parameter at the same time. If both are provided, the API returns a 422 error.

​
Custom Tags

Beyond the built-in tags, you can create custom tags for your own deployment workflows:

​
Creating Custom Tags

Via the API: 
# Create a custom tag
curl -X POST -H "X-Auth-Token: $LANGWATCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "canary"}' \
  "https://app.langwatch.ai/api/prompts/tags"
Via MCP tools: Use platform_create_prompt_tag to create a custom tag, then platform_assign_prompt_tag to assign it to a version.

​
Managing Custom Tags

OperationAPI EndpointMCP Tool
List all tagsGET /api/prompts/tagsplatform_list_prompt_tags
Create tagPOST /api/prompts/tagsplatform_create_prompt_tag
Rename tagPUT /api/prompts/tags/{tag}platform_rename_prompt_tag
Delete tagDELETE /api/prompts/tags/{tag}platform_delete_prompt_tag
Assign tag to versionPUT /api/prompts/{id}/tags/{tag}platform_assign_prompt_tag
Custom tag names must not be purely numeric and cannot be “latest”. The latest tag is protected and cannot be renamed or deleted. production and staging are default seeded tags that can be renamed or deleted like any custom tag.

​
Tag Management via SDKs

Both SDKs provide a .tags namespace for managing tags programmatically.

​
TypeScript SDK

import { LangWatch } from "langwatch";

const langwatch = new LangWatch();

// List all tags
const tags = await langwatch.prompts.tags.list();

// Create a new tag
await langwatch.prompts.tags.create({ name: "canary" });

// Assign a tag to a specific version
await langwatch.prompts.tags.assign("pizza-prompt", {
  tag: "canary",
  versionId: "version-abc123",
});

// Delete a tag
await langwatch.prompts.tags.delete("canary");
The TypeScript SDK does not currently support tags.rename(). Use the REST API or Python SDK for renaming tags.

​
Python SDK

import langwatch

# List all tags
tags = langwatch.prompts.tags.list()

# Create a new tag
langwatch.prompts.tags.create("canary")

# Assign a tag to a specific version
langwatch.prompts.tags.assign("pizza-prompt", tag="canary", version_id="version-abc123")

# Rename a tag
langwatch.prompts.tags.rename("canary", new_name="canary-v2")

# Delete a tag
langwatch.prompts.tags.delete("canary")

​
Assigning Tags at Create and Update Time

You can assign tags when creating or updating prompts, so the version is tagged in a single operation.

​
TypeScript SDK

// Create a prompt with initial tags
await langwatch.prompts.create({
  handle: "my-prompt",
  messages: [{ role: "system", content: "You are a helpful assistant." }],
  model: "gpt-5-mini",
  tags: ["staging"],
});

// Update a prompt and reassign tags
await langwatch.prompts.update("my-prompt", {
  tags: ["production"],
  commitMessage: "promote to production",
});

​
Python SDK

# Create a prompt with initial tags
langwatch.prompts.create(
    handle="my-prompt",
    messages=[{"role": "system", "content": "You are a helpful assistant."}],
    tags=["staging"],
)

# Update a prompt and reassign tags
langwatch.prompts.update(
    "my-prompt",
    scope="PROJECT",
    tags=["production"],
    commit_message="promote to production",
)

​
MCP Tools

Tags can also be assigned during prompt creation and updates via MCP: 
// Create with tags
platform_create_prompt({
  name: "My Prompt",
  handle: "my-prompt",
  messages: [...],
  model: "gpt-5-mini",
  tags: ["staging"]
})

// Update with tags
platform_update_prompt({
  idOrHandle: "my-prompt",
  commitMessage: "promote to production",
  tags: ["production"]
})

​
REST API Tag Endpoints

Tag CRUD endpoints are organization-scoped (use an org-level API key). The assign endpoint is project-scoped.
MethodEndpointDescription
GET/api/prompts/tagsList all tags for the organization
POST/api/prompts/tagsCreate a new tag ({ "name": "canary" })
PUT/api/prompts/tags/:tagRename a tag ({ "name": "new-name" })
DELETE/api/prompts/tags/:tagDelete a tag (cascades removal from all versions)
PUT/api/prompts/:id/tags/:tagAssign a tag to a version ({ "versionId": "..." })

​
CLI

CLI tag management is planned — see issue #3090. Once available, you will be able to list, create, rename, delete, and assign tags from the command line.

​
Common Workflows

​
Blue-Green Deployment

  1. Create two custom tags: blue and green
  2. Point your application at one tag (e.g., blue)
  3. Update the other tag (green) with the new version
  4. Switch your application to read from green
  5. If issues arise, switch back to blue

​
Canary Releases

  1. Create a canary tag
  2. Assign the new version to canary
  3. Route a small percentage of traffic to the canary version
  4. Monitor performance via LangWatch analytics
  5. Promote to production when satisfied