> ## Documentation Index
> Fetch the complete documentation index at: https://langwatch.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```typescript theme={null}
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

```python theme={null}
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

```bash theme={null}
# 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.

<Warning>
  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.
</Warning>

## Custom Tags

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

### Creating Custom Tags

**Via the API:**

```bash theme={null}
# 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` |

<Note>
  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.
</Note>

## Tag Management via SDKs

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

### TypeScript SDK

```typescript theme={null}
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");
```

<Warning>
  The TypeScript SDK does not currently support `tags.rename()`. Use the REST API or Python SDK for renaming tags.
</Warning>

### Python SDK

```python theme={null}
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

```typescript theme={null}
// 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

```python theme={null}
# 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](https://github.com/langwatch/langwatch/issues/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