Create prompt template version by name

curl --request POST \
  --url https://api.example.com/api/v2/projects/{project_id}/prompt-templates/name/{template_name}/versions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "template_messages": [
    {
      "content": "<string>",
      "media_slots": null
    }
  ],
  "model": "<string>",
  "provider": "<string>",
  "version_name": null,
  "version_description": null,
  "llm_parameters": null,
  "tool_schema": null,
  "output_schema": null,
  "environments": null
}
'

{
  "prompt_template_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "prompt_template_version_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "prompt_template_name": "<string>",
  "version_name": "<string>",
  "version_description": "<string>",
  "metadata": {
    "provider": "<string>",
    "flavor": "<string>",
    "model": "<string>",
    "params": {},
    "provider_info": {}
  },
  "format_version": 123,
  "project_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "content": [
    {
      "role": "<string>",
      "content": "<string>",
      "media_slots": [
        {
          "placeholder_name": "<string>"
        }
      ]
    }
  ],
  "tool_schema": [
    {
      "name": "<string>",
      "description": "<string>",
      "parameters": {}
    }
  ],
  "output_schema": {}
}

Prompt Templates

Create prompt template version by name

Create a new version of a prompt template, referenced by a string or name you define. See SDK method.

Set create_template_if_not_exists=true to auto-create the template if it doesn’t exist.

Version Creation Semantics:

A new version is created only if there is no existing version with identical:

Content (prompt messages)
Model
LLM parameters
Version name (if provided)
Version description
Tool schema
Output schema

If an identical version exists in any of the target environments, that version is reused and its environments are updated to match the requested environments. This ensures you never create duplicate versions with the same configuration.

Environment Deployment:

When creating a new version, it will be deployed to the specified environments (or “latest” if none specified)
When reuploading an existing prompt template with a new environment, the environments on that prompt template version will be updated

These checks are performed so that you can safely upload prompt templates without worrying that you will be creating duplicate versions. This is especially useful in development workflows where your prompts are stored in code.

POST

api

projects

{project_id}

prompt-templates

name

{template_name}

versions

Create prompt template version by name

curl --request POST \
  --url https://api.example.com/api/v2/projects/{project_id}/prompt-templates/name/{template_name}/versions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "template_messages": [
    {
      "content": "<string>",
      "media_slots": null
    }
  ],
  "model": "<string>",
  "provider": "<string>",
  "version_name": null,
  "version_description": null,
  "llm_parameters": null,
  "tool_schema": null,
  "output_schema": null,
  "environments": null
}
'

{
  "prompt_template_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "prompt_template_version_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "prompt_template_name": "<string>",
  "version_name": "<string>",
  "version_description": "<string>",
  "metadata": {
    "provider": "<string>",
    "flavor": "<string>",
    "model": "<string>",
    "params": {},
    "provider_info": {}
  },
  "format_version": 123,
  "project_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "content": [
    {
      "role": "<string>",
      "content": "<string>",
      "media_slots": [
        {
          "placeholder_name": "<string>"
        }
      ]
    }
  ],
  "tool_schema": [
    {
      "name": "<string>",
      "description": "<string>",
      "parameters": {}
    }
  ],
  "output_schema": {}
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

project_id

string

required

template_name

string

required

Query Parameters

create_template_if_not_exists

boolean | null

Body

application/json

template_messages

(PromptTemplateMessageInfo · object | HistoryPlaceholderInfo · object)[]

required

PromptTemplateMessageInfo
HistoryPlaceholderInfo

Show child attributes

model

string

required

provider

string

required

version_name

string | null

version_description

string | null

llm_parameters

Llm Parameters · object | null

Show child attributes

tool_schema

NormalizedToolSchema · object[] | null

Show child attributes

output_schema

Output Schema · object | null

environments

string[] | null

Response

201 - application/json

PlainPromptTemplate(prompt_template_id: uuid.UUID, prompt_template_version_id: uuid.UUID, prompt_template_name: str, version_name: Optional[str], version_description: Optional[str], metadata: server.api_routes.prompt_templates_api_v2.PromptTemplateMetadata, format_version: int, project_id: uuid.UUID, content: list[typing.Union[server.project_sessions.prompt_template_model.ChatMessageWithMediaSlot, server.project_sessions.prompt_template_model.ChatMessage, server.project_sessions.prompt_template_model.HistoryPlaceholder]], tool_schema: Optional[list[shared.common.NormalizedToolSchema]], output_schema: Optional[dict[str, Any]])

prompt_template_id

string<uuid>

required

prompt_template_version_id

string<uuid>

required

prompt_template_name

string

required

version_name

string | null

required

version_description

string | null

required

metadata

PromptTemplateMetadata · object

required

Show child attributes

format_version

integer

required

project_id

string<uuid>

required

content

(ChatMessageWithMediaSlot · object | ChatMessage · object | HistoryPlaceholder · object)[]

required

ChatMessageWithMediaSlot
ChatMessage
HistoryPlaceholder

Show child attributes

tool_schema

NormalizedToolSchema · object[] | null

required

Show child attributes

output_schema

Output Schema · object | null

required

Update environment for prompt template version

List prompt templates

⌘I