Versions and aliases

Prompts and skills change over time: a domain expert rewrites instructions, a skill gets a new template. Versions keep every change, and aliases let your code follow the version you choose, so you can test a change in staging and promote it to production without a code release.

Every change to the content of a prompt or a skill creates a new, numbered version: version 1 at creation, then 2, 3, and so on. The content of a version doesn't change after it's created. Each version can carry notes that explain what changed, and you can edit them later.

• In Studio, saving a change to the content creates a version. For the steps, see Create a prompt in Studio and Create a skill in Studio.
• Through the API, create_version creates one. If the content is identical to the latest version and you pass no notes or aliases, no new version is created: the response returns the latest version number and sets deduplicated to true.

Changing the sharing settings, or the title or description of a prompt, doesn't create a version. The description of a skill is part of its content, so changing it creates a version.

version = client.beta.prompts.create_version(
    prompt_id=prompt_id,
    definition={"content": "Summarize in three bullet points: {{text}}"},
    notes="Bullet points instead of a paragraph",
)
print(version.version)

for v in client.beta.prompts.list_versions(prompt_id=prompt_id).data:
    print(v.version, v.notes, v.aliases)

version = client.beta.prompts.create_version(
    prompt_id=prompt_id,
    definition={"content": "Summarize in three bullet points: {{text}}"},
    notes="Bullet points instead of a paragraph",
)
print(version.version)

for v in client.beta.prompts.list_versions(prompt_id=prompt_id).data:
    print(v.version, v.notes, v.aliases)

An alias is a name that points to one version, such as staging or production. Your code fetches the alias, not a version number. To change what your application uses, point the alias at another version: the next fetch returns it.

A common pattern:

1. Point staging at a new version and test it.
2. When it passes, point production at the same version.
3. To roll back, point production back at the previous version.

You can assign aliases when you create a prompt or a version, or later on an existing version. An alias is on one version at a time: assigning it to a version moves it from the version it was on. Setting the aliases of a version replaces its list: pass an empty list to remove them all.

client.beta.prompts.update_version_metadata(
    prompt_id=prompt_id,
    version=3,
    aliases={"values": ["staging"]},
)

client.beta.prompts.update_version_metadata(
    prompt_id=prompt_id,
    version=3,
    aliases={"values": ["staging"]},
)

Without a version or an alias, a fetch returns the latest version. In production, fetch an alias, or a fixed version, so that your application's behavior changes only when you decide.

prompt_id takes the prompt ID or the prompt name with the prompt: prefix, such as prompt:support-reply.

latest = client.beta.prompts.get(prompt_id=prompt_id)
pinned = client.beta.prompts.get(prompt_id=prompt_id, version=3)
production = client.beta.prompts.get(prompt_id=prompt_id, alias="production")

latest = client.beta.prompts.get(prompt_id=prompt_id)
pinned = client.beta.prompts.get(prompt_id=prompt_id, version=3)
production = client.beta.prompts.get(prompt_id=prompt_id, alias="production")

Skills work the same way, with client.beta.skills and skill_id. skill_id takes the skill ID or the skill name with the skill: prefix. A skill version holds its description, its instructions, and its files.