Prompts

The prompts functions are currently in BETA. The API may change without notice. A one-time warning is emitted on first use.

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.

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.

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

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.

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.

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.

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.

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.

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.

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.

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.

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

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

Promote a New Version

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.

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

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

API reference

API clients

List Prompts

Create a Prompt

With Invocation Parameters

Get a Prompt

Update a Prompt

Delete a Prompt

Manage Versions

List Versions

Create a New Version

Get a Version by ID

Manage Labels

Get a Version by Label

Set Labels on a Version

Promote a New Version

Delete a Label

​List Prompts

​Create a Prompt

​With Invocation Parameters

​Get a Prompt

​Update a Prompt

​Delete a Prompt

​Manage Versions

​List Versions

​Create a New Version

​Get a Version by ID

​Manage Labels

​Get a Version by Label

​Set Labels on a Version

​Promote a New Version

​Delete a Label

List Prompts

Create a Prompt

With Invocation Parameters

Get a Prompt

Update a Prompt

Delete a Prompt

Manage Versions

List Versions

Create a New Version

Get a Version by ID

Manage Labels

Get a Version by Label

Set Labels on a Version

Promote a New Version

Delete a Label