--- title: "Upsert Prompt Template by External ID" method: PUT path: "/prompt-templates/by-external-id/{source}/{external_id}" tags: ["external-ids", "prompt-templates"] --- # Upsert Prompt Template by External ID `PUT /prompt-templates/by-external-id/{source}/{external_id}` ## Path parameters - `source` string, required - `external_id` string, required ## Request body - CreatePromptTemplate - `prompt_template` BasePromptTemplate, required - `prompt_name` string, required — The unique prompt name within the workspace. 1-512 characters. - `tags` string[] — Tags to attach to the prompt registry entry. - `folder_id` integer, nullable — The ID of the folder to publish the prompt template into. If omitted, the prompt is created at the workspace root. Use Resolve Folder ID by Path to look up an ID from a path, or Create Folder to make one. - `workspace_id` integer, nullable — Optional workspace override; defaults to the workspace associated with the API key. - `prompt_version` PromptVersion, required - `prompt_template` union, required — The prompt content, either chat or completion. - CompletionPrompt - `content` union[], required - union - TextContent - … - ThinkingContent - … - CodeContent — Code content block (e.g. from code execution tools). - … - ImageContent - … - MediaContent - … - MediaVariable - … - OutputMediaContent — LLM-generated media output (e.g. from image generation tools). - … - ServerToolUseContent — Server-side tool use block (e.g. web search, code execution). - … - WebSearchToolResultContent — Results from a web search tool invocation. - … - CodeExecutionResultContent — Result from a code execution tool. - … - McpListToolsContent — MCP list tools response block. - … - McpCallContent — MCP tool call block. - … - McpApprovalRequestContent — MCP tool approval request block. - … - McpApprovalResponseContent — MCP tool approval response block. - … - BashCodeExecutionToolResultContent — Result from bash code execution tool. - … - TextEditorCodeExecutionToolResultContent — Result from text editor code execution tool. - … - ShellCallContent — Shell tool call block. - … - ShellCallOutputContent — Shell tool output block. - … - ApplyPatchCallContent — Apply patch tool call block. - … - ApplyPatchCallOutputContent — Apply patch tool output block. - … - `input_variables` string[] - `template_format` 'f-string' | 'jinja2' - `type` 'completion' - ChatPrompt - `messages` union[], required - union - SystemMessage - … - UserMessage - … - AssistantMessage - … - FunctionMessage - … - ToolMessage - … - PlaceholderMessage - … - DeveloperMessage - … - `functions` Function[], nullable - `name` string, required - `description` string - `strict` boolean — Whether to enable strict schema validation for the function parameters. - `parameters` object - `tools` Tool[], nullable - union - FunctionTool — A custom function tool definition. - … - BuiltInTool — A provider-native built-in tool (e.g. web search, code interpreter, bash). - … - `function_call` union - string - MessageFunctionCall - `name` string, required - `tool_choice` union - string - ChatToolChoice - `type` 'function' - `function` MessageFunctionCall, required - … - `type` 'chat' - `input_variables` string[] - `commit_message` string, nullable — Message describing the changes in this version. Maximum 72 characters. - `metadata` Metadata — Metadata associated with the prompt blueprint. Supports additional custom fields beyond the model field. - `model` Model - `provider` string, required — The LLM provider (e.g. openai, anthropic, google, openai.azure, vertexai, mistral, cohere, amazon.bedrock, huggingface). - `model_config_display_name` string, nullable — Optional display name for the model configuration. - `base_model` string, nullable — The base model name (e.g. for fine-tuned models). - `name` string, required — The model name (e.g. gpt-4o, claude-sonnet-4-20250514). - `parameters` object — Model parameters (e.g. temperature, max_tokens, top_p). - `display_params` object — Display-friendly parameter values shown in the UI. - `api_type` string, nullable — The API type (e.g. chat.completions, responses, images). Used to select the correct API endpoint for the provider. - `release_labels` string[], nullable — Release labels to create or move to the newly created version. - `external_ids` ExternalId[], nullable — Identifiers from other systems. - `source` string, required — The external system or namespace that owns the ID. - `external_id` string, required — The identifier for this entity in the external system. ## Response `200` Prompt template updated - CreatePromptTemplateResponse - `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 - `release_labels` string[], nullable - `prompt_template` union, required - CompletionPrompt - `content` union[], required - union - TextContent - `type` 'text' - `text` string, required - `id` string, nullable - `annotations` union[], nullable — Citations and references within the text (web citations, file citations, map citations, container file citations). - … - `thought_signature` string, nullable - ThinkingContent - `signature` string, nullable - `type` 'thinking' - `thinking` string, required - `id` string, nullable - CodeContent — Code content block (e.g. from code execution tools). - `type` 'code' - `code` string, required - `id` string, nullable - `container_id` string, nullable - ImageContent - `type` 'image_url' - `image_url` ImageURL, required - … - `image_variable` string, nullable - MediaContent - `type` 'media' - `media` Media, required - … - MediaVariable - `type` 'media_variable' - `name` string, required — Name of the media variable - OutputMediaContent — LLM-generated media output (e.g. from image generation tools). - `type` 'output_media' - `id` string, nullable - `url` string, required - `mime_type` string - `media_type` 'image' | 'video' | 'audio' - `provider_metadata` object, nullable - ServerToolUseContent — Server-side tool use block (e.g. web search, code execution). - `type` 'server_tool_use' - `id` string, required - `name` string, required - `input` object - WebSearchToolResultContent — Results from a web search tool invocation. - `type` 'web_search_tool_result' - `tool_use_id` string, required - `content` WebSearchResult[] - … - CodeExecutionResultContent — Result from a code execution tool. - `type` 'code_execution_result' - `output` string, required - `outcome` string - McpListToolsContent — MCP list tools response block. - `type` 'mcp_list_tools' - `id` string, nullable - `server_label` string - `tools` object[] - … - `error` union - … - McpCallContent — MCP tool call block. - `type` 'mcp_call' - `id` string, nullable - `name` string - `server_label` string - `arguments` string - `output` string, nullable - `error` union - … - `approval_request_id` string, nullable - McpApprovalRequestContent — MCP tool approval request block. - `type` 'mcp_approval_request' - `id` string, nullable - `name` string - `arguments` string - `server_label` string - McpApprovalResponseContent — MCP tool approval response block. - `type` 'mcp_approval_response' - `approval_request_id` string, required - `approve` boolean, required - BashCodeExecutionToolResultContent — Result from bash code execution tool. - `type` 'bash_code_execution_tool_result' - `tool_use_id` string, required - `content` object - TextEditorCodeExecutionToolResultContent — Result from text editor code execution tool. - `type` 'text_editor_code_execution_tool_result' - `tool_use_id` string, required - `content` object - ShellCallContent — Shell tool call block. - `type` 'shell_call' - `id` string, nullable - `call_id` string, nullable - `action` object - `status` string, nullable - ShellCallOutputContent — Shell tool output block. - `type` 'shell_call_output' - `id` string, nullable - `call_id` string, nullable - `output` object[] - … - `status` string, nullable - ApplyPatchCallContent — Apply patch tool call block. - `type` 'apply_patch_call' - `id` string, nullable - `call_id` string, nullable - `operation` object - `status` string, nullable - ApplyPatchCallOutputContent — Apply patch tool output block. - `type` 'apply_patch_call_output' - `id` string, nullable - `call_id` string, nullable - `output` string, nullable - `status` string, nullable - `input_variables` string[] - `template_format` 'f-string' | 'jinja2' - `type` 'completion' - ChatPrompt - `messages` union[], required - union - SystemMessage - `input_variables` string[] - `template_format` 'f-string' | 'jinja2' - `content` union[], required - … - `role` 'system' - `name` string, nullable - UserMessage - `input_variables` string[] - `template_format` 'f-string' | 'jinja2' - `content` union[], required - … - `role` 'user' - `name` string, nullable - AssistantMessage - `input_variables` string[] - `template_format` 'f-string' | 'jinja2' - `content` union[], nullable - … - `role` 'assistant' - `function_call` FunctionCall - … - `name` string, nullable - `tool_calls` ToolCall[], nullable - … - FunctionMessage - `input_variables` string[] - `template_format` 'f-string' | 'jinja2' - `content` union[], nullable - … - `role` 'function' - `name` string, required - ToolMessage - `input_variables` string[] - `template_format` 'f-string' | 'jinja2' - `content` union[], required - … - `role` 'tool' - `tool_call_id` string, required - `name` string, nullable - PlaceholderMessage - `input_variables` string[] - `template_format` 'f-string' | 'jinja2' - `content` union[], nullable - … - `raw_request_display_role` string - `role` 'placeholder' - `name` string, required - DeveloperMessage - `input_variables` string[] - `template_format` 'f-string' | 'jinja2' - `content` union[], required - … - `role` 'developer' - `name` string, nullable - `functions` Function[], nullable - `name` string, required - `description` string - `strict` boolean — Whether to enable strict schema validation for the function parameters. - `parameters` object - `tools` Tool[], nullable - union - FunctionTool — A custom function tool definition. - `type` 'function' - `function` Function, required - … - BuiltInTool — A provider-native built-in tool (e.g. web search, code interpreter, bash). - `id` string, required - `name` string, required - `description` string, required - `provider` string, required - `type` 'web_search' | 'file_search' | 'code_interpreter' | 'image_generation' | 'google_maps' | 'url_context' | 'mcp' | 'bash' | 'shell' | 'apply_patch' | 'text_editor', required - `config` object, required — Provider-specific tool configuration. Structure varies by provider and tool type. - `function_call` union - string - MessageFunctionCall - `name` string, required - `tool_choice` union - string - ChatToolChoice - `type` 'function' - `function` MessageFunctionCall, required - `name` string, required - `type` 'chat' - `input_variables` string[] - `metadata` Metadata — Metadata associated with the prompt blueprint. Supports additional custom fields beyond the model field. - `model` Model - `provider` string, required — The LLM provider (e.g. openai, anthropic, google, openai.azure, vertexai, mistral, cohere, amazon.bedrock, huggingface). - `model_config_display_name` string, nullable — Optional display name for the model configuration. - `base_model` string, nullable — The base model name (e.g. for fine-tuned models). - `name` string, required — The model name (e.g. gpt-4o, claude-sonnet-4-20250514). - `parameters` object — Model parameters (e.g. temperature, max_tokens, top_p). - `display_params` object — Display-friendly parameter values shown in the UI. - `api_type` string, nullable — The API type (e.g. chat.completions, responses, images). Used to select the correct API endpoint for the provider. - `commit_message` string, nullable - `external_ids` ExternalId[], required — External ID mappings attached to the prompt template. - `source` string, required — The external system or namespace that owns the ID. - `external_id` string, required — The identifier for this entity in the external system. ## Other responses - `201` — Prompt template created - `400` — Bad Request - `401` — Unauthorized - `404` — Entity Not Found - `409` — Conflict - `422` — Validation Error --- [API](https://skmtc.net/promptlayer/apis/promptlayer-api.md) · [All operations](https://skmtc.net/promptlayer/apis/promptlayer-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/promptlayer/promptlayer-api/revisions/a23093a0a506/schema)