Sign in

v10

latestOpenAPI 3.1.0raw.githubusercontent.com2026-07-0643140398.0 KB
Messages
Messages

Messages

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
post/v1/messages

Request body

modelstring required

Model identifier or alias.

streamboolean

Whether to stream the response back to the client.

containerstring nullable

Container identifier for reuse across requests.

priorityinteger nullable

Priority of the request, used for prioritizing responses.

seedinteger nullable

Random seed for reproducibility.

min_pnumber nullable

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

top_pnumber

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

temperaturenumber

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

top_kinteger

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

repetition_penaltynumber nullable

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

presence_penaltynumber nullable

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

frequency_penaltynumber nullable

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

max_tokensinteger required

Maximum number of tokens to generate in the response.

stop_sequencesstring[]

Custom stop sequences that stop generation when matched.

service_tier'auto' | 'standard_only'

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

inference_geostring nullable

Geographic region hint for inference processing.

correlation_idstring nullable

Correlation ID for tracking the request across systems.

maximum_loaded_skillsinteger nullable

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

{"stackTrail":"components:schemas:ChatBody:properties:context_management:anyOf","oasType":"schema","type":"unknown","title":"Context Management","description":"Optional context management configuration","nullable":true}

Example request

{
  "max_tokens": 1000,
  "messages": [
    {
      "content": "How do you fry an egg? Choose the best method.",
      "role": "user"
    }
  ],
  "response_format": {
    "type": "text"
  },
  "stream": false,
  "system": {
    "citations": {
      "enabled": true
    },
    "text": "You are a helpful cooking assistant. Provide clear, step-by-step instructions."
  },
  "temperature": 0.7,
  "thinking": {
    "enabled": false
  },
  "tool_choice": {
    "disable_parallel_tool_use": false,
    "type": "auto"
  },
  "tools": [
    {
      "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"
      },
      "name": "egg_fryer"
    }
  ]
}

Response

Successful chat message

idstring

Message identifier.

type'message'

Object type.

role'assistant'

Message author role.

modelstring

Model name used.

stop_reasonstring nullable

Message stop reason.

stop_sequencestring nullable

Matched stop sequence, if any.

Example response

{
  "content": [
    {
      "sources": [
        {
          "content_type": "text/plain",
          "document": {
            "artifact": "quarterly_report_q3",
            "doc_metadata": {
              "department": "finance",
              "file_name": "Q3_Financial_Report.pdf",
              "page_number": 5
            },
            "object": "ingest.document"
          },
          "id": "chunk_123e4567-e89b-12d3-a456-426614174000",
          "metadata": {
            "abs_idx": 8,
            "author": "Finance Team",
            "date": "2023-10-15",
            "rel_idx": 3,
            "section": "Revenue Analysis",
            "title": "Q3 Financial Report"
          },
          "next_texts": [
            "The technology sector contributed 60% of total growth.",
            "Marketing expenses remained within budget projections."
          ],
          "object": "context.chunk",
          "previous_texts": [
            "Q3 FINANCIAL SUMMARY",
            "This report covers the third quarter performance metrics."
          ],
          "score": 0.856,
          "text": "Revenue increased by 15% compared to the previous quarter, primarily driven by strong performance in the technology sector."
        }
      ]
    }
  ]
}
All 43 operations