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: <x-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>"
    }
  ]
}
'
{
  "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>"
}

Documentation Index

Fetch the complete documentation index at: https://docs.promptlayer.com/llms.txt

Use this file to discover all available pages before exploring further.

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.

Headers

X-API-KEY
string
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

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

commit_message
string | null