Update Prompt

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
    }
  }'

const response = await fetch('https://api.helicone.ai/v1/prompt-2025/update', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    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,
    },
  }),
});

const result = await response.json();

import requests

response = requests.post(
    'https://api.helicone.ai/v1/prompt-2025/update',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json',
    },
    json={
        '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,
        },
    },
)

result = response.json()

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

{
  "data": null,
  "error": "Failed to create new version"
}

POST

prompt-2025

update

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
    }
  }'

const response = await fetch('https://api.helicone.ai/v1/prompt-2025/update', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    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,
    },
  }),
});

const result = await response.json();

import requests

response = requests.post(
    'https://api.helicone.ai/v1/prompt-2025/update',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json',
    },
    json={
        '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,
        },
    },
)

result = response.json()

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

{
  "data": null,
  "error": "Failed to create new version"
}

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

string

required

The unique identifier of the prompt to update

string

required

The version ID to base the new version on

boolean

required

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

string

required

Description of the changes in this version

string

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

object

required

The updated prompt content in OpenAI chat format

Show Prompt Body

string

The model to use

array

Array of message objects with role and content

number

Sampling temperature (0-2)

number

Nucleus sampling parameter

number

Maximum tokens to generate

array

Array of tool/function definitions

string | object

Controls which tool to call

Response

object

string

The unique identifier for the new version

string | null

Error message if the request failed, null otherwise

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
    }
  }'

const response = await fetch('https://api.helicone.ai/v1/prompt-2025/update', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    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,
    },
  }),
});

const result = await response.json();

import requests

response = requests.post(
    'https://api.helicone.ai/v1/prompt-2025/update',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json',
    },
    json={
        '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,
        },
    },
)

result = response.json()

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

{
  "data": null,
  "error": "Failed to create new version"
}

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

⌘I

Overview

AI Gateway

Requests

Sessions

Prompts

Evaluations

Webhooks

Users

Request Body

Response

Version Management

Minor Versions

Major Versions

​Request Body

​Response

​Version Management

​Minor Versions

​Major Versions

Request Body

Response

Version Management

Minor Versions

Major Versions