Messages

Create a Message

Claude-compatible Messages API for single queries and multi-turn conversations.

POST /v1/messages

Send a structured list of input messages with text content, and the model will generate the next message in the conversation.

• Uses the Claude Messages API request format
• Supports single queries and stateless multi-turn conversations
• Streaming and non-streaming responses

For image and document analysis, see File Analysis.

Endpoint

https://api.tokatlas.ai/v1/messages

Authentication

All endpoints require API key authentication. Add your key to the request headers:

x-api-key: YOUR_API_KEY
anthropic-version: 2023-06-01
Content-Type: application/json

Important

Never commit a real API key to a repository or expose it in client-side code.

Request Body

Parameter	Type	Required	Default	Description
model	string	Yes	-	Model that will complete your prompt
messages	array	Yes	-	Input messages for the conversation
max_tokens	integer	Yes	-	Maximum number of tokens to generate before stopping
system	string or array	No	-	System prompt (not a message role)
temperature	number	No	1.0	Output randomness, range 0–1
top_p	number	No	-	Nucleus sampling parameter, range 0–1
top_k	integer	No	-	Sample from the top K options only
stream	boolean	No	false	Whether to stream the response via SSE
stop_sequences	array	No	-	Custom text sequences that stop generation
metadata	object	No	-	Request metadata (e.g. user_id)
tools	array	No	-	Tools the model can use
tool_choice	object	No	-	How the model should use tools
thinking	object	No	-	Extended thinking configuration

model

Current official model IDs checked on 2026-10-03 are listed below. First query your available models, then use the exact ID in model. An upstream release does not imply access through your Tokatlas account.

• claude-opus-5-5 — Claude Opus 5.5
• claude-sonnet-5-5 — Claude Sonnet 5.5
• claude-fable-5-1 — Claude Fable 5.1
• claude-haiku-4-5 — Claude Haiku 4.5

Official model documentation

Thinking modes and tool restrictions differ between generations. Start with a minimal text request before adding thinking or forced tool selection.

messages

Input messages. Models operate on alternating user and assistant turns. When creating a new message, pass prior turns in messages, and the model generates the next message.

Each message must include role and content. Consecutive same-role turns are combined into a single turn. There is a limit of 100,000 messages in a single request.

Field	Type	Required	Description
role	string	Yes	user or assistant
content	string or array	Yes	Message content

Note

There is no "system" role in Messages API input. Use the top-level system parameter for system prompts.

Single user message:

[{"role": "user", "content": "Hello, Claude"}]

Multi-turn conversation:

[
  {"role": "user", "content": "Hello there."},
  {"role": "assistant", "content": "Hi, I'm Claude. How can I help you?"},
  {"role": "user", "content": "Can you explain LLMs in plain English?"}
]

Prefilled assistant response (response continues from the last assistant turn):

[
  {"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"},
  {"role": "assistant", "content": "The best answer is ("}
]

content may be a string or an array of content blocks. A string is shorthand for a single "text" block:

{"role": "user", "content": "Hello, Claude"}

{"role": "user", "content": [{"type": "text", "text": "Hello, Claude"}]}

max_tokens

The maximum number of tokens to generate before stopping. Models may stop before reaching this limit. Different models have different maximum values. Minimum: 1.

system

System prompt for role, personality, goals, and instructions.

String format:

{
  "system": "You are a professional Python programming tutor"
}

Structured format:

{
  "system": [
    {
      "type": "text",
      "text": "You are a professional Python programming tutor"
    }
  ]
}

temperature

Amount of randomness injected into the response, range 0–1. Defaults to 1.0.

• Lower values (e.g. 0.2) — more deterministic / analytical
• Higher values (e.g. 0.8) — more creative / generative

top_p

Nucleus sampling parameter, range 0–1. Recommend using either temperature or top_p, not both.

top_k

Only sample from the top K options for each subsequent token. Recommended for advanced use cases only.

stream

Whether to incrementally stream the response using Server-Sent Events (SSE).

• true — Streaming response
• false — Complete response at once (default)

stop_sequences

Custom text sequences that cause the model to stop generating. Up to 4 sequences. When matched, stop_reason is "stop_sequence" and stop_sequence contains the matched value.

metadata

Request metadata object. Includes:

• user_id — external opaque user identifier (uuid/hash). Do not include PII.

tools

List of tools the model can use to complete tasks.

{
  "tools": [
    {
      "name": "get_weather",
      "description": "Get the current weather in a given location",
      "input_schema": {
        "type": "object",
        "properties": {
          "location": {
            "type": "string",
            "description": "The city and state, e.g. San Francisco, CA"
          },
          "unit": {
            "type": "string",
            "enum": ["celsius", "fahrenheit"]
          }
        },
        "required": ["location"]
      }
    }
  ]
}

tool_choice

Controls how the model uses tools:

• {"type": "auto"} — auto-decide (default)
• {"type": "any"} — must use a tool
• {"type": "tool", "name": "tool_name"} — use a specific tool
• {"type": "none"} — do not use tools

thinking

Configuration for extended thinking. When enabled, responses may include thinking content blocks before the final answer.

Response

The table describes the protocol response object. Where the non-streaming examples use a { "code": 200, "data": { ... } } envelope, read the object in data; for routes returning the protocol object directly, read the root object. Parse streaming responses as events, not one JSON document. Native SDKs require a route that returns their expected protocol format directly.

Field	Type	Description
id	string	Unique message identifier
type	string	Object type, always message
role	string	Always assistant
content	array	Content blocks generated by the model
model	string	Model that handled the request
stop_reason	string	Why generation stopped
stop_sequence	string or null	Matched stop sequence, if any
usage	object	Token usage statistics

content[]

Array of content blocks. Common types:

Text:

[{"type": "text", "text": "Hello! I'm Claude."}]

Tool use:

[
  {
    "type": "tool_use",
    "id": "toolu_01A09q90qw90lq917835lq9",
    "name": "get_weather",
    "input": {"location": "San Francisco, CA", "unit": "celsius"}
  }
]

stop_reason

Value	Description
end_turn	Natural completion
max_tokens	Reached max_tokens
stop_sequence	Hit a stop sequence
tool_use	Invoked a tool

usage

Field	Type	Description
input_tokens	integer	Number of input tokens
output_tokens	integer	Number of output tokens

Usage Examples

Basic Conversation

{
  "model": "claude-sonnet-4-6",
  "max_tokens": 1024,
  "messages": [
    {"role": "user", "content": "Explain quantum computing basics"}
  ]
}

System Prompt

{
  "model": "claude-sonnet-4-6",
  "max_tokens": 1024,
  "system": "You are a senior Python developer expert in code review.",
  "messages": [
    {"role": "user", "content": "How should I optimize this function?"}
  ]
}

Multi-turn Conversation

{
  "model": "claude-sonnet-4-6",
  "max_tokens": 1024,
  "messages": [
    {"role": "user", "content": "What is machine learning?"},
    {"role": "assistant", "content": "Machine learning is a branch of AI..."},
    {"role": "user", "content": "Can you give a practical example?"}
  ]
}

Streaming Output

{
  "model": "claude-sonnet-4-6",
  "max_tokens": 1024,
  "stream": true,
  "messages": [
    {"role": "user", "content": "Write a short essay about AI"}
  ]
}

Request Examples

See language setup. Set API_KEY and replace model, file URL, and ID placeholders first. Each version displays the raw response to the same request.

cURL

curl --fail-with-body --silent --show-error --max-time 180 \
  --request POST \
  --url "https://api.tokatlas.ai/v1/messages" \
  --header "x-api-key: $API_KEY" \
  --header "anthropic-version: 2023-06-01" \
  --header "Content-Type: application/json" \
  --data '{
  "model": "claude-sonnet-4-6",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": "Hello, world"
    }
  ]
}'

Python

import os
import requests

headers = {
    'x-api-key': os.environ["API_KEY"],
    'anthropic-version': '2023-06-01',
    'Content-Type': 'application/json',
}
payload = {'model': 'claude-sonnet-4-6',
 'max_tokens': 1024,
 'messages': [{'role': 'user', 'content': 'Hello, world'}]}
response = requests.request(
    'POST', 'https://api.tokatlas.ai/v1/messages', headers=headers,
    json=payload,
    timeout=180,
)
response.raise_for_status()
print(response.text)

JavaScript

if (!process.env.API_KEY) throw new Error("Set API_KEY first.");
const response = await fetch("https://api.tokatlas.ai/v1/messages", {
  method: "POST",
  headers: {
    "x-api-key": process.env.API_KEY,
    "anthropic-version": "2023-06-01",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "model": "claude-sonnet-4-6",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": "Hello, world"
    }
  ]
}),
  signal: AbortSignal.timeout(180_000),
});
if (!response.ok) {
  throw new Error(`HTTP ${response.status}: ${await response.text()}`);
}
console.log(await response.text());

Java

import java.net.URI;
import java.net.http.*;
import java.time.Duration;

public class Example {
    public static void main(String[] args) throws Exception {
        String apiKey = System.getenv("API_KEY");
        if (apiKey == null || apiKey.isBlank()) {
            throw new IllegalArgumentException("Set API_KEY first.");
        }
        String payload = String.join("\n",
            "{",
            "  \"model\": \"claude-sonnet-4-6\",",
            "  \"max_tokens\": 1024,",
            "  \"messages\": [",
            "    {",
            "      \"role\": \"user\",",
            "      \"content\": \"Hello, world\"",
            "    }",
            "  ]",
            "}"
        );
        HttpClient client = HttpClient.newBuilder()
            .connectTimeout(Duration.ofSeconds(30)).build();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.tokatlas.ai/v1/messages"))
            .timeout(Duration.ofSeconds(180))
            .header("x-api-key", apiKey)
            .header("anthropic-version", "2023-06-01")
            .header("Content-Type", "application/json")
            .method("POST", HttpRequest.BodyPublishers.ofString(payload))
            .build();
        HttpResponse<String> response = client.send(
            request, HttpResponse.BodyHandlers.ofString());
        if (response.statusCode() < 200 || response.statusCode() >= 300) {
            throw new IllegalStateException("HTTP " + response.statusCode() + ": "
                + response.body());
        }
        System.out.println(response.body());
    }
}

Go

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io"
    "net/http"
    "os"
)

func main() {
    url := "https://api.tokatlas.ai/v1/messages"

    payload := map[string]interface{}{
        "model":      "claude-sonnet-4-6",
        "max_tokens": 1024,
        "messages": []map[string]string{
            {
                "role":    "user",
                "content": "Hello, world",
            },
        },
    }

    jsonData, _ := json.Marshal(payload)

    req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
    req.Header.Set("x-api-key", os.Getenv("API_KEY"))
    req.Header.Set("anthropic-version", "2023-06-01")
    req.Header.Set("Content-Type", "application/json")

    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
}

Response Example

Non-streaming (stream: false)

{
  "code": 200,
  "data": {
    "id": "msg_013Zva2CMHLNnXjNJJKqJ2EF",
    "type": "message",
    "role": "assistant",
    "content": [
      {
        "type": "text",
        "text": "Hello! I'm Claude. Nice to meet you."
      }
    ],
    "model": "claude-sonnet-4-6",
    "stop_reason": "end_turn",
    "stop_sequence": null,
    "usage": {
      "input_tokens": 12,
      "output_tokens": 18
    }
  }
}

Streaming (stream: true)

When stream is true, the API returns a Server-Sent Events (SSE) stream. Events follow the Claude Messages streaming sequence, ending with message_stop.

event: message_start
data: {"type":"message_start","message":{"id":"msg_013Zva2CMHLNnXjNJJKqJ2EF","type":"message","role":"assistant","content":[],"model":"claude-sonnet-4-6","stop_reason":null,"stop_sequence":null,"usage":{"input_tokens":12,"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":"! I'm Claude."}}

event: content_block_stop
data: {"type":"content_block_stop","index":0}

event: message_delta
data: {"type":"message_delta","delta":{"stop_reason":"end_turn","stop_sequence":null},"usage":{"output_tokens":18}}

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

Related Topics

• File Analysis — Image and document analysis
• Tool Calling — Function calling and tool use