Prompts
REST API methods for interacting with Phoenix prompts
Retrieve a paginated list of all prompts in the system. A prompt can have multiple versions.
Cursor for pagination (base64-encoded prompt ID)
The max number of prompts to return at a time.
100
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 and its initial version. A prompt can have multiple versions.
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"
}
}
Retrieve all versions of a specific prompt with pagination support. Each prompt can have multiple versions with different configurations.
The identifier of the prompt, i.e. name or ID.
Cursor for pagination (base64-encoded promptVersion ID)
The max number of prompt versions to return at a time.
100
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"
}
Retrieve a specific prompt version using its unique identifier. A prompt version contains the actual template and configuration.
The ID of the prompt version.
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"
}
}
Retrieve a specific prompt version using its tag name. Tags are used to identify specific versions of a prompt.
The identifier of the prompt, i.e. name or ID.
The tag of the prompt version
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"
}
}
Retrieve the most recent version of a specific prompt.
The identifier of the prompt, i.e. name or ID.
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 a new tag to a specific prompt version. Tags help identify and categorize different versions of a prompt.
The ID of the prompt version.
^[a-z0-9]([_a-z0-9-]*[a-z0-9])?$
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
Retrieve all tags associated with a specific prompt version. Tags are used to identify and categorize different versions of a prompt.
The ID of the prompt version.
Cursor for pagination (base64-encoded promptVersionTag ID)
The max number of tags to return at a time.
100
GET /v1/prompt_versions/{prompt_version_id}/tags HTTP/1.1
Host:
Accept: */*
{
"data": [
{
"name": "text",
"description": "text",
"id": "text"
}
],
"next_cursor": "text"
}
Last updated
Was this helpful?