> ## Documentation Index
> Fetch the complete documentation index at: /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.md) 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.

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

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.md) 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.

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

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

```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": {}
  }
}
```

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.

```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": {}
  }
}
```

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.

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

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.

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

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

## Gotchas and behavior notes

> [accordion] 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] 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] 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.

> [card] [Prompt mutations reference](/docs/ax/graphql-reference/mutations/prompts.md)
>
> Full argument and field listing for all six prompt mutations.

> [card] [All GraphQL mutations](/docs/ax/graphql-reference/mutations.md)
>
> Browse mutations for every other domain.

> [card] [API explorer](/docs/ax/graphql-reference/overview/api-explorer.md)
>
> Try queries and mutations interactively with autocomplete.