Get Prompt Versions

Retrieve all versions of a prompt

POST /v1/prompt-2025/query/versions

cURL - All 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"
  }'

200 Success - All Versions

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

Retrieves all versions of a specific prompt, optionally filtered by major version.

Request Body

promptId · string · required

The unique identifier of the prompt

majorVersion · number

Optional filter to return only versions with this major version number

Response

data · array

Array of prompt version objects

Show Prompt Version Object

id · string

The unique identifier for this version

prompt_id · string

The prompt ID this version belongs to

model · string

The model specified in this version

major_version · number

Major version number

minor_version · number

Minor version number

commit_message · string

Description of changes in this version

environments · string[]

Array of environments this version is deployed to

created_at · string

ISO 8601 timestamp of when this version was created

s3_url · string

S3 URL where the full prompt body is stored

error · string | null

Error message if the request failed, null otherwise

cURL - All 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"
  }'

200 Success - All Versions

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

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)

Versions are returned in descending order (newest first).

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

See the Get Prompt Body endpoint for details.

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