Create prompt template version by ID

curl --request POST \
  --url https://api.example.com/api/v2/projects/{project_id}/prompt-templates/id/{template_id}/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 ID

Create a new version of an existing prompt template. Freeplay assigns a random ID. Use when you have the template ID from a previous API call.

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

{template_id}

versions

Create prompt template version by ID

curl --request POST \
  --url https://api.example.com/api/v2/projects/{project_id}/prompt-templates/id/{template_id}/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_id

string

required

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

List prompt template versions

Get prompt template version by ID

⌘I