Messages API

ZERG exposes an Anthropic Messages API compatible endpoint. This enables Anthropic SDK clients and tooling to target ZERG directly.

Overview

The /api/v1/messages endpoint mirrors the Anthropic wire format. ZERG translates the request to the configured provider and returns Anthropic-formatted responses. Supports streaming via SSE for token-by-token output.

Authentication

Requires x-api-key: <token> header (Anthropic-compatible) or Authorization: Bearer <token> header. Tokens are issued by Mango.

Endpoints

Create Message

POST /api/v1/messages

Request Body:

{
  "model": "claude-sonnet-4-20250514",
  "max_tokens": 1024,
  "messages": [
    { "role": "user", "content": "Explain quicksort" }
  ],
  "system": "You are a helpful assistant.",
  "temperature": 0.7,
  "stream": false
}

Response (non-streaming):

{
  "id": "msg_abc123",
  "type": "message",
  "role": "assistant",
  "content": [
    { "type": "text", "text": "Quicksort is a divide-and-conquer algorithm..." }
  ],
  "model": "claude-sonnet-4-20250514",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 42,
    "output_tokens": 156
  }
}

Supported Parameters:

Parameter	Type	Default	Description
model	string	required	Model identifier from the model catalog
messages	array	required	Array of message objects
max_tokens	integer	4096	Maximum tokens in the response
system	string	""	System prompt
temperature	float	0.7	Sampling temperature
stream	boolean	false	Enable SSE streaming
stop_sequences	string[]	[]	Custom stop sequences
top_p	float	1.0	Nucleus sampling
thinking	object	null	Extended thinking config {type: "enabled", budget_tokens: 2048}

Streaming (stream: true):

Returns SSE events following the Anthropic streaming format:

event: message_start
data: {"type": "message_start", "message": {...}}

event: content_block_start
data: {"type": "content_block_start", "index": 0, "content_block": {"type": "text", "text": ""}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "text_delta", "text": "Quicksort"}}

event: message_stop
data: {"type": "message_stop"}

Tool Use:

ZERG supports tool definition and execution through the Anthropic tool schema. Tools defined in the request are executed by the Luna agent runtime.

{
  "tools": [{
    "name": "web_search",
    "description": "Search the web",
    "input_schema": {
      "type": "object",
      "properties": {
        "query": { "type": "string" }
      }
    }
  }]
}

Error Codes:

Code	Description
400	Invalid request body
401	Missing or invalid authentication
404	Model not found or unavailable
429	Rate limit exceeded
500	Provider or internal error
529	Provider overloaded

Example:

curl http://127.0.0.1:11434/api/v1/messages \
  -H "x-api-key: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 500,
    "messages": [{"role": "user", "content": "Write a poem"}]
  }'