Delete Prompt Version

The deletePromptVersion endpoint allows you to permanently delete a specific version of a prompt. This is useful for cleaning up test versions or removing unwanted iterations.

Usage

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

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

async function deleteVersion() {
  const promptId = "your-prompt-id";
  const versionId = "version-id-to-delete";

  try {
    const response = await promptTK.deletePromptVersion(promptId, versionId);
    console.log("Version deleted:", response);
  } catch (error) {
    console.error("Error deleting version:", error);
  }
}

deleteVersion();

Expected Output:

{
  success: true,
  message: 'Prompt version deleted successfully'
}

Route

The deletePromptVersion function makes a request to the following endpoint:

DELETE /v1/prompts/:promptId/version/delete

Request Parameters

Parameter	Type	Required	Description
promptId	string	Yes	The ID of the prompt (path parameter)
versionId	string	Yes	The ID of the version to delete

Request Body

{
  "versionId": "string" // required
}

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 version deleted successfully"
}

On error, you may receive:

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

or

{
  "success": false,
  "message": "Prompt ID and Version ID are required"
}

or

{
  "success": false,
  "message": "Version not found or could not be deleted"
}

or

{
  "success": false,
  "message": "Failed to delete prompt version",
  "error": "...error message..."
}

Important Notes

⚠️ WARNING: This action is permanent and cannot be undone!

Deletion Rules

• ❌ Cannot Delete Version 1: The initial version cannot be deleted
• ❌ Cannot Delete Active Version: Must activate different version first
• ✅ Can Delete Non-Active Versions: Any inactive version can be deleted
• 🗑️ Permanent Deletion: Version data is permanently removed
• 🌳 Breaks Lineage: Child versions will no longer reference deleted parent

What Gets Deleted

• ✅ Version metadata (versionId, versionNumber, etc.)
• ✅ Input template for that version
• ✅ Generated output text
• ✅ Token usage data
• ✅ All version-specific information

What Remains

• ✅ The prompt record itself
• ✅ Other versions of the prompt
• ✅ Version lineage (with gaps where deleted version was)

Use Cases

Clean Up Test Versions

// Delete experimental versions
const versions = await promptTK.listPromptVersions(promptId);
const testVersions = versions.data.filter(v => v.label?.includes('TEST'));

for (const version of testVersions) {
  if (version.versionId !== prompt.activeVersionId) {
    await promptTK.deletePromptVersion(promptId, version.versionId);
    console.log(`Deleted test version ${version.versionNumber}`);
  }
}

Remove Failed Iterations

// Delete a version that didn't work out
const failedVersionId = "version-id-to-remove";
await promptTK.deletePromptVersion(promptId, failedVersionId);
console.log("Failed version removed");

Version Cleanup Before Deletion

// Clean up all versions before deleting prompt
const versions = await promptTK.listPromptVersions(promptId);

// Keep only version 1, delete all others
for (const version of versions.data) {
  if (version.versionNumber !== 1) {
    await promptTK.deletePromptVersion(promptId, version.versionId);
  }
}

Safety Workflow

Always check before deleting:

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

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

async function safeDeleteVersion(promptId, versionId) {
  // 1. Get prompt info
  const prompt = await promptTK.fetchPromptById(promptId);

  // 2. Check if it's the active version
  if (prompt.data.activeVersionId === versionId) {
    throw new Error("Cannot delete active version. Activate a different version first.");
  }

  // 3. Get version details
  const versions = await promptTK.listPromptVersions(promptId);
  const versionToDelete = versions.data.find(v => v.versionId === versionId);

  if (!versionToDelete) {
    throw new Error("Version not found");
  }

  // 4. Check if it's version 1
  if (versionToDelete.versionNumber === 1) {
    throw new Error("Cannot delete version 1");
  }

  // 5. Confirm deletion
  console.log(`About to delete version ${versionToDelete.versionNumber}`);
  console.log(`Label: ${versionToDelete.label || 'No label'}`);
  console.log(`Created: ${new Date(versionToDelete.createdAt).toLocaleString()}`);

  // In real app, show confirmation dialog here
  const confirmed = true; // Replace with actual confirmation

  if (confirmed) {
    await promptTK.deletePromptVersion(promptId, versionId);
    console.log("✅ Version deleted successfully");
  } else {
    console.log("Deletion cancelled");
  }
}

Deletion Constraints

Cannot Delete If:

1. Version 1: The initial version must always exist
2. Currently Active: The active version cannot be deleted
3. Does Not Exist: Version must exist to be deleted
4. Not Owner: User must own the prompt

Must Do Before Deleting Active Version:

1. Activate a different version first
2. Then delete the now-inactive version

// Example: Delete current active version
const prompt = await promptTK.fetchPromptById(promptId);
const versionToDelete = prompt.data.activeVersionId;

// Activate version 1
await promptTK.activatePromptVersion(promptId, version1Id);

// Now can delete the previous active version
await promptTK.deletePromptVersion(promptId, versionToDelete);

Handling Version Lineage

When you delete a version that has children:

Before deletion:
Version 1 → Version 2 → Version 3 → Version 4

After deleting Version 2:
Version 1 → [deleted] → Version 3 → Version 4

• Version 3 will still have parentVersionId pointing to the deleted version
• The lineage reference remains but the parent no longer exists
• This creates a gap in the version tree

Best Practices

1. Don’t Delete Production Versions: Keep versions that were used in production
2. Clean Up Regularly: Remove test/experimental versions periodically
3. Confirm Before Deleting: Always double-check before deletion
4. Check Active Status: Ensure version isn’t active before deleting
5. Document Deletion: Log why versions were deleted for audit trail
6. Keep Version 1: Never delete the original version
7. Backup Important Versions: Export data before deletion if needed

Bulk Deletion Example

async function cleanupOldVersions(promptId, keepCount = 5) {
  const versions = await promptTK.listPromptVersions(promptId);
  const prompt = await promptTK.fetchPromptById(promptId);

  // Keep active version and specified number of recent versions
  const versionsToKeep = new Set([
    prompt.data.activeVersionId,
    ...versions.data.slice(0, keepCount).map(v => v.versionId)
  ]);

  // Delete old versions
  let deletedCount = 0;
  for (const version of versions.data) {
    if (!versionsToKeep.has(version.versionId) && version.versionNumber !== 1) {
      await promptTK.deletePromptVersion(promptId, version.versionId);
      deletedCount++;
      console.log(`Deleted version ${version.versionNumber}`);
    }
  }

  console.log(`✅ Cleanup complete. Deleted ${deletedCount} old versions.`);
  console.log(`Kept ${versionsToKeep.size} versions including active version.`);
}

Error Handling

async function deleteWithErrorHandling(promptId, versionId) {
  try {
    await promptTK.deletePromptVersion(promptId, versionId);
    console.log("✅ Version deleted");
  } catch (error) {
    if (error.message.includes('Version not found')) {
      console.error("❌ Version doesn't exist");
    } else if (error.message.includes('could not be deleted')) {
      console.error("❌ Cannot delete this version (might be active or version 1)");
    } else {
      console.error("❌ Unexpected error:", error.message);
    }
  }
}

Related Endpoints

• List Prompt Versions - View all versions before deleting
• Activate Version - Activate different version before deleting active
• Get Prompt by ID - Check current active version
• Delete Prompt - Delete entire prompt (all versions)