curl -X POST https://api.helicone.ai/v1/prompt-2025/query/versions \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"promptId": "prompt_abc123xyz"
}'
curl -X POST https://api.helicone.ai/v1/prompt-2025/query/versions \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"promptId": "prompt_abc123xyz",
"majorVersion": 2
}'
// Get all versions
const response = await fetch(
'https://api.helicone.ai/v1/prompt-2025/query/versions',
{
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json',
},
body: JSON.stringify({
promptId: 'prompt_abc123xyz',
}),
}
);
// Get versions for major version 2
const response2 = await fetch(
'https://api.helicone.ai/v1/prompt-2025/query/versions',
{
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json',
},
body: JSON.stringify({
promptId: 'prompt_abc123xyz',
majorVersion: 2,
}),
}
);
const result = await response.json();
import requests
# Get all versions
response = requests.post(
'https://api.helicone.ai/v1/prompt-2025/query/versions',
headers={
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json',
},
json={
'promptId': 'prompt_abc123xyz',
},
)
# Get versions for major version 2
response2 = requests.post(
'https://api.helicone.ai/v1/prompt-2025/query/versions',
headers={
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json',
},
json={
'promptId': 'prompt_abc123xyz',
'majorVersion': 2,
},
)
result = response.json()
{
"data": [
{
"id": "version_ghi789rst",
"prompt_id": "prompt_abc123xyz",
"model": "gpt-4o",
"major_version": 2,
"minor_version": 1,
"commit_message": "Updated temperature and added max_tokens",
"environments": ["production"],
"created_at": "2024-03-11T14:30:00Z",
"s3_url": "https://s3.amazonaws.com/..."
},
{
"id": "version_def456uvw",
"prompt_id": "prompt_abc123xyz",
"model": "gpt-4o",
"major_version": 2,
"minor_version": 0,
"commit_message": "Major rewrite with new system prompt",
"environments": ["staging"],
"created_at": "2024-03-10T16:00:00Z",
"s3_url": "https://s3.amazonaws.com/..."
},
{
"id": "version_abc123xyz",
"prompt_id": "prompt_abc123xyz",
"model": "gpt-4o",
"major_version": 1,
"minor_version": 0,
"commit_message": "Initial version",
"environments": [],
"created_at": "2024-03-10T12:00:00Z",
"s3_url": "https://s3.amazonaws.com/..."
}
],
"error": null
}
{
"data": [
{
"id": "version_ghi789rst",
"prompt_id": "prompt_abc123xyz",
"model": "gpt-4o",
"major_version": 2,
"minor_version": 1,
"commit_message": "Updated temperature and added max_tokens",
"environments": ["production"],
"created_at": "2024-03-11T14:30:00Z",
"s3_url": "https://s3.amazonaws.com/..."
},
{
"id": "version_def456uvw",
"prompt_id": "prompt_abc123xyz",
"model": "gpt-4o",
"major_version": 2,
"minor_version": 0,
"commit_message": "Major rewrite with new system prompt",
"environments": ["staging"],
"created_at": "2024-03-10T16:00:00Z",
"s3_url": "https://s3.amazonaws.com/..."
}
],
"error": null
}
{
"data": null,
"error": "Failed to retrieve versions"
}
Prompts
Get Prompt Versions
Retrieve all versions of a prompt
POST
/
v1
/
prompt-2025
/
query
/
versions
curl -X POST https://api.helicone.ai/v1/prompt-2025/query/versions \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"promptId": "prompt_abc123xyz"
}'
curl -X POST https://api.helicone.ai/v1/prompt-2025/query/versions \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"promptId": "prompt_abc123xyz",
"majorVersion": 2
}'
// Get all versions
const response = await fetch(
'https://api.helicone.ai/v1/prompt-2025/query/versions',
{
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json',
},
body: JSON.stringify({
promptId: 'prompt_abc123xyz',
}),
}
);
// Get versions for major version 2
const response2 = await fetch(
'https://api.helicone.ai/v1/prompt-2025/query/versions',
{
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json',
},
body: JSON.stringify({
promptId: 'prompt_abc123xyz',
majorVersion: 2,
}),
}
);
const result = await response.json();
import requests
# Get all versions
response = requests.post(
'https://api.helicone.ai/v1/prompt-2025/query/versions',
headers={
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json',
},
json={
'promptId': 'prompt_abc123xyz',
},
)
# Get versions for major version 2
response2 = requests.post(
'https://api.helicone.ai/v1/prompt-2025/query/versions',
headers={
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json',
},
json={
'promptId': 'prompt_abc123xyz',
'majorVersion': 2,
},
)
result = response.json()
{
"data": [
{
"id": "version_ghi789rst",
"prompt_id": "prompt_abc123xyz",
"model": "gpt-4o",
"major_version": 2,
"minor_version": 1,
"commit_message": "Updated temperature and added max_tokens",
"environments": ["production"],
"created_at": "2024-03-11T14:30:00Z",
"s3_url": "https://s3.amazonaws.com/..."
},
{
"id": "version_def456uvw",
"prompt_id": "prompt_abc123xyz",
"model": "gpt-4o",
"major_version": 2,
"minor_version": 0,
"commit_message": "Major rewrite with new system prompt",
"environments": ["staging"],
"created_at": "2024-03-10T16:00:00Z",
"s3_url": "https://s3.amazonaws.com/..."
},
{
"id": "version_abc123xyz",
"prompt_id": "prompt_abc123xyz",
"model": "gpt-4o",
"major_version": 1,
"minor_version": 0,
"commit_message": "Initial version",
"environments": [],
"created_at": "2024-03-10T12:00:00Z",
"s3_url": "https://s3.amazonaws.com/..."
}
],
"error": null
}
{
"data": [
{
"id": "version_ghi789rst",
"prompt_id": "prompt_abc123xyz",
"model": "gpt-4o",
"major_version": 2,
"minor_version": 1,
"commit_message": "Updated temperature and added max_tokens",
"environments": ["production"],
"created_at": "2024-03-11T14:30:00Z",
"s3_url": "https://s3.amazonaws.com/..."
},
{
"id": "version_def456uvw",
"prompt_id": "prompt_abc123xyz",
"model": "gpt-4o",
"major_version": 2,
"minor_version": 0,
"commit_message": "Major rewrite with new system prompt",
"environments": ["staging"],
"created_at": "2024-03-10T16:00:00Z",
"s3_url": "https://s3.amazonaws.com/..."
}
],
"error": null
}
{
"data": null,
"error": "Failed to retrieve versions"
}
Retrieves all versions of a specific prompt, optionally filtered by major version.
Request Body
string
required
The unique identifier of the prompt
number
Optional filter to return only versions with this major version number
Response
array
Array of prompt version objects
Show Prompt Version Object
Show Prompt Version Object
string
The unique identifier for this version
string
The prompt ID this version belongs to
string
The model specified in this version
number
Major version number
number
Minor version number
string
Description of changes in this version
string[]
Array of environments this version is deployed to
string
ISO 8601 timestamp of when this version was created
string
S3 URL where the full prompt body is stored
string | null
Error message if the request failed, null otherwise
curl -X POST https://api.helicone.ai/v1/prompt-2025/query/versions \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"promptId": "prompt_abc123xyz"
}'
curl -X POST https://api.helicone.ai/v1/prompt-2025/query/versions \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"promptId": "prompt_abc123xyz",
"majorVersion": 2
}'
// Get all versions
const response = await fetch(
'https://api.helicone.ai/v1/prompt-2025/query/versions',
{
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json',
},
body: JSON.stringify({
promptId: 'prompt_abc123xyz',
}),
}
);
// Get versions for major version 2
const response2 = await fetch(
'https://api.helicone.ai/v1/prompt-2025/query/versions',
{
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json',
},
body: JSON.stringify({
promptId: 'prompt_abc123xyz',
majorVersion: 2,
}),
}
);
const result = await response.json();
import requests
# Get all versions
response = requests.post(
'https://api.helicone.ai/v1/prompt-2025/query/versions',
headers={
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json',
},
json={
'promptId': 'prompt_abc123xyz',
},
)
# Get versions for major version 2
response2 = requests.post(
'https://api.helicone.ai/v1/prompt-2025/query/versions',
headers={
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json',
},
json={
'promptId': 'prompt_abc123xyz',
'majorVersion': 2,
},
)
result = response.json()
{
"data": [
{
"id": "version_ghi789rst",
"prompt_id": "prompt_abc123xyz",
"model": "gpt-4o",
"major_version": 2,
"minor_version": 1,
"commit_message": "Updated temperature and added max_tokens",
"environments": ["production"],
"created_at": "2024-03-11T14:30:00Z",
"s3_url": "https://s3.amazonaws.com/..."
},
{
"id": "version_def456uvw",
"prompt_id": "prompt_abc123xyz",
"model": "gpt-4o",
"major_version": 2,
"minor_version": 0,
"commit_message": "Major rewrite with new system prompt",
"environments": ["staging"],
"created_at": "2024-03-10T16:00:00Z",
"s3_url": "https://s3.amazonaws.com/..."
},
{
"id": "version_abc123xyz",
"prompt_id": "prompt_abc123xyz",
"model": "gpt-4o",
"major_version": 1,
"minor_version": 0,
"commit_message": "Initial version",
"environments": [],
"created_at": "2024-03-10T12:00:00Z",
"s3_url": "https://s3.amazonaws.com/..."
}
],
"error": null
}
{
"data": [
{
"id": "version_ghi789rst",
"prompt_id": "prompt_abc123xyz",
"model": "gpt-4o",
"major_version": 2,
"minor_version": 1,
"commit_message": "Updated temperature and added max_tokens",
"environments": ["production"],
"created_at": "2024-03-11T14:30:00Z",
"s3_url": "https://s3.amazonaws.com/..."
},
{
"id": "version_def456uvw",
"prompt_id": "prompt_abc123xyz",
"model": "gpt-4o",
"major_version": 2,
"minor_version": 0,
"commit_message": "Major rewrite with new system prompt",
"environments": ["staging"],
"created_at": "2024-03-10T16:00:00Z",
"s3_url": "https://s3.amazonaws.com/..."
}
],
"error": null
}
{
"data": null,
"error": "Failed to retrieve versions"
}
Version Numbering
Prompt versions use semantic versioning:- Major version: Breaking changes or complete rewrites (e.g., 1.x → 2.x)
- Minor version: Incremental updates and improvements (e.g., 2.0 → 2.1)
Getting the Full Prompt Body
The versions endpoint returns metadata only. To get the full prompt body including messages, use:- GET
/v1/prompt-2025/{promptVersionId}/prompt-body- Get prompt body for a specific version - POST
/v2/prompt-2025/query/version- Get version with body included
Environment Management
Versions can be associated with environments (e.g., “production”, “staging”, “development”). Use these endpoints to manage environments:- POST
/v1/prompt-2025/update/environment- Assign a version to an environment - POST
/v1/prompt-2025/remove/environment- Remove a version from an environment - POST
/v1/prompt-2025/query/environment-version- Get the version for a specific environment
⌘I