Plan Tags

Overview

A Plan Tag is a named reference pointing to a plan, similar to a Docker tag. Tags provide a stable, human-readable way to reference plans that may be recompiled over time. In API responses, the referenced plan is inlined.

Here is an example:

name: smoke-tests-latest
spec:
  planID: pl_abc123
status:
  createdAt: "2025-01-15T10:00:00Z"
  updatedAt: "2025-01-20T14:30:00Z"
history:
- planID: pl_abc123
  taggedAt: "2025-01-20T14:30:00Z"
- planID: pl_xyz789
  taggedAt: "2025-01-15T10:00:00Z"
  untaggedAt: "2025-01-20T14:30:00Z"

name

The tag name, unique within the organization. Used as the identifier for the tag in API operations.

name is required.

plan

The resolved plan this tag points to. This field is populated in API responses and contains the full plan object.

spec

The tag spec contains the user-editable specification.

spec.planID

The ID of the plan this tag points to. Updating this field moves the tag to a different plan.

planID is required.

status

The tag status is server-managed.

status.createdAt

When the tag was created. Serialized as RFC3339.

status.updatedAt

When the tag was last updated. Serialized as RFC3339.

history

The history field is an array of historical tag-to-plan assignments, providing an audit trail of which plans the tag has pointed to over time.

Each entry has the following fields:

Field	Description
planID	The plan this tag pointed to during this period
taggedAt	When the tag was assigned to this plan (RFC3339)
untaggedAt	When the tag was moved or deleted (RFC3339, empty if current)

The most recent entry (with an empty untaggedAt) represents the current assignment.