Skip to main content
PUT
/
prompt-templates
/
by-external-id
/
{source}
/
{external_id}
Upsert Prompt Template by External ID
curl --request PUT \
  --url https://api.promptlayer.com/prompt-templates/by-external-id/{source}/{external_id} \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '
{
  "prompt_template": {
    "prompt_name": "<string>",
    "tags": [],
    "folder_id": 1,
    "workspace_id": 123
  },
  "prompt_version": {
    "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"
    },
    "commit_message": "<string>",
    "metadata": {
      "model": {
        "provider": "<string>",
        "name": "<string>",
        "model_config_display_name": "<string>",
        "base_model": "<string>",
        "parameters": {},
        "display_params": {},
        "api_type": "<string>"
      }
    }
  },
  "release_labels": [
    "<string>"
  ],
  "external_ids": [
    {
      "source": "<string>",
      "external_id": "<string>"
    }
  ]
}
'
import requests

url = "https://api.promptlayer.com/prompt-templates/by-external-id/{source}/{external_id}"

payload = {
    "prompt_template": {
        "prompt_name": "<string>",
        "tags": [],
        "folder_id": 1,
        "workspace_id": 123
    },
    "prompt_version": {
        "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"
        },
        "commit_message": "<string>",
        "metadata": { "model": {
                "provider": "<string>",
                "name": "<string>",
                "model_config_display_name": "<string>",
                "base_model": "<string>",
                "parameters": {},
                "display_params": {},
                "api_type": "<string>"
            } }
    },
    "release_labels": ["<string>"],
    "external_ids": [
        {
            "source": "<string>",
            "external_id": "<string>"
        }
    ]
}
headers = {
    "X-API-KEY": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.text)
const options = {
  method: 'PUT',
  headers: {'X-API-KEY': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    prompt_template: {prompt_name: '<string>', tags: [], folder_id: 1, workspace_id: 123},
    prompt_version: {
      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'
      },
      commit_message: '<string>',
      metadata: {
        model: {
          provider: '<string>',
          name: '<string>',
          model_config_display_name: '<string>',
          base_model: '<string>',
          parameters: {},
          display_params: {},
          api_type: '<string>'
        }
      }
    },
    release_labels: ['<string>'],
    external_ids: [{source: '<string>', external_id: '<string>'}]
  })
};

fetch('https://api.promptlayer.com/prompt-templates/by-external-id/{source}/{external_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.promptlayer.com/prompt-templates/by-external-id/{source}/{external_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => json_encode([
    'prompt_template' => [
        'prompt_name' => '<string>',
        'tags' => [
                
        ],
        'folder_id' => 1,
        'workspace_id' => 123
    ],
    'prompt_version' => [
        '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'
        ],
        'commit_message' => '<string>',
        'metadata' => [
                'model' => [
                                'provider' => '<string>',
                                'name' => '<string>',
                                'model_config_display_name' => '<string>',
                                'base_model' => '<string>',
                                'parameters' => [
                                                                
                                ],
                                'display_params' => [
                                                                
                                ],
                                'api_type' => '<string>'
                ]
        ]
    ],
    'release_labels' => [
        '<string>'
    ],
    'external_ids' => [
        [
                'source' => '<string>',
                'external_id' => '<string>'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-KEY: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.promptlayer.com/prompt-templates/by-external-id/{source}/{external_id}"

	payload := strings.NewReader("{\n  \"prompt_template\": {\n    \"prompt_name\": \"<string>\",\n    \"tags\": [],\n    \"folder_id\": 1,\n    \"workspace_id\": 123\n  },\n  \"prompt_version\": {\n    \"prompt_template\": {\n      \"content\": [\n        {\n          \"text\": \"<string>\",\n          \"type\": \"text\",\n          \"id\": \"<string>\",\n          \"annotations\": [\n            {\n              \"type\": \"<string>\",\n              \"title\": \"<string>\",\n              \"url\": \"<string>\",\n              \"start_index\": 123,\n              \"end_index\": 123,\n              \"cited_text\": \"<string>\",\n              \"encrypted_index\": \"<string>\"\n            }\n          ],\n          \"thought_signature\": \"<string>\"\n        }\n      ],\n      \"input_variables\": [],\n      \"template_format\": \"f-string\",\n      \"type\": \"completion\"\n    },\n    \"commit_message\": \"<string>\",\n    \"metadata\": {\n      \"model\": {\n        \"provider\": \"<string>\",\n        \"name\": \"<string>\",\n        \"model_config_display_name\": \"<string>\",\n        \"base_model\": \"<string>\",\n        \"parameters\": {},\n        \"display_params\": {},\n        \"api_type\": \"<string>\"\n      }\n    }\n  },\n  \"release_labels\": [\n    \"<string>\"\n  ],\n  \"external_ids\": [\n    {\n      \"source\": \"<string>\",\n      \"external_id\": \"<string>\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("X-API-KEY", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
HttpResponse<String> response = Unirest.put("https://api.promptlayer.com/prompt-templates/by-external-id/{source}/{external_id}")
  .header("X-API-KEY", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"prompt_template\": {\n    \"prompt_name\": \"<string>\",\n    \"tags\": [],\n    \"folder_id\": 1,\n    \"workspace_id\": 123\n  },\n  \"prompt_version\": {\n    \"prompt_template\": {\n      \"content\": [\n        {\n          \"text\": \"<string>\",\n          \"type\": \"text\",\n          \"id\": \"<string>\",\n          \"annotations\": [\n            {\n              \"type\": \"<string>\",\n              \"title\": \"<string>\",\n              \"url\": \"<string>\",\n              \"start_index\": 123,\n              \"end_index\": 123,\n              \"cited_text\": \"<string>\",\n              \"encrypted_index\": \"<string>\"\n            }\n          ],\n          \"thought_signature\": \"<string>\"\n        }\n      ],\n      \"input_variables\": [],\n      \"template_format\": \"f-string\",\n      \"type\": \"completion\"\n    },\n    \"commit_message\": \"<string>\",\n    \"metadata\": {\n      \"model\": {\n        \"provider\": \"<string>\",\n        \"name\": \"<string>\",\n        \"model_config_display_name\": \"<string>\",\n        \"base_model\": \"<string>\",\n        \"parameters\": {},\n        \"display_params\": {},\n        \"api_type\": \"<string>\"\n      }\n    }\n  },\n  \"release_labels\": [\n    \"<string>\"\n  ],\n  \"external_ids\": [\n    {\n      \"source\": \"<string>\",\n      \"external_id\": \"<string>\"\n    }\n  ]\n}")
  .asString();
require 'uri'
require 'net/http'

url = URI("https://api.promptlayer.com/prompt-templates/by-external-id/{source}/{external_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)
request["X-API-KEY"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"prompt_template\": {\n    \"prompt_name\": \"<string>\",\n    \"tags\": [],\n    \"folder_id\": 1,\n    \"workspace_id\": 123\n  },\n  \"prompt_version\": {\n    \"prompt_template\": {\n      \"content\": [\n        {\n          \"text\": \"<string>\",\n          \"type\": \"text\",\n          \"id\": \"<string>\",\n          \"annotations\": [\n            {\n              \"type\": \"<string>\",\n              \"title\": \"<string>\",\n              \"url\": \"<string>\",\n              \"start_index\": 123,\n              \"end_index\": 123,\n              \"cited_text\": \"<string>\",\n              \"encrypted_index\": \"<string>\"\n            }\n          ],\n          \"thought_signature\": \"<string>\"\n        }\n      ],\n      \"input_variables\": [],\n      \"template_format\": \"f-string\",\n      \"type\": \"completion\"\n    },\n    \"commit_message\": \"<string>\",\n    \"metadata\": {\n      \"model\": {\n        \"provider\": \"<string>\",\n        \"name\": \"<string>\",\n        \"model_config_display_name\": \"<string>\",\n        \"base_model\": \"<string>\",\n        \"parameters\": {},\n        \"display_params\": {},\n        \"api_type\": \"<string>\"\n      }\n    }\n  },\n  \"release_labels\": [\n    \"<string>\"\n  ],\n  \"external_ids\": [\n    {\n      \"source\": \"<string>\",\n      \"external_id\": \"<string>\"\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body
{
  "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"
  },
  "external_ids": [
    {
      "source": "<string>",
      "external_id": "<string>"
    }
  ],
  "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>"
}
{
  "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"
  },
  "external_ids": [
    {
      "source": "<string>",
      "external_id": "<string>"
    }
  ],
  "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>"
}
{
  "message": "<string>",
  "success": false
}
{
  "message": "<string>",
  "success": false
}
{
  "message": "<string>",
  "success": false
}
{
  "message": "<string>",
  "success": false
}
{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}
Publish a prompt template by a customer-defined external ID. If the mapping already exists, PromptLayer creates a new version on the mapped prompt template. If the mapping does not exist, PromptLayer creates or updates the prompt template from the request body and attaches the mapping. This is the only external ID endpoint that uses PUT. See External IDs for mapping rules and conflict behavior.

Authorizations

​
X-API-KEY
string
header
required

Path Parameters

​
source
string
required

External ID source.

Required string length: 1 - 128
​
external_id
string
required

External ID value. URL-encode any reserved path characters.

Required string length: 1 - 512

Body

application/json
​
prompt_template
BasePromptTemplate · object
required

Template metadata, including prompt name, tags, folder, and workspace fields.

​
prompt_version
PromptVersion · object
required

Version content and configuration.

​
release_labels
string[] | null

Release labels to create or move to the newly created version.

​
external_ids
ExternalId · object[] | null

Identifiers from other systems.

Response

Prompt template updated

​
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
​
external_ids
ExternalId · object[]
required

External ID mappings attached to the prompt template.

​
release_labels
string[] | null
​
metadata
Metadata · object | null

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

​
commit_message
string | null