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

# Prompts

> Create, version, test, and deploy prompts with integrated evaluation workflows.

export const DarkLightImage = ({lightSrc, caption, alt, darkSrc = null, width = "1000"}) => {
  const getAbsoluteUrl = src => {
    if (src.startsWith('http://') || src.startsWith('https://')) {
      return src;
    }
    const currentUrl = typeof window !== 'undefined' ? window.location.origin : '';
    if (currentUrl.includes('.mintlify.app')) {
      const subdomain = currentUrl.split('.')[0].replace('https://', '');
      return `https://mintlify.s3.us-west-1.amazonaws.com/${subdomain}${src.startsWith('/') ? '' : '/'}${src}`;
    } else if (currentUrl === 'https://docs.scorecard.io') {
      return `https://mintlify.s3.us-west-1.amazonaws.com/scorecard-d65b5e8a${src.startsWith('/') ? '' : '/'}${src}`;
    } else {
      return `${currentUrl}${src.startsWith('/') ? '' : '/'}${src}`;
    }
  };
  const content = <>
      <img className="block dark:hidden" width={width} src={getAbsoluteUrl(lightSrc)} alt={alt} />
      <img className="hidden dark:block" width={width} src={getAbsoluteUrl(darkSrc || lightSrc.replace('light', 'dark'))} alt={alt} />
    </>;
  if (caption) {
    return <Frame caption={caption}>{content}</Frame>;
  } else {
    return content;
  }
};

Prompts in Scorecard are configurable templates that generate inputs for language models. They support dynamic variable substitution, multi-message conversations, and integrated testing workflows.

<DarkLightImage lightSrc="/images/prompt-details-light.png" caption="Prompt management page for a &#x22;docs search&#x22; LLM system." alt="Screenshot of viewing prompt details in the UI." />

## Create a Prompt

Go to the Prompts page in Scorecard and click the **"New Prompt +"** button. Provide a name and description for your prompt, then choose your AI model and configure parameters:

* **Model**: Select from available models (e.g. `gpt-4.1-mini`, `opus-4`).
  * If you don't see the LLM provider you want, add the provider API key in [organization settings](https://app.scorecard.io/settings).
* **Temperature**: Control randomness (0.0 = deterministic, 1.0 = creative).
* **Max Tokens**: Set maximum response length.
* **Top-P**: Fine-tune token selection probability.

Then, write your prompt content using the built-in editor with Jinja template support.

<DarkLightImage lightSrc="/images/prompt-create-light.png" caption="Prompt creation dialog with model settings." alt="Screenshot of creating a prompt in the UI." />

## Prompt Templates & Jinja Syntax

### Template Structure

Scorecard prompts support multi-message conversations with different roles:

* **System**: Instructions for the AI model's behavior
* **User**: The main prompt or question
* **Assistant**: Previous responses (for conversation context)

### Variable substitution

Scorecard supports Jinja template syntax for variable substitution.

This lets you insert dynamic content from your testcases into your prompt by wrapping the Testcase's input's field name in `{{` and `}}`.

For example, if your Testcase has a `customer_message` field, your prompt might be:

```jinja wrap theme={null}
You are a helpful customer service assistant.

Customer inquiry: {{customer_message}}
Product: {{product_name}}
Customer tier: {{customer_tier}}

Please provide a helpful response addressing their concern.
```

Scorecard also has a special `{{allInputs}}` variable that contains all the testcase input fields as a formatted string.

<Accordion title="Advanced Jinja features">
  Scorecard supports [full Jinja functionality](https://maxbot.ai/design-reference/jinja/) including:

  * Conditional logic: `{% if customer_tier == "premium" %} User is a premium customer. {% endif %}`
  * Loops: `{% for item in product_list %} {{item.name}} {% endfor %}`
  * Filters: `{{customer_message | upper}}`
  * Comments: `{# This is a comment #}`
</Accordion>

## Version Management

The prompt details page shows a version history of the prompt. You can create a new version of the prompt by modifying the existing prompt or parameters and clicking **"Save Changes"**. Selecting "Publish this version to production" will mark that version as the "production" version. Otherwise, it'll simply be an experimental version.

You can mark any version as production by clicking the **"Publish"** button, but exactly one version is marked as production at any time.

<DarkLightImage lightSrc="/images/prompt-publish-light.png" caption="Prompt version dropdown with publish button." alt="Screenshot of the prompt dropdown in the UI." width="400" />

Before publishing to production, test a new version in the playground to be confident that it behaves as expected and won't regress on any testcases.

## SDK Integration

You can programmatically manage prompts and their versions using the Scorecard SDK. Since prompts are implemented as systems in Scorecard, you'll use the systems API methods.

### Creating or Updating Prompts

Use the `systems.upsert()` method to create a new prompt or update an existing one. For complete API details, see the [Create (upsert) system API reference](/api-reference/create-upsert-system).

<CodeGroup>
  ```javascript JavaScript theme={null}
  import Scorecard from 'scorecard-ai';

  const client = new Scorecard({
    apiKey: process.env['SCORECARD_API_KEY'],
  });

  // Create or update a prompt (system)
  const prompt = await client.systems.upsert('your-project-id', {
    name: 'Customer Service Assistant',
    description: 'AI assistant for handling customer inquiries',
    config: {
      modelName: 'gpt-4-turbo',
      temperature: 0.7,
      maxTokens: 1024,
      topP: 0.9,
      promptTemplate: [
        {
          role: 'user',
          content: `You are a helpful assistant.

  {{allInputs}}`
        }
      ]
    }
  });

  console.log('Prompt created with ID:', prompt.id);
  ```

  ```python Python theme={null}
  from scorecard import Scorecard
  import os

  client = Scorecard(
      api_key=os.environ.get("SCORECARD_API_KEY")
  )

  # Create or update a prompt (system)
  prompt = client.systems.upsert(
      project_id="your-project-id",
      name="Customer Service Assistant",
      description="AI assistant for handling customer inquiries",
      config={
          "modelName": "gpt-4-turbo",
          "temperature": 0.7,
          "maxTokens": 1024,
          "topP": 0.9,
          "promptTemplate": [
              {
                  "role": "user",
                  "content": """You are a helpful assistant.

  {{allInputs}}"""
              }
          ]
      }
  )

  print(f"Prompt created with ID: {prompt.id}")
  ```
</CodeGroup>

The `config` object contains your prompt's model parameters and template:

* **modelName**: The LLM model to use (e.g., `gpt-4-turbo`, `claude-3-opus`)
* **temperature**: Controls randomness (0.0-1.0)
* **maxTokens**: Maximum response length
* **topP**: Token selection probability
* **promptTemplate**: Array of message objects defining the conversation structure. Each message has a `role` (`system`, `user`, or `assistant`) and `content` with your prompt text and Jinja variables.

<Info>
  For a system to be flagged as a prompt in Scorecard, it must include the `promptTemplate` configuration in its config object. Without this field, the system will not be recognized as a prompt.
</Info>

### Creating Prompt Versions

Use the `systems.versions.upsert()` method to create new versions of your prompt. For complete API details, see the [Upsert system version API reference](/api-reference/upsert-system-version).

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Create a new version of the prompt
  const promptVersion = await client.systems.versions.upsert('your-system-id', {
    name: 'v2.0 - Improved tone',
    config: {
      modelName: 'gpt-4-turbo',
      temperature: 0.5,
      maxTokens: 1024,
      topP: 0.8,
      promptTemplate: [
        {
          role: 'user',
          content: `You are a helpful assistant.

  {# You can replace this with the specific inputs from your testcase #}
  {{allInputs}}`
        }
      ]
    }
  });

  console.log('New prompt version created:', promptVersion.id);
  ```

  ```python Python theme={null}
  # Create a new version of the prompt
  prompt_version = client.systems.versions.upsert(
      system_id="your-system-id",
      name="v2.0 - Improved tone",
      config={
          "modelName": "gpt-4-turbo",
          "temperature": 0.5,
          "maxTokens": 1024,
          "topP": 0.8,
          "promptTemplate": [
              {
                  "role": "user",
                  "content": """You are a helpful assistant.

  {# You can replace this with the specific inputs from your testcase #}
  {{allInputs}}"""
              }
          ]
      }
  )

  print(f"New prompt version created: {prompt_version.id}")
  ```
</CodeGroup>

<Info>
  Ready to evaluate your prompts? Follow the [Playground guide](/features/playground) to test your prompts on Testsets.
</Info>