Skip to main content
PATCH
/
rest
/
prompt-templates
/
{identifier}
Patch Prompt Template Version
curl --request PATCH \
  --url https://api.promptlayer.com/rest/prompt-templates/{identifier} \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <x-api-key>' \
  --data '
{
  "version": 1,
  "label": "<string>",
  "messages": {},
  "tools": {},
  "functions": {},
  "function_call": "<string>",
  "tool_choice": "<string>",
  "content": {},
  "model_parameters": {},
  "response_format": {},
  "commit_message": "<string>",
  "release_labels": [
    "<string>"
  ]
}
'
{
  "id": 123,
  "prompt_name": "<string>",
  "prompt_version_id": 123,
  "version_number": 123,
  "tags": [
    "<string>"
  ],
  "prompt_template": {
    "content": [
      {
        "text": "<string>",
        "type": "text",
        "id": "<string>",
        "annotations": [
          {
            "type": "<string>",
            "title": "<string>",
            "url": "<string>",
            "start_index": 123,
            "end_index": 123,
            "cited_text": "<string>",
            "encrypted_index": "<string>"
          }
        ],
        "thought_signature": "<string>"
      }
    ],
    "input_variables": [],
    "template_format": "f-string",
    "type": "completion"
  },
  "release_labels": [
    "<string>"
  ],
  "metadata": {
    "model": {
      "provider": "<string>",
      "name": "<string>",
      "model_config_display_name": "<string>",
      "base_model": "<string>",
      "parameters": {},
      "display_params": {},
      "api_type": "<string>"
    }
  },
  "commit_message": "<string>"
}
Partially update a prompt template by creating a new version with merged changes. This endpoint allows you to modify specific fields of a prompt template without resending the entire configuration. The PATCH operation:
  1. Fetches the specified base version (latest by default, or a specific version/label)
  2. Applies your field-level patches to the base template
  3. Validates the merged result
  4. Creates a new version with the merged configuration

​
HTTP Request

PATCH /rest/prompt-templates/{identifier}

​
Path Parameters

  • identifier (string, required): The prompt template name or numeric ID.

​
Request Body

The request body expects a JSON object with the following structure:

​
Schema

{
  "version": "integer (optional)",
  "label": "string (optional)",
  "messages": "object | array (optional)",
  "tools": "object | array | null (optional)",
  "functions": "object | array | null (optional)",
  "function_call": "string | object | null (optional)",
  "tool_choice": "string | object | null (optional)",
  "content": "object | array (optional)",
  "model_parameters": "object (optional)",
  "response_format": "object | null (optional)",
  "commit_message": "string (optional)",
  "release_labels": ["string"]
}

​
Parameters

​
Base Version Targeting

These are mutually exclusive. If neither is provided, the latest version is used.
  • version (integer, optional): The version number to base changes on.
  • label (string, optional): A release label identifying the base version (e.g. "prod", "staging").

​
Chat Template Fields

These fields only apply to chat-type templates. Sending them for a completion template returns a 400 error.
  • messages (object or array, optional):
    • Object: Index-based patch. Keys are string indices (e.g. {"0": {...}}), values are replacement message objects. Only the specified indices are updated; others are preserved.
    • Array: Full replacement. Replaces all messages entirely.
  • tools (object, array, or null, optional): Same patching behavior as messages. Set to null to remove all tools.
  • functions (object, array, or null, optional): Same patching behavior as messages. Set to null to remove all functions.
  • function_call (string, object, or null, optional): Replaces the function_call setting. Set to null to remove.
  • tool_choice (string, object, or null, optional): Replaces the tool_choice setting. Set to null to remove.

​
Completion Template Fields

  • content (object or array, optional): Patch for completion template content. Same index-based or full-replacement behavior as messages. Completion templates only — sending this for a chat template returns a 400 error.

​
Model & Metadata

  • model_parameters (object, optional): Parameters to shallow-merge into existing model parameters (e.g. temperature, max_tokens). Existing keys not mentioned here are preserved.
  • response_format (object or null, optional): Convenience field to set response_format in model parameters. Cannot be used simultaneously with response_format inside model_parameters. Set to null to remove.

​
Version Metadata

  • commit_message (string, optional): A message describing the changes in this version.
  • release_labels (array of strings, optional): Release labels to create or move to the newly created version.

​
Response

Status Code: 201 (Created) 
{
  "id": 17,
  "prompt_name": "web-search-prompt",
  "prompt_version_id": 109,
  "version_number": 5,
  "tags": [],
  "prompt_template": { "..." },
  "commit_message": "Updated system message",
  "metadata": { "..." },
  "release_labels": ["staging"]
}

​
Examples

​
Patch a Single Message by Index

Update just one message in a chat template while preserving all others: 
import requests

response = requests.patch(
    "https://api.promptlayer.com/rest/prompt-templates/my-prompt",
    headers={"X-API-KEY": "your-api-key"},
    json={
        "messages": {
            "0": {
                "role": "system",
                "content": [{"type": "text", "text": "You are a helpful assistant."}]
            }
        },
        "commit_message": "Updated system message"
    }
)

​
Replace All Messages

Pass an array to fully replace the messages list: 
response = requests.patch(
    "https://api.promptlayer.com/rest/prompt-templates/my-prompt",
    headers={"X-API-KEY": "your-api-key"},
    json={
        "messages": [
            {"role": "system", "content": [{"type": "text", "text": "New system prompt."}]},
            {"role": "user", "content": [{"type": "text", "text": "{user_input}"}]}
        ]
    }
)

​
Update Model Parameters

Shallow-merge new parameters while preserving existing ones: 
response = requests.patch(
    "https://api.promptlayer.com/rest/prompt-templates/my-prompt",
    headers={"X-API-KEY": "your-api-key"},
    json={
        "model_parameters": {"temperature": 0.7, "max_tokens": 500},
        "commit_message": "Tuned generation parameters"
    }
)

​
Patch from a Specific Version

Base the patch on a specific version instead of the latest: 
response = requests.patch(
    "https://api.promptlayer.com/rest/prompt-templates/my-prompt",
    headers={"X-API-KEY": "your-api-key"},
    json={
        "version": 3,
        "messages": {
            "0": {
                "role": "system",
                "content": [{"type": "text", "text": "Hotfix based on v3"}]
            }
        },
        "commit_message": "Hotfix from version 3"
    }
)

​
Patch from a Release Label

Use the version currently tagged with a label as the base: 
response = requests.patch(
    "https://api.promptlayer.com/rest/prompt-templates/my-prompt",
    headers={"X-API-KEY": "your-api-key"},
    json={
        "label": "production",
        "messages": {
            "0": {
                "role": "system",
                "content": [{"type": "text", "text": "Patched production prompt"}]
            }
        },
        "commit_message": "Quick fix on production version"
    }
)

​
Update and Deploy

Combine changes with release label assignment: 
response = requests.patch(
    "https://api.promptlayer.com/rest/prompt-templates/my-prompt",
    headers={"X-API-KEY": "your-api-key"},
    json={
        "model_parameters": {"temperature": 0.5},
        "response_format": {"type": "json_object"},
        "commit_message": "Deploy with JSON mode",
        "release_labels": ["staging", "production"]
    }
)

​
Add Tools to a Prompt

response = requests.patch(
    "https://api.promptlayer.com/rest/prompt-templates/my-prompt",
    headers={"X-API-KEY": "your-api-key"},
    json={
        "tools": [
            {
                "type": "function",
                "function": {
                    "name": "search",
                    "description": "Search the web",
                    "parameters": {
                        "type": "object",
                        "properties": {"query": {"type": "string"}}
                    }
                }
            }
        ],
        "tool_choice": "auto",
        "commit_message": "Added search tool"
    }
)

​
Merge Behavior

FieldMerge Behavior
messagesObject: index-based patch (update specific indices, preserve others). Array: full replacement.
toolsSame as messages. null removes all tools.
functionsSame as messages. null removes all functions.
function_callFull replacement. null removes.
tool_choiceFull replacement. null removes.
contentSame as messages (completion templates only).
model_parametersShallow merge with existing parameters.
response_formatFull replacement. null removes.
release_labelsCreates or moves labels to the new version.

​
Error Responses

Status CodeError
400Validation error, conflicting response_format, out-of-bounds index, wrong template type, version and label both specified
401Missing or invalid API key
404Prompt template not found, version not found, label not found

Headers

​
X-API-KEY
string
required

Path Parameters

​
identifier
string
required

The prompt template name or ID.

Body

application/json
​
version
integer | null

The base version number to patch from. Mutually exclusive with label. If neither is provided, the latest version is used.

Required range: x > 0
​
label
string | null

The release label identifying the base version to patch from (e.g. 'prod', 'staging'). Mutually exclusive with version.

​
messages

Index-based patch. Keys are string indices (e.g. "0", "1"), values are the replacement message objects.

​
tools

Patch for tools. Object for index-based patching, array for full replacement, null to remove. Chat templates only.

​
functions

Patch for functions. Object for index-based patching, array for full replacement, null to remove. Chat templates only.

​
function_call

Replace the function_call setting. Set to null to remove. Chat templates only.

​
tool_choice

Replace the tool_choice setting. Set to null to remove. Chat templates only.

​
content

Patch for completion template content. Object for index-based patching, array for full replacement. Completion templates only.

​
model_parameters
Model Parameters · object

Parameters to shallow-merge into the existing model parameters (e.g. temperature, max_tokens). Existing keys not specified here are preserved.

​
response_format
Response Format · object

Convenience field to set response_format in model parameters. Cannot be used simultaneously with response_format inside model_parameters. Set to null to remove.

​
commit_message
string | null

A message describing the changes in this version.

​
release_labels
string[] | null

Release labels to create or move to the newly created version (e.g. ['staging', 'production']).

Response

New version created successfully

​
id
integer
required

The ID of the prompt template.

​
prompt_name
string
required

The name of the prompt template.

​
prompt_version_id
integer
required

The ID of the created prompt version.

​
version_number
integer
required

The version number of the prompt template.

​
tags
string[]
required
​
prompt_template
Completion Template · object
required
​
release_labels
string[] | null
​
metadata
Metadata · object

Metadata associated with the prompt blueprint. Supports additional custom fields beyond the model field.

​
commit_message
string | null