Skip to content
PromptTK Api Docs

Activate Prompt Version

The activatePromptVersion endpoint allows you to set a specific version as the active version of a prompt. The active version is what gets used in production and determines the current prompt output.

Usage

Section titled “Usage”
import { PromptTK } from "@devvle/ptk-api-sdk";


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


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


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


activateVersion();

Expected Output:

{
  success: true,
  message: 'Prompt version activated successfully',
  data: {
    recordId: 'prompt-id',
    promptName: 'My Prompt',
    projectId: 'project-id',
    ownerId: 'user-id',
    createdAt: 1234567880,
    updatedAt: 1234567900,
    activeVersionId: 'version-id-to-activate',
    latestVersionNumber: 3
  }
}

Route

Section titled “Route”

The activatePromptVersion function makes a request to the following endpoint:

POST /v1/prompts/:promptId/version/activate

Request Parameters

Section titled “Request Parameters”
ParameterTypeRequiredDescription
promptIdstringYesThe ID of the prompt (path parameter)
versionIdstringYesThe ID of the version to activate

Request Body

Section titled “Request Body”
{
  "versionId": "string" // required
}

Headers

Section titled “Headers”
HeaderValue
Content-Typeapplication/json
AuthorizationBearer your-api-key
x-user-idyour-user-id

Response

Section titled “Response”

On success (200 OK):

{
  "success": true,
  "message": "Prompt version activated successfully",
  "data": {
    "recordId": "prompt-id",
    "promptName": "My Prompt",
    "projectId": "project-id",
    "ownerId": "user-id",
    "createdAt": 1234567880,
    "updatedAt": 1234567900,
    "activeVersionId": "version-id",
    "latestVersionNumber": 3
  }
}

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": "Failed to activate prompt version",
  "error": "...error message..."
}

What Activation Does

Section titled “What Activation Does”

When you activate a version:

  1. Sets Active Version: Updates the prompt’s activeVersionId field
  2. Updates Timestamp: Sets the prompt’s updatedAt to current time
  3. Production Use: The active version is what applications use
  4. Rollback: Can activate previous versions to rollback changes

Use Cases

Section titled “Use Cases”

Switch to Latest Version

Section titled “Switch to Latest Version”
const versions = await promptTK.listPromptVersions(promptId);
const latestVersion = versions.data[0]; // Versions are in descending order
await promptTK.activatePromptVersion(promptId, latestVersion.versionId);
console.log("Switched to latest version");

Rollback to Previous Version

Section titled “Rollback to Previous Version”
const versions = await promptTK.listPromptVersions(promptId);
const previousVersion = versions.data[1]; // Second newest
await promptTK.activatePromptVersion(promptId, previousVersion.versionId);
console.log("Rolled back to previous version");

A/B Testing Workflow

Section titled “A/B Testing Workflow”
// Create two test versions
const versionA = await promptTK.createPromptVersion(promptId, inputA, "api", "Version A");
const versionB = await promptTK.createPromptVersion(promptId, inputB, "api", "Version B");


// Test version A
await promptTK.activatePromptVersion(promptId, versionA.data.versionId);
// ... run tests with version A


// Switch to version B
await promptTK.activatePromptVersion(promptId, versionB.data.versionId);
// ... run tests with version B


// Activate the winner
await promptTK.activatePromptVersion(promptId, winningVersionId);

Safe Deployment

Section titled “Safe Deployment”
// Activate new version
const newVersionId = "new-version-id";
const oldVersionId = prompt.activeVersionId; // Save current active


try {
  await promptTK.activatePromptVersion(promptId, newVersionId);
  console.log("New version activated");


  // Monitor for issues...
  // If problems detected, rollback:
  // await promptTK.activatePromptVersion(promptId, oldVersionId);
} catch (error) {
  console.error("Activation failed, staying on current version");
}

Important Notes

Section titled “Important Notes”
  • 🎯 One Active Version: Only one version can be active at a time
  • 🔄 Instant Switch: Activation happens immediately
  • 📝 No Data Loss: Previous active version remains available
  • 🔙 Easy Rollback: Can activate any previous version anytime
  • 🚀 Production Ready: Active version is used by all systems

Best Practices

Section titled “Best Practices”
  1. Test Before Activating: Review version output before making it active
  2. Document Changes: Use version labels to track what each version does
  3. Save Current Active: Store current activeVersionId before switching
  4. Monitor After Activation: Watch for issues after activating new versions
  5. Use Version Labels: Identify versions by meaningful labels, not just numbers

Workflow Example

Section titled “Workflow Example”

Complete workflow for creating and activating a new version:

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


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


async function deployNewVersion(promptId, newInput) {
  // 1. Get current state
  const prompt = await promptTK.fetchPromptById(promptId);
  const currentActiveId = prompt.data.activeVersionId;


  console.log(`Current active version: ${currentActiveId}`);


  // 2. Create new version
  const newVersion = await promptTK.createPromptVersion(
    promptId,
    newInput,
    "api",
    "Production v2.0"
  );


  console.log(`New version created: ${newVersion.data.versionId}`);


  // 3. Review the new version
  const versions = await promptTK.listPromptVersions(promptId);
  const createdVersion = versions.data.find(v => v.versionId === newVersion.data.versionId);


  console.log("New version output preview:", createdVersion.output.substring(0, 100));


  // 4. Activate the new version
  await promptTK.activatePromptVersion(promptId, newVersion.data.versionId);


  console.log("✅ New version is now active!");
  console.log(`Previous version ${currentActiveId} is still available for rollback`);


  return {
    newVersionId: newVersion.data.versionId,
    previousVersionId: currentActiveId
  };
}
Section titled “Related Endpoints”