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

# Prompt mutations

> Create, edit and delete Prompt Hub prompts, add versions and manage labels. Arguments, return types and a validated example for each of the 6 mutations.

Create, edit and delete Prompt Hub prompts, add versions and manage labels.

For task-oriented walkthroughs of these operations, see the [Prompt guide](/docs/ax/graphql-reference/guides/prompts). Every mutation below is sent as a `POST` to `https://app.arize.com/graphql` with an `x-api-key` header; see [Forming calls](/docs/ax/graphql-reference/overview/how-to-use-graphql/forming-calls).

## Mutations in this page

* [`createPrompt`](#createprompt): Create a new prompt
* [`editPrompt`](#editprompt): Edit an existing prompt
* [`deletePrompt`](#deleteprompt): Delete an existing prompt
* [`createPromptVersion`](#createpromptversion): Create a new prompt version
* [`updatePromptVersionLabel`](#updatepromptversionlabel): update prompt version label.
* [`removePromptVersionLabel`](#removepromptversionlabel): Remove a label from a prompt version

## Reference

### createPrompt

Create a new prompt

`createPrompt(input: CreatePromptMutationInput!): CreatePromptMutationPayload`

#### Arguments

**input** `CreatePromptMutationInput!` *required*

**CreatePromptMutationInput fields**

**spaceId** `ID!` *required*

The space id for the prompt

**name** `String!` *required*

The name of the prompt

**description** `String`

The description of the saved prompt

**tags** `[String!]`

Tag names to associate with the prompt. Names that do not already exist in the space are created, which requires TAG\_CREATE. Deprecated: create tags explicitly and use addTagsToPrompt.

**commitMessage** `String!` *required*

The commit message describing the changes in this version

**inputVariableFormat** `PromptVersionInputVariableFormatEnum!` *required*

The input variable format for determining prompt variables in the messages One of: `F_STRING`, `MUSTACHE`, `NONE`.

**provider** `ExternalLLMProvider!` *required*

The provider to use for the call. One of: `openAI`, `azureOpenAI`, `anthropic`, `vertexAI`, `awsBedrock`, `custom`, `nvidiaNim`, `gemini`, `litellm`, `fireworks`, `togetherAi`.

**model** `String`

The model to use for the call.

**messages** `[LLMMessageInput!]!` *required*

The full message to send to the LLM (e.g., a prompt template with all variables filled in).

**LLMMessageInput fields**

**role** `MessageRole!` *required*

The role of the messages author only applicable for chat models One of: `system`, `user`, `assistant`, `tool`.

**content** `String`

The content of the message

**imageUrls** `[String]`

The image contents of the message as a list of urls

**toolCalls** `[GeneratedToolInput!]`

The tool calls generated by the model, such as function calls.

**GeneratedToolInput fields**

**id** `String!` *required*

The id of the tool call.

**type** `ToolTypeEnum!` *required*

The type of the tool interaction. Supports function and built-in tools (e.g. web\_search). One of: `function`, `web_search`.

**function** `GeneratedFunctionDetailsInput`

The function that the model called (only for type=function). Nested `GeneratedFunctionDetailsInput` (same shape as above).

**output** `JSONObject`

Optional tool output payload for non-function tools (e.g. web\_search results).

**toolCallId** `String`

The id of the tool call, used to track the tool call in the response

**invocationParams** `InvocationParamsInput!` *required*

The params to call the LLM with.

**InvocationParamsInput fields**

**temperature** `Float`

The sampling temperature for the call, the higher the value the more random the output.

**top\_p** `Float`

Alternative to sampling temperature, the model considers the results of the tokens with top\_p probability mass. So 0.1 means only the tokens comprising the top 10% mass are considered. Modify this or temperature but not both.

**stop** `[String!]`

A list of sequences where the API will stop generating further tokens.

**max\_tokens** `Int`

The maximum number of tokens to generate. Set to -1 to generate the model's maximum. For custom providers, a value of -1 will generate the default token length.

**max\_completion\_tokens** `Int`

The maximum number of tokens to generate. Set to -1 to generate the model's maximum. For custom providers, a value of -1 will generate the default token length.

**presence\_penalty** `Float`

The penalty for repeating topics, the higher the value the more likely the llm is to talk about new topics. Must be between -2.0 and 2.0.

**frequency\_penalty** `Float`

The penalty for frequency of tokens, the higher the value, the less likely the llm is to repeat the same line verbatim. Must be between -2.0 and 2.0

**top\_k** `Int`

Top-K changes how the model selects tokens for output. A top-K of 1 means the next selected token is the most probable among all tokens in the model's vocabulary (also called greedy decoding), while a top-K of 3 means that the next token is selected from among the three most probable tokens by using temperature.

**toolConfig** `ToolConfigInput`

The tool config to call the LLM with.

**ToolConfigInput fields**

**tools** `[ToolInput!]`

A list of tools that can be called by the LLM during the chat. Nested `ToolInput` (same shape as above).

**toolChoice** `ToolChoiceInput`

Nested `ToolChoiceInput` (same shape as above).

**response\_format** `ResponseFormatInput`

The response format configuration for structured outputs from the LLM.

**ResponseFormatInput fields**

**type** `ResponseFormatType`

The type of response format to use One of: `text`, `json_object`, `json_schema`.

**jsonSchema** `JsonSchemaInput`

JSON schema configuration (required when type is json\_schema) Nested `JsonSchemaInput` (same shape as above).

**thinking\_level** `String`

Controls how much reasoning the model performs before responding. Supported by Gemini 3.x models. Accepted values: 'low', 'high'.

**thinking\_budget** `Int`

Maximum tokens the model may use for internal reasoning. Supported by Gemini 2.5 models. Range: 0–24,576 (Flash/Flash-Lite) or 128–32,768 (Pro). Set 0 to disable thinking on Flash models.

**reasoning\_effort** `String`

Controls how much reasoning the model performs before responding. Supported by OpenAI o-series and GPT-5 models. o-series: 'low' | 'medium' | 'high'. GPT-5: 'none' | 'low' | 'medium' | 'high' | 'xhigh'.

**verbosity** `String`

Controls the verbosity of model output. Supported by OpenAI GPT-5 series. Accepted values: 'low' | 'medium' | 'high'.

**service\_tier** `String`

Processing tier for the request. Supported by OpenAI on the openAI provider only, and only for models eligible for Priority processing. Accepted values: 'auto' | 'priority'. Omit to use the project default.

**providerParams** `ProviderParamsInput!` *required*

The provider params to use for the call.

**ProviderParamsInput fields**

**azureParams** `AzureOpenAIParams`

The Azure OpenAI params to use for the call.

**AzureOpenAIParams fields**

**azureDeploymentName** `String!` *required*

The Azure deployment name to use for the call.

**azureOpenAIEndpoint** `String!` *required*

The Azure OpenAI endpoint to use for the call.

**azureOpenAIVersion** `String`

The Azure OpenAI version to use for the call.

**anthropicHeaders** `AnthropicHeadersInput`

The headers to send to the via bedrock for the InvokeModel API for Anthropic models. Not used for other providers.

**AnthropicHeadersInput fields**

**anthropicBeta** `[String]`

The beta version of the Anthropic API to use

**customProviderParams** `CustomProviderParams`

Custom provider params to use for the call.

**CustomProviderParams fields**

**customModelEndpoint** `CustomLlmEndpointInput!` *required*

When connecting to a custom model, the endpoint to use for the call. Nested `CustomLlmEndpointInput` (same shape as above).

**customProviderAPIVersion** `String`

The API version to use for the call. Optional for custom models.

**anthropic\_version** `String`

The version of the Anthropic API to use

**region** `String`

The region in which the model is deployed (e.g., us-east-1). Also known as 'location' for Vertex invocations.

**bedrockOptions** `BedrockOptionsInput`

The options to use for the Bedrock API.

**BedrockOptionsInput fields**

**useConverseEndpoint** `Boolean`

Whether to use the converse endpoint for the Bedrock API.

**integrationId** `ID`

The selected named LLM integration id (relay global id). If provided, server will use its configuration.

**id** `String`

Unique identifier for this input

**clientMutationId** `String`

#### Returns

**prompt** `Prompt!`

**Prompt fields**

Scalar fields: `id`, `name`, `description`, `tags`, `createdAt`, `updatedAt`, `commitHash`, `commitMessage`, `messages`, `inputVariableFormat`, `toolCalls`, `llmParameters`, `provider`, `modelName`.

Object fields (select subfields): `tagsConnection`, `webhookSubscriptions`, `versionHistory`, `toolChoice`, `createdBy`, `latestPromptOptimizationTask`.

#### Example

Only required input fields are shown. Replace `<ID>` and `<string>` placeholders with real values; the [object graph](/docs/ax/graphql-reference/queries/object-graph) page shows how to look IDs up.

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

```json Variables theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
{
  "input": {
    "spaceId": "<ID>",
    "name": "<string>",
    "commitMessage": "<string>",
    "inputVariableFormat": "F_STRING",
    "provider": "openAI",
    "messages": [
      {
        "role": "system"
      }
    ],
    "invocationParams": {},
    "providerParams": {}
  }
}
```

### editPrompt

Edit an existing prompt

`editPrompt(input: EditPromptMutationInput!): EditPromptMutationPayload`

#### Arguments

**input** `EditPromptMutationInput!` *required*

**EditPromptMutationInput fields**

**promptId** `ID!` *required*

The prompt id to edit

**spaceId** `ID!` *required*

The space id for the prompt

**name** `String!` *required*

The name of the prompt

**description** `String`

The description of the saved prompt

**clientMutationId** `String`

#### Returns

**prompt** `Prompt!`

**Prompt fields**

Scalar fields: `id`, `name`, `description`, `tags`, `createdAt`, `updatedAt`, `commitHash`, `commitMessage`, `messages`, `inputVariableFormat`, `toolCalls`, `llmParameters`, `provider`, `modelName`.

Object fields (select subfields): `tagsConnection`, `webhookSubscriptions`, `versionHistory`, `toolChoice`, `createdBy`, `latestPromptOptimizationTask`.

#### Example

Only required input fields are shown. Replace `<ID>` and `<string>` placeholders with real values; the [object graph](/docs/ax/graphql-reference/queries/object-graph) page shows how to look IDs up.

```graphql Mutation theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
mutation EditPrompt($input: EditPromptMutationInput!) {
  editPrompt(input: $input) {
    prompt { id name }
  }
}
```

```json Variables theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
{
  "input": {
    "promptId": "<ID>",
    "spaceId": "<ID>",
    "name": "<string>"
  }
}
```

### deletePrompt

Delete an existing prompt

`deletePrompt(input: DeletePromptMutationInput!): DeletePromptMutationPayload`

#### Arguments

**input** `DeletePromptMutationInput!` *required*

**DeletePromptMutationInput fields**

**promptId** `ID!` *required*

The prompt id to delete

**spaceId** `ID!` *required*

The space id for the prompt

**clientMutationId** `String`

#### Returns

**success** `Boolean!`

Indicates whether the prompt was deleted

#### Example

Only required input fields are shown. Replace `<ID>` and `<string>` placeholders with real values; the [object graph](/docs/ax/graphql-reference/queries/object-graph) page shows how to look IDs up.

```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": "<ID>",
    "spaceId": "<ID>"
  }
}
```

### createPromptVersion

Create a new prompt version

`createPromptVersion(input: CreatePromptVersionMutationInput!): CreatePromptVersionMutationPayload`

#### Arguments

**input** `CreatePromptVersionMutationInput!` *required*

**CreatePromptVersionMutationInput fields**

**spaceId** `ID!` *required*

The space ID for the prompt

**promptId** `ID!` *required*

The prompt ID in which the version will be created

**commitMessage** `String!` *required*

The commit message describing the changes in this version

**inputVariableFormat** `PromptVersionInputVariableFormatEnum!` *required*

The input variable format for determining prompt variables in the messages One of: `F_STRING`, `MUSTACHE`, `NONE`.

**provider** `ExternalLLMProvider!` *required*

The provider to use for the call. One of: `openAI`, `azureOpenAI`, `anthropic`, `vertexAI`, `awsBedrock`, `custom`, `nvidiaNim`, `gemini`, `litellm`, `fireworks`, `togetherAi`.

**model** `String`

The model to use for the call.

**messages** `[LLMMessageInput!]!` *required*

The full message to send to the LLM (e.g., a prompt template with all variables filled in).

**LLMMessageInput fields**

**role** `MessageRole!` *required*

The role of the messages author only applicable for chat models One of: `system`, `user`, `assistant`, `tool`.

**content** `String`

The content of the message

**imageUrls** `[String]`

The image contents of the message as a list of urls

**toolCalls** `[GeneratedToolInput!]`

The tool calls generated by the model, such as function calls.

**GeneratedToolInput fields**

**id** `String!` *required*

The id of the tool call.

**type** `ToolTypeEnum!` *required*

The type of the tool interaction. Supports function and built-in tools (e.g. web\_search). One of: `function`, `web_search`.

**function** `GeneratedFunctionDetailsInput`

The function that the model called (only for type=function). Nested `GeneratedFunctionDetailsInput` (same shape as above).

**output** `JSONObject`

Optional tool output payload for non-function tools (e.g. web\_search results).

**toolCallId** `String`

The id of the tool call, used to track the tool call in the response

**invocationParams** `InvocationParamsInput!` *required*

The params to call the LLM with.

**InvocationParamsInput fields**

**temperature** `Float`

The sampling temperature for the call, the higher the value the more random the output.

**top\_p** `Float`

Alternative to sampling temperature, the model considers the results of the tokens with top\_p probability mass. So 0.1 means only the tokens comprising the top 10% mass are considered. Modify this or temperature but not both.

**stop** `[String!]`

A list of sequences where the API will stop generating further tokens.

**max\_tokens** `Int`

The maximum number of tokens to generate. Set to -1 to generate the model's maximum. For custom providers, a value of -1 will generate the default token length.

**max\_completion\_tokens** `Int`

The maximum number of tokens to generate. Set to -1 to generate the model's maximum. For custom providers, a value of -1 will generate the default token length.

**presence\_penalty** `Float`

The penalty for repeating topics, the higher the value the more likely the llm is to talk about new topics. Must be between -2.0 and 2.0.

**frequency\_penalty** `Float`

The penalty for frequency of tokens, the higher the value, the less likely the llm is to repeat the same line verbatim. Must be between -2.0 and 2.0

**top\_k** `Int`

Top-K changes how the model selects tokens for output. A top-K of 1 means the next selected token is the most probable among all tokens in the model's vocabulary (also called greedy decoding), while a top-K of 3 means that the next token is selected from among the three most probable tokens by using temperature.

**toolConfig** `ToolConfigInput`

The tool config to call the LLM with.

**ToolConfigInput fields**

**tools** `[ToolInput!]`

A list of tools that can be called by the LLM during the chat. Nested `ToolInput` (same shape as above).

**toolChoice** `ToolChoiceInput`

Nested `ToolChoiceInput` (same shape as above).

**response\_format** `ResponseFormatInput`

The response format configuration for structured outputs from the LLM.

**ResponseFormatInput fields**

**type** `ResponseFormatType`

The type of response format to use One of: `text`, `json_object`, `json_schema`.

**jsonSchema** `JsonSchemaInput`

JSON schema configuration (required when type is json\_schema) Nested `JsonSchemaInput` (same shape as above).

**thinking\_level** `String`

Controls how much reasoning the model performs before responding. Supported by Gemini 3.x models. Accepted values: 'low', 'high'.

**thinking\_budget** `Int`

Maximum tokens the model may use for internal reasoning. Supported by Gemini 2.5 models. Range: 0–24,576 (Flash/Flash-Lite) or 128–32,768 (Pro). Set 0 to disable thinking on Flash models.

**reasoning\_effort** `String`

Controls how much reasoning the model performs before responding. Supported by OpenAI o-series and GPT-5 models. o-series: 'low' | 'medium' | 'high'. GPT-5: 'none' | 'low' | 'medium' | 'high' | 'xhigh'.

**verbosity** `String`

Controls the verbosity of model output. Supported by OpenAI GPT-5 series. Accepted values: 'low' | 'medium' | 'high'.

**service\_tier** `String`

Processing tier for the request. Supported by OpenAI on the openAI provider only, and only for models eligible for Priority processing. Accepted values: 'auto' | 'priority'. Omit to use the project default.

**providerParams** `ProviderParamsInput!` *required*

The provider params to use for the call.

**ProviderParamsInput fields**

**azureParams** `AzureOpenAIParams`

The Azure OpenAI params to use for the call.

**AzureOpenAIParams fields**

**azureDeploymentName** `String!` *required*

The Azure deployment name to use for the call.

**azureOpenAIEndpoint** `String!` *required*

The Azure OpenAI endpoint to use for the call.

**azureOpenAIVersion** `String`

The Azure OpenAI version to use for the call.

**anthropicHeaders** `AnthropicHeadersInput`

The headers to send to the via bedrock for the InvokeModel API for Anthropic models. Not used for other providers.

**AnthropicHeadersInput fields**

**anthropicBeta** `[String]`

The beta version of the Anthropic API to use

**customProviderParams** `CustomProviderParams`

Custom provider params to use for the call.

**CustomProviderParams fields**

**customModelEndpoint** `CustomLlmEndpointInput!` *required*

When connecting to a custom model, the endpoint to use for the call. Nested `CustomLlmEndpointInput` (same shape as above).

**customProviderAPIVersion** `String`

The API version to use for the call. Optional for custom models.

**anthropic\_version** `String`

The version of the Anthropic API to use

**region** `String`

The region in which the model is deployed (e.g., us-east-1). Also known as 'location' for Vertex invocations.

**bedrockOptions** `BedrockOptionsInput`

The options to use for the Bedrock API.

**BedrockOptionsInput fields**

**useConverseEndpoint** `Boolean`

Whether to use the converse endpoint for the Bedrock API.

**integrationId** `ID`

The selected named LLM integration id (relay global id). If provided, server will use its configuration.

**id** `String`

Unique identifier for this input

**clientMutationId** `String`

#### Returns

**promptVersion** `PromptVersion!`

**PromptVersion fields**

Scalar fields: `id`, `createdAt`, `commitHash`, `commitMessage`, `messages`, `inputVariableFormat`, `toolCalls`, `llmParameters`, `provider`, `modelName`, `labels`, `promptName`, `versionNumber`.

Object fields (select subfields): `toolChoice`, `createdBy`, `providerParameters`, `integration`.

#### Example

Only required input fields are shown. Replace `<ID>` and `<string>` placeholders with real values; the [object graph](/docs/ax/graphql-reference/queries/object-graph) page shows how to look IDs up.

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

```json Variables theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
{
  "input": {
    "spaceId": "<ID>",
    "promptId": "<ID>",
    "commitMessage": "<string>",
    "inputVariableFormat": "F_STRING",
    "provider": "openAI",
    "messages": [
      {
        "role": "system"
      }
    ],
    "invocationParams": {},
    "providerParams": {}
  }
}
```

### updatePromptVersionLabel

update prompt version label.

`updatePromptVersionLabel(input: updatePromptVersionLabelMutationInput!): updatePromptVersionLabelMutationPayload`

#### Arguments

**input** `updatePromptVersionLabelMutationInput!` *required*

**updatePromptVersionLabelMutationInput fields**

**spaceId** `ID!` *required*

The ID of the space

**versionId** `ID!` *required*

the prompt version ID we wish to add a label to.

**name** `String!` *required*

the label we wish to attach to the version ID

**clientMutationId** `String`

#### Returns

**prompt** `Prompt!`

**Prompt fields**

Scalar fields: `id`, `name`, `description`, `tags`, `createdAt`, `updatedAt`, `commitHash`, `commitMessage`, `messages`, `inputVariableFormat`, `toolCalls`, `llmParameters`, `provider`, `modelName`.

Object fields (select subfields): `tagsConnection`, `webhookSubscriptions`, `versionHistory`, `toolChoice`, `createdBy`, `latestPromptOptimizationTask`.

#### Example

Only required input fields are shown. Replace `<ID>` and `<string>` placeholders with real values; the [object graph](/docs/ax/graphql-reference/queries/object-graph) page shows how to look IDs up.

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

```json Variables theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
{
  "input": {
    "spaceId": "<ID>",
    "versionId": "<ID>",
    "name": "<string>"
  }
}
```

### removePromptVersionLabel

Remove a label from a prompt version

`removePromptVersionLabel(input: removePromptVersionLabelMutationInput!): removePromptVersionLabelMutationPayload`

#### Arguments

**input** `removePromptVersionLabelMutationInput!` *required*

**removePromptVersionLabelMutationInput fields**

**spaceId** `ID!` *required*

The ID of the space

**promptVersionId** `ID!` *required*

The prompt version ID from which to remove the label

**name** `String!` *required*

The label to remove from the version

**clientMutationId** `String`

#### Returns

**prompt** `Prompt!`

**Prompt fields**

Scalar fields: `id`, `name`, `description`, `tags`, `createdAt`, `updatedAt`, `commitHash`, `commitMessage`, `messages`, `inputVariableFormat`, `toolCalls`, `llmParameters`, `provider`, `modelName`.

Object fields (select subfields): `tagsConnection`, `webhookSubscriptions`, `versionHistory`, `toolChoice`, `createdBy`, `latestPromptOptimizationTask`.

#### Example

Only required input fields are shown. Replace `<ID>` and `<string>` placeholders with real values; the [object graph](/docs/ax/graphql-reference/queries/object-graph) page shows how to look IDs up.

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

```json Variables theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
{
  "input": {
    "spaceId": "<ID>",
    "promptVersionId": "<ID>",
    "name": "<string>"
  }
}
```