Create Prompt Version

The createPromptVersion endpoint allows you to create a new version of an existing prompt. This generates a new AI-powered prompt based on the input template and links it to the parent prompt with version tracking.

Usage

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

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

const versionInput = {
  mainPrompt: "Write a story about a {animal} in the {location}.",
  outputType: "plain text",
  responseFormat: "plain text",
  promptGoal: "Create an engaging narrative",
  // ... other optional fields
};

async function createVersion() {
  const promptId = "your-prompt-id";
  const source = "api"; // optional: 'api', 'ui', 'tool-tab'
  const label = "Version with new parameters"; // optional: descriptive label
  const parentVersionId = "parent-version-id"; // optional: defaults to active version

  try {
    const response = await promptTK.createPromptVersion(
      promptId,
      versionInput,
      source,
      label,
      parentVersionId
    );
    console.log("Version created:", response);
  } catch (error) {
    console.error("Error creating version:", error);
  }
}

createVersion();

Expected Output:

{
  success: true,
  message: 'Prompt version created successfully',
  data: {
    versionId: 'new-version-id',
    versionNumber: 2,
    input: { /* input template */ },
    output: 'Generated prompt text...',
    createdAt: 1234567890,
    updatedAt: 1234567890,
    createdBy: 'user-id',
    source: 'api',
    label: 'Version with new parameters',
    parentVersionId: 'parent-version-id'
  }
}

Route

The createPromptVersion function makes a request to the following endpoint:

POST /v1/prompts/:promptId/version/new

Request Parameters

Parameter	Type	Required	Description
promptId	string	Yes	The ID of the prompt (path parameter)
input	object	Yes	The prompt input template
source	string	No	Source of creation: ‘api’, ‘ui’, ‘tool-tab’
label	string	No	Descriptive label for the version
parentVersionId	string	No	Parent version ID (defaults to active version)

Request Body

{
  "input": {
    "mainPrompt": "string", // required
    "endUserDescription": "string", // optional
    "promptSenderDescription": "string", // optional
    "relationship": "string", // optional
    "mustHaves": "string", // optional
    "contextRequirements": "string", // optional
    "lengthRequirements": "string", // optional
    "avoidElements": "string", // optional
    "styleAndTone": ["string"], // optional
    "examplePrompts": "string", // optional
    "outputType": "string", // optional
    "responseFormat": "string", // optional
    "promptGoal": "string", // optional
    "hallucinationControl": "string" // optional
  },
  "source": "string", // optional
  "label": "string", // optional
  "parentVersionId": "string" // optional
}

See the Prompt Input documentation for detailed information about input fields.

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 created successfully",
  "data": {
    "versionId": "string",
    "versionNumber": 2,
    "input": { /* input template */ },
    "output": "Generated prompt text",
    "createdAt": 1234567890,
    "updatedAt": 1234567890,
    "createdBy": "user-id",
    "source": "api",
    "label": "Version label",
    "parentVersionId": "parent-version-id",
    "inputTokens": 100,
    "outputTokens": 200,
    "ptkInputTokens": 50,
    "ptkOutputTokens": 75
  }
}

On error, you may receive:

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

or

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

or

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

Version Management

Version Numbers

• Each prompt starts with version 1
• New versions increment automatically (1, 2, 3, etc.)
• Version numbers are unique within a prompt

Parent-Child Relationships

• Each version (except version 1) has a parent version
• If parentVersionId is not specified, the current active version becomes the parent
• This creates a version tree showing the evolution of your prompt

Active Version

• Creating a new version does NOT automatically activate it
• The previously active version remains active
• Use Activate Version to switch to the new version

Use Cases

• Iterative Improvement: Test different variations of your prompt
• A/B Testing: Compare performance of different prompt formulations
• Parameter Tuning: Adjust tone, length, or style requirements
• Experimentation: Try different approaches without losing previous versions
• Rollback Capability: Keep working versions while testing improvements

Important Notes

• 🤖 AI Generation: This endpoint uses AI to generate the prompt output based on your input template
• 💰 Token Usage: Tokens are consumed for AI generation (tracked in response)
• 🔗 Versioning: Creates a new version linked to the parent prompt
• 📊 Tracking: Usage data is recorded for analytics
• 🎯 Active Version: The active version is what gets used in production; new versions must be activated manually

Best Practices

1. Use Descriptive Labels: Help identify versions later with clear, descriptive labels
2. Track Parent Versions: Maintain the version tree for better organization
3. Test Before Activating: Create and review versions before making them active
4. Document Changes: Use labels to note what changed between versions
5. Monitor Token Usage: Keep track of token consumption for budgeting

Example: Creating Multiple Test Versions

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

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

const promptId = "your-prompt-id";

// Test version 1: More formal tone
const formalVersion = await promptTK.createPromptVersion(
  promptId,
  {
    mainPrompt: "Compose a professional email about {topic}.",
    styleAndTone: ["formal", "professional"],
    lengthRequirements: "2-3 paragraphs"
  },
  "api",
  "Formal tone test"
);

// Test version 2: More casual tone
const casualVersion = await promptTK.createPromptVersion(
  promptId,
  {
    mainPrompt: "Write a friendly message about {topic}.",
    styleAndTone: ["casual", "friendly"],
    lengthRequirements: "2-3 paragraphs"
  },
  "api",
  "Casual tone test",
  formalVersion.data.versionId // Make formal version the parent
);

console.log("Created test versions for A/B testing");

Related Endpoints

• List Prompt Versions - View all versions of a prompt
• Activate Version - Set a version as active
• Update Version - Modify version metadata
• Delete Version - Remove a version
• Generate Prompt - Create a new prompt (version 1)