Create a prompt version

curl -X POST https://api.respan.ai/api/prompts/prompt_id/versions/ \
     -H "Authorization: Bearer sk_live_xxxxx" \
     -H "Content-Type: application/json" \
     -d '{
  "messages": [
    {
      "role": "system",
      "content": "You are a helpful customer support assistant. Context: {{context}}"
    },
    {
      "role": "user",
      "content": "{{user_query}}"
    }
  ],
  "model": "gpt-4o",
  "description": "Production version with context awareness",
  "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}}"
    }
  ],
  "model": "gpt-4o",
  "stream": false,
  "temperature": 0.7,
  "max_tokens": 2048,
  "top_p": 1,
  "frequency_penalty": 0,
  "presence_penalty": 0,
  "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",
  "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"
}

Create a new version of a prompt. Use {{variable_name}} syntax in messages to define template variables.

Path parameters

prompt_idstringRequired

The unique prompt identifier.

Request

This endpoint expects an object.

messageslist of maps from strings to anyRequired

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

modelstringRequired

Primary model for this version.

descriptionstringOptional

Version description.

thinkingobject or nullOptional

Optional provider-specific reasoning configuration.

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 created 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

Path parameters

Headers

Request

Response

Errors