Messages
curl --request POST \
--url https://api2.matterai.so/v1/messages \
--header 'Content-Type: application/json' \
--data '
{
"model": "<string>",
"messages": [
{
"role": "<string>",
"content": [
{
"type": "<string>",
"text": "<string>"
}
]
}
],
"system": [
{
"type": "<string>",
"text": "<string>"
}
],
"max_tokens": 123,
"stream": true,
"thinking": {
"type": "<string>",
"budget_tokens": 123
},
"temperature": 123,
"top_p": 123
}
'import requests
url = "https://api2.matterai.so/v1/messages"
payload = {
"model": "<string>",
"messages": [
{
"role": "<string>",
"content": [
{
"type": "<string>",
"text": "<string>"
}
]
}
],
"system": [
{
"type": "<string>",
"text": "<string>"
}
],
"max_tokens": 123,
"stream": True,
"thinking": {
"type": "<string>",
"budget_tokens": 123
},
"temperature": 123,
"top_p": 123
}
headers = {"Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({
model: '<string>',
messages: [{role: '<string>', content: [{type: '<string>', text: '<string>'}]}],
system: [{type: '<string>', text: '<string>'}],
max_tokens: 123,
stream: true,
thinking: {type: '<string>', budget_tokens: 123},
temperature: 123,
top_p: 123
})
};
fetch('https://api2.matterai.so/v1/messages', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api2.matterai.so/v1/messages",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'model' => '<string>',
'messages' => [
[
'role' => '<string>',
'content' => [
[
'type' => '<string>',
'text' => '<string>'
]
]
]
],
'system' => [
[
'type' => '<string>',
'text' => '<string>'
]
],
'max_tokens' => 123,
'stream' => true,
'thinking' => [
'type' => '<string>',
'budget_tokens' => 123
],
'temperature' => 123,
'top_p' => 123
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api2.matterai.so/v1/messages"
payload := strings.NewReader("{\n \"model\": \"<string>\",\n \"messages\": [\n {\n \"role\": \"<string>\",\n \"content\": [\n {\n \"type\": \"<string>\",\n \"text\": \"<string>\"\n }\n ]\n }\n ],\n \"system\": [\n {\n \"type\": \"<string>\",\n \"text\": \"<string>\"\n }\n ],\n \"max_tokens\": 123,\n \"stream\": true,\n \"thinking\": {\n \"type\": \"<string>\",\n \"budget_tokens\": 123\n },\n \"temperature\": 123,\n \"top_p\": 123\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api2.matterai.so/v1/messages")
.header("Content-Type", "application/json")
.body("{\n \"model\": \"<string>\",\n \"messages\": [\n {\n \"role\": \"<string>\",\n \"content\": [\n {\n \"type\": \"<string>\",\n \"text\": \"<string>\"\n }\n ]\n }\n ],\n \"system\": [\n {\n \"type\": \"<string>\",\n \"text\": \"<string>\"\n }\n ],\n \"max_tokens\": 123,\n \"stream\": true,\n \"thinking\": {\n \"type\": \"<string>\",\n \"budget_tokens\": 123\n },\n \"temperature\": 123,\n \"top_p\": 123\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api2.matterai.so/v1/messages")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n \"model\": \"<string>\",\n \"messages\": [\n {\n \"role\": \"<string>\",\n \"content\": [\n {\n \"type\": \"<string>\",\n \"text\": \"<string>\"\n }\n ]\n }\n ],\n \"system\": [\n {\n \"type\": \"<string>\",\n \"text\": \"<string>\"\n }\n ],\n \"max_tokens\": 123,\n \"stream\": true,\n \"thinking\": {\n \"type\": \"<string>\",\n \"budget_tokens\": 123\n },\n \"temperature\": 123,\n \"top_p\": 123\n}"
response = http.request(request)
puts response.read_body{
"400": {},
"401": {},
"429": {},
"500": {},
"id": "<string>",
"type": "<string>",
"role": "<string>",
"content": [
{
"type": "<string>",
"text": "<string>",
"thinking": "<string>",
"thinking_latency_ms": 123
}
],
"model": "<string>",
"stop_reason": "<string>",
"stop_sequence": "<string>",
"usage": {
"input_tokens": 123,
"output_tokens": 123,
"cache_creation_input_tokens": 123,
"cache_read_input_tokens": 123
}
}Messages
Create a message completion using the MatterAI API (Anthropic-compatible)
POST
/
v1
/
messages
Messages
curl --request POST \
--url https://api2.matterai.so/v1/messages \
--header 'Content-Type: application/json' \
--data '
{
"model": "<string>",
"messages": [
{
"role": "<string>",
"content": [
{
"type": "<string>",
"text": "<string>"
}
]
}
],
"system": [
{
"type": "<string>",
"text": "<string>"
}
],
"max_tokens": 123,
"stream": true,
"thinking": {
"type": "<string>",
"budget_tokens": 123
},
"temperature": 123,
"top_p": 123
}
'import requests
url = "https://api2.matterai.so/v1/messages"
payload = {
"model": "<string>",
"messages": [
{
"role": "<string>",
"content": [
{
"type": "<string>",
"text": "<string>"
}
]
}
],
"system": [
{
"type": "<string>",
"text": "<string>"
}
],
"max_tokens": 123,
"stream": True,
"thinking": {
"type": "<string>",
"budget_tokens": 123
},
"temperature": 123,
"top_p": 123
}
headers = {"Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({
model: '<string>',
messages: [{role: '<string>', content: [{type: '<string>', text: '<string>'}]}],
system: [{type: '<string>', text: '<string>'}],
max_tokens: 123,
stream: true,
thinking: {type: '<string>', budget_tokens: 123},
temperature: 123,
top_p: 123
})
};
fetch('https://api2.matterai.so/v1/messages', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api2.matterai.so/v1/messages",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'model' => '<string>',
'messages' => [
[
'role' => '<string>',
'content' => [
[
'type' => '<string>',
'text' => '<string>'
]
]
]
],
'system' => [
[
'type' => '<string>',
'text' => '<string>'
]
],
'max_tokens' => 123,
'stream' => true,
'thinking' => [
'type' => '<string>',
'budget_tokens' => 123
],
'temperature' => 123,
'top_p' => 123
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api2.matterai.so/v1/messages"
payload := strings.NewReader("{\n \"model\": \"<string>\",\n \"messages\": [\n {\n \"role\": \"<string>\",\n \"content\": [\n {\n \"type\": \"<string>\",\n \"text\": \"<string>\"\n }\n ]\n }\n ],\n \"system\": [\n {\n \"type\": \"<string>\",\n \"text\": \"<string>\"\n }\n ],\n \"max_tokens\": 123,\n \"stream\": true,\n \"thinking\": {\n \"type\": \"<string>\",\n \"budget_tokens\": 123\n },\n \"temperature\": 123,\n \"top_p\": 123\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api2.matterai.so/v1/messages")
.header("Content-Type", "application/json")
.body("{\n \"model\": \"<string>\",\n \"messages\": [\n {\n \"role\": \"<string>\",\n \"content\": [\n {\n \"type\": \"<string>\",\n \"text\": \"<string>\"\n }\n ]\n }\n ],\n \"system\": [\n {\n \"type\": \"<string>\",\n \"text\": \"<string>\"\n }\n ],\n \"max_tokens\": 123,\n \"stream\": true,\n \"thinking\": {\n \"type\": \"<string>\",\n \"budget_tokens\": 123\n },\n \"temperature\": 123,\n \"top_p\": 123\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api2.matterai.so/v1/messages")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n \"model\": \"<string>\",\n \"messages\": [\n {\n \"role\": \"<string>\",\n \"content\": [\n {\n \"type\": \"<string>\",\n \"text\": \"<string>\"\n }\n ]\n }\n ],\n \"system\": [\n {\n \"type\": \"<string>\",\n \"text\": \"<string>\"\n }\n ],\n \"max_tokens\": 123,\n \"stream\": true,\n \"thinking\": {\n \"type\": \"<string>\",\n \"budget_tokens\": 123\n },\n \"temperature\": 123,\n \"top_p\": 123\n}"
response = http.request(request)
puts response.read_body{
"400": {},
"401": {},
"429": {},
"500": {},
"id": "<string>",
"type": "<string>",
"role": "<string>",
"content": [
{
"type": "<string>",
"text": "<string>",
"thinking": "<string>",
"thinking_latency_ms": 123
}
],
"model": "<string>",
"stop_reason": "<string>",
"stop_sequence": "<string>",
"usage": {
"input_tokens": 123,
"output_tokens": 123,
"cache_creation_input_tokens": 123,
"cache_read_input_tokens": 123
}
}Authentication
All API requests require authentication using a Bearer token. You can obtain your API key from the MatterAI Console.Authorization: Bearer MATTERAI_API_KEY
Keep your API key secure and never expose it in client-side code. Get your API
key from the MatterAI console.
Request
string
required
The model used for the completion. Available models:
"axon-2-5-pro",
"axon-2-5-mini".array
required
An array of message objects that make up the conversation.
array
integer
default:"512"
The maximum number of tokens to generate in the completion.
boolean
default:"false"
Whether to stream the response as it’s generated.
object
number
default:"0.1"
Controls randomness in the output. Higher values make output more random,
lower values make it more focused and deterministic. Range: 0.0 to 2.0.
number
default:"1"
Controls diversity via nucleus sampling. Range: 0.0 to 1.0.
Response
string
A unique identifier for the message completion.
string
The object type, which is always
"message".string
The role of the response, always
"assistant".array
string
The model used for the completion. Available models:
"axon-2-5-pro",
"axon-2-5-mini".string
The reason the model stopped generating tokens. Possible values:
"end_turn",
"stop_sequence", "max_tokens".string
The stop sequence that triggered the stop, if any.
object
Example Request
curl --location 'https://api2.matterai.so/v1/messages' \
--header 'content-type: application/json' \
--header 'Authorization: Bearer MATTERAI_API_KEY' \
--data '{
"model": "axon-2-5-pro",
"messages": [
{
"role": "user",
"content": [
{
"type": "text",
"text": "Hi"
}
]
}
],
"system": [
{
"type": "text",
"text": "You are Axon, helpful assistant"
}
],
"max_tokens": 512,
"thinking": {
"type": "enabled",
"budget_tokens": 8192
},
"stream": true
}'
const response = await fetch("https://api2.matterai.so/v1/messages", {
method: "POST",
headers: {
"Content-Type": "application/json",
Authorization: "Bearer MATTERAI_API_KEY",
},
body: JSON.stringify({
model: "axon-2-5-pro",
messages: [
{
role: "user",
content: [
{
type: "text",
text: "Hi",
},
],
},
],
system: [
{
type: "text",
text: "You are Axon, helpful assistant",
},
],
max_tokens: 512,
thinking: {
type: "enabled",
budget_tokens: 8192,
},
stream: true,
}),
});
const data = await response.json();
console.log(data);
import requests
url = "https://api2.matterai.so/v1/messages"
headers = {
"Content-Type": "application/json",
"Authorization": "Bearer MATTERAI_API_KEY"
}
payload = {
"model": "axon-2-5-pro",
"messages": [
{
"role": "user",
"content": [
{
"type": "text",
"text": "Hi"
}
]
}
],
"system": [
{
"type": "text",
"text": "You are Axon, helpful assistant"
}
],
"max_tokens": 512,
"thinking": {
"type": "enabled",
"budget_tokens": 8192
},
"stream": True
}
response = requests.post(url, json=payload, headers=headers)
print(response.json())
Example Response
{
"id": "msg-abc123",
"type": "message",
"role": "assistant",
"content": [
{
"type": "thinking",
"thinking": "Let me analyze this request carefully...",
"thinking_latency_ms": 450
},
{
"type": "text",
"text": "Hello! I'm Axon, a helpful assistant. How can I help you today?"
}
],
"model": "axon-2-5-pro",
"stop_reason": "end_turn",
"stop_sequence": null,
"usage": {
"input_tokens": 35,
"output_tokens": 89,
"cache_creation_input_tokens": 0,
"cache_read_input_tokens": 0
}
}
Streaming
Whenstream is set to true, the API will return a stream of Server-Sent Events (SSE). Each event contains a JSON object with the partial response:
data: {"type":"message_start","message":{"id":"msg-abc123","type":"message","role":"assistant","content":[],"model":"axon-2-5-pro","stop_reason":null,"stop_sequence":null,"usage":{"input_tokens":0,"output_tokens":0}}}
data: {"type":"content_block_start","index":0,"content_block":{"type":"thinking","thinking":""}}
data: {"type":"content_block_delta","index":0,"delta":{"type":"thinking_delta","thinking":"Let me"}}
data: {"type":"content_block_delta","index":0,"delta":{"type":"thinking_delta","thinking":" think"}}
data: {"type":"content_block_stop","index":0}
data: {"type":"content_block_start","index":1,"content_block":{"type":"text","text":""}}
data: {"type":"content_block_delta","index":1,"delta":{"type":"text_delta","text":"Hello!"}}
data: {"type":"content_block_stop","index":1}
data: {"type":"message_delta","delta":{"stop_reason":"end_turn"},"usage":{"output_tokens":45}}
data: [DONE]
Error Responses
The API returns standard HTTP status codes to indicate success or failure:Bad Request
Invalid request parameters or malformed JSON.
Unauthorized
Invalid or missing API key.
Rate Limited
Too many requests. Please slow down.
Internal Server Error
Server error. Please try again later.
{
"error": {
"type": "error",
"error": {
"type": "authentication_error",
"message": "Invalid API key provided"
}
}
}
⌘I