Messages | PrivateGPT

Generate a chat completion from a conversation history.

This endpoint enables multi-turn conversations with the AI model, with optional tool support and comprehensive message validation.

Key Features:

Multi-turn conversations: Support for system, user, and assistant messages
Tool Support: Full tool use/result validation with automatic or manual selection
Citations: Enable system.citations.enabled to include references in responses
Streaming: Enable stream for partial updates in real-time
Default Prompts: Enable system.use_default_prompt for using Zylon prompts
Thinking: Enable thinking.enabled for step-by-step reasoning capabilities
Sampling Parameters: Control randomness with temperature, top_p, top_k, etc.

Notes:

Tool use/result blocks must be properly paired within assistant messages
Tool choice type must be ‘auto’, ‘tool’, or ‘none’
When tool_choice.type is ‘tool’, tool_choice.name must specify a valid tool
All message content is validated for completeness and proper structure
Last message must be from user or assistant for proper conversation flow
MCP servers provide external tool capabilities via Model Context Protocol
Sampling parameters control response randomness and token selection

Generate a chat completion from a conversation history. This endpoint enables multi-turn conversations with the AI model, with optional tool support and comprehensive message validation. Key Features: * Multi-turn conversations: Support for system, user, and assistant messages * Tool Support: Full tool use/result validation with automatic or manual selection * Citations: Enable `system.citations.enabled` to include references in responses * Streaming: Enable `stream` for partial updates in real-time * Default Prompts: Enable `system.use_default_prompt` for using Zylon prompts * Thinking: Enable `thinking.enabled` for step-by-step reasoning capabilities * Sampling Parameters: Control randomness with temperature, top_p, top_k, etc. Notes: * Tool use/result blocks must be properly paired within assistant messages * Tool choice type must be 'auto', 'tool', or 'none' * When tool_choice.type is 'tool', tool_choice.name must specify a valid tool * All message content is validated for completeness and proper structure * Last message must be from user or assistant for proper conversation flow * MCP servers provide external tool capabilities via Model Context Protocol * Sampling parameters control response randomness and token selection

Request

Request body for chat completion supporting multi-turn conversations with AI models.

Contains message history, tool definitions, system prompts, and response configuration. Supports both streaming and non-streaming responses with optional tool usage, citations, and advanced sampling parameters.

The request body defines the complete conversation context and AI behavior parameters for generating responses.

Request body for chat completion supporting multi-turn conversations with AI models. Contains message history, tool definitions, system prompts, and response configuration. Supports both streaming and non-streaming responses with optional tool usage, citations, and advanced sampling parameters. The request body defines the complete conversation context and AI behavior parameters for generating responses.

modelstringRequiredDefaults to default

Model identifier or alias.

messageslist of objectsRequired

Conversation messages for the request.

max_tokensintegerRequired>=1

Maximum number of tokens to generate in the response.

systemlist of objectsOptional

System prompt input. Accepts str, list[str], System, list[System], or null. It is normalized internally to list[System].

toolslist of objects or nullOptional

Optional tool definitions.

thinkingobjectOptional

Thinking configuration.

tool_choiceobjectOptional

Tool selection policy.

output_configobjectOptional

Optional output configuration options.

cache_controlobject or nullOptional

Optional request-level cache control.

streambooleanOptionalDefaults to false

Whether to stream the response back to the client.

tool_contextlist of objects or nullOptional

Context to provide to the tools, such as documents, databases connection strings, or data relevant to tool usage.

mcp_serverslist of objectsOptional

List of MCP servers to use for tool retrieval. Each server can have its own configuration.

containerstring or nullOptional

Container identifier for reuse across requests.

response_formatobjectOptional

Deprecated response format. Use output_config.format instead.

priorityinteger or nullOptional

Priority of the request, used for prioritizing responses.

seedinteger or nullOptional

Random seed for reproducibility.

min_pdouble or nullOptional

Minimum probability threshold for token selection. Tokens with probability below this value are filtered out.

top_pdoubleOptional0-1

Nucleus sampling parameter. Only tokens with cumulative probability up to this value are considered.

temperaturedoubleOptional0-1

Controls randomness in generation. Higher values make output more random, lower values more deterministic.

top_kintegerOptional>=0

Limits token selection to the top K most likely tokens at each step.

repetition_penaltydouble or nullOptional

Penalty applied to tokens that have already appeared in the sequence to reduce repetition.

presence_penaltydouble or nullOptional

Penalty applied based on whether a token has appeared in the text, encouraging topic diversity.

frequency_penaltydouble or nullOptional

Penalty applied based on how frequently a token appears in the text, reducing repetitive content.

stop_sequenceslist of stringsOptional

Custom stop sequences that stop generation when matched.

metadataobjectOptional

Request metadata (for example, user_id).

service_tierenumOptionalDefaults to auto

Service tier preference (for example, “auto” or “standard_only”).

inference_geostring or nullOptional

Geographic region hint for inference processing.

correlation_idstring or nullOptional

Correlation ID for tracking the request across systems.

maximum_loaded_skillsinteger or nullOptional>=1

Optional cap for concurrently loaded skills in a conversation. When exceeded, the oldest loaded skill is evicted.

Response

Successful chat message

idstring

Message identifier.

type"message"Defaults to message

Object type.

role"assistant"Defaults to assistant

Message author role.

contentlist of objects

Assistant content blocks.

modelstringDefaults to private-gpt

Model name used.

containerobject or null

Optional execution container.

stop_detailsobject or null

Optional structured stop details.

stop_reasonstring or null

Message stop reason.

stop_sequencestring or null

Matched stop sequence, if any.

usageobject

Token usage stats.

Errors

401

Unauthorized Error

Generate a chat completion from a conversation history.

This endpoint enables multi-turn conversations with the AI model, with optional tool support and comprehensive message validation.

Key Features:

Multi-turn conversations: Support for system, user, and assistant messages
Tool Support: Full tool use/result validation with automatic or manual selection
Citations: Enable system.citations.enabled to include references in responses
Streaming: Enable stream for partial updates in real-time
Default Prompts: Enable system.use_default_prompt for using Zylon prompts
Thinking: Enable thinking.enabled for step-by-step reasoning capabilities
Sampling Parameters: Control randomness with temperature, top_p, top_k, etc.

Notes:

Tool use/result blocks must be properly paired within assistant messages
Tool choice type must be ‘auto’, ‘tool’, or ‘none’
When tool_choice.type is ‘tool’, tool_choice.name must specify a valid tool
All message content is validated for completeness and proper structure
Last message must be from user or assistant for proper conversation flow
MCP servers provide external tool capabilities via Model Context Protocol
Sampling parameters control response randomness and token selection

$	curl -X POST /v1/messages \
>	-H "Content-Type: application/json" \
>	-d '{
>	"model": "default",
>	"messages": [
>	{
>	"role": "user",
>	"content": "How do you fry an egg? Choose the best method."
>	}
>	],
>	"max_tokens": 1000,
>	"system": [
>	{
>	"text": "You are a helpful cooking assistant. Provide clear, step-by-step instructions.",
>	"citations": {
>	"enabled": true
>	}
>	}
>	],
>	"tools": [
>	{
>	"name": "egg_fryer",
>	"description": "A tool to fry eggs with precise temperature control",
>	"input_schema": {
>	"properties": {
>	"temperature": {
>	"description": "Temperature in degrees Celsius",
>	"type": "number"
>	},
>	"time": {
>	"description": "Time in minutes to fry the egg",
>	"type": "number"
>	}
>	},
>	"required": [
>	"temperature",
>	"time"
>	],
>	"type": "object"
>	}
>	}
>	],
>	"thinking": {
>	"enabled": false
>	},
>	"tool_choice": {
>	"type": "auto",
>	"disable_parallel_tool_use": false
>	},
>	"stream": false,
>	"response_format": {
>	"type": "text"
>	},
>	"temperature": 0.7
>	}'

1	{
2	"id": "msg_12345",
3	"type": "message",
4	"role": "assistant",
5	"content": [
6	{
7	"start_timestamp": "2025-07-10T09:11:16.003615Z",
8	"stop_timestamp": "2025-07-10T09:11:28.048942Z",
9	"text": "Based on the analysis, I found 3 potential security issues...",
10	"type": "text"
11	}
12	],
13	"model": "private-gpt",
14	"stop_reason": "end_turn",
15	"usage": {
16	"input_tokens": 432,
17	"output_tokens": 89
18	}
19	}