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

# Managing prompts with GraphQL

> Automate Arize AX Prompt Hub with the GraphQL API: create and version prompts, promote labels like production and staging, and delete old prompts entirely.

[Prompt Hub](/docs/ax/prompts/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](/docs/ax/graphql-reference/overview/how-to-use-graphql/forming-calls) 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.

<CodeGroup>
  ```graphql Query theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  query FindSpace($search: String) {
    viewer {
      spaces(search: $search, first: 5) {
        edges {
          node {
            id
            name
          }
        }
      }
    }
  }
  ```

  ```json Variables theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  {
    "search": "LLM_test"
  }
  ```
</CodeGroup>

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](/docs/ax/graphql-reference/overview/how-to-use-graphql/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.

<CodeGroup>
  ```graphql Query theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  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 }
                }
              }
            }
          }
        }
      }
    }
  }
  ```

  ```json Variables theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  {
    "spaceId": "<SPACE_ID>",
    "search": "support-reply"
  }
  ```
</CodeGroup>

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

<CodeGroup>
  ```graphql Mutation theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  mutation CreatePrompt($input: CreatePromptMutationInput!) {
    createPrompt(input: $input) {
      prompt { id name commitMessage }
    }
  }
  ```

  ```json Variables theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  {
    "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": {}
    }
  }
  ```
</CodeGroup>

Reference: [`createPrompt`](/docs/ax/graphql-reference/mutations/prompts#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.

<CodeGroup>
  ```graphql Mutation theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  mutation CreatePromptVersion($input: CreatePromptVersionMutationInput!) {
    createPromptVersion(input: $input) {
      promptVersion { id versionNumber commitMessage }
    }
  }
  ```

  ```json Variables theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  {
    "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": {}
    }
  }
  ```
</CodeGroup>

Reference: [`createPromptVersion`](/docs/ax/graphql-reference/mutations/prompts#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.

<CodeGroup>
  ```graphql Mutation theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  mutation UpdatePromptVersionLabel($input: updatePromptVersionLabelMutationInput!) {
    updatePromptVersionLabel(input: $input) {
      prompt { id name }
    }
  }
  ```

  ```graphql Rollback theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  mutation RemovePromptVersionLabel($input: removePromptVersionLabelMutationInput!) {
    removePromptVersionLabel(input: $input) {
      prompt { id name }
    }
  }
  ```

  ```json Promote variables theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  {
    "input": {
      "spaceId": "<SPACE_ID>",
      "versionId": "<PROMPT_VERSION_ID>",
      "name": "production"
    }
  }
  ```

  ```json Rollback variables theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  {
    "input": {
      "spaceId": "<SPACE_ID>",
      "promptVersionId": "<PROMPT_VERSION_ID>",
      "name": "production"
    }
  }
  ```
</CodeGroup>

Reference: [`updatePromptVersionLabel`](/docs/ax/graphql-reference/mutations/prompts#updatepromptversionlabel), [`removePromptVersionLabel`](/docs/ax/graphql-reference/mutations/prompts#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.

<CodeGroup>
  ```graphql Mutation theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  mutation DeletePrompt($input: DeletePromptMutationInput!) {
    deletePrompt(input: $input) {
      success
    }
  }
  ```

  ```json Variables theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  {
    "input": {
      "promptId": "<PROMPT_ID>",
      "spaceId": "<SPACE_ID>"
    }
  }
  ```
</CodeGroup>

Reference: [`deletePrompt`](/docs/ax/graphql-reference/mutations/prompts#deleteprompt).

## Gotchas and behavior notes

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

<CardGroup cols={3}>
  <Card title="Prompt mutations reference" icon="book" href="/docs/ax/graphql-reference/mutations/prompts">
    Full argument and field listing for all six prompt mutations.
  </Card>

  <Card title="All GraphQL mutations" icon="list" href="/docs/ax/graphql-reference/mutations">
    Browse mutations for every other domain.
  </Card>

  <Card title="API explorer" icon="terminal" href="/docs/ax/graphql-reference/overview/api-explorer">
    Try queries and mutations interactively with autocomplete.
  </Card>
</CardGroup>