---
title: "Advanced configurations"
subtitle: "How a prompt call merges with your request, which version runs, streaming, and templates."
---

This page covers what happens when your code calls a saved prompt. To create, commit, and deploy a prompt, start with the [Quickstart](/docs/documentation/features/prompt-management/prompt-management-quickstart).

## Prompt schema

`schema_version` in the `prompt` object decides how the saved prompt merges with the rest of your request. Use v2 for new code.

| | v2 (recommended) | v1 (default) |
| --- | --- | --- |
| Turn it on | `"schema_version": 2` | Omit `schema_version`, or set `1` |
| Model, parameters, tools | The prompt wins | Your request wins, unless `override: true` |
| Messages | The prompt's messages come first, then yours | Yours replace the prompt's, unless `override: true` |
| Change settings per call | `patch` | `override_params` and `override_config` |

With v2, the `model` you send only fills the SDK's required field, and `messages` can be empty. Put per-call changes in `patch`:

```python
response = client.chat.completions.create(
    model="gpt-5.5",  # the prompt's saved model is used
    messages=[],
    extra_body={
        "prompt": {
            "prompt_id": "YOUR_PROMPT_ID",
            "schema_version": 2,
            "variables": {"ticket_body": "I was charged twice this month."},
            "patch": {"temperature": 0.9, "max_tokens": 500},
        }
    },
)
```

`patch` can't contain `messages` or `input`. The request fails with HTTP 400 if it does.

With the [Responses API](/docs/ai-gateway/requests/endpoints), pass the prompt in `respan_params.prompt` with `schema_version: 2`. The prompt's messages become `instructions`, and your `input` stays the user turn.

<Accordion title="v1 override options">

| Field | Effect |
| --- | --- |
| `override` | `true`: the prompt wins every conflict. `false` (default): your request wins. |
| `override_params` | Settings that replace the prompt's, for example `{"temperature": 0.8}`. Can include `messages`. |
| `override_config` | `{"messages_override_mode": "append"}` adds `override_params.messages` after the prompt's messages. `"override"` (default) replaces them. |

```python
extra_body={
    "prompt": {
        "prompt_id": "YOUR_PROMPT_ID",
        "override": True,
        "override_config": {"messages_override_mode": "append"},
        "override_params": {"messages": [{"role": "user", "content": "Keep it under 50 words."}]},
    }
}
```

</Accordion>

## Deployment & versioning

To choose the version a call runs, or to roll back in the editor, see [Choose which version a call uses](/docs/documentation/features/prompt-management/prompt-management-quickstart#choose-which-version-a-call-uses) and [Ship a new version](/docs/documentation/features/prompt-management/prompt-management-quickstart#ship-a-new-version).

To manage versions from code, use the Prompts API:

- [Create a prompt version](/docs/apis/prompts/create-prompt-version) saves a draft.
- [Commit a prompt version](/docs/apis/prompts/commit-prompt-version) turns the draft into a numbered version.
- [Deploy a prompt version](/docs/apis/prompts/deploy-prompt-version) makes a committed version live. Deploy an older number to roll back.
- [List prompt versions](/docs/apis/prompts/list-prompt-versions) shows every version.
- [Bulk operations](/docs/apis/prompts/update-commit-or-deploy-prompts-in-bulk) update, commit, or deploy several prompts in one request.

## Streaming

Which setting controls streaming depends on the prompt schema:

- **v2:** your request's `stream` decides. The prompt's **Stream** setting is ignored.
- **v1 with `override: true`:** the prompt's **Stream** setting (in **Model settings**) applies. If it's **True**, set `stream=True` in your call so your SDK reads the stream.

```python
stream = client.chat.completions.create(
    model="gpt-5.5",  # the prompt's saved model is used
    messages=[],
    stream=True,
    extra_body={"prompt": {"prompt_id": "YOUR_PROMPT_ID", "schema_version": 2}},
)
for chunk in stream:
    print(chunk.choices[0].delta.content or "", end="")
```

## Variables & Jinja templates

Add a variable to a message with `{{variable_name}}`. Names can't contain spaces. Respan renders messages as [Jinja2](https://jinja.palletsprojects.com/en/stable/templates/) templates, so you can also use conditions, loops, filters, and dot access on objects:

```jinja
{% if customer.plan == "Enterprise" %}Mention their dedicated support line.{% endif %}
Recent orders:
{% for order in customer.orders %}- {{ order.id }}: {{ order.status }}
{% endfor %}
```

In the editor's **Variables** tab, each variable has a type. From code, send each type like this:

| Type | Value in `variables` |
| --- | --- |
| **Text** | A string. |
| **Image** | `{"_type": "image_url", "value": "https://example.com/receipt.png"}` |
| **Object** | Any JSON object, for use with dot access and loops. |
| **Prompt** | A prompt object. See [Prompt composition](/docs/documentation/features/prompt-management/prompt-composition). |

## Prompt logging

If you call the model yourself and send logs with [Create span](/docs/apis/spans/create-span), add a `prompt` object so the span links to the prompt:

```json
{
  "model": "gpt-5.5",
  "prompt_messages": [{ "role": "user", "content": "I was charged twice this month." }],
  "completion_message": { "role": "assistant", "content": "Sorry about the double charge. I've refunded it." },
  "prompt": {
    "prompt_id": "YOUR_PROMPT_ID",
    "variables": { "ticket_body": "I was charged twice this month." }
  }
}
```

For a prompt you manage outside Respan, use your own ID and add `"is_custom_prompt": true` to the `prompt` object.

## Prompt object reference

The `prompt` object you send with a [chat completion](/docs/apis/gateway/create-chat-completion):

| Field | Type | Description |
| --- | --- | --- |
| `prompt_id` | string | Required. The prompt's ID, shown in the editor's side panel. |
| `variables` | object | Values for the prompt's variables. See [Variables & Jinja templates](#variables--jinja-templates). |
| `version` | integer or `"latest"` | The version to run. Omit it for the deployed version. See [Choose which version a call uses](/docs/documentation/features/prompt-management/prompt-management-quickstart#choose-which-version-a-call-uses). |
| `schema_version` | integer | `2` for the recommended merge rules. Default `1`. See [Prompt schema](#prompt-schema). |
| `patch` | object | v2 only. Settings that replace the prompt's for this call. No `messages` or `input`. |
| `override` | boolean | v1 only. `true` lets the prompt win conflicts. Default `false`. |
| `override_params` | object | v1 only. Settings that replace the prompt's for this call. |
| `override_config` | object | v1 only. `messages_override_mode`: `"append"` or `"override"` (default). |