Prompts

REST API methods for interacting with Phoenix prompts

List all prompts

get

Retrieve a paginated list of all prompts in the system. A prompt can have multiple versions.

Query parameters

cursorany ofOptional

Cursor for pagination (base64-encoded prompt ID)

stringOptional

or

nullOptional

limitintegerOptional

The max number of prompts to return at a time.

Default: 100

Responses

200

A list of prompts with pagination information

application/json

403

Forbidden

text/plain

422

Unprocessable Entity

text/plain

get

HTTPcURLJavaScriptPython

GET /v1/prompts HTTP/1.1
Host: 
Accept: */*

{
  "data": [
    {
      "name": "text",
      "description": "text",
      "source_prompt_id": "text",
      "id": "text"
    }
  ],
  "next_cursor": "text"
}

Create a new prompt

post

Create a new prompt and its initial version. A prompt can have multiple versions.

Body

Responses

200

The newly created prompt version

application/json

403

Forbidden

text/plain

422

Unprocessable Entity

text/plain

post

HTTPcURLJavaScriptPython

POST /v1/prompts HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 847

{
  "prompt": {
    "name": "text",
    "description": "text",
    "source_prompt_id": "text"
  },
  "version": {
    "description": "text",
    "model_provider": "OPENAI",
    "model_name": "text",
    "template": {
      "type": "text",
      "messages": [
        {
          "role": "user",
          "content": "text"
        }
      ]
    },
    "template_type": "STR",
    "template_format": "MUSTACHE",
    "invocation_parameters": {
      "type": "text",
      "openai": {
        "temperature": 1,
        "max_tokens": 1,
        "max_completion_tokens": 1,
        "frequency_penalty": 1,
        "presence_penalty": 1,
        "top_p": 1,
        "seed": 1,
        "reasoning_effort": "low"
      }
    },
    "tools": {
      "type": "text",
      "tools": [
        {
          "type": "text",
          "function": {
            "name": "text",
            "description": "text",
            "parameters": {
              "ANY_ADDITIONAL_PROPERTY": "anything"
            },
            "strict": true
          }
        }
      ],
      "tool_choice": {
        "type": "text"
      },
      "disable_parallel_tool_calls": true
    },
    "response_format": {
      "type": "text",
      "json_schema": {
        "name": "text",
        "description": "text",
        "schema": {
          "ANY_ADDITIONAL_PROPERTY": "anything"
        },
        "strict": true
      }
    }
  }
}

{
  "data": {
    "description": "text",
    "model_provider": "OPENAI",
    "model_name": "text",
    "template": {
      "type": "text",
      "messages": [
        {
          "role": "user",
          "content": "text"
        }
      ]
    },
    "template_type": "STR",
    "template_format": "MUSTACHE",
    "invocation_parameters": {
      "type": "text",
      "openai": {
        "temperature": 1,
        "max_tokens": 1,
        "max_completion_tokens": 1,
        "frequency_penalty": 1,
        "presence_penalty": 1,
        "top_p": 1,
        "seed": 1,
        "reasoning_effort": "low"
      }
    },
    "tools": {
      "type": "text",
      "tools": [
        {
          "type": "text",
          "function": {
            "name": "text",
            "description": "text",
            "parameters": {
              "ANY_ADDITIONAL_PROPERTY": "anything"
            },
            "strict": true
          }
        }
      ],
      "tool_choice": {
        "type": "text"
      },
      "disable_parallel_tool_calls": true
    },
    "response_format": {
      "type": "text",
      "json_schema": {
        "name": "text",
        "description": "text",
        "schema": {
          "ANY_ADDITIONAL_PROPERTY": "anything"
        },
        "strict": true
      }
    },
    "id": "text"
  }
}

List prompt versions

get

Retrieve all versions of a specific prompt with pagination support. Each prompt can have multiple versions with different configurations.

Path parameters

prompt_identifierstringRequired

The identifier of the prompt, i.e. name or ID.

Query parameters

cursorany ofOptional

Cursor for pagination (base64-encoded promptVersion ID)

stringOptional

or

nullOptional

limitintegerOptional

The max number of prompt versions to return at a time.

Default: 100

Responses

200

A list of prompt versions with pagination information

application/json

403

Forbidden

text/plain

404

Not Found

text/plain

422

Unprocessable Entity

text/plain

get

HTTPcURLJavaScriptPython

GET /v1/prompts/{prompt_identifier}/versions HTTP/1.1
Host: 
Accept: */*

{
  "data": [
    {
      "description": "text",
      "model_provider": "OPENAI",
      "model_name": "text",
      "template": {
        "type": "text",
        "messages": [
          {
            "role": "user",
            "content": "text"
          }
        ]
      },
      "template_type": "STR",
      "template_format": "MUSTACHE",
      "invocation_parameters": {
        "type": "text",
        "openai": {
          "temperature": 1,
          "max_tokens": 1,
          "max_completion_tokens": 1,
          "frequency_penalty": 1,
          "presence_penalty": 1,
          "top_p": 1,
          "seed": 1,
          "reasoning_effort": "low"
        }
      },
      "tools": {
        "type": "text",
        "tools": [
          {
            "type": "text",
            "function": {
              "name": "text",
              "description": "text",
              "parameters": {
                "ANY_ADDITIONAL_PROPERTY": "anything"
              },
              "strict": true
            }
          }
        ],
        "tool_choice": {
          "type": "text"
        },
        "disable_parallel_tool_calls": true
      },
      "response_format": {
        "type": "text",
        "json_schema": {
          "name": "text",
          "description": "text",
          "schema": {
            "ANY_ADDITIONAL_PROPERTY": "anything"
          },
          "strict": true
        }
      },
      "id": "text"
    }
  ],
  "next_cursor": "text"
}

Get prompt version by tag

get

Retrieve a specific prompt version using its tag name. Tags are used to identify specific versions of a prompt.

Path parameters

prompt_identifierstringRequired

The identifier of the prompt, i.e. name or ID.

tag_namestringRequired

The tag of the prompt version

Responses

200

The prompt version with the specified tag

application/json

403

Forbidden

text/plain

404

Not Found

text/plain

422

Unprocessable Entity

text/plain

get

HTTPcURLJavaScriptPython

GET /v1/prompts/{prompt_identifier}/tags/{tag_name} HTTP/1.1
Host: 
Accept: */*

{
  "data": {
    "description": "text",
    "model_provider": "OPENAI",
    "model_name": "text",
    "template": {
      "type": "text",
      "messages": [
        {
          "role": "user",
          "content": "text"
        }
      ]
    },
    "template_type": "STR",
    "template_format": "MUSTACHE",
    "invocation_parameters": {
      "type": "text",
      "openai": {
        "temperature": 1,
        "max_tokens": 1,
        "max_completion_tokens": 1,
        "frequency_penalty": 1,
        "presence_penalty": 1,
        "top_p": 1,
        "seed": 1,
        "reasoning_effort": "low"
      }
    },
    "tools": {
      "type": "text",
      "tools": [
        {
          "type": "text",
          "function": {
            "name": "text",
            "description": "text",
            "parameters": {
              "ANY_ADDITIONAL_PROPERTY": "anything"
            },
            "strict": true
          }
        }
      ],
      "tool_choice": {
        "type": "text"
      },
      "disable_parallel_tool_calls": true
    },
    "response_format": {
      "type": "text",
      "json_schema": {
        "name": "text",
        "description": "text",
        "schema": {
          "ANY_ADDITIONAL_PROPERTY": "anything"
        },
        "strict": true
      }
    },
    "id": "text"
  }
}

Get latest prompt version

get

Retrieve the most recent version of a specific prompt.

Path parameters

prompt_identifierstringRequired

The identifier of the prompt, i.e. name or ID.

Responses

200

The latest version of the specified prompt

application/json

403

Forbidden

text/plain

404

Not Found

text/plain

422

Unprocessable Entity

text/plain

get

HTTPcURLJavaScriptPython

GET /v1/prompts/{prompt_identifier}/latest HTTP/1.1
Host: 
Accept: */*

{
  "data": {
    "description": "text",
    "model_provider": "OPENAI",
    "model_name": "text",
    "template": {
      "type": "text",
      "messages": [
        {
          "role": "user",
          "content": "text"
        }
      ]
    },
    "template_type": "STR",
    "template_format": "MUSTACHE",
    "invocation_parameters": {
      "type": "text",
      "openai": {
        "temperature": 1,
        "max_tokens": 1,
        "max_completion_tokens": 1,
        "frequency_penalty": 1,
        "presence_penalty": 1,
        "top_p": 1,
        "seed": 1,
        "reasoning_effort": "low"
      }
    },
    "tools": {
      "type": "text",
      "tools": [
        {
          "type": "text",
          "function": {
            "name": "text",
            "description": "text",
            "parameters": {
              "ANY_ADDITIONAL_PROPERTY": "anything"
            },
            "strict": true
          }
        }
      ],
      "tool_choice": {
        "type": "text"
      },
      "disable_parallel_tool_calls": true
    },
    "response_format": {
      "type": "text",
      "json_schema": {
        "name": "text",
        "description": "text",
        "schema": {
          "ANY_ADDITIONAL_PROPERTY": "anything"
        },
        "strict": true
      }
    },
    "id": "text"
  }
}

Add tag to prompt version

post

Add a new tag to a specific prompt version. Tags help identify and categorize different versions of a prompt.

Path parameters

prompt_version_idstringRequired

The ID of the prompt version.

Body

namestringRequiredPattern: ^[a-z0-9]([_a-z0-9-]*[a-z0-9])?$

descriptionany ofOptional

stringOptional

or

nullOptional

Responses

204

No content returned on successful tag creation

403

Forbidden

text/plain

404

Not Found

text/plain

422

Unprocessable Entity

text/plain

post

HTTPcURLJavaScriptPython

POST /v1/prompt_versions/{prompt_version_id}/tags HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 36

{
  "name": "text",
  "description": "text"
}

No content

List prompt version tags

get

Retrieve all tags associated with a specific prompt version. Tags are used to identify and categorize different versions of a prompt.

Path parameters

prompt_version_idstringRequired

The ID of the prompt version.

Query parameters

cursorany ofOptional

Cursor for pagination (base64-encoded promptVersionTag ID)

stringOptional

or

nullOptional

limitintegerOptional

The max number of tags to return at a time.

Default: 100

Responses

200

A list of tags associated with the prompt version

application/json

403

Forbidden

text/plain

404

Not Found

text/plain

422

Unprocessable Entity

text/plain

get

HTTPcURLJavaScriptPython

GET /v1/prompt_versions/{prompt_version_id}/tags HTTP/1.1
Host: 
Accept: */*

{
  "data": [
    {
      "name": "text",
      "description": "text",
      "id": "text"
    }
  ],
  "next_cursor": "text"
}

Get prompt version by ID

get

Retrieve a specific prompt version using its unique identifier. A prompt version contains the actual template and configuration.

Path parameters

prompt_version_idstringRequired

The ID of the prompt version.

Responses

200

The requested prompt version

application/json

403

Forbidden

text/plain

404

Not Found

text/plain

422

Unprocessable Entity

text/plain

get

HTTPcURLJavaScriptPython

GET /v1/prompt_versions/{prompt_version_id} HTTP/1.1
Host: 
Accept: */*

{
  "data": {
    "description": "text",
    "model_provider": "OPENAI",
    "model_name": "text",
    "template": {
      "type": "text",
      "messages": [
        {
          "role": "user",
          "content": "text"
        }
      ]
    },
    "template_type": "STR",
    "template_format": "MUSTACHE",
    "invocation_parameters": {
      "type": "text",
      "openai": {
        "temperature": 1,
        "max_tokens": 1,
        "max_completion_tokens": 1,
        "frequency_penalty": 1,
        "presence_penalty": 1,
        "top_p": 1,
        "seed": 1,
        "reasoning_effort": "low"
      }
    },
    "tools": {
      "type": "text",
      "tools": [
        {
          "type": "text",
          "function": {
            "name": "text",
            "description": "text",
            "parameters": {
              "ANY_ADDITIONAL_PROPERTY": "anything"
            },
            "strict": true
          }
        }
      ],
      "tool_choice": {
        "type": "text"
      },
      "disable_parallel_tool_calls": true
    },
    "response_format": {
      "type": "text",
      "json_schema": {
        "name": "text",
        "description": "text",
        "schema": {
          "ANY_ADDITIONAL_PROPERTY": "anything"
        },
        "strict": true
      }
    },
    "id": "text"
  }
}