Update a prompt version

curl -X PATCH https://api.respan.ai/api/prompts/prompt_id/versions/3/ \
     -H "Authorization: Bearer <respanApiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "description": "Production version with context awareness",
  "messages": [
    {
      "role": "system",
      "content": "You are a helpful customer support assistant. Context: {{context}}"
    },
    {
      "role": "user",
      "content": "{{user_query}}"
    }
  ],
  "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
}'

{
  "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,
  "is_deployed": 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"
}

Update a prompt version. Set deploy: true to make this version live immediately.

Authentication

AuthorizationBearer

Use your Respan API key for Respan API authentication. Enter only the Respan API key value; clients send Authorization: Bearer <RESPAN_API_KEY>. For /api/responses, OpenAI or Azure OpenAI provider credentials go in Settings -> Providers or the request body credential_override field, not in this auth field.

Path parameters

prompt_idstringRequired

The unique prompt identifier.

versionintegerRequired

The prompt version number.

Request

This endpoint expects an object.

descriptionstringOptional

Version description.

messageslist of maps from strings to anyOptional

Messages for this version. Use {{variable_name}} placeholders for template variables.

thinkingobject or nullOptional

Optional provider-specific reasoning configuration.

modelstringOptional

Primary model for this version.

streambooleanOptionalDefaults to false

Whether to stream responses.

temperaturedoubleOptional

Sampling temperature (0-2).

max_tokensintegerOptional

Maximum tokens to generate.

top_pdoubleOptional

Nucleus sampling parameter.

frequency_penaltydoubleOptional

Frequency penalty (-2 to 2).

presence_penaltydoubleOptional

Presence penalty (-2 to 2).

reasoning_effortstring or nullOptional

verbositystring or nullOptional

seedinteger or nullOptional

variablesobjectOptional

Template variables and their default values.

fallback_modelslist of stringsOptional

Fallback models if the primary model fails.

load_balance_modelslist of objectsOptional

Weighted load-balancing model configuration.

toolslist of objectsOptional

Tools available to the model.

tool_choicestring or map from strings to any or nullOptional

response_formatobject or nullOptional

Structured output / response format configuration.

json_schemaobject or nullOptional

JSON schema used for structured outputs when configured.

is_enforcing_response_formatbooleanOptionalDefaults to false

Whether to strictly enforce the response format.

deploybooleanOptionalDefaults to false

Deploy this version as the live version immediately.

Response

Prompt version updated successfully.

idstring

prompt_version_idstring

versioninteger

descriptionstring or null

messageslist of maps from strings to any

thinkingobject or null

modelstring

streamboolean

temperaturedouble or null

max_tokensinteger or null

top_pdouble or null

frequency_penaltydouble or null

presence_penaltydouble or null

reasoning_effortstring or null

verbositystring or null

seedinteger or null

variablesobject

fallback_modelslist of strings or null

load_balance_modelslist of objects or null

toolslist of objects or null

tool_choicestring or map from strings to any or null

response_formatobject or null

json_schemaobject or null

is_enforcing_response_formatboolean

readonlyboolean

is_deployedboolean

edited_byobject

created_atdatetime

updated_atdatetime

Errors

400

Bad Request Error

401

Unauthorized Error

404

Not Found Error