> ## Documentation Index
> Fetch the complete documentation index at: https://arize-ax.mintlify.site/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

Lists prompts available to the client, sorted by update date with the most recently updated prompts first. Returns a paginated list of `Prompt` objects.

```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",   // case-insensitive substring filter on prompt name (optional)
  limit: 10,
});
console.log(prompts);
```

## Create a Prompt

Creates a new prompt with an initial version. Returns a `PromptWithVersion` containing the created prompt and its initial version.

```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

Gets a prompt by its name or ID. The response always includes a resolved version. By default the latest version is returned. Use `versionId` or `label` to resolve a specific version instead (mutually exclusive). Returns a `PromptWithVersion`.

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

// Get the latest version
const prompt = await getPrompt({
  prompt: "customer-support",
  space: "my-space",
});

// Get a specific version by ID
const byVersion = await getPrompt({
  prompt: "customer-support",
  space: "my-space",
  versionId: "UHJvbXB0VmVyc2lvbjoxMjM0NQ==",
});

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

## Update a Prompt

Updates a prompt's metadata by its name or ID. Currently supports updating the description (pass `null` to clear it). Returns the updated `Prompt`.

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

const updated = await updatePrompt({
  prompt: "customer-support",
  space: "my-space",
  description: "Updated description for this prompt",
});
```

## Delete a Prompt

Deletes a prompt by its name or ID. This operation is irreversible.

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

await deletePrompt({
  prompt: "customer-support",
  space: "my-space",
});
```

## Manage Versions

### List Versions

Lists all versions of a prompt, sorted by creation date with the most recently created first. Returns a paginated list of `PromptVersion` objects.

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

const { data: versions, pagination } = await listPromptVersions({
  prompt: "customer-support",
  space: "my-space",
});
console.log(versions);
```

### Create a New Version

Creates a new version of an existing prompt. Returns the created `PromptVersion`.

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

const version = await createPromptVersion({
  prompt: "customer-support",
  space: "my-space",
  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

Gets a single prompt version by its ID. Version IDs are pure IDs with no name resolution. Returns the `PromptVersion`.

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

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

## 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

Resolves a label on a prompt to the version it points to. Returns the full `PromptVersion` that the label currently references.

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

const version = await getPromptVersionByLabel({
  prompt: "customer-support",
  space: "my-space",
  labelName: "production",
});
```

### Set Labels on a Version

Sets (replaces) all labels on a prompt version. This is an idempotent operation. If a label already exists on another version of the same prompt, it will be moved to this version. Labels not included in the request will be removed from this version. Returns the updated `PromptVersion`, whose `labels` field reflects the new set.

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

const { labels } = await setPromptVersionLabels({
  versionId: "UHJvbXB0VmVyc2lvbjoxMjM0NQ==",
  labels: ["production", "staging"],
});
console.log(labels);
```

### Promote a New Version

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

const newVersion = await createPromptVersion({
  prompt: "customer-support",
  space: "my-space",
  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

Removes a specific label from a prompt version.

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

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