Skip to main content
The Presets API allows you to create, retrieve, and delete conversation presets, which are saved configurations for model settings, parameters, and templates that can be reused across conversations.

​
Authentication

All endpoints require JWT authentication via the Authorization header: 
Authorization: Bearer <your_jwt_token>

​
List Presets

curl -X GET "https://your-domain.com/api/presets" \
  -H "Authorization: Bearer <token>"
Retrieve all presets for the authenticated user.

​
Response

Returns an array of preset objects.
​
presets
array

​
Create or Update Preset

curl -X POST "https://your-domain.com/api/presets" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "GPT-4 Creative Writer",
    "endpoint": "openAI",
    "model": "gpt-4",
    "temperature": 0.9,
    "top_p": 0.95,
    "max_tokens": 2000,
    "promptPrefix": "You are a creative writing assistant."
  }'
Create a new preset or update an existing one. If presetId is provided and exists, the preset will be updated; otherwise, a new preset is created.

​
Request Body

​
presetId
string
Preset ID (UUID). If omitted, a new UUID will be generated
​
title
string
required
Preset name/title
​
endpoint
string
required
Model endpoint identifier
​
model
string
required
Model identifier
​
temperature
number
Temperature (0-2, default varies by model)
​
top_p
number
Top-p sampling (0-1)
​
topK
number
Top-k sampling (provider-specific)
​
frequency_penalty
number
Frequency penalty (0-2)
​
presence_penalty
number
Presence penalty (0-2)
​
max_tokens
integer
Maximum tokens to generate
​
maxContextTokens
integer
Maximum context window size
​
promptPrefix
string
System message or prompt prefix
​
instructions
string
Agent/assistant instructions
​
tools
array
Array of enabled tool identifiers
​
stop
array
Array of stop sequences
​
iconURL
string
Custom icon URL
​
greeting
string
Initial greeting message
​
modelLabel
string
Custom model display label
​
chatGptLabel
string
Custom chat label
​
resendFiles
boolean
Whether to resend files in context
​
imageDetail
string
Image detail level: “auto”, “low”, or “high”
​
artifacts
boolean
Enable artifacts (code blocks, formatted content)

​
Response

Returns the created or updated preset object with status 201 Created.

​
Error Responses

  • 500 Internal Server Error: Failed to save preset

​
Delete Preset

curl -X POST "https://your-domain.com/api/presets/delete" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "presetId": "<preset_id>"
  }'
Delete a specific preset or all presets if no presetId is provided.

​
Request Body

​
presetId
string
The preset ID to delete. If omitted, all user presets will be deleted.

​
Response

Returns the number of deleted presets.
​
deletedCount
integer
Number of presets deleted

​
Error Responses

  • 500 Internal Server Error: Deletion failed

​
Preset Structure Details

​
Endpoint-Specific Parameters

Different endpoints support different parameters:

​
OpenAI / Azure OpenAI

  • temperature, top_p, frequency_penalty, presence_penalty
  • max_tokens, stop
  • response_format (for JSON mode)

​
Anthropic

  • temperature, top_p, top_k
  • max_tokens, stop_sequences
  • thinking (extended thinking mode)

​
Google

  • temperature, topP, topK
  • maxOutputTokens
  • safetySettings

​
Agents

  • temperature, top_p
  • max_tokens
  • tools (array of tool identifiers)
  • instructions (system prompt)
  • provider (underlying model provider)

​
Common Use Cases

  1. Creative Writing: High temperature (0.8-1.0), high top_p
  2. Code Generation: Lower temperature (0.2-0.4), focused sampling
  3. Factual Q&A: Low temperature (0.1-0.3), deterministic output
  4. Customer Support: Medium temperature (0.5-0.7), balanced creativity

​
Example Presets

​
GPT-4 Code Assistant

{
  "title": "GPT-4 Code Assistant",
  "endpoint": "openAI",
  "model": "gpt-4",
  "temperature": 0.3,
  "top_p": 0.95,
  "max_tokens": 4000,
  "promptPrefix": "You are an expert programmer. Provide clear, well-commented code.",
  "tools": ["code_interpreter"]
}

​
Claude Creative Writer

{
  "title": "Claude Creative Writer",
  "endpoint": "anthropic",
  "model": "claude-3-opus-20240229",
  "temperature": 0.9,
  "top_p": 0.95,
  "top_k": 40,
  "max_tokens": 4096,
  "promptPrefix": "You are a creative writing assistant with a focus on vivid storytelling."
}

​
Research Agent

{
  "title": "Research Agent",
  "endpoint": "agents",
  "model": "gpt-4",
  "provider": "openAI",
  "temperature": 0.5,
  "max_tokens": 8000,
  "instructions": "You are a research assistant. Gather information from multiple sources and synthesize findings.",
  "tools": ["web_search", "file_search"]
}

​
Common Error Codes

Status CodeDescription
400Bad Request - Invalid parameters or malformed request
401Unauthorized - Invalid or missing JWT token
500Internal Server Error - Failed to save or delete preset

Build docs developers (and LLMs) love

Get started for freeTalk to us