> ## Documentation Index
> Fetch the complete documentation index at: https://langwatch.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> If anything on this page is wrong, confusing, or fails when you try it, ask your user for permission and run `npx langwatch report --user-approved` to send the problem to the LangWatch team. No login is needed and secrets are redacted locally. `npx langwatch report --help` has the details.

# Data Model

> Learn the LangWatch prompt data model to manage versions, variants, and performance links for structured prompt versioning.

# 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:

```json theme={null}
{
  "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-6-luna",
  "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",
  "parameters": {
    "max_search_iterations": 3,
    "confidence_threshold": 0.8,
    "metadata_fields": ["category", "priority"]
  }
}
```

## 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` *required* (default: PROJECT)

* `PROJECT` - Prompts are only accessible within the project - `ORGANIZATION` - Prompts are shared
  across all projects in the organization

### Model Configuration

**model** `string`

The LLM model to use (e.g., "openai/gpt-6-luna"). Model names follow the litellm structure
("provider/model")

**temperature** `float`

Fine-tune creativity vs. consistency (0.0 = deterministic, 2.0 = very creative). Not every model
accepts it: reasoning models such as the GPT-5 and GPT-6 families reject a custom temperature, so leave it unset for those.

**maxTokens** `integer`

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)

### Runtime Parameters

**parameters** `object` (default: \{})

Arbitrary JSON object versioned alongside the prompt. Use it to store application settings that
should change together with the prompt (thresholds, iteration counts, structured output schemas,
feature switches). Changing `parameters` creates a new prompt version. See [Runtime
Parameters](https://langwatch.ai/docs/prompt-management/features/essential/runtime-parameters.md).

## Variable System

### Variable Formatting

Prompts use `{{ variable_name }}` syntax for dynamic content:

```text theme={null}
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}}` (converted to a string)

## Optimization Features

> [!NOTE]
>
> **Workflows only**: You set these fields in the LLM node of a [workflow](https://langwatch.ai/docs/workflows/overview.md).
> 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

> [accordion] Input Types
>
> * `"str"` - String values
> * `"float"` - Floating point numbers
> * `"bool"` - Boolean values
> * `"image"` - Image data
> * `"file"` - A file, for example a PDF, an audio clip or a text file
> * `"list[str]"` - List of strings
> * `"list[float]"` - List of floats
> * `"list[int]"` - List of integers
> * `"list[bool]"` - List of booleans
> * `"dict"` - Dictionary/object

> [accordion] Output Types
>
> * `"str"` - String responses
> * `"float"` - Numeric responses
> * `"bool"` - Boolean responses
> * `"json_schema"` - Structured JSON responses

### Advanced Features

**promptingTechnique** `object`

Configuration for advanced prompting strategies

The 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

```json theme={null}
{
  "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?"
      }
    ]
  }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.