> ## 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 using the Arize TypeScript SDK.

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

## List Prompts

```typescript theme={null}
import { listPrompts } from "@arizeai/ax-client";

const { data: prompts, pagination } = await listPrompts({
  space: "my-space",  // space name or ID (optional)
  name: "customer",   // substring filter on prompt name (optional)
  limit: 10,
});
```

## Create a Prompt

```typescript theme={null}
import { createPrompt } from "@arizeai/ax-client";

const prompt = await createPrompt({
  space: "my-space",  // space name or ID
  name: "customer-support",
  description: "A prompt for customer support interactions",
  version: {
    commitMessage: "Initial version",
    inputVariableFormat: "f_string",
    provider: "open_ai",
    model: "gpt-4o",
    messages: [
      { role: "system", content: "You are a helpful assistant for {company_name}." },
      { role: "user", content: "{user_query}" },
    ],
  },
});
```

### With Invocation Parameters

```typescript theme={null}
import { createPrompt } from "@arizeai/ax-client";

const prompt = await createPrompt({
  space: "my-space",
  name: "summarizer",
  version: {
    commitMessage: "Initial version",
    inputVariableFormat: "f_string",
    provider: "open_ai",
    model: "gpt-4o-mini",
    messages: [
      { role: "user", content: "Summarize the following text: {text}" },
    ],
    invocationParams: { temperature: 0.2, max_tokens: 512 },
  },
});
```

## Get a Prompt

```typescript theme={null}
import { getPrompt } from "@arizeai/ax-client";

// Get the latest version
const prompt = await getPrompt({ prompt: "your_prompt_id" });

// Get a specific version by ID
const byVersion = await getPrompt({
  prompt: "your_prompt_id",
  versionId: "your_version_id",
});

// Get the version pointed to by a label
const production = await getPrompt({
  prompt: "your_prompt_id",
  label: "production",
});
```

## Update a Prompt

```typescript theme={null}
import { updatePrompt } from "@arizeai/ax-client";

const updated = await updatePrompt({
  prompt: "your_prompt_id",
  description: "Updated description for this prompt",
});
```

## Delete a Prompt

```typescript theme={null}
import { deletePrompt } from "@arizeai/ax-client";

await deletePrompt({ prompt: "your_prompt_id" });
```

## Manage Versions

### List Versions

```typescript theme={null}
import { listPromptVersions } from "@arizeai/ax-client";

const { data: versions, pagination } = await listPromptVersions({
  prompt: "your_prompt_id",
});
```

### Create a New Version

```typescript theme={null}
import { createPromptVersion } from "@arizeai/ax-client";

const version = await createPromptVersion({
  prompt: "your_prompt_id",
  commitMessage: "Improved system prompt for edge cases",
  inputVariableFormat: "f_string",
  provider: "open_ai",
  model: "gpt-4o",
  messages: [
    { role: "system", content: "You are an expert assistant for {company_name}. Be concise." },
    { role: "user", content: "{user_query}" },
  ],
});
```

### Get a Version by ID

```typescript theme={null}
import { getPromptVersion } from "@arizeai/ax-client";

const version = await getPromptVersion({
  versionId: "your_version_id",
});
```

## Manage Labels

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

### Get a Version by Label

```typescript theme={null}
import { getPromptVersionByLabel } from "@arizeai/ax-client";

const version = await getPromptVersionByLabel({
  prompt: "your_prompt_id",
  labelName: "production",
});
```

### Set Labels on a Version

Replaces all existing labels on the version with the provided list.

```typescript theme={null}
import { setPromptVersionLabels } from "@arizeai/ax-client";

const { labels } = await setPromptVersionLabels({
  versionId: "your_version_id",
  labels: ["production"],
});
```

### Promote a New Version

```typescript theme={null}
import { createPromptVersion, setPromptVersionLabels } from "@arizeai/ax-client";

const newVersion = await createPromptVersion({
  prompt: "your_prompt_id",
  commitMessage: "Tuned for better conciseness",
  inputVariableFormat: "f_string",
  provider: "open_ai",
  model: "gpt-4o",
  messages: [{ role: "user", content: "{user_query}" }],
});

await setPromptVersionLabels({
  versionId: newVersion.id,
  labels: ["production"],
});
```

### Delete a Label

```typescript theme={null}
import { deletePromptVersionLabel } from "@arizeai/ax-client";

await deletePromptVersionLabel({
  versionId: "your_version_id",
  labelName: "staging",
});
```