Prompts

Create, manage, and execute AI prompts with the SDK

The Prompts resource provides methods for managing AI prompts, creating versions, and executing prompts with your data.

List Prompts

Retrieve a list of all your prompts.

const prompts = await client.prompts.list({
  mine: true,  // Only show your prompts
  limit: 100   // Maximum number of results
})

prompts.forEach(prompt => {
  console.log(`${prompt.name} (${prompt.id})`)
  console.log(`  Versions: ${prompt.versions.length}`)
  console.log(`  Tags: ${prompt.tags.join(', ')}`)
})

Get a Prompt

Retrieve detailed information about a specific prompt, including all versions.

const prompt = await client.prompts.get('prompt-id')

console.log(prompt.name)
console.log(prompt.description)

// View all versions
prompt.versions.forEach(version => {
  console.log(`Version ${version.version}:`)
  console.log(`  Model: ${version.provider}/${version.model}`)
  console.log(`  Template: ${version.template}`)
})

Create a Prompt

Create a new prompt with template, input schema, and model configuration.

const prompt = await client.prompts.create({
  name: 'blog-post-generator',
  description: 'Generates engaging blog posts',
  template: `Write a {{tone}} blog post about {{topic}} for {{audience}}.

Length: {{length}} words
Include: {{keywords}}`,

  // Define input validation schema
  inputSchema: {
    type: 'object',
    properties: {
      topic: {
        type: 'string',
        description: 'Blog post topic'
      },
      audience: {
        type: 'string',
        description: 'Target audience'
      },
      tone: {
        type: 'string',
        enum: ['professional', 'casual', 'technical'],
        default: 'professional'
      },
      length: {
        type: 'number',
        minimum: 500,
        maximum: 2000,
        default: 1000
      },
      keywords: {
        type: 'string',
        description: 'Comma-separated keywords'
      }
    },
    required: ['topic', 'audience']
  },

  // Model configuration
  provider: 'anthropic',
  model: 'claude-sonnet-4-5',
  temperature: 0.7,
  maxTokens: 2000,

  // Metadata
  tags: ['content', 'marketing', 'blog'],
  isPublic: false
})

console.log(`Created prompt: ${prompt.id}`)

The inputSchema uses JSON Schema format. It validates inputs before execution and provides documentation for API consumers.

Execute a Prompt

Execute a prompt with input variables and get the AI-generated output.

const result = await client.prompts.execute('prompt-id', {
  topic: 'The Future of AI',
  audience: 'Business Leaders',
  tone: 'professional',
  length: 1500,
  keywords: 'innovation, automation, ethics'
})

console.log('Generated Content:')
console.log(result.output)
console.log()
console.log('Metrics:')
console.log(`  Latency: ${result.latencyMs}ms`)
console.log(`  Cost: $${result.costUsd}`)
console.log(`  Tokens: ${result.tokenIn} in → ${result.tokenOut} out`)

Execute Specific Version

By default, the latest version is executed. You can specify a version number:

const result = await client.prompts.execute(
  'prompt-id',
  { topic: 'AI Ethics' },
  { version: 2 }  // Execute version 2 specifically
)

Create New Version

Create a new version of an existing prompt to iterate on your templates and configurations.

const version = await client.prompts.createVersion('prompt-id', {
  template: 'Improved template with better instructions...',
  temperature: 0.8,  // Increase creativity
  maxTokens: 3000,   // Allow longer outputs

  // Update input schema if needed
  inputSchema: {
    // ... updated schema
  }
})

console.log(`Created version ${version.version}`)

Versions are immutable. Create new versions to iterate while keeping previous versions available for rollback.

Update Prompt Metadata

Update a prompt's name, description, tags, and visibility.

const updated = await client.prompts.update('prompt-id', {
  name: 'updated-name',
  description: 'New description',
  tags: ['updated', 'tags', 'here'],
  isPublic: true  // Make publicly accessible
})

Delete a Prompt

Permanently delete a prompt and all its versions.

await client.prompts.delete('prompt-id')
console.log('Prompt deleted')

This action cannot be undone. All versions and execution history will be preserved but the prompt cannot be executed anymore.

Complete Example

import Prompt Forge from '@promptforge/sdk'

const client = new Prompt Forge({
  apiKey: process.env.PROMPTFORGE_API_KEY
})

async function generateBlogPost() {
  // Create a prompt
  const prompt = await client.prompts.create({
    name: 'technical-blog-generator',
    template: 'Write a technical blog post about {{topic}}',
    inputSchema: {
      type: 'object',
      properties: {
        topic: { type: 'string' }
      },
      required: ['topic']
    },
    provider: 'anthropic',
    model: 'claude-sonnet-4-5',
    temperature: 0.7,
    maxTokens: 2000
  })

  // Execute it
  const result = await client.prompts.execute(prompt.id, {
    topic: 'Microservices Architecture'
  })

  console.log(result.output)

  // Create an improved version
  await client.prompts.createVersion(prompt.id, {
    template: 'Write a detailed technical blog post about {{topic}} with code examples',
    temperature: 0.8
  })

  // Execute the new version (latest)
  const improved = await client.prompts.execute(prompt.id, {
    topic: 'Microservices Architecture'
  })

  console.log(improved.output)
}

generateBlogPost()

Next Steps

→ Learn about Chains for multi-step workflows → See error handling best practices