Create a prompt version

curl -X POST https://api.respan.ai/api/prompts/prompt_id/versions/ \
     -H "Authorization: Bearer <respanApiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "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
}'

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

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

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, 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.

AuthorizationBearer

Use a dashboard JWT only for dashboard-authenticated endpoints. Respan API-key endpoints use the respanApiKey auth field instead.

Path parameters

prompt_idstringRequired

The unique prompt identifier.

Request

This endpoint expects an object.

messageslist of objectsRequired

Non-empty message array. Each message requires role; content may be omitted, an empty string, null, or an empty array.

descriptionstringOptional

Version description.

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 anyOptional

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.

idstringOptional

prompt_version_idstringOptional

versionintegerOptional

descriptionstring or nullOptional

messageslist of maps from strings to anyOptional

thinkingobject or nullOptional

modelstringOptional

streambooleanOptional

temperaturedouble or nullOptional

max_tokensinteger or nullOptional

top_pdouble or nullOptional

frequency_penaltydouble or nullOptional

presence_penaltydouble or nullOptional

reasoning_effortstring or nullOptional

verbositystring or nullOptional

seedinteger or nullOptional

variablesobjectOptional

fallback_modelslist of strings or nullOptional

load_balance_modelslist of objects or nullOptional

toolslist of objects or nullOptional

tool_choicestring or map from strings to anyOptional

response_formatobject or nullOptional

json_schemaobject or nullOptional

is_enforcing_response_formatbooleanOptional

readonlybooleanOptional

is_deployedbooleanOptional

edited_byobjectOptional

created_atdatetimeOptional

updated_atdatetimeOptional

Errors

400

Bad Request Error

401

Unauthorized Error

404

Not Found Error