Create Prompt

Create a new prompt with initial version

POST /v1/prompt-2025

cURL

curl -X POST https://api.helicone.ai/v1/prompt-2025 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Support Agent",
    "tags": ["support", "customer-service"],
    "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.7,
      "max_tokens": 500
    }
  }'

201 Success

{
  "data": {
    "id": "prompt_abc123xyz",
    "versionId": "version_def456uvw"
  },
  "error": null
}

Creates a new prompt template with an initial version. The prompt body uses the OpenAI chat format.

Request Body

name · string · required

Name of the prompt template

tags · string[] · required

Array of tags to categorize the prompt

promptBody · object · required

The prompt content in OpenAI chat format

Show Prompt Body

model · string

The model to use (e.g., “gpt-4o”, “claude-3-sonnet-20240229”)

messages · array

Array of message objects

Show Message Object

role · string · required

Message role: “system”, “user”, “assistant”, “developer”, “tool”, or “function”

content · string | array | null · required

Message content. Can be:

• A string for simple text messages
• An array of content parts for multi-modal messages
• null for certain message types

name · string

Optional name for the message

tool_call_id · string

Required for tool messages

tool_calls · array

Tool calls made by the assistant

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

Show Tool Object

type · string

Must be “function”

function · object

Function definition with name, description, and parameters

tool_choice · string | object

Controls which tool to call: “auto”, “none”, or specific tool

Response

data · object

id · string

The unique identifier for the created prompt

versionId · string

The unique identifier for the initial version

error · string | null

Error message if the request failed, null otherwise

cURL

curl -X POST https://api.helicone.ai/v1/prompt-2025 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Support Agent",
    "tags": ["support", "customer-service"],
    "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.7,
      "max_tokens": 500
    }
  }'

201 Success

{
  "data": {
    "id": "prompt_abc123xyz",
    "versionId": "version_def456uvw"
  },
  "error": null
}