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

# Prompts

> Manage prompt templates and versions programmatically. Create, version, label, and retrieve prompts for use with LLM integrations.

<Note>
  The `prompts` client methods are currently in **BETA**. The API may change without notice. A one-time warning is emitted on first use.
</Note>

Manage prompt templates and their versions programmatically. Create versioned prompts, assign labels to specific versions, and retrieve prompts by label for use in production workflows.

## Key Capabilities

* Create and manage prompt templates within spaces
* Version prompts with commit messages
* Assign and resolve labels (e.g. `"production"`, `"staging"`) to specific versions
* List prompts and versions with pagination support
* Retrieve, update, and delete prompts

## List Prompts

List all prompts you have access to, with optional filtering by space.

```python theme={null}
resp = client.prompts.list(
    space="your-space-name-or-id",  # optional
    name="customer-support",        # optional substring filter
    limit=50,
)

for prompt in resp.prompts:
    print(prompt.id, prompt.name)
```

For details on pagination, field introspection, and data conversion (to dict/JSON/DataFrame), see [Response Objects](/api-clients/python/version-8/overview#response-objects).

## Create a Prompt

Create a new prompt with an initial version. Prompt names must be unique within the target space.

```python theme={null}
from arize.prompts.types import InputVariableFormat, LlmProvider, LLMMessage

prompt = client.prompts.create(
    space="your-space-name-or-id",
    name="customer-support-agent",
    description="Handles tier-1 customer support queries",
    commit_message="Initial version",
    input_variable_format=InputVariableFormat.F_STRING,
    provider=LlmProvider.OPENAI,
    model="gpt-4o",
    messages=[
        LLMMessage(role="system", content="You are a helpful customer support agent for {company_name}."),
        LLMMessage(role="user", content="{user_query}"),
    ],
)

print(prompt.id, prompt.name)
```

### With Invocation Parameters

Set default inference parameters alongside the prompt template.

```python theme={null}
from arize.prompts.types import InvocationParams

prompt = client.prompts.create(
    space="your-space-name-or-id",
    name="summarizer",
    commit_message="Initial version",
    input_variable_format=InputVariableFormat.F_STRING,
    provider=LlmProvider.OPENAI,
    model="gpt-4o-mini",
    messages=[
        LLMMessage(role="user", content="Summarize the following text: {text}"),
    ],
    invocation_params=InvocationParams(temperature=0.2, max_tokens=512),
)
```

## Get a Prompt

Retrieve a prompt by name or ID. By default the latest version is returned. When using a name, provide `space` to disambiguate.

```python theme={null}
prompt = client.prompts.get(
    prompt="your-prompt-name-or-id",
    space="your-space-name-or-id",  # required when using a name
)

print(prompt.id, prompt.name)
print(prompt.version)
```

### Get a Specific Version

```python theme={null}
prompt = client.prompts.get(
    prompt="your-prompt-name-or-id",
    space="your-space-name-or-id",  # required when resolving by prompt name
    version_id="specific-version-id",
)
```

### Get by Label

Resolve a named label (e.g. `"production"`) to the version it currently points to.

```python theme={null}
prompt = client.prompts.get(
    prompt="your-prompt-name-or-id",
    space="your-space-name-or-id",  # required when resolving by prompt name
    label="production",
)
```

## Update a Prompt

Update a prompt's metadata. Currently supports updating the description.

```python theme={null}
prompt = client.prompts.update(
    prompt="your-prompt-name-or-id",
    space="your-space-name-or-id",  # required when resolving by prompt name
    description="Updated description for this prompt",
)

print(prompt)
```

## Delete a Prompt

Delete a prompt by name or ID. This operation is irreversible and removes all associated versions. There is no response from this call.

```python theme={null}
client.prompts.delete(
    prompt="your-prompt-name-or-id",
    space="your-space-name-or-id",  # required when resolving by prompt name
)

print("Prompt deleted successfully")
```

## Manage Versions

### List Versions

List all versions for a prompt in reverse-chronological order.

```python theme={null}
resp = client.prompts.list_versions(
    prompt="your-prompt-name-or-id",
    space="your-space-name-or-id",  # required when resolving by prompt name
    limit=50,
)

for version in resp.prompt_versions:
    print(version.id, version.commit_message)
```

### Get a Version

Retrieve a specific prompt version by its ID.

<Note>
  The `get_version` method is currently in **ALPHA**. The API may change without notice.
</Note>

```python theme={null}
version = client.prompts.get_version(version_id="your-version-id")

print(version.id, version.commit_message)
```

### Create a New Version

Add a new version to an existing prompt. Each version is immutable after creation.

```python theme={null}
version = client.prompts.create_version(
    prompt="your-prompt-name-or-id",
    space="your-space-name-or-id",  # required when resolving by prompt name
    commit_message="Improved system prompt for edge cases",
    input_variable_format=InputVariableFormat.F_STRING,
    provider=LlmProvider.OPENAI,
    model="gpt-4o",
    messages=[
        LLMMessage(role="system", content="You are an expert customer support agent for {company_name}. Be concise."),
        LLMMessage(role="user", content="{user_query}"),
    ],
)

print(version.id)
```

## Manage Labels

Labels are mutable pointers to a specific version. Use them to decouple your application code from version IDs — update the label when you want to promote a new version without changing application code.

### Get a Version by Label

Resolve a label name to the version it currently points to.

```python theme={null}
version = client.prompts.get_version_by_label(
    prompt="your-prompt-name-or-id",
    space="your-space-name-or-id",  # required when resolving by prompt name
    label_name="production",
)

print(version.id, version.commit_message)
```

### Set Labels on a Version

Assign one or more labels to a version. This replaces all existing labels on that version.

```python theme={null}
resp = client.prompts.set_labels(
    version_id="your-version-id",
    labels=["production"],
)
```

### Promote a New Version

```python theme={null}
# Create the new version
new_version = client.prompts.create_version(
    prompt="your-prompt-name-or-id",
    commit_message="Tuned temperature and tone",
    input_variable_format=InputVariableFormat.F_STRING,
    provider=LlmProvider.OPENAI,
    model="gpt-4o",
    messages=[...],
)

# Promote it to production
client.prompts.set_labels(
    version_id=new_version.id,
    labels=["production"],
)
```

### Delete a Label

Remove a label from a version. This does not delete the version itself.

```python theme={null}
client.prompts.delete_label(
    version_id="your-version-id",
    label_name="staging",
)
```