> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/helicone/helicone/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Prompt Versions

> Retrieve all versions of a prompt

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

## Request Body

<ParamField body="promptId" type="string" required>
  The unique identifier of the prompt
</ParamField>

<ParamField body="majorVersion" type="number">
  Optional filter to return only versions with this major version number
</ParamField>

## Response

<ResponseField name="data" type="array">
  Array of prompt version objects

  <Expandable title="Prompt Version Object">
    <ResponseField name="id" type="string">
      The unique identifier for this version
    </ResponseField>

    <ResponseField name="prompt_id" type="string">
      The prompt ID this version belongs to
    </ResponseField>

    <ResponseField name="model" type="string">
      The model specified in this version
    </ResponseField>

    <ResponseField name="major_version" type="number">
      Major version number
    </ResponseField>

    <ResponseField name="minor_version" type="number">
      Minor version number
    </ResponseField>

    <ResponseField name="commit_message" type="string">
      Description of changes in this version
    </ResponseField>

    <ResponseField name="environments" type="string[]">
      Array of environments this version is deployed to
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO 8601 timestamp of when this version was created
    </ResponseField>

    <ResponseField name="s3_url" type="string">
      S3 URL where the full prompt body is stored
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="error" type="string | null">
  Error message if the request failed, null otherwise
</ResponseField>

<RequestExample>
  ```bash cURL - All Versions theme={null}
  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"
    }'
  ```

  ```bash cURL - Specific Major Version theme={null}
  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
    }'
  ```

  ```typescript TypeScript theme={null}
  // 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();
  ```

  ```python Python theme={null}
  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()
  ```
</RequestExample>

<ResponseExample>
  ```json 200 Success - All Versions theme={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/..."
      },
      {
        "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
  }
  ```

  ```json 200 Success - Major Version 2 Only theme={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
  }
  ```

  ```json 500 Error theme={null}
  {
    "data": null,
    "error": "Failed to retrieve versions"
  }
  ```
</ResponseExample>

## 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](/api/prompts/get-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