> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://www.respan.ai/docs/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://www.respan.ai/docs/_mcp/server. # Create a prompt version POST https://api.respan.ai/api/prompts/{prompt_id}/versions/ Content-Type: application/json Use `{{variable_name}}` syntax in messages to define template variables. The new version becomes the prompt's current draft, and every earlier version becomes read-only. To deploy it, commit it, then use Deploy a prompt version. Reference: https://www.respan.ai/docs/apis/prompts/create-prompt-version ## Authentication - `Authorization` header (bearer token, required) — Use your Respan API key for Respan API authentication. Enter only the Respan API key value; clients send Authorization: Bearer \. For /api/responses, provider credentials such as Perplexity, OpenAI, or Azure OpenAI go in Settings -> Providers or respan\_params.credential\_override in the request body, not in this authentication field. - `Authorization` header (bearer token, required) — Use a dashboard JWT only for dashboard-authenticated endpoints. Respan API-key endpoints use the respanApiKey auth field instead. ## Request ### Path parameters - `prompt_id` (string, required) — The unique prompt identifier. ### Body (application/json) This endpoint expects an object. - `messages` (list of ApiPromptsPromptIdVersionsPostRequestBodyContentApplicationJsonSchemaMessagesItems, required) — Non-empty message array. Each message requires `role`; `content` may be omitted, an empty string, `null`, or an empty array. - `description` (string, optional) — Version description. - `thinking` (ApiPromptsPromptIdVersionsPostRequestBodyContentApplicationJsonSchemaThinking, optional, nullable) — Optional provider-specific reasoning configuration. - `model` (string, optional) — Primary model for this version. - `stream` (boolean, optional, default: false) — Whether to stream responses. - `temperature` (double, optional) — Sampling temperature (0-2). - `max_tokens` (integer, optional) — Maximum tokens to generate. - `top_p` (double, optional) — Nucleus sampling parameter. - `frequency_penalty` (double, optional) — Frequency penalty (-2 to 2). - `presence_penalty` (double, optional) — Presence penalty (-2 to 2). - `reasoning_effort` (string, optional, nullable) - `verbosity` (string, optional, nullable) - `seed` (integer, optional, nullable) - `variables` (ApiPromptsPromptIdVersionsPostRequestBodyContentApplicationJsonSchemaVariables, optional) — Template variables and their default values. - `fallback_models` (list of string, optional) — Fallback models if the primary model fails. - `load_balance_models` (list of ApiPromptsPromptIdVersionsPostRequestBodyContentApplicationJsonSchemaLoadBalanceModelsItems, optional) — Weighted load-balancing model configuration. - `tools` (list of ApiPromptsPromptIdVersionsPostRequestBodyContentApplicationJsonSchemaToolsItems, optional) — Tools available to the model. - `tool_choice` (ApiPromptsPromptIdVersionsPostRequestBodyContentApplicationJsonSchemaToolChoice, optional) - `response_format` (ApiPromptsPromptIdVersionsPostRequestBodyContentApplicationJsonSchemaResponseFormat, optional, nullable) — Structured output / response format configuration. - `json_schema` (ApiPromptsPromptIdVersionsPostRequestBodyContentApplicationJsonSchemaJsonSchema, optional, nullable) — JSON schema used for structured outputs when configured. - `is_enforcing_response_format` (boolean, optional, default: false) — Whether to strictly enforce the response format. ## Response ### 201 Prompt version created successfully. - `id` (string, optional) - `prompt_version_id` (string, optional) - `version` (integer, optional) - `description` (string, optional, nullable) - `messages` (list of map from string to any, optional) - `thinking` (ApiPromptsPromptIdVersionsPostResponsesContentApplicationJsonSchemaThinking, optional, nullable) - `model` (string, optional) - `stream` (boolean, optional) - `temperature` (double, optional, nullable) - `max_tokens` (integer, optional, nullable) - `top_p` (double, optional, nullable) - `frequency_penalty` (double, optional, nullable) - `presence_penalty` (double, optional, nullable) - `reasoning_effort` (string, optional, nullable) - `verbosity` (string, optional, nullable) - `seed` (integer, optional, nullable) - `variables` (ApiPromptsPromptIdVersionsPostResponsesContentApplicationJsonSchemaVariables, optional) - `fallback_models` (list of string, optional, nullable) - `load_balance_models` (list of ApiPromptsPromptIdVersionsPostResponsesContentApplicationJsonSchemaLoadBalanceModelsItems, optional, nullable) - `tools` (list of ApiPromptsPromptIdVersionsPostResponsesContentApplicationJsonSchemaToolsItems, optional, nullable) - `tool_choice` (ApiPromptsPromptIdVersionsPostResponsesContentApplicationJsonSchemaToolChoice, optional) - `response_format` (ApiPromptsPromptIdVersionsPostResponsesContentApplicationJsonSchemaResponseFormat, optional, nullable) - `json_schema` (ApiPromptsPromptIdVersionsPostResponsesContentApplicationJsonSchemaJsonSchema, optional, nullable) - `is_enforcing_response_format` (boolean, optional) - `readonly` (boolean, optional) - `edited_by` (ApiPromptsPromptIdVersionsPostResponsesContentApplicationJsonSchemaEditedBy, optional) - `created_at` (datetime, optional) - `updated_at` (datetime, optional) ## Errors ### 400 Bad Request Error Validation failed. - `map from string to any` ### 403 Forbidden Error The API key is missing, invalid or expired. - `detail` (string, required) ### 404 Not Found Error Prompt not found - `detail` (string, required) ## Types ### ApiPromptsPromptIdVersionsPostRequestBodyContentApplicationJsonSchemaMessagesItems - `role` (string, required) - `content` (ApiPromptsPromptIdVersionsPostRequestBodyContentApplicationJsonSchemaMessagesItemsContent, optional) ### ApiPromptsPromptIdVersionsPostRequestBodyContentApplicationJsonSchemaThinking Optional provider-specific reasoning configuration. ### ApiPromptsPromptIdVersionsPostRequestBodyContentApplicationJsonSchemaVariables Template variables and their default values. ### ApiPromptsPromptIdVersionsPostRequestBodyContentApplicationJsonSchemaLoadBalanceModelsItems ### ApiPromptsPromptIdVersionsPostRequestBodyContentApplicationJsonSchemaToolsItems ### ApiPromptsPromptIdVersionsPostRequestBodyContentApplicationJsonSchemaToolChoice ### ApiPromptsPromptIdVersionsPostRequestBodyContentApplicationJsonSchemaResponseFormat Structured output / response format configuration. ### ApiPromptsPromptIdVersionsPostRequestBodyContentApplicationJsonSchemaJsonSchema JSON schema used for structured outputs when configured. ### ApiPromptsPromptIdVersionsPostResponsesContentApplicationJsonSchemaThinking ### ApiPromptsPromptIdVersionsPostResponsesContentApplicationJsonSchemaVariables ### ApiPromptsPromptIdVersionsPostResponsesContentApplicationJsonSchemaLoadBalanceModelsItems ### ApiPromptsPromptIdVersionsPostResponsesContentApplicationJsonSchemaToolsItems ### ApiPromptsPromptIdVersionsPostResponsesContentApplicationJsonSchemaToolChoice ### ApiPromptsPromptIdVersionsPostResponsesContentApplicationJsonSchemaResponseFormat ### ApiPromptsPromptIdVersionsPostResponsesContentApplicationJsonSchemaJsonSchema ### ApiPromptsPromptIdVersionsPostResponsesContentApplicationJsonSchemaEditedBy - `id` (integer, optional) - `email` (string, optional) - `first_name` (string, optional) - `last_name` (string, optional) ### ApiPromptsPromptIdVersionsPostRequestBodyContentApplicationJsonSchemaMessagesItemsContent ## Examples **Request** ```json { "messages": [ { "role": "system", "content": "You are a helpful customer support assistant. Context: {{context}}" }, { "role": "user", "content": "{{user_query}}" } ], "description": "Production version with context awareness", "model": "gpt-4o", "temperature": 0.7, "max_tokens": 2048, "variables": { "context": "Product information and FAQs", "user_query": "How do I reset my password?" }, "fallback_models": [ "gpt-4o-mini" ], "load_balance_models": [ { "model": "gpt-4o", "weight": 0.8 }, { "model": "gpt-4o-mini", "weight": 0.2 } ], "deploy": false } ``` **Response** ```json { "id": "pv_abc123", "prompt_version_id": "pv_abc123", "version": 3, "description": "Added context variable", "messages": [ { "role": "system", "content": "You are a helpful assistant. Context: {{context}}" }, { "role": "user", "content": "{{user_query}}" } ], "thinking": null, "model": "gpt-4o", "stream": false, "temperature": 0.7, "max_tokens": 2048, "top_p": 1, "frequency_penalty": 0, "presence_penalty": 0, "reasoning_effort": null, "verbosity": null, "seed": null, "variables": { "context": "", "user_query": "" }, "fallback_models": [ "gpt-4o-mini" ], "load_balance_models": [ { "model": "gpt-4o", "weight": 0.8 }, { "model": "gpt-4o-mini", "weight": 0.2 } ], "tools": [ { "type": "function", "function": { "name": "search_knowledge_base" } } ], "tool_choice": "auto", "response_format": null, "json_schema": null, "is_enforcing_response_format": false, "readonly": false, "edited_by": { "id": 123, "email": "user@example.com", "first_name": "John", "last_name": "Doe" }, "created_at": "2026-01-20T10:30:00Z", "updated_at": "2026-01-20T10:30:00Z", "is_deployed": false } ``` **SDK Code** ```python import requests url = "https://api.respan.ai/api/prompts/prompt_id/versions/" payload = { "messages": [ { "role": "system", "content": "You are a helpful customer support assistant. Context: {{context}}" }, { "role": "user", "content": "{{user_query}}" } ], "description": "Production version with context awareness", "model": "gpt-4o", "temperature": 0.7, "max_tokens": 2048, "variables": { "context": "Product information and FAQs", "user_query": "How do I reset my password?" }, "fallback_models": ["gpt-4o-mini"], "load_balance_models": [ { "model": "gpt-4o", "weight": 0.8 }, { "model": "gpt-4o-mini", "weight": 0.2 } ], "deploy": False } headers = { "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript const url = 'https://api.respan.ai/api/prompts/prompt_id/versions/'; const options = { method: 'POST', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"messages":[{"role":"system","content":"You are a helpful customer support assistant. Context: {{context}}"},{"role":"user","content":"{{user_query}}"}],"description":"Production version with context awareness","model":"gpt-4o","temperature":0.7,"max_tokens":2048,"variables":{"context":"Product information and FAQs","user_query":"How do I reset my password?"},"fallback_models":["gpt-4o-mini"],"load_balance_models":[{"model":"gpt-4o","weight":0.8},{"model":"gpt-4o-mini","weight":0.2}],"deploy":false}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.respan.ai/api/prompts/prompt_id/versions/" payload := strings.NewReader("{\n \"messages\": [\n {\n \"role\": \"system\",\n \"content\": \"You are a helpful customer support assistant. Context: {{context}}\"\n },\n {\n \"role\": \"user\",\n \"content\": \"{{user_query}}\"\n }\n ],\n \"description\": \"Production version with context awareness\",\n \"model\": \"gpt-4o\",\n \"temperature\": 0.7,\n \"max_tokens\": 2048,\n \"variables\": {\n \"context\": \"Product information and FAQs\",\n \"user_query\": \"How do I reset my password?\"\n },\n \"fallback_models\": [\n \"gpt-4o-mini\"\n ],\n \"load_balance_models\": [\n {\n \"model\": \"gpt-4o\",\n \"weight\": 0.8\n },\n {\n \"model\": \"gpt-4o-mini\",\n \"weight\": 0.2\n }\n ],\n \"deploy\": false\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Authorization", "Bearer ") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.respan.ai/api/prompts/prompt_id/versions/") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{\n \"messages\": [\n {\n \"role\": \"system\",\n \"content\": \"You are a helpful customer support assistant. Context: {{context}}\"\n },\n {\n \"role\": \"user\",\n \"content\": \"{{user_query}}\"\n }\n ],\n \"description\": \"Production version with context awareness\",\n \"model\": \"gpt-4o\",\n \"temperature\": 0.7,\n \"max_tokens\": 2048,\n \"variables\": {\n \"context\": \"Product information and FAQs\",\n \"user_query\": \"How do I reset my password?\"\n },\n \"fallback_models\": [\n \"gpt-4o-mini\"\n ],\n \"load_balance_models\": [\n {\n \"model\": \"gpt-4o\",\n \"weight\": 0.8\n },\n {\n \"model\": \"gpt-4o-mini\",\n \"weight\": 0.2\n }\n ],\n \"deploy\": false\n}" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.respan.ai/api/prompts/prompt_id/versions/") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{\n \"messages\": [\n {\n \"role\": \"system\",\n \"content\": \"You are a helpful customer support assistant. Context: {{context}}\"\n },\n {\n \"role\": \"user\",\n \"content\": \"{{user_query}}\"\n }\n ],\n \"description\": \"Production version with context awareness\",\n \"model\": \"gpt-4o\",\n \"temperature\": 0.7,\n \"max_tokens\": 2048,\n \"variables\": {\n \"context\": \"Product information and FAQs\",\n \"user_query\": \"How do I reset my password?\"\n },\n \"fallback_models\": [\n \"gpt-4o-mini\"\n ],\n \"load_balance_models\": [\n {\n \"model\": \"gpt-4o\",\n \"weight\": 0.8\n },\n {\n \"model\": \"gpt-4o-mini\",\n \"weight\": 0.2\n }\n ],\n \"deploy\": false\n}") .asString(); ``` ```php request('POST', 'https://api.respan.ai/api/prompts/prompt_id/versions/', [ 'body' => '{ "messages": [ { "role": "system", "content": "You are a helpful customer support assistant. Context: {{context}}" }, { "role": "user", "content": "{{user_query}}" } ], "description": "Production version with context awareness", "model": "gpt-4o", "temperature": 0.7, "max_tokens": 2048, "variables": { "context": "Product information and FAQs", "user_query": "How do I reset my password?" }, "fallback_models": [ "gpt-4o-mini" ], "load_balance_models": [ { "model": "gpt-4o", "weight": 0.8 }, { "model": "gpt-4o-mini", "weight": 0.2 } ], "deploy": false }', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.respan.ai/api/prompts/prompt_id/versions/"); var request = new RestRequest(Method.POST); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"messages\": [\n {\n \"role\": \"system\",\n \"content\": \"You are a helpful customer support assistant. Context: {{context}}\"\n },\n {\n \"role\": \"user\",\n \"content\": \"{{user_query}}\"\n }\n ],\n \"description\": \"Production version with context awareness\",\n \"model\": \"gpt-4o\",\n \"temperature\": 0.7,\n \"max_tokens\": 2048,\n \"variables\": {\n \"context\": \"Product information and FAQs\",\n \"user_query\": \"How do I reset my password?\"\n },\n \"fallback_models\": [\n \"gpt-4o-mini\"\n ],\n \"load_balance_models\": [\n {\n \"model\": \"gpt-4o\",\n \"weight\": 0.8\n },\n {\n \"model\": \"gpt-4o-mini\",\n \"weight\": 0.2\n }\n ],\n \"deploy\": false\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = [ "messages": [ [ "role": "system", "content": "You are a helpful customer support assistant. Context: {{context}}" ], [ "role": "user", "content": "{{user_query}}" ] ], "description": "Production version with context awareness", "model": "gpt-4o", "temperature": 0.7, "max_tokens": 2048, "variables": [ "context": "Product information and FAQs", "user_query": "How do I reset my password?" ], "fallback_models": ["gpt-4o-mini"], "load_balance_models": [ [ "model": "gpt-4o", "weight": 0.8 ], [ "model": "gpt-4o-mini", "weight": 0.2 ] ], "deploy": false ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.respan.ai/api/prompts/prompt_id/versions/")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```