Advanced configurations

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.

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.

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

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, pass the prompt in respan_params.prompt with schema_version: 2. The prompt’s messages become instructions, and your input stays the user turn.

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."}]},
    }
}

Deployment & versioning

To choose the version a call runs, or to roll back in the editor, see Choose which version a call uses and Ship a new version.

To manage versions from code, use the Prompts API:

• Create a prompt version saves a draft.
• Commit a prompt version turns the draft into a numbered version.
• Deploy a prompt version makes a committed version live. Deploy an older number to roll back.
• List prompt versions shows every version.
• Bulk operations 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.

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  templates, so you can also use conditions, loops, filters, and dot access on objects:

{% 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:

Prompt logging

If you call the model yourself and send logs with Create span, add a prompt object so the span links to the prompt:

{
  "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: