feat: REST API PUT /prompt_versions/{id}/tags/{tag_name} — upsert tag

[mikeldking]

Summary

Implements PUT /prompt_versions/{prompt_version_id}/tags/{tag_name} — the upsert endpoint for prompt version tags, as specified in #12424.

• Creates the tag if it doesn't exist on any version of the prompt
• Moves the tag to this version if it already exists on another version of the same prompt (upsert semantics via ON CONFLICT DO UPDATE on the unique (name, prompt_id) constraint)
• Returns 204 No Content on success
• Requires MEMBER+ write access (via Depends(is_not_locked))
• Optional JSON body: {"description": "..."} — all fields optional, body may be omitted entirely

What changed

• src/phoenix/server/api/routers/v1/prompts.py: Added UpsertPromptVersionTagRequestBody model and PUT /prompt_versions/{prompt_version_id}/tags/{tag_name} endpoint
• schemas/openapi.json: Added new path and UpsertPromptVersionTagRequestBody schema component
• tests/unit/server/api/routers/v1/test_prompts.py: Six new unit tests covering create, move, no-body, invalid version ID, version not found, and invalid tag name cases
• tests/integration/_helpers.py: Registered the new PUT endpoint in _VIEWER_BLOCKED_WRITE_OPERATIONS to ensure viewer-role access control coverage

How to verify

# Create a prompt version, then tag it:
PUT /v1/prompt_versions/<version_id>/tags/production
Content-Type: application/json

{"description": "Current production version"}
# 204 No Content

# Move the same tag to a different version:
PUT /v1/prompt_versions/<other_version_id>/tags/production
# 204 No Content (tag moved from first version to this one)

Checklist

• Implementation follows existing codebase patterns (mirrors createPromptVersionTag POST endpoint)
• except ValidationError used (consistent with other Identifier validation in file)
• Depends(is_not_locked) applied
• 6 unit tests covering happy path, upsert/move, no-body, 404, and 422 cases
• Viewer-blocked write operations list updated in integration test helpers
• OpenAPI schema updated
• No JS/TS packages modified — no changeset needed

🤖 Generated with Claude Code

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
arize-phoenix	🟢 Ready	View Preview	Mar 28, 2026, 5:10 AM

[claude]

Code review

No issues found. Checked for bugs and CLAUDE.md compliance.

[anticorrelator]

Looks good — clean implementation that follows existing patterns well. One thing to address:

Upsert silently wipes existing tag description when no body is sent

When request_body is None or {}, description resolves to None. Since insert_on_conflict with DO_UPDATE updates all non-PK columns (via _clean(stmt.excluded.items())), a caller who only wants to move a tag to a different version loses its description as a side effect.

This affects both the no-body and empty-body cases. A few options:

1. Only include description in the conflict update set when it's explicitly provided in the body
2. Use COALESCE(excluded.description, prompt_version_tag.description) to preserve existing values
3. Document the behavior explicitly if it's intentional

Also worth adding test coverage for: (a) upsert that updates description, (b) move that verifies description is preserved/cleared as intended.