Tags

Use tags to manage prompt deployment stages like production, staging, and custom environments in LangWatch.

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:

Tag	Behavior
latest	Automatically assigned to the newest version on every save. Cannot be removed.
production	Assign this to the version you want your production application to use.
staging	Assign 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

Operation	API Endpoint	MCP Tool
List all tags	GET /api/prompts/tags	platform_list_prompt_tags
Create tag	POST /api/prompts/tags	platform_create_prompt_tag
Rename tag	PUT /api/prompts/tags/{tag}	platform_rename_prompt_tag
Delete tag	DELETE /api/prompts/tags/{tag}	platform_delete_prompt_tag
Assign tag to version	PUT /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.

Method	Endpoint	Description
GET	/api/prompts/tags	List all tags for the organization
POST	/api/prompts/tags	Create a new tag ({ "name": "canary" })
PUT	/api/prompts/tags/:tag	Rename a tag ({ "name": "new-name" })
DELETE	/api/prompts/tags/:tag	Delete a tag (cascades removal from all versions)
PUT	/api/prompts/:id/tags/:tag	Assign 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