Prompt mutations

Create, edit and delete Prompt Hub prompts, add versions and manage labels. For task-oriented walkthroughs of these operations, see the Prompt guide. Every mutation below is sent as a POST to https://app.arize.com/graphql with an x-api-key header; see Forming calls.

Mutations in this page

createPrompt: Create a new prompt
editPrompt: Edit an existing prompt
deletePrompt: Delete an existing prompt
createPromptVersion: Create a new prompt version
updatePromptVersionLabel: update prompt version label.
removePromptVersionLabel: Remove a label from a prompt version

Reference

createPrompt

Create a new prompt createPrompt(input: CreatePromptMutationInput!): CreatePromptMutationPayload

Arguments

CreatePromptMutationInput!

required

Show CreatePromptMutationInput fields

ID!

required

The space id for the prompt

String!

required

The name of the prompt

String

The description of the saved prompt

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

String!

required

The commit message describing the changes in this version

PromptVersionInputVariableFormatEnum!

required

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

ExternalLLMProvider!

required

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

String

The model to use for the call.

[LLMMessageInput!]!

required

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

Show LLMMessageInput fields

MessageRole!

required

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

String

The content of the message

[String]

The image contents of the message as a list of urls

[GeneratedToolInput!]

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

Show GeneratedToolInput fields

String!

required

The id of the tool call.

ToolTypeEnum!

required

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

GeneratedFunctionDetailsInput

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

JSONObject

Optional tool output payload for non-function tools (e.g. web_search results).

String

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

InvocationParamsInput!

required

The params to call the LLM with.

Show InvocationParamsInput fields

Float

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

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.

[String!]

A list of sequences where the API will stop generating further 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.

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.

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.

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

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.

ToolConfigInput

The tool config to call the LLM with.

Show ToolConfigInput fields

[ToolInput!]

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

ToolChoiceInput

Nested ToolChoiceInput (same shape as above).

ResponseFormatInput

The response format configuration for structured outputs from the LLM.

Show ResponseFormatInput fields

ResponseFormatType

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

JsonSchemaInput

JSON schema configuration (required when type is json_schema) Nested JsonSchemaInput (same shape as above).

String

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

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.

String

String

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

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.

ProviderParamsInput!

required

The provider params to use for the call.

Show ProviderParamsInput fields

AzureOpenAIParams

The Azure OpenAI params to use for the call.

Show AzureOpenAIParams fields

String!

required

The Azure deployment name to use for the call.

String!

required

The Azure OpenAI endpoint to use for the call.

String

The Azure OpenAI version to use for the call.

AnthropicHeadersInput

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

Show AnthropicHeadersInput fields

[String]

The beta version of the Anthropic API to use

CustomProviderParams

Custom provider params to use for the call.

Show CustomProviderParams fields

CustomLlmEndpointInput!

required

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

String

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

String

The version of the Anthropic API to use

String

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

BedrockOptionsInput

The options to use for the Bedrock API.

Show BedrockOptionsInput fields

Boolean

Whether to use the converse endpoint for the Bedrock API.

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

String

Unique identifier for this input

String

Returns

Prompt!

Show 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 page shows how to look IDs up.

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

{
  "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

EditPromptMutationInput!

required

Show EditPromptMutationInput fields

ID!

required

The prompt id to edit

ID!

required

The space id for the prompt

String!

required

The name of the prompt

String

The description of the saved prompt

String

Returns

Prompt!

Show Prompt fields

Example

Only required input fields are shown. Replace <ID> and <string> placeholders with real values; the object graph page shows how to look IDs up.

mutation EditPrompt($input: EditPromptMutationInput!) {
  editPrompt(input: $input) {
    prompt { id name }
  }
}

{
  "input": {
    "promptId": "<ID>",
    "spaceId": "<ID>",
    "name": "<string>"
  }
}

deletePrompt

Delete an existing prompt deletePrompt(input: DeletePromptMutationInput!): DeletePromptMutationPayload

Arguments

DeletePromptMutationInput!

required

Show DeletePromptMutationInput fields

ID!

required

The prompt id to delete

ID!

required

The space id for the prompt

String

Returns

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 page shows how to look IDs up.

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

{
  "input": {
    "promptId": "<ID>",
    "spaceId": "<ID>"
  }
}

createPromptVersion

Create a new prompt version createPromptVersion(input: CreatePromptVersionMutationInput!): CreatePromptVersionMutationPayload

Arguments

CreatePromptVersionMutationInput!

required

Show CreatePromptVersionMutationInput fields

ID!

required

The space ID for the prompt

ID!

required

The prompt ID in which the version will be created

String!

required

The commit message describing the changes in this version

PromptVersionInputVariableFormatEnum!

required

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

ExternalLLMProvider!

required

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

String

The model to use for the call.

[LLMMessageInput!]!

required

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

Show LLMMessageInput fields

MessageRole!

required

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

String

The content of the message

[String]

The image contents of the message as a list of urls

[GeneratedToolInput!]

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

Show GeneratedToolInput fields

String!

required

The id of the tool call.

ToolTypeEnum!

required

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

GeneratedFunctionDetailsInput

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

JSONObject

Optional tool output payload for non-function tools (e.g. web_search results).

String

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

InvocationParamsInput!

required

The params to call the LLM with.

Show InvocationParamsInput fields

Float

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

Float

[String!]

A list of sequences where the API will stop generating further 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.

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.

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.

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

Int

ToolConfigInput

The tool config to call the LLM with.

Show ToolConfigInput fields

[ToolInput!]

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

ToolChoiceInput

Nested ToolChoiceInput (same shape as above).

ResponseFormatInput

The response format configuration for structured outputs from the LLM.

Show ResponseFormatInput fields

ResponseFormatType

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

JsonSchemaInput

JSON schema configuration (required when type is json_schema) Nested JsonSchemaInput (same shape as above).

String

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

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.

String

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

String

ProviderParamsInput!

required

The provider params to use for the call.

Show ProviderParamsInput fields

AzureOpenAIParams

The Azure OpenAI params to use for the call.

Show AzureOpenAIParams fields

String!

required

The Azure deployment name to use for the call.

String!

required

The Azure OpenAI endpoint to use for the call.

String

The Azure OpenAI version to use for the call.

AnthropicHeadersInput

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

Show AnthropicHeadersInput fields

[String]

The beta version of the Anthropic API to use

CustomProviderParams

Custom provider params to use for the call.

Show CustomProviderParams fields

CustomLlmEndpointInput!

required

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

String

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

String

The version of the Anthropic API to use

String

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

BedrockOptionsInput

The options to use for the Bedrock API.

Show BedrockOptionsInput fields

Boolean

Whether to use the converse endpoint for the Bedrock API.

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

String

Unique identifier for this input

String

Returns

PromptVersion!

Show 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 page shows how to look IDs up.

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

{
  "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

updatePromptVersionLabelMutationInput!

required

Show updatePromptVersionLabelMutationInput fields

ID!

required

The ID of the space

ID!

required

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

String!

required

the label we wish to attach to the version ID

String

Returns

Prompt!

Show Prompt fields

Example

Only required input fields are shown. Replace <ID> and <string> placeholders with real values; the object graph page shows how to look IDs up.

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

{
  "input": {
    "spaceId": "<ID>",
    "versionId": "<ID>",
    "name": "<string>"
  }
}

removePromptVersionLabel

Remove a label from a prompt version removePromptVersionLabel(input: removePromptVersionLabelMutationInput!): removePromptVersionLabelMutationPayload

Arguments

removePromptVersionLabelMutationInput!

required

Show removePromptVersionLabelMutationInput fields

ID!

required

The ID of the space

ID!

required

The prompt version ID from which to remove the label

String!

required

The label to remove from the version

String

Returns

Prompt!

Show Prompt fields

Example

Only required input fields are shown. Replace <ID> and <string> placeholders with real values; the object graph page shows how to look IDs up.

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

{
  "input": {
    "spaceId": "<ID>",
    "promptVersionId": "<ID>",
    "name": "<string>"
  }
}

Skills

MCP server

API reference

API clients

Mutations in this page

Reference

createPrompt

Arguments

Returns

Example

editPrompt

Arguments

Returns

Example

deletePrompt

Arguments

Returns

Example

createPromptVersion

Arguments

Returns

Example

updatePromptVersionLabel

Arguments

Returns

Example

removePromptVersionLabel

Arguments

Returns

Example

​Mutations in this page

​Reference

​createPrompt

​Arguments

​Returns

​Example

​editPrompt

​Arguments

​Returns

​Example

​deletePrompt

​Arguments

​Returns

​Example

​createPromptVersion

​Arguments

​Returns

​Example

​updatePromptVersionLabel

​Arguments

​Returns

​Example

​removePromptVersionLabel

​Arguments

​Returns

​Example

Mutations in this page

Reference

createPrompt

Arguments

Returns

Example

editPrompt

Arguments

Returns

Example

deletePrompt

Arguments

Returns

Example

createPromptVersion

Arguments

Returns

Example

updatePromptVersionLabel

Arguments

Returns

Example

removePromptVersionLabel

Arguments

Returns

Example