> ## 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 testing in the playground.

<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-5-mini`, `opus-4.8`).
  * 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 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-5',
      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-5",
          "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-5`, `claude-opus-4-8`)
* **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-5',
      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-5",
          "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>