Skip to main content
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
}
'
{
  "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

​
model
string
required
The model used for the completion. Available models: "axon-2-5-pro", "axon-2-5-mini".
​
messages
array
required
An array of message objects that make up the conversation.
​
system
array
System prompts to provide context or instructions.
​
max_tokens
integer
default:"512"
The maximum number of tokens to generate in the completion.
​
stream
boolean
default:"false"
Whether to stream the response as it’s generated.
​
thinking
object
Configuration for thinking/reasoning capabilities.
​
temperature
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.
​
top_p
number
default:"1"
Controls diversity via nucleus sampling. Range: 0.0 to 1.0.

​
Response

​
id
string
A unique identifier for the message completion.
​
type
string
The object type, which is always "message".
​
role
string
The role of the response, always "assistant".
​
content
array
The content blocks in the response.
​
model
string
The model used for the completion. Available models: "axon-2-5-pro", "axon-2-5-mini".
​
stop_reason
string
The reason the model stopped generating tokens. Possible values: "end_turn", "stop_sequence", "max_tokens".
​
stop_sequence
string
The stop sequence that triggered the stop, if any.
​
usage
object
Usage statistics for the completion request.

​
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
}'

​
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

When stream 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:
​
400
Bad Request
Invalid request parameters or malformed JSON.
​
401
Unauthorized
Invalid or missing API key.
​
429
Rate Limited
Too many requests. Please slow down.
​
500
Internal Server Error
Server error. Please try again later.
Example error response: 
{
  "error": {
    "type": "error",
    "error": {
      "type": "authentication_error",
      "message": "Invalid API key provided"
    }
  }
}