@arizeai/phoenix-client 7.14.0 → 7.16.0

package/docs/projects.mdx

@@ -1,16 +1,21 @@
 ---
 title: "Projects"
-description: "List projects and manage project retention-policy assignments"
+description: "List projects and manage project retention-policy and annotation-config assignments"
 ---
 
-The projects module lists Phoenix projects and assigns existing trace retention policies to them.
+The projects module lists Phoenix projects, assigns existing trace retention policies to them, and manages which annotation configs they use.
 
 <section className="hidden" data-agent-context="relevant-source-files" aria-label="Relevant source files">
   <h2>Relevant Source Files</h2>
   <ul>
     <li><code>src/projects/getProjects.ts</code></li>
     <li><code>src/projects/setProjectRetentionPolicy.ts</code></li>
+    <li><code>src/projects/listProjectAnnotationConfigs.ts</code></li>
+    <li><code>src/projects/assignProjectAnnotationConfig.ts</code></li>
+    <li><code>src/projects/unassignProjectAnnotationConfig.ts</code></li>
+    <li><code>src/projects/setProjectAnnotationConfigs.ts</code></li>
     <li><code>src/types/projects.ts</code></li>
+    <li><code>src/types/annotationConfigs.ts</code></li>
   </ul>
 </section>
 
@@ -60,12 +65,60 @@ await setProjectRetentionPolicy({
 
 Assigning or resetting a retention policy requires an admin when authentication is enabled. Invalid policy GlobalIDs produce a `422` response, while callers without permission receive `403`; both are surfaced as `HttpError` instances by the client.
 
+## Assign Annotation Configs
+
+Annotation configs define the annotations that can be recorded on a project's traces, spans, and sessions. These helpers change which existing configs a project uses. They don't create, update, or delete the configs themselves. All four require Phoenix server 17.16.0 or later.
+
+```ts
+import {
+  assignProjectAnnotationConfig,
+  listProjectAnnotationConfigs,
+  setProjectAnnotationConfigs,
+  unassignProjectAnnotationConfig,
+} from "@arizeai/phoenix-client/projects";
+
+// Assign a config by name or GlobalID. Assigning an already-assigned config is a no-op.
+const correctness = await assignProjectAnnotationConfig({
+  projectName: "support-bot",
+  configName: "correctness",
+});
+
+// Unassign a config. Unassigning a config that isn't assigned is a no-op.
+await unassignProjectAnnotationConfig({
+  projectName: "support-bot",
+  configId: correctness.id,
+});
+
+// List every assigned config (pagination is handled automatically)
+const configs = await listProjectAnnotationConfigs({ projectName: "support-bot" });
+
+// Replace the whole set, keeping only categorical configs; configs not listed are unassigned
+await setProjectAnnotationConfigs({
+  projectName: "support-bot",
+  configIds: configs
+    .filter((config) => config.type === "CATEGORICAL")
+    .map((config) => config.id),
+});
+
+// Clear every assignment
+await setProjectAnnotationConfigs({ projectName: "support-bot", configIds: [] });
+```
+
+Select the config with exactly one of `configName`, `configId`, or the shorthand `config`, which accepts either. Use `configId` if a config name contains `/`, because the server can't route it in the URL path.
+
+`setProjectAnnotationConfigs` takes config GlobalIDs only, because the server doesn't accept names for this operation. Unknown or invalid config IDs produce a `422` response, and a missing project produces a `404`. The single-config helpers return a `404` when the project or the config is missing. The client surfaces all of these as `HttpError` instances.
+
 <section className="hidden" data-agent-context="source-map" aria-label="Source map">
   <h2>Source Map</h2>
   <ul>
     <li><code>src/projects/getProjects.ts</code></li>
     <li><code>src/projects/setProjectRetentionPolicy.ts</code></li>
+    <li><code>src/projects/listProjectAnnotationConfigs.ts</code></li>
+    <li><code>src/projects/assignProjectAnnotationConfig.ts</code></li>
+    <li><code>src/projects/unassignProjectAnnotationConfig.ts</code></li>
+    <li><code>src/projects/setProjectAnnotationConfigs.ts</code></li>
     <li><code>src/projects/index.ts</code></li>
     <li><code>src/types/projects.ts</code></li>
+    <li><code>src/types/annotationConfigs.ts</code></li>
   </ul>
 </section>

package/docs/prompts.mdx

@@ -3,7 +3,7 @@ title: "Prompts"
 description: "Manage prompts with @arizeai/phoenix-client"
 ---
 
-The prompts module lets you create prompt versions in Phoenix, fetch them back by selector, list prompts, update a prompt's description and metadata, delete a prompt, and adapt prompt versions to supported provider SDKs.
+The prompts module lets you create prompt versions in Phoenix, fetch them back by selector, manage prompt version tags, list prompts, update a prompt's description and metadata, delete a prompt, and adapt prompt versions to supported provider SDKs.
 
 <section className="hidden" data-agent-context="relevant-source-files" aria-label="Relevant source files">
   <h2>Relevant Source Files</h2>
@@ -43,6 +43,32 @@ const prompt = await getPrompt({
 
 `prompt` can be selected by `{ name }`, `{ name, tag }`, or `{ versionId }`.
 
+## Manage Version Tags
+
+```ts
+import {
+  deletePromptVersionTag,
+  upsertPromptVersionTag,
+} from "@arizeai/phoenix-client/prompts";
+
+await upsertPromptVersionTag({
+  prompt: { versionId: "UHJvbXB0VmVyc2lvbjox" },
+  name: "production",
+  description: "Currently deployed version",
+});
+
+await deletePromptVersionTag({
+  prompt: { versionId: "UHJvbXB0VmVyc2lvbjox" },
+  name: "staging",
+});
+```
+
+Tag names are unique within a prompt, not within an individual version. Upserting a new name creates the tag on the target version. Upserting a name that already exists on another version of the same prompt moves that tag to the target version and updates its description. The same name can still be used independently by unrelated prompts.
+
+Deletion also resolves the name within the prompt identified by `prompt.versionId`; the tag can be attached to any version of that prompt.
+
+Tag upserts require Phoenix 8.22.0 or later. Tag deletion requires Phoenix 13.20.0 or later.
+
 ## Update Description And Metadata
 
 ```ts
@@ -99,9 +125,12 @@ Supported `sdk` targets:
   <ul>
     <li><code>src/prompts/createPrompt.ts</code></li>
     <li><code>src/prompts/deletePrompt.ts</code></li>
+    <li><code>src/prompts/deletePromptVersionTag.ts</code></li>
     <li><code>src/prompts/getPrompt.ts</code></li>
     <li><code>src/prompts/listPrompts.ts</code></li>
     <li><code>src/prompts/updatePrompt.ts</code></li>
+    <li><code>src/prompts/upsertPromptVersionTag.ts</code></li>
+    <li><code>src/utils/resolvePromptVersionId.ts</code></li>
     <li><code>src/prompts/sdks/toSDK.ts</code></li>
     <li><code>src/types/prompts.ts</code></li>
   </ul>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arizeai/phoenix-client",
-  "version": "7.14.0",
+  "version": "7.16.0",
   "description": "A client for the Phoenix API",
   "keywords": [
     "arize",
@@ -116,22 +116,22 @@
     "zod": "^4.6.5"
   },
   "devDependencies": {
-    "@ai-sdk/openai": "^4.0.71",
-    "@ai-sdk/otel": "^1.0.107",
+    "@ai-sdk/openai": "^4.0.78",
+    "@ai-sdk/otel": "^1.0.116",
     "@anthropic-ai/sdk": "^0.111.0",
     "@arizeai/phoenix-evals": "2.6.0",
     "@arizeai/phoenix-testing": "0.0.0",
     "@opentelemetry/api": "^1.9.1",
     "@opentelemetry/sdk-trace-node": "^2.11.0",
     "@types/async": "^3.2.26",
-    "@types/node": "^26.6.2",
-    "ai": "^7.0.107",
+    "@types/node": "^26.6.3",
+    "ai": "^7.0.116",
     "dotenv": "^17.4.2",
     "jest": "^30.5.2",
     "openai": "^6.49.0",
     "openapi-typescript": "^7.13.0",
-    "tsx": "^4.23.13",
-    "vitest": "^5.0.1"
+    "tsx": "^4.23.15",
+    "vitest": "^5.0.2"
   },
   "peerDependencies": {
     "@anthropic-ai/sdk": "^0.35.0",

package/src/__generated__/api/v1.ts

@@ -10580,10 +10580,14 @@ export interface operations {
     getSpans: {
         parameters: {
             query?: {
-                /** @description Pagination cursor (Span Global ID) */
+                /** @description Pagination cursor: the next_cursor of a previous response with the same sort */
                 cursor?: string | null;
                 /** @description Maximum number of spans to return */
                 limit?: number;
+                /** @description Sort field. 'id' orders by insertion; 'start_time' orders by when the span started, breaking ties by id. */
+                sort?: "id" | "start_time";
+                /** @description Sort direction */
+                order?: "asc" | "desc";
                 /** @description Inclusive lower bound time */
                 start_time?: string | null;
                 /** @description Exclusive upper bound time */

package/src/constants/serverRequirements.ts

@@ -199,6 +199,20 @@ export const DELETE_PROMPT: RouteRequirement = {
   minServerVersion: [13, 20, 0],
 };
 
+export const UPSERT_PROMPT_VERSION_TAG: RouteRequirement = {
+  kind: "route",
+  method: "POST",
+  path: "/v1/prompt_versions/{prompt_version_id}/tags",
+  minServerVersion: [8, 22, 0],
+};
+
+export const DELETE_PROMPT_VERSION_TAG: RouteRequirement = {
+  kind: "route",
+  method: "DELETE",
+  path: "/v1/prompt_versions/{prompt_version_id}/tags/{tag_name}",
+  minServerVersion: [13, 20, 0],
+};
+
 export const PATCH_PROMPT: RouteRequirement = {
   kind: "route",
   method: "PATCH",
@@ -206,6 +220,34 @@ export const PATCH_PROMPT: RouteRequirement = {
   minServerVersion: [19, 18, 0],
 };
 
+export const LIST_PROJECT_ANNOTATION_CONFIGS: RouteRequirement = {
+  kind: "route",
+  method: "GET",
+  path: "/v1/projects/{project_identifier}/annotation_configs",
+  minServerVersion: [17, 16, 0],
+};
+
+export const SET_PROJECT_ANNOTATION_CONFIGS: RouteRequirement = {
+  kind: "route",
+  method: "PUT",
+  path: "/v1/projects/{project_identifier}/annotation_configs",
+  minServerVersion: [17, 16, 0],
+};
+
+export const ASSIGN_PROJECT_ANNOTATION_CONFIG: RouteRequirement = {
+  kind: "route",
+  method: "PUT",
+  path: "/v1/projects/{project_identifier}/annotation_configs/{config_identifier}",
+  minServerVersion: [17, 16, 0],
+};
+
+export const UNASSIGN_PROJECT_ANNOTATION_CONFIG: RouteRequirement = {
+  kind: "route",
+  method: "DELETE",
+  path: "/v1/projects/{project_identifier}/annotation_configs/{config_identifier}",
+  minServerVersion: [17, 16, 0],
+};
+
 export const AGENT_SESSION_CREATE: RouteRequirement = {
   kind: "route",
   method: "POST",
@@ -293,7 +335,13 @@ export const ALL_REQUIREMENTS: readonly CapabilityRequirement[] = [
   ADD_SPAN_NOTE_IDENTIFIER,
   ADD_SESSION_NOTE_IDENTIFIER,
   DELETE_PROMPT,
+  UPSERT_PROMPT_VERSION_TAG,
+  DELETE_PROMPT_VERSION_TAG,
   PATCH_PROMPT,
+  LIST_PROJECT_ANNOTATION_CONFIGS,
+  SET_PROJECT_ANNOTATION_CONFIGS,
+  ASSIGN_PROJECT_ANNOTATION_CONFIG,
+  UNASSIGN_PROJECT_ANNOTATION_CONFIG,
   AGENT_SESSION_CREATE,
   AGENT_SESSION_LIST,
   AGENT_SESSION_GET,

package/src/projects/assignProjectAnnotationConfig.ts

@@ -0,0 +1,78 @@
+import invariant from "tiny-invariant";
+
+import { createClient } from "../client";
+import { ASSIGN_PROJECT_ANNOTATION_CONFIG } from "../constants/serverRequirements";
+import type {
+  AnnotationConfig,
+  AnnotationConfigIdentifier,
+} from "../types/annotationConfigs";
+import { resolveAnnotationConfigIdentifier } from "../types/annotationConfigs";
+import type { ClientFn } from "../types/core";
+import type { ProjectIdentifier } from "../types/projects";
+import { resolveProjectIdentifier } from "../types/projects";
+import { ensureServerCapability } from "../utils/serverVersionUtils";
+
+/**
+ * Parameters for assigning an annotation config to a project.
+ */
+export type AssignProjectAnnotationConfigParams = ClientFn &
+  ProjectIdentifier &
+  AnnotationConfigIdentifier;
+
+/**
+ * Assign an existing annotation config to a project.
+ *
+ * Assignment is idempotent: assigning a config that is already assigned to
+ * the project succeeds and returns the config.
+ *
+ * @param params - The project and annotation config to assign.
+ * @param params.project - A project name or GlobalID.
+ * @param params.projectId - A project GlobalID.
+ * @param params.projectName - A project name.
+ * @param params.config - An annotation config name or GlobalID.
+ * @param params.configId - An annotation config GlobalID.
+ * @param params.configName - An annotation config name.
+ * Use `configId` instead if the name may contain `/`, which the server
+ * cannot route.
+ * @param params.client - An optional Phoenix client instance.
+ * @returns The assigned annotation config.
+ * @throws {@link HttpError} when Phoenix rejects the request, e.g. with a 404
+ * if the project or annotation config does not exist.
+ *
+ * @requires Phoenix server >= 17.16.0
+ *
+ * @example
+ * ```ts
+ * import { assignProjectAnnotationConfig } from "@arizeai/phoenix-client/projects";
+ *
+ * const config = await assignProjectAnnotationConfig({
+ *   projectName: "support-bot",
+ *   configName: "correctness",
+ * });
+ * ```
+ */
+export async function assignProjectAnnotationConfig(
+  params: AssignProjectAnnotationConfigParams
+): Promise<AnnotationConfig> {
+  const client = params.client ?? createClient();
+  await ensureServerCapability({
+    client,
+    requirement: ASSIGN_PROJECT_ANNOTATION_CONFIG,
+  });
+
+  const { data, error } = await client.PUT(
+    "/v1/projects/{project_identifier}/annotation_configs/{config_identifier}",
+    {
+      params: {
+        path: {
+          project_identifier: resolveProjectIdentifier(params),
+          config_identifier: resolveAnnotationConfigIdentifier(params),
+        },
+      },
+    }
+  );
+
+  if (error) throw error;
+  invariant(data?.data, "Failed to assign annotation config to project");
+  return data.data;
+}

package/src/projects/index.ts

@@ -1,2 +1,10 @@
+export * from "./assignProjectAnnotationConfig";
 export * from "./getProjects";
+export * from "./listProjectAnnotationConfigs";
+export * from "./setProjectAnnotationConfigs";
 export * from "./setProjectRetentionPolicy";
+export * from "./unassignProjectAnnotationConfig";
+export type {
+  AnnotationConfig,
+  AnnotationConfigIdentifier,
+} from "../types/annotationConfigs";

package/src/projects/listProjectAnnotationConfigs.ts

@@ -0,0 +1,85 @@
+import invariant from "tiny-invariant";
+
+import type { components } from "../__generated__/api/v1";
+import { createClient } from "../client";
+import { LIST_PROJECT_ANNOTATION_CONFIGS } from "../constants/serverRequirements";
+import type { AnnotationConfig } from "../types/annotationConfigs";
+import type { ClientFn } from "../types/core";
+import type { ProjectIdentifier } from "../types/projects";
+import { resolveProjectIdentifier } from "../types/projects";
+import { ensureServerCapability } from "../utils/serverVersionUtils";
+
+/**
+ * Parameters for listing the annotation configs assigned to a project.
+ */
+export type ListProjectAnnotationConfigsParams = ClientFn & ProjectIdentifier;
+
+type ProjectAnnotationConfigsResponse =
+  components["schemas"]["GetProjectAnnotationConfigsResponseBody"];
+
+const DEFAULT_PAGE_SIZE = 100;
+
+/**
+ * List every annotation config assigned to a project, with automatic
+ * pagination handling.
+ *
+ * @param params - The project whose assigned configs should be listed.
+ * @param params.project - A project name or GlobalID.
+ * @param params.projectId - A project GlobalID.
+ * @param params.projectName - A project name.
+ * @param params.client - An optional Phoenix client instance.
+ * @returns The annotation configs assigned to the project.
+ * @throws {@link HttpError} when Phoenix rejects the request, e.g. with a 404
+ * if the project does not exist.
+ *
+ * @requires Phoenix server >= 17.16.0
+ *
+ * @example
+ * ```ts
+ * import { listProjectAnnotationConfigs } from "@arizeai/phoenix-client/projects";
+ *
+ * const configs = await listProjectAnnotationConfigs({
+ *   projectName: "support-bot",
+ * });
+ *
+ * for (const config of configs) {
+ *   console.log(`${config.name} (${config.type})`);
+ * }
+ * ```
+ */
+export async function listProjectAnnotationConfigs(
+  params: ListProjectAnnotationConfigsParams
+): Promise<AnnotationConfig[]> {
+  const client = params.client ?? createClient();
+  await ensureServerCapability({
+    client,
+    requirement: LIST_PROJECT_ANNOTATION_CONFIGS,
+  });
+  const projectIdentifier = resolveProjectIdentifier(params);
+
+  const configs: AnnotationConfig[] = [];
+  let cursor: string | null = null;
+
+  do {
+    const response: {
+      data?: ProjectAnnotationConfigsResponse;
+      error?: unknown;
+    } = await client.GET(
+      "/v1/projects/{project_identifier}/annotation_configs",
+      {
+        params: {
+          path: { project_identifier: projectIdentifier },
+          query: { cursor, limit: DEFAULT_PAGE_SIZE },
+        },
+      }
+    );
+
+    if (response.error) throw response.error;
+    invariant(response.data?.data, "Failed to list project annotation configs");
+
+    cursor = response.data.next_cursor ?? null;
+    configs.push(...response.data.data);
+  } while (cursor != null);
+
+  return configs;
+}

package/src/projects/setProjectAnnotationConfigs.ts

@@ -0,0 +1,86 @@
+import invariant from "tiny-invariant";
+
+import { createClient } from "../client";
+import { SET_PROJECT_ANNOTATION_CONFIGS } from "../constants/serverRequirements";
+import type { AnnotationConfig } from "../types/annotationConfigs";
+import type { ClientFn } from "../types/core";
+import type { ProjectIdentifier } from "../types/projects";
+import { resolveProjectIdentifier } from "../types/projects";
+import { ensureServerCapability } from "../utils/serverVersionUtils";
+
+/**
+ * Parameters for replacing the annotation configs assigned to a project.
+ */
+export type SetProjectAnnotationConfigsParams = ClientFn &
+  ProjectIdentifier & {
+    /**
+     * The GlobalIDs of every annotation config that should be assigned to the
+     * project. Configs not in this list are unassigned; an empty list clears
+     * all assignments.
+     */
+    configIds: string[];
+  };
+
+/**
+ * Replace the full set of annotation configs assigned to a project.
+ *
+ * Configs in `configIds` that are not yet assigned are added, and assigned
+ * configs missing from `configIds` are removed. The annotation configs
+ * themselves are never deleted.
+ *
+ * @param params - The project and its desired annotation configs.
+ * @param params.project - A project name or GlobalID.
+ * @param params.projectId - A project GlobalID.
+ * @param params.projectName - A project name.
+ * @param params.configIds - The annotation config GlobalIDs to assign.
+ * @param params.client - An optional Phoenix client instance.
+ * @returns The annotation configs assigned to the project after the update.
+ * @throws {@link HttpError} when Phoenix rejects the request, e.g. with a 404
+ * if the project does not exist or a 422 if any config ID is invalid or
+ * missing.
+ *
+ * @requires Phoenix server >= 17.16.0
+ *
+ * @example
+ * ```ts
+ * import { setProjectAnnotationConfigs } from "@arizeai/phoenix-client/projects";
+ *
+ * await setProjectAnnotationConfigs({
+ *   projectName: "support-bot",
+ *   configIds: ["Q2F0ZWdvcmljYWxBbm5vdGF0aW9uQ29uZmlnOjE="],
+ * });
+ *
+ * // Clear every assignment
+ * await setProjectAnnotationConfigs({
+ *   projectName: "support-bot",
+ *   configIds: [],
+ * });
+ * ```
+ */
+export async function setProjectAnnotationConfigs(
+  params: SetProjectAnnotationConfigsParams
+): Promise<AnnotationConfig[]> {
+  const client = params.client ?? createClient();
+  await ensureServerCapability({
+    client,
+    requirement: SET_PROJECT_ANNOTATION_CONFIGS,
+  });
+
+  const { data, error } = await client.PUT(
+    "/v1/projects/{project_identifier}/annotation_configs",
+    {
+      params: {
+        path: {
+          project_identifier: resolveProjectIdentifier(params),
+        },
+      },
+      body: {
+        annotation_config_ids: params.configIds,
+      },
+    }
+  );
+
+  if (error) throw error;
+  invariant(data?.data, "Failed to set project annotation configs");
+  return data.data;
+}

package/src/projects/unassignProjectAnnotationConfig.ts

@@ -0,0 +1,71 @@
+import { createClient } from "../client";
+import { UNASSIGN_PROJECT_ANNOTATION_CONFIG } from "../constants/serverRequirements";
+import type { AnnotationConfigIdentifier } from "../types/annotationConfigs";
+import { resolveAnnotationConfigIdentifier } from "../types/annotationConfigs";
+import type { ClientFn } from "../types/core";
+import type { ProjectIdentifier } from "../types/projects";
+import { resolveProjectIdentifier } from "../types/projects";
+import { ensureServerCapability } from "../utils/serverVersionUtils";
+
+/**
+ * Parameters for unassigning an annotation config from a project.
+ */
+export type UnassignProjectAnnotationConfigParams = ClientFn &
+  ProjectIdentifier &
+  AnnotationConfigIdentifier;
+
+/**
+ * Unassign an annotation config from a project.
+ *
+ * Unassignment is idempotent: unassigning a config that is not assigned to
+ * the project succeeds. The annotation config itself is not deleted.
+ *
+ * @param params - The project and annotation config to unassign.
+ * @param params.project - A project name or GlobalID.
+ * @param params.projectId - A project GlobalID.
+ * @param params.projectName - A project name.
+ * @param params.config - An annotation config name or GlobalID.
+ * @param params.configId - An annotation config GlobalID.
+ * @param params.configName - An annotation config name.
+ * Use `configId` instead if the name may contain `/`, which the server
+ * cannot route.
+ * @param params.client - An optional Phoenix client instance.
+ * @returns A promise that resolves once the config is unassigned.
+ * @throws {@link HttpError} when Phoenix rejects the request, e.g. with a 404
+ * if the project or annotation config does not exist.
+ *
+ * @requires Phoenix server >= 17.16.0
+ *
+ * @example
+ * ```ts
+ * import { unassignProjectAnnotationConfig } from "@arizeai/phoenix-client/projects";
+ *
+ * await unassignProjectAnnotationConfig({
+ *   projectName: "support-bot",
+ *   configName: "correctness",
+ * });
+ * ```
+ */
+export async function unassignProjectAnnotationConfig(
+  params: UnassignProjectAnnotationConfigParams
+): Promise<void> {
+  const client = params.client ?? createClient();
+  await ensureServerCapability({
+    client,
+    requirement: UNASSIGN_PROJECT_ANNOTATION_CONFIG,
+  });
+
+  const { error } = await client.DELETE(
+    "/v1/projects/{project_identifier}/annotation_configs/{config_identifier}",
+    {
+      params: {
+        path: {
+          project_identifier: resolveProjectIdentifier(params),
+          config_identifier: resolveAnnotationConfigIdentifier(params),
+        },
+      },
+    }
+  );
+
+  if (error) throw error;
+}

package/src/prompts/deletePromptVersionTag.ts

@@ -0,0 +1,64 @@
+import { createClient } from "../client";
+import { DELETE_PROMPT_VERSION_TAG } from "../constants/serverRequirements";
+import type { ClientFn } from "../types/core";
+import type { GetPromptByVersionSelector } from "../types/prompts";
+import { resolvePromptVersionId } from "../utils/resolvePromptVersionId";
+import { ensureServerCapability } from "../utils/serverVersionUtils";
+
+/**
+ * Parameters for deleting a prompt version tag.
+ */
+export interface DeletePromptVersionTagParams extends ClientFn {
+  /** A version belonging to the prompt that owns the tag. */
+  prompt: GetPromptByVersionSelector;
+  /** The prompt-scoped tag name to delete. */
+  name: string;
+}
+
+/**
+ * Delete a tag from the prompt that owns the given prompt version.
+ *
+ * Tag names are unique within a prompt, so `name` identifies the tag across
+ * all versions of that prompt. The tag does not need to be attached to the
+ * selected version.
+ *
+ * @param params - The prompt version tag to delete.
+ * @param params.prompt - A version selector used to identify the prompt.
+ * @param params.name - The prompt-scoped tag name to delete.
+ * @returns A promise that resolves once the tag has been deleted.
+ * @throws {@link HttpError} when Phoenix rejects the request.
+ *
+ * @example
+ * ```ts
+ * import { deletePromptVersionTag } from "@arizeai/phoenix-client/prompts";
+ *
+ * await deletePromptVersionTag({
+ *   prompt: { versionId: "UHJvbXB0VmVyc2lvbjox" },
+ *   name: "production",
+ * });
+ * ```
+ */
+export async function deletePromptVersionTag({
+  client: _client,
+  prompt,
+  name,
+}: DeletePromptVersionTagParams): Promise<void> {
+  const promptVersionId = resolvePromptVersionId(prompt);
+  const client = _client ?? createClient();
+  await ensureServerCapability({
+    client,
+    requirement: DELETE_PROMPT_VERSION_TAG,
+  });
+
+  await client.DELETE(
+    "/v1/prompt_versions/{prompt_version_id}/tags/{tag_name}",
+    {
+      params: {
+        path: {
+          prompt_version_id: promptVersionId,
+          tag_name: name,
+        },
+      },
+    }
+  );
+}

package/src/prompts/index.ts

@@ -1,6 +1,8 @@
 export * from "./getPrompt";
 export * from "./createPrompt";
 export * from "./deletePrompt";
+export * from "./deletePromptVersionTag";
 export * from "./listPrompts";
+export * from "./upsertPromptVersionTag";
 export * from "./updatePrompt";
 export * from "./sdks";