​
Prompt Data Model

This page explains the structure of prompts in LangWatch and how they’re organized.

​
Overview

Prompts in LangWatch contain all the information needed to generate AI responses, including the prompt text, model configuration, and optimization settings.

​
Complete Prompt Structure

When you retrieve a prompt, you get all the configuration in a single response: 
{
  "id": "prompt_TrYXZLsiTJkn9N6PiZiae",
  "handle": "customer-support-bot",
  "scope": "PROJECT",
  "projectId": "proj_123",
  "organizationId": null,
  "version": 1,
  "versionId": "version_abc123",
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z",
  "authorId": "user_789",
  "deletedAt": null,
  
  "prompt": "You are a helpful customer support agent...",
  "model": "openai/gpt-4o-mini",
  "temperature": 0.7,
  "maxTokens": 1000,
  "messages": [
    { "role": "system", "content": "You are a helpful customer support agent..." },
    { "role": "user", "content": "I need help with my account" }
  ],
  "inputs": [
    { "name": "user_name", "type": "string" },
    { "name": "user_email", "type": "string" }
  ],
  "outputs": [
    { "name": "user_name", "type": "string" },
    { "name": "user_email", "type": "string" }
  ],
  "demonstrations": {
    "columns": [
      { "id": "input", "name": "User Input", "type": "string" },
      { "id": "output", "name": "Expected Output", "type": "string" }
    ],
    "rows": [
      { "id": "example_1", "input": "I need help with my account", "output": "I'd be happy to help you with your account. What specific issue are you experiencing?" }
    ]
  },
  "promptingTechnique": "chain_of_thought"
}

​
Field Descriptions

​
Core Fields

​
id
string
required
Unique identifier for the prompt
​
handle
string
required
Human-readable identifier for the prompt (primary way to reference prompts)
​
projectId
string
required
The project that owns the prompt
​
organizationId
string | null
The organization that owns the prompt
​
version
integer
required
Current version number
​
versionId
string
required
Unique identifier for this version
​
createdAt
timestamp
required
When this version was created
​
updatedAt
timestamp
required
When the prompt was last updated
​
authorId
string
required
The user who created this version
​
deletedAt
timestamp | null
Soft delete timestamp (null if not deleted)

​
Scope and Access

​
scope
string
default:"PROJECT"
required
  • PROJECT - Prompts are only accessible within the project
  • ORGANIZATION - Prompts are shared across all projects in the organization

​
Model Configuration

​
model
string
required
The LLM model to use (e.g., “openai/gpt-4o-mini”). Model names follow the litellm structure (“provider/model”)
​
temperature
float
required
Fine-tune creativity vs. consistency (0.0 = deterministic, 2.0 = very creative)
​
maxTokens
integer
required
Control response length and costs

​
Content Fields

​
prompt
string
required
The main prompt text (system message)
​
messages
array
Array of chat messages with roles and content (alternative to prompt field)

​
Variable System

​
Variable Formatting

Prompts use {{ variable_name }} syntax for dynamic content: 
You are a helpful customer support agent. The user is {{user_name}} and their email is {{user_email}}.

Please help them with: {{input}}

​
Supported Variable Types

  • Strings: {{user_name}}
  • Numbers: {{count}}
  • Booleans: {{is_premium}}
  • Lists: {{items}}
  • Objects: {{user_data}} (will be converted to string)

​
Optimization Features

Studio Only: These advanced optimization features require the optimization studio interface for proper experimentation, performance measurement, and A/B testing. They cannot be configured via the API.

​
Input/Output Definitions

​
inputs
array
Array of input variable definitions with identifiers and types
​
outputs
array
Array of output variable definitions with identifiers and types

​
Type System

​
Advanced Features

​
promptingTechnique
object
Configuration for advanced prompting strategiesThe prompting strategy to use.
  • "few_shot" - Few-shot learning with examples
  • "in_context" - In-context learning approach
  • "chain_of_thought" - Chain-of-thought reasoning
​
demonstrations
object
Few-shot examples with columns and rows structure

​
Demonstrations Structure

{
  "demonstrations": {
    "columns": [
      { "id": "input", "name": "User Input", "type": "string" },
      { "id": "output", "name": "Expected Output", "type": "string" }
    ],
    "rows": [
      {
        "id": "example_1",
        "input": "I need help with my account",
        "output": "I'd be happy to help you with your account. What specific issue are you experiencing?"
      }
    ]
  }
}