Build, test, and deploy prompt templates on Respan. New to prompts? Start with the quickstart guide .
Prompt schema The prompt object supports a schema_version field that controls how prompt configuration and request-body parameters are merged.
Prompt schema v2 (recommended) Set schema_version=2 for the recommended merge behavior:
Prompt configuration always wins for conflicting fields (no override flag needed).
Uses prepend/instructions-style merging depending on the endpoint mode.
Supports a patch field for applying additional parameter overrides. The patch object must not contain messages or input.
Important: OpenAI SDKs strip fields like schema_version, patch, and prompt_slug during validation. Prompt schema v2 requires raw HTTP requests (e.g., requests in Python or fetch in TypeScript).
import requests headers = { 'Content-Type' : 'application/json' , 'Authorization' : 'Bearer YOUR_RESPAN_API_KEY' , } data = { 'prompt' : { 'prompt_id' : 'YOUR_PROMPT_ID' , 'schema_version' : 2 , 'variables' : { 'task_description' : 'Square a number' , }, 'patch' : { 'temperature' : 0.9 , 'max_tokens' : 500 } } } response = requests.post( 'https://api.respan.ai/api/chat/completions' , headers = headers, json = data ) print (response.json())
Prompt schema v1 (default, legacy) When schema_version is absent or 1, merging is controlled by the override flag:
override=true: prompt configuration wins for all conflicting fields.override=false (default): request body wins for conflicting fields.
Override other parameters
request_body = { "prompt" : { "prompt_id" : "042f5f" , "override" : True , "override_params" : { "temperature" : 0.8 , "max_tokens" : 150 , "model" : "gpt-4o" } } }
Append new messages to the end of existing prompt messages: request_body = { "prompt" : { "prompt_id" : "042f5f" , "override_config" : { "messages_override_mode" : "append" }, "override_params" : { "messages" : [{ "role" : "user" , "content" : "Additional context" }]}, } }
Replace all existing prompt messages: request_body = { "prompt" : { "prompt_id" : "042f5f" , "override_config" : { "messages_override_mode" : "override" }, "override_params" : { "messages" : [{ "role" : "user" , "content" : "Completely new conversation" }]}, } }
Variables Use {{variable_name}} syntax to add dynamic content to your prompts. Variables let you reuse the same template across different inputs — pass values at runtime from code, or fill them from testset columns in experiments. See the quickstart for setup and basic usage.
Jinja templates Respan supports Jinja templates for conditionals, filters, and JSON input access.
Feature Syntax Example Conditionals {% if %}...{% endif %}{% if condition %}{{ variable_name }}{% endif %}JSON inputs {{ input.key }}{{ input.name }}Filters {{ var | filter }}{{ variable_name | filter_name }}Comments {# ... #}{# This is a comment #}
See the Filters in Jinja templates guide for details.
You can also set default variable values when creating a version via the API:
data = { "messages" : [ { "role" : "system" , "content" : "You are a helpful {{ role }} ." }, { "role" : "user" , "content" : "Help me with {{ task_description }} ." } ], "model" : "gpt-4o-mini" , "variables" : { "role" : "assistant" , "task_description" : "sorting an array" }, }
Prompt composition Prompt composition lets a variable in one prompt reference another prompt. At request time, the child is rendered first, converted to plain text, and inserted into the parent variable.
To use prompt composition, create two prompts: a child prompt and a parent prompt that has a {{variable}} where the child’s output will be injected.
Configure the variable
In the parent prompt editor:
Open the Variables panel on the right side
Find the variable you want to embed a prompt into
Change its type from Text to Prompt
Select the child prompt
Fill in all the child’s variables
Run your prompt
Click Run to test. The child prompt is rendered first, converted to plain text, and injected into the parent variable before the LLM sees it.
Limits:
Circular references are rejected (HTTP 400).
Maximum prompt-chain depth is 2 (parent → child is safest). Exceeding this returns HTTP 400.
Instead of passing a plain string for a variable, pass a typed prompt object: { "_type" : "prompt" , "prompt_id" : "CHILD_PROMPT_ID" , "version" : 1 , "variables" : { "some_key" : "some_value" } }
Supported fields:
_type — must be "prompt"prompt_id — identifies the child promptversion — integer or "latest" (optional, defaults to deployed version)variables — nested variables for the child prompt (optional) Full example: response = client.chat.completions.create( model = "gpt-4o-mini" , messages = [], extra_body = { "prompt" : { "prompt_id" : "PARENT_PROMPT_ID" , "override" : True , "variables" : { "conversation" : { "_type" : "prompt" , "prompt_id" : "CHILD_PROMPT_ID" , "version" : 2 , "variables" : { "customer_name" : "Sarah" , "department" : "billing" } }, "request" : "dispute a charge from last month" } } }, )
Observability: Resolved prompt variables are enriched in logs with _rendered_result — the plain-text output of the child prompt at runtime. This helps debug what the child actually resolved to.See the Chat Completions API reference for more details. Structured output Define structured output using JSON schema to ensure AI responses follow a specific format, following the OpenAI Structured Outputs specification .
Configure JSON schema in the prompt editor or the playground : You can generate schemas using the AI generator or browse examples in the editor. Pass response_format when creating a prompt version: data = { "messages" : [ { "role" : "system" , "content" : "Extract the information." }, { "role" : "user" , "content" : " {{ input_text }} " } ], "model" : "gpt-4o-mini" , "response_format" : { "type" : "json_schema" , "json_schema" : { "name" : "extraction" , "strict" : True , "schema" : { "type" : "object" , "properties" : { "date" : { "type" : "string" }, "customer_id" : { "type" : "integer" } }, "required" : [ "date" , "customer_id" ], "additionalProperties" : False } } } }
Streaming Enable streaming in the prompt settings sidebar. After enabling, commit and deploy the prompt.
If you use a prompt with streaming enabled, you must also set stream=True in your SDK call:
response = client.chat.completions.create( model = "gpt-4o-mini" , messages = [{ "role" : "user" , "content" : "Tell me a long story" }], stream = True , extra_body = { "prompt" : { "prompt_id" : "YOUR_PROMPT_ID" , "variables" : { "variable_name" : "variable_value" }, } } )
Deployment & versioning Commit saves a new version of your prompt. Deploy makes a version live for production traffic.View version history in the Overview panel, or click Version in the Editor for detailed diffs. Click on each version to see the diff of changes. To deploy, go to the Deployments tab and click Deploy . To rollback, deploy an earlier version from the Deployments tab. Version pinning When calling a prompt from code, control which version is used:
Omit version to use the deployed (live) version.
Set version to a number (e.g., 3) to pin that version.
Use "version": "latest" to use the most recent draft (not deployed).
{ "prompt" : { "prompt_id" : "YOUR_PROMPT_ID" , "version" : 3 , } }
Deploy via API Use the Prompt Versions API to create and deploy versions programmatically. Set deploy: true to make a version live immediately. import requests url = "https://api.respan.ai/api/prompts/<prompt_id>/versions/" headers = { "Authorization" : "Bearer YOUR_RESPAN_API_KEY" , "Content-Type" : "application/json" } data = { "messages" : [ { "role" : "system" , "content" : "You are a helpful {{ role }} ." }, { "role" : "user" , "content" : "Hello, how are you?" } ], "model" : "gpt-4o-mini" , "temperature" : 0.7 , "max_tokens" : 256 , "deploy" : True # Deploy as the live version immediately } response = requests.post(url, headers = headers, json = data) print (response.json())
To deploy an existing version, use the Update Version API with deploy: true: url = "https://api.respan.ai/api/prompts/<prompt_id>/versions/<version_id>/" data = { "deploy" : True } response = requests.patch(url, headers = headers, json = data)
Playground Test and iterate on prompts in the Prompt Playground .
From the prompt editor, enter variable values and click Playground in the top bar to test. Click Commit to save changes back to your prompt library.
You can also debug production logs by clicking Open in Playground on any log entry.
Set the number of variants in the side panel to generate multiple responses and compare them in the Variants tab.
Prompt logging Respan prompts
External prompts
Log prompt usage to track performance metrics, compare versions, and analyze request distribution. import requests url = "https://api.respan.ai/api/request-logs/create/" payload = { "model" : "claude-3-5-sonnet-20240620" , "completion_message" : { "role" : "assistant" , "content" : "Hi, how can I assist you today?" }, "prompt" : { "prompt_id" : "xxxxxx" , "variables" : { "task_description" : "Square a number" , "specific_library" : "math" }, }, "generation_time" : 5.7 , "ttft" : 3.1 , } headers = { "Authorization" : "Bearer YOUR_RESPAN_API_KEY" , "Content-Type" : "application/json" } response = requests.post(url, headers = headers, json = payload)
Filter logs by prompt name on the Logs page . If you manage prompts outside of Respan, pass any prompt_id and set is_custom_prompt: true: payload = { "model" : "claude-3-5-sonnet-20240620" , "prompt_messages" : [{ "role" : "user" , "content" : "Hi" }], "completion_message" : { "role" : "assistant" , "content" : "Hello!" }, "prompt_id" : "your-custom-id" , "is_custom_prompt" : True , "generation_time" : 5.7 }
Team collaboration
Share — click the Link button in the Editor to share a promptComments — add comments to discuss changesLabels — categorize and organize prompts
Parameters reference The unique identifier of your saved prompt template.
Variables to inject into your prompt template. Values can be strings or typed prompt objects for composition . { "variables" : { "user_name" : "John" , "task" : "summarize" } }
When true, the saved prompt configuration overrides SDK parameters like model and messages.
Parameters that override your saved prompt configuration (temperature, max_tokens, messages, model, etc.).
Controls how override parameters are applied.
messages_override_mode: "append" (add to existing) or "override" (replace all) Controls the prompt merge strategy. 1 (default, legacy) uses override flag logic. 2 (recommended) uses prepend/instructions-style merging where the prompt config always wins. See Prompt schema . Additional parameter overrides applied in v2 mode (schema_version=2). Must not contain messages or input. Useful for overriding fields like temperature or max_tokens while letting the prompt config control messages and model.
When enabled, the response includes the final prompt messages used.
Pin a specific prompt version. Omit for deployed version, use "latest" for newest draft.
You can generate schemas using the AI generator or browse examples in the editor.
Click on each version to see the diff of changes.
To deploy, go to the Deployments tab and click Deploy.
To rollback, deploy an earlier version from the Deployments tab.
