Managing prompts with GraphQL

Prompt Hub is Arize AX’s version-controlled store for prompt templates, shared across the playground, tasks, and experiments. The GraphQL API lets you manage that same store from code: create prompts, add versions as you iterate, and move labels like production or staging between versions without touching the UI. This guide assumes you already know how to form a GraphQL call with an x-api-key header against https://app.arize.com/graphql.

Find the IDs you need

Every prompt mutation needs a space ID, and most need a prompt or prompt version ID. Start from viewer to find your space.

query FindSpace($search: String) {
  viewer {
    spaces(search: $search, first: 5) {
      edges {
        node {
          id
          name
        }
      }
    }
  }
}

{
  "search": "LLM_test"
}

Once you have a prompt or version ID, fetch it directly with the node root field, for example node(id: "<PROMPT_ID>") { ... on Prompt { name } }. See Using global node IDs for how these opaque IDs work.

List prompts and their versions in a space

The Space.prompts connection returns every prompt in a space. Each prompt’s versionHistory connection returns its versions, including the labels attached to each one, so you can see what is currently labeled production without a separate call.

query ListPromptsWithVersions($spaceId: ID!, $search: String) {
  node(id: $spaceId) {
    ... on Space {
      prompts(search: $search, first: 20) {
        edges {
          node {
            id
            name
            versionHistory(first: 5) {
              edges {
                node { id versionNumber labels }
              }
            }
          }
        }
      }
    }
  }
}

{
  "spaceId": "<SPACE_ID>",
  "search": "support-reply"
}

Create a prompt with a first version

createPrompt creates the prompt and its first version in one call: the messages, model, provider, and invocation parameters all live on the input, not on a separate version mutation. inputVariableFormat tells the parser how {variable} placeholders in your messages are written.

mutation CreatePrompt($input: CreatePromptMutationInput!) {
  createPrompt(input: $input) {
    prompt { id name commitMessage }
  }
}

{
  "input": {
    "spaceId": "<SPACE_ID>",
    "name": "support-reply-drafter",
    "commitMessage": "Initial version",
    "inputVariableFormat": "F_STRING",
    "provider": "openAI",
    "model": "gpt-4.1",
    "messages": [
      { "role": "system", "content": "You are a support agent. Be concise and polite." },
      { "role": "user", "content": "Customer message: {customer_message}" }
    ],
    "invocationParams": { "temperature": 0.2, "max_tokens": 500 },
    "providerParams": {}
  }
}

Reference: createPrompt.

Add a new version to an existing prompt

Use createPromptVersion once you want to change the messages, model, or parameters without losing history. Each version keeps its own commitMessage, so treat it like a commit log entry describing what changed.

mutation CreatePromptVersion($input: CreatePromptVersionMutationInput!) {
  createPromptVersion(input: $input) {
    promptVersion { id versionNumber commitMessage }
  }
}

{
  "input": {
    "spaceId": "<SPACE_ID>",
    "promptId": "<PROMPT_ID>",
    "commitMessage": "Tighten the tone, lead with a solution",
    "inputVariableFormat": "F_STRING",
    "provider": "openAI",
    "model": "gpt-4.1",
    "messages": [
      { "role": "system", "content": "You are a support agent. Be concise, polite, and solution-first." },
      { "role": "user", "content": "Customer message: {customer_message}" }
    ],
    "invocationParams": { "temperature": 0.1 },
    "providerParams": {}
  }
}

Reference: createPromptVersion.

Promote a version with a label, then roll it back

Labels like production or staging point at a specific version, and moving a label is how you deploy a new version without changing the prompt ID your application references. updatePromptVersionLabel moves (or creates) a label on the version you pass in; if another version already holds that label, Prompt Hub moves it off that version. removePromptVersionLabel takes the label off entirely, for example to roll back a bad promotion. Note the version field name differs between the two: versionId on one, promptVersionId on the other.

mutation UpdatePromptVersionLabel($input: updatePromptVersionLabelMutationInput!) {
  updatePromptVersionLabel(input: $input) {
    prompt { id name }
  }
}

mutation RemovePromptVersionLabel($input: removePromptVersionLabelMutationInput!) {
  removePromptVersionLabel(input: $input) {
    prompt { id name }
  }
}

{
  "input": {
    "spaceId": "<SPACE_ID>",
    "versionId": "<PROMPT_VERSION_ID>",
    "name": "production"
  }
}

{
  "input": {
    "spaceId": "<SPACE_ID>",
    "promptVersionId": "<PROMPT_VERSION_ID>",
    "name": "production"
  }
}

Reference: updatePromptVersionLabel, removePromptVersionLabel.

Delete a prompt

Deleting a prompt removes every version under it. There is no separate “delete version” mutation in this domain, so retire a single bad version by removing its labels rather than deleting the whole prompt.

mutation DeletePrompt($input: DeletePromptMutationInput!) {
  deletePrompt(input: $input) {
    success
  }
}

{
  "input": {
    "promptId": "<PROMPT_ID>",
    "spaceId": "<SPACE_ID>"
  }
}

Reference: deletePrompt.

Gotchas and behavior notes

updatePromptVersionLabelMutationInput is lowercase, and the version field name changes

Unlike every other input type in this domain, the schema spells this one updatePromptVersionLabelMutationInput and updatePromptVersionLabelMutationPayload with a lowercase first letter; use the exact casing or the request fails to parse. It also takes versionId for the version, while removePromptVersionLabel takes promptVersionId for the same concept. Double-check which name applies when you switch between the two.

createPrompt's tags field is deprecated

CreatePromptMutationInput.tags is marked deprecated in the schema in favor of creating tags explicitly and attaching them with a separate addTagsToPrompt mutation (not covered in this guide). Avoid relying on tags for new integrations.

Input and output provider enums do not match, and messages read back as JSON

createPrompt and createPromptVersion accept provider: ExternalLLMProvider, which excludes cursor and typeSafeAi. But Prompt.provider and PromptVersion.provider are typed as the broader LLMIntegrationProvider, which includes them, so a prompt saved through one of those integrations can return a value you cannot pass back in. Separately, Prompt.messages and PromptVersion.messages are typed [JSON!]! on read even though the write side takes a strongly typed [LLMMessageInput!]!, so reusing a fetched prompt’s messages in a new version means reshaping the JSON back into the role/content input shape yourself.

Prompt mutations reference

Full argument and field listing for all six prompt mutations.

All GraphQL mutations

Browse mutations for every other domain.

API explorer

Try queries and mutations interactively with autocomplete.

Skills

MCP server

API reference

API clients

Managing prompts with GraphQL

Find the IDs you need

List prompts and their versions in a space

Create a prompt with a first version

Add a new version to an existing prompt

Promote a version with a label, then roll it back

Delete a prompt

Gotchas and behavior notes

Prompt mutations reference

All GraphQL mutations

API explorer

​Find the IDs you need

​List prompts and their versions in a space

​Create a prompt with a first version

​Add a new version to an existing prompt

​Promote a version with a label, then roll it back

​Delete a prompt

​Gotchas and behavior notes

Prompt mutations reference

All GraphQL mutations

API explorer

Find the IDs you need

List prompts and their versions in a space

Create a prompt with a first version

Add a new version to an existing prompt

Promote a version with a label, then roll it back

Delete a prompt

Gotchas and behavior notes