List Prompt Versions

The listPromptVersions endpoint allows you to retrieve all versions of a specific prompt. This is useful for viewing version history, comparing versions, and understanding how your prompt has evolved over time.

Usage

import { PromptTK } from "@devvle/ptk-api-sdk";

const promptTK = new PromptTK({
  userId: "your-user-id",
  apiKey: "your-api-key",
});

async function listVersions() {
  const promptId = "your-prompt-id";

  try {
    const response = await promptTK.listPromptVersions(promptId);
    console.log("Versions:", response);

    // Access the versions array
    response.data.forEach(version => {
      console.log(`Version ${version.versionNumber}: ${version.label || 'No label'}`);
    });
  } catch (error) {
    console.error("Error listing versions:", error);
  }
}

listVersions();

Expected Output:

{
  success: true,
  message: 'Prompt versions retrieved successfully',
  data: [
    {
      versionId: 'version-3-id',
      versionNumber: 3,
      input: { /* input template */ },
      output: 'Generated prompt text for v3...',
      createdAt: 1234567900,
      updatedAt: 1234567900,
      createdBy: 'user-id',
      source: 'api',
      label: 'Latest improvements',
      parentVersionId: 'version-2-id',
      inputTokens: [...],
      outputTokens: [...],
      ptkInputTokens: 50,
      ptkOutputTokens: 75
    },
    {
      versionId: 'version-2-id',
      versionNumber: 2,
      input: { /* input template */ },
      output: 'Generated prompt text for v2...',
      createdAt: 1234567890,
      updatedAt: 1234567890,
      createdBy: 'user-id',
      source: 'ui',
      label: 'First iteration',
      parentVersionId: 'version-1-id',
      inputTokens: [...],
      outputTokens: [...],
      ptkInputTokens: 45,
      ptkOutputTokens: 70
    },
    {
      versionId: 'version-1-id',
      versionNumber: 1,
      input: { /* input template */ },
      output: 'Generated prompt text for v1...',
      createdAt: 1234567880,
      updatedAt: 1234567880,
      createdBy: 'user-id',
      source: 'ui',
      parentVersionId: null,
      inputTokens: [...],
      outputTokens: [...],
      ptkInputTokens: 40,
      ptkOutputTokens: 65
    }
  ]
}

Route

The listPromptVersions function makes a request to the following endpoint:

GET /v1/prompts/:promptId/version/list

Request Parameters

Parameter	Type	Required	Description
`promptId`	string	Yes	The ID of the prompt (path parameter)

Headers

Header	Value
`Content-Type`	`application/json`
`Authorization`	`Bearer your-api-key`
`x-user-id`	`your-user-id`

Response

On success (200 OK):

{
  "success": true,
  "message": "Prompt versions retrieved successfully",
  "data": [
    {
      "versionId": "string",
      "versionNumber": 3,
      "input": { /* input template object */ },
      "output": "Generated prompt text",
      "createdAt": 1234567890,
      "updatedAt": 1234567890,
      "createdBy": "user-id",
      "source": "api",
      "label": "Version label",
      "parentVersionId": "parent-version-id",
      "inputTokens": ["array", "of", "tokens"],
      "inputTokenCount": 100,
      "outputTokens": ["array", "of", "tokens"],
      "outputTokenCount": 200,
      "ptkInputTokens": 50,
      "ptkOutputTokens": 75
    }
    // ... more versions
  ]
}

On error, you may receive:

{
  "success": false,
  "message": "User ID is required"
}

{
  "success": false,
  "message": "Prompt ID is required"
}

{
  "success": false,
  "message": "Failed to retrieve prompt versions",
  "error": "...error message..."
}

Version Ordering

Versions are returned in descending order by version number (newest first):

Version 3 (latest)
Version 2
Version 1 (original)

This makes it easy to see the most recent changes first.

Version Fields Explained

Core Fields

versionId: Unique identifier for this version
versionNumber: Sequential number (1, 2, 3, etc.)
input: The prompt input template used to generate this version
output: The generated prompt text

Metadata Fields

createdAt: Timestamp when version was created
updatedAt: Timestamp when version was last updated
createdBy: User ID who created the version
source: Where the version was created (‘ui’, ‘api’, ‘tool-tab’)
label: Optional descriptive label for the version
parentVersionId: ID of the parent version (null for version 1)

Token Usage Fields

inputTokens: Array of input tokens
inputTokenCount: Number of input tokens
outputTokens: Array of output tokens
outputTokenCount: Number of output tokens
ptkInputTokens: PromptTK system input tokens
ptkOutputTokens: PromptTK system output tokens

Use Cases

View Version History

const response = await promptTK.listPromptVersions(promptId);
console.log("Version History:");
response.data.forEach(v => {
  console.log(`v${v.versionNumber}: ${v.label} (${new Date(v.createdAt).toLocaleDateString()})`);
});

Find Active Version

const prompt = await promptTK.fetchPromptById(promptId);
const versions = await promptTK.listPromptVersions(promptId);
const activeVersion = versions.data.find(v => v.versionId === prompt.data.activeVersionId);
console.log("Active version:", activeVersion.versionNumber);

Compare Versions

const versions = await promptTK.listPromptVersions(promptId);
const v1 = versions.data.find(v => v.versionNumber === 1);
const v2 = versions.data.find(v => v.versionNumber === 2);
console.log("Input differences:", {
  v1: v1.input.mainPrompt,
  v2: v2.input.mainPrompt
});

Track Version Lineage

const versions = await promptTK.listPromptVersions(promptId);
function buildVersionTree(versions, parentId = null, indent = 0) {
  versions
    .filter(v => v.parentVersionId === parentId)
    .forEach(v => {
      console.log(`${'  '.repeat(indent)}├─ v${v.versionNumber}: ${v.label || 'No label'}`);
      buildVersionTree(versions, v.versionId, indent + 1);
    });
}
buildVersionTree(versions.data);

Calculate Total Token Usage

const versions = await promptTK.listPromptVersions(promptId);
const totalTokens = versions.data.reduce((sum, v) => {
  return sum + (v.ptkInputTokens || 0) + (v.ptkOutputTokens || 0);
}, 0);
console.log(`Total tokens used across all versions: ${totalTokens}`);

Important Notes

📋 Read-Only: This endpoint only retrieves versions, it doesn’t modify them
🔢 Descending Order: Versions are returned newest first (v3, v2, v1)
🌳 Parent Tracking: Use parentVersionId to understand version relationships
📊 Complete Data: Each version includes full input template and generated output
🎯 Active Version: The active version is determined by the parent prompt, not this list

Best Practices

Cache Results: Version lists don’t change often, consider caching
Filter by Source: Use source field to filter by creation method
Display Labels: Show label in UI to help users identify versions
Show Dates: Use createdAt to show when versions were created
Indicate Active: Highlight which version is currently active

Create Prompt Version - Create a new version
Activate Version - Set a version as active
Update Version - Modify version metadata
Delete Version - Remove a version
Get Prompt by ID - Get prompt details including active version

Example: Version Management Dashboard

import { PromptTK } from "@devvle/ptk-api-sdk";

const promptTK = new PromptTK({
  userId: "your-user-id",
  apiKey: "your-api-key",
});

async function displayVersionDashboard(promptId) {
  // Get prompt and versions
  const [promptResponse, versionsResponse] = await Promise.all([
    promptTK.fetchPromptById(promptId),
    promptTK.listPromptVersions(promptId)
  ]);

  const prompt = promptResponse.data;
  const versions = versionsResponse.data;

  console.log(`\n📝 Prompt: ${prompt.promptName}`);
  console.log(`📊 Total Versions: ${versions.length}`);
  console.log(`🎯 Active Version: ${versions.find(v => v.versionId === prompt.activeVersionId)?.versionNumber || 'N/A'}`);
  console.log(`📅 Last Updated: ${new Date(prompt.updatedAt).toLocaleString()}\n`);

  console.log("Version History:");
  versions.forEach(version => {
    const isActive = version.versionId === prompt.activeVersionId ? " 🎯" : "";
    const label = version.label ? ` - ${version.label}` : "";
    console.log(`  v${version.versionNumber}${isActive}${label}`);
    console.log(`    Created: ${new Date(version.createdAt).toLocaleDateString()}`);
    console.log(`    Source: ${version.source}`);
    console.log(`    Tokens: ${(version.ptkInputTokens || 0) + (version.ptkOutputTokens || 0)}`);
    console.log("");
  });
}

displayVersionDashboard("your-prompt-id");