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.
Query parameters
cursorany ofOptional
Cursor for pagination (base64-encoded prompt ID)
stringOptional
nullOptional
limitintegerOptionalDefault:
The max number of prompts to return at a time.
100Responses
200
A list of prompts with pagination information
application/json
403
Forbidden
text/plain
422
Unprocessable Entity
text/plain
get
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.
Body
Responses
200
The newly created prompt version
application/json
403
Forbidden
text/plain
422
Unprocessable Entity
text/plain
post
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.
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
nullOptional
limitintegerOptionalDefault:
The max number of prompt versions to return at a time.
100Responses
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
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.
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
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.
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
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.
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
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.
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
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
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.
Path parameters
prompt_version_idstringRequired
The ID of the prompt version.
Query parameters
cursorany ofOptional
Cursor for pagination (base64-encoded promptVersionTag ID)
stringOptional
nullOptional
limitintegerOptionalDefault:
The max number of tags to return at a time.
100Responses
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
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?