Update Prompt

Create a new version of an existing prompt

POST /v1/prompt-2025/update

cURL

curl -X POST https://api.helicone.ai/v1/prompt-2025/update \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "promptId": "prompt_abc123xyz",
    "promptVersionId": "version_def456uvw",
    "newMajorVersion": false,
    "commitMessage": "Updated temperature and added max_tokens",
    "environment": "production",
    "promptBody": {
      "model": "gpt-4o",
      "messages": [
        {
          "role": "system",
          "content": "You are a helpful customer support agent. Be polite and professional."
        },
        {
          "role": "user",
          "content": "{{user_question}}"
        }
      ],
      "temperature": 0.5,
      "max_tokens": 750
    }
  }'

200 Success

{
  "data": {
    "id": "version_ghi789rst"
  },
  "error": null
}

Creates a new version of an existing prompt. You can create either a minor version (incremental updates) or a major version (breaking changes).

Request Body

promptId · string · required

The unique identifier of the prompt to update

promptVersionId · string · required

The version ID to base the new version on

newMajorVersion · boolean · required

Whether to create a new major version (true) or minor version (false)

commitMessage · string · required

Description of the changes in this version

environment · string

Optional environment to associate with this version (e.g., “production”, “staging”)

promptBody · object · required

The updated prompt content in OpenAI chat format

Show Prompt Body

model · string

The model to use

messages · array

Array of message objects with role and content

temperature · number

Sampling temperature (0-2)

top_p · number

Nucleus sampling parameter

max_tokens · number

Maximum tokens to generate

tools · array

Array of tool/function definitions

tool_choice · string | object

Controls which tool to call

Response

data · object

id · string

The unique identifier for the new version

error · string | null

Error message if the request failed, null otherwise

cURL

curl -X POST https://api.helicone.ai/v1/prompt-2025/update \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "promptId": "prompt_abc123xyz",
    "promptVersionId": "version_def456uvw",
    "newMajorVersion": false,
    "commitMessage": "Updated temperature and added max_tokens",
    "environment": "production",
    "promptBody": {
      "model": "gpt-4o",
      "messages": [
        {
          "role": "system",
          "content": "You are a helpful customer support agent. Be polite and professional."
        },
        {
          "role": "user",
          "content": "{{user_question}}"
        }
      ],
      "temperature": 0.5,
      "max_tokens": 750
    }
  }'

200 Success

{
  "data": {
    "id": "version_ghi789rst"
  },
  "error": null
}

Version Management

Minor Versions

Set newMajorVersion: false for incremental updates:

• Bug fixes
• Small improvements
• Configuration tweaks

Example: 1.0 → 1.1 → 1.2

Major Versions

Set newMajorVersion: true for breaking changes:

• Complete rewrites
• Structural changes
• Different model or approach

Example: 1.5 → 2.0 → 3.0