POST/v1/messages

Messages

Send a message and receive an AI response. Supports streaming responses via SSE, system prompts, multi-turn conversations, and tool use.

Test the messages endpoint with your API key:

Bash

curl -X POST https://api.mr-coder.io/v1/messages \
  -H "x-api-key: sk-mr-auth-your-key-here" \
  -H "Content-Type: application/json" \
  -d '{"model": "claude-haiku-5-5", "max_tokens": 100, "messages": [{"role": "user", "content": "Say hello in 5 words"}]}'

Request Parameters

Parameter	Type	Description
`model`*	string	Model ID with provider prefix (e.g., anthropic:claude-sonnet-4-6, anthropic:claude-haiku-5-5). Bare IDs default to anthropic:. See the Models endpoint for the full list.
`messages`*	array	Array of message objects with role (user/assistant/system) and content. At least one user message is required.
`max_tokens`*	integer	Maximum tokens to generate. Must be at least 1. For streaming, set to a reasonable value (e.g., 1024) to avoid truncation.
`stream`	boolean	Enable streaming response via Server-Sent Events (SSE). Defaults to false. When true, response is chunked as the model generates.
`system`	string	System prompt to prepend to the conversation. Use for instructions, persona, or context.
`temperature`	number	Sampling temperature (0.0–1.0). Higher values make output more random. Defaults to 1.0.
`top_p`	number	Nucleus sampling threshold. Defaults to 1.0. Use with temperature for more precise control.
`tools`	array	Array of tool definitions. See Tool Use section below.
`tool_choice`	string	Control when tools are called: auto (model decides), any (must call tool), or a specific tool name.
`metadata`	object	Optional key-value metadata to attach to the request. Useful for tracking or tagging.

Message Object

JSON

{
  "role": "user" | "assistant" | "system",
  "content": string | array  // string for text, array for content blocks
}

For assistant messages returned by the model, content may also include tool use blocks and tool result references.

Non-Streaming Response

When stream: false (default), the response is a single JSON object:

JSON

{
  "id": "msg_xxxxxxxxxxxxxxxxxxxx",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Hello! Here are five words: Hello there, how are you?"
    }
  ],
  "model": "claude-haiku-5-5",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 85,
    "output_tokens": 23
  }
}

Code Examples

Bash

curl -X POST https://api.mr-coder.io/v1/messages \
  -H "x-api-key: sk-mr-auth-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"model": "claude-haiku-5-5", "max_tokens": 100, "messages": [{"role": "user", "content": "Say hello in 5 words"}]}'

TypeScript

const response = await fetch(
  'https://api.mr-coder.io/v1/messages',
  {
    method: 'POST',
    headers: {
      'x-api-key': 'sk-mr-auth-xxxxxxxx',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      model: 'claude-haiku-5-5',
      max_tokens: 100,
      messages: [{ role: 'user', content: 'Say hello in 5 words' }],
    }),
  }
);

const data = await response.json();
console.log(data.content[0].text);

Python

import requests

response = requests.post(
    'https://api.mr-coder.io/v1/messages',
    headers={
        'x-api-key': 'sk-mr-auth-xxxxxxxx',
        'Content-Type': 'application/json',
    },
    json={
        'model': 'claude-haiku-5-5',
        'max_tokens': 100,
        'messages': [{'role': 'user', 'content': 'Say hello in 5 words'}],
    }
)

data = response.json()
print(data['content'][0]['text'])

Streaming Response

Client requirement: Your HTTP client must support Transfer-Encoding: chunked and parse Server-Sent Events (SSE). Most modern HTTP libraries support this.

When stream: true, the response is streamed as SSE events:

Bash

event: message_start
data: {"type":"message_start","message":{"id":"msg_xxx","type":"message","role":"assistant","content":[],"model":"claude-sonnet-4-6","stop_reason":null,"stop_sequence":null,"usage":{"input_tokens":85,"output_tokens":0}}}

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":"Hello"}}

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

event: message_delta
data: {"type":"message_delta","delta":{"stop_reason":"end_turn"},"usage":{"output_tokens":5}}

event: message_stop
data: {}

SSE Event Types

Event	Description
message_start	Sent at the beginning. Contains the full message object with id, model, and usage (input_tokens only at this point).
content_block_start	Sent when a content block begins. Contains the block type (text or tool_use).
content_block_delta	Sent for each text delta or tool_use delta. Contains the incremental text or tool call.
content_block_stop	Sent when a content block is complete.
message_delta	Sent with final usage stats and stop_reason when generation is complete.
message_stop	Sent at the very end. No data payload.

Streaming Code Examples

Bash

curl -N -X POST https://api.mr-coder.io/v1/messages \
  -H "x-api-key: sk-mr-auth-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"model": "claude-sonnet-4-6", "max_tokens": 200, "stream": true, "messages": [{"role": "user", "content": "What is 2+2?"}]}'

TypeScript

const response = await fetch(
  'https://api.mr-coder.io/v1/messages',
  {
    method: 'POST',
    headers: {
      'x-api-key': 'sk-mr-auth-xxxxxxxx',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      model: 'claude-sonnet-4-6',
      max_tokens: 200,
      stream: true,
      messages: [{ role: 'user', content: 'What is 2+2?' }],
    }),
  }
);

const reader = response.body?.getReader();
if (!reader) throw new Error('No response body');
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;

  // Handle both \n and \r\n line endings
  const chunk = decoder.decode(value).replace(/\r\n/g, '\n');
  for (const line of chunk.split('\n')) {
    if (line.startsWith('data: ')) {
      try {
        const data = JSON.parse(line.slice(6));
        if (data.type === 'content_block_delta') {
          process.stdout.write(data.delta.text);
        }
      } catch {
        // Skip malformed JSON lines
      }
    }
  }
}

System Prompt + Multi-turn

Include a system prompt for instructions and pass the full conversation history for multi-turn context:

JSON

{
  "model": "claude-haiku-5-5",
  "max_tokens": 100,
  "stream": false,
  "system": "You are a pirate. Respond in pirate speak.",
  "messages": [
    {"role": "user", "content": "What is Python?"},
    {"role": "assistant", "content": "Arrr! Python be a programm'n language that ye can use fer build'n all sorts of code treasure!"},
    {"role": "user", "content": "Tell me more"}
  ]
}

Bash

curl -X POST https://api.mr-coder.io/v1/messages \
  -H "x-api-key: sk-mr-auth-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"model": "claude-haiku-5-5", "max_tokens": 100, "system": "You are a pirate.", "messages": [{"role": "user", "content": "What is Python?"}]}'

← AuthenticationAPI key headers and key types Models Endpoint →List available models