Skip to main content
The prompts functions are currently in ALPHA. The API may change without notice. A one-time warning is emitted on first use.

​
List Prompts

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

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: "openAI",
    model: "gpt-4o",
    messages: [
      { role: "system", content: "You are a helpful assistant for {company_name}." },
      { role: "user", content: "{user_query}" },
    ],
  },
});

​
With Invocation Parameters

import { createPrompt } from "@arizeai/ax-client";

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

​
Get a Prompt

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

import { updatePrompt } from "@arizeai/ax-client";

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

​
Delete a Prompt

import { deletePrompt } from "@arizeai/ax-client";

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

​
Manage Versions

​
List Versions

import { listPromptVersions } from "@arizeai/ax-client";

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

​
Create a New Version

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: "openAI",
  model: "gpt-4o",
  messages: [
    { role: "system", content: "You are an expert assistant for {company_name}. Be concise." },
    { role: "user", content: "{user_query}" },
  ],
});

​
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 Label

import { getPromptLabel } from "@arizeai/ax-client";

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

​
Set Labels on a Version

Replaces all existing labels on the version with the provided list. 
import { setPromptVersionLabels } from "@arizeai/ax-client";

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

​
Promote a New Version

import { createPromptVersion, setPromptVersionLabels } from "@arizeai/ax-client";

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

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

​
Delete a Label

import { deletePromptVersionLabel } from "@arizeai/ax-client";

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