For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
DiscordPlatform
DocumentationIntegrationsAPI referenceSDKsChangelog
DocumentationIntegrationsAPI referenceSDKsChangelog
  • API Reference
      • POSTList prompts
      • POSTCreate a prompt
      • GETRetrieve a prompt
      • PATCHUpdate a prompt
      • DELDelete a prompt
      • POSTCreate a prompt version
      • GETList prompt versions
      • GETRetrieve a prompt version
      • PATCHUpdate a prompt version
      • DELDelete a prompt version
      • POSTCommit a prompt version
      • POSTDeploy a prompt version
      • GETGet prompts summary
      • POSTGet prompts summary with filters
  • Reference
    • Filters API Reference
LogoLogo
DiscordPlatform
API ReferencePrompts

Create a prompt version

POST
https://api.respan.ai/api/prompts/:prompt_id/versions/
POST
/api/prompts/:prompt_id/versions/
$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
>}'
1{
2  "id": "pv_abc123",
3  "prompt_version_id": "pv_abc123",
4  "version": 3,
5  "description": "Added context variable",
6  "messages": [
7    {
8      "role": "system",
9      "content": "You are a helpful assistant. Context: {{context}}"
10    },
11    {
12      "role": "user",
13      "content": "{{user_query}}"
14    }
15  ],
16  "thinking": null,
17  "model": "gpt-4o",
18  "stream": false,
19  "temperature": 0.7,
20  "max_tokens": 2048,
21  "top_p": 1,
22  "frequency_penalty": 0,
23  "presence_penalty": 0,
24  "reasoning_effort": null,
25  "verbosity": null,
26  "seed": null,
27  "variables": {
28    "context": "",
29    "user_query": ""
30  },
31  "fallback_models": [
32    "gpt-4o-mini"
33  ],
34  "load_balance_models": [
35    {
36      "model": "gpt-4o",
37      "weight": 0.8
38    },
39    {
40      "model": "gpt-4o-mini",
41      "weight": 0.2
42    }
43  ],
44  "tools": [
45    {
46      "type": "function",
47      "function": {
48        "name": "search_knowledge_base"
49      }
50    }
51  ],
52  "tool_choice": "auto",
53  "response_format": null,
54  "json_schema": null,
55  "is_enforcing_response_format": false,
56  "readonly": false,
57  "is_deployed": false,
58  "edited_by": {
59    "id": 123,
60    "email": "user@example.com",
61    "first_name": "John",
62    "last_name": "Doe"
63  },
64  "created_at": "2026-01-20T10:30:00Z",
65  "updated_at": "2026-01-20T10:30:00Z"
66}

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

Was this page helpful?
Previous

List prompt versions

Next
Built with

Path parameters

prompt_idstringRequired
The unique prompt identifier.

Headers

AuthorizationstringRequired

Bearer token. Use Bearer YOUR_API_KEY.

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