Axon Model API Reference | MatterAI Documentation

Chat

curl --request POST \
  --url https://api2.matterai.so/v1/web/chat/completions \
  --header 'Content-Type: application/json' \
  --data '
{
  "model": "<string>",
  "messages": [
    {
      "role": "<string>",
      "content": "<string>"
    }
  ],
  "stream": true,
  "tools": [
    {
      "type": "<string>",
      "function": {
        "name": "<string>",
        "description": "<string>",
        "parameters": {}
      }
    }
  ],
  "tool_choice": "<string>",
  "max_new_tokens": 123,
  "reasoning": {
    "effort": "<string>",
    "summary": "<string>"
  },
  "response_format": {
    "type": "<string>"
  },
  "temperature": 123,
  "top_p": 123
}
'

import requests

url = "https://api2.matterai.so/v1/web/chat/completions"

payload = {
    "model": "<string>",
    "messages": [
        {
            "role": "<string>",
            "content": "<string>"
        }
    ],
    "stream": True,
    "tools": [
        {
            "type": "<string>",
            "function": {
                "name": "<string>",
                "description": "<string>",
                "parameters": {}
            }
        }
    ],
    "tool_choice": "<string>",
    "max_new_tokens": 123,
    "reasoning": {
        "effort": "<string>",
        "summary": "<string>"
    },
    "response_format": { "type": "<string>" },
    "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: '<string>'}],
    stream: true,
    tools: [
      {
        type: '<string>',
        function: {name: '<string>', description: '<string>', parameters: {}}
      }
    ],
    tool_choice: '<string>',
    max_new_tokens: 123,
    reasoning: {effort: '<string>', summary: '<string>'},
    response_format: {type: '<string>'},
    temperature: 123,
    top_p: 123
  })
};

fetch('https://api2.matterai.so/v1/web/chat/completions', 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/web/chat/completions",
  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' => '<string>'
        ]
    ],
    'stream' => true,
    'tools' => [
        [
                'type' => '<string>',
                'function' => [
                                'name' => '<string>',
                                'description' => '<string>',
                                'parameters' => [
                                                                
                                ]
                ]
        ]
    ],
    'tool_choice' => '<string>',
    'max_new_tokens' => 123,
    'reasoning' => [
        'effort' => '<string>',
        'summary' => '<string>'
    ],
    'response_format' => [
        'type' => '<string>'
    ],
    '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/web/chat/completions"

	payload := strings.NewReader("{\n  \"model\": \"<string>\",\n  \"messages\": [\n    {\n      \"role\": \"<string>\",\n      \"content\": \"<string>\"\n    }\n  ],\n  \"stream\": true,\n  \"tools\": [\n    {\n      \"type\": \"<string>\",\n      \"function\": {\n        \"name\": \"<string>\",\n        \"description\": \"<string>\",\n        \"parameters\": {}\n      }\n    }\n  ],\n  \"tool_choice\": \"<string>\",\n  \"max_new_tokens\": 123,\n  \"reasoning\": {\n    \"effort\": \"<string>\",\n    \"summary\": \"<string>\"\n  },\n  \"response_format\": {\n    \"type\": \"<string>\"\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/web/chat/completions")
  .header("Content-Type", "application/json")
  .body("{\n  \"model\": \"<string>\",\n  \"messages\": [\n    {\n      \"role\": \"<string>\",\n      \"content\": \"<string>\"\n    }\n  ],\n  \"stream\": true,\n  \"tools\": [\n    {\n      \"type\": \"<string>\",\n      \"function\": {\n        \"name\": \"<string>\",\n        \"description\": \"<string>\",\n        \"parameters\": {}\n      }\n    }\n  ],\n  \"tool_choice\": \"<string>\",\n  \"max_new_tokens\": 123,\n  \"reasoning\": {\n    \"effort\": \"<string>\",\n    \"summary\": \"<string>\"\n  },\n  \"response_format\": {\n    \"type\": \"<string>\"\n  },\n  \"temperature\": 123,\n  \"top_p\": 123\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api2.matterai.so/v1/web/chat/completions")

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\": \"<string>\"\n    }\n  ],\n  \"stream\": true,\n  \"tools\": [\n    {\n      \"type\": \"<string>\",\n      \"function\": {\n        \"name\": \"<string>\",\n        \"description\": \"<string>\",\n        \"parameters\": {}\n      }\n    }\n  ],\n  \"tool_choice\": \"<string>\",\n  \"max_new_tokens\": 123,\n  \"reasoning\": {\n    \"effort\": \"<string>\",\n    \"summary\": \"<string>\"\n  },\n  \"response_format\": {\n    \"type\": \"<string>\"\n  },\n  \"temperature\": 123,\n  \"top_p\": 123\n}"

response = http.request(request)
puts response.read_body

{
  "400": {},
  "401": {},
  "429": {},
  "500": {},
  "id": "<string>",
  "object": "<string>",
  "created": 123,
  "model": "<string>",
  "choices": [
    {
      "index": 123,
      "message": {
        "role": "<string>",
        "content": "<string>"
      },
      "finish_reason": "<string>"
    }
  ],
  "usage": {
    "prompt_tokens": 123,
    "completion_tokens": 123,
    "total_tokens": 123
  }
}

POST

web

chat

completions

Chat

curl --request POST \
  --url https://api2.matterai.so/v1/web/chat/completions \
  --header 'Content-Type: application/json' \
  --data '
{
  "model": "<string>",
  "messages": [
    {
      "role": "<string>",
      "content": "<string>"
    }
  ],
  "stream": true,
  "tools": [
    {
      "type": "<string>",
      "function": {
        "name": "<string>",
        "description": "<string>",
        "parameters": {}
      }
    }
  ],
  "tool_choice": "<string>",
  "max_new_tokens": 123,
  "reasoning": {
    "effort": "<string>",
    "summary": "<string>"
  },
  "response_format": {
    "type": "<string>"
  },
  "temperature": 123,
  "top_p": 123
}
'

import requests

url = "https://api2.matterai.so/v1/web/chat/completions"

payload = {
    "model": "<string>",
    "messages": [
        {
            "role": "<string>",
            "content": "<string>"
        }
    ],
    "stream": True,
    "tools": [
        {
            "type": "<string>",
            "function": {
                "name": "<string>",
                "description": "<string>",
                "parameters": {}
            }
        }
    ],
    "tool_choice": "<string>",
    "max_new_tokens": 123,
    "reasoning": {
        "effort": "<string>",
        "summary": "<string>"
    },
    "response_format": { "type": "<string>" },
    "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: '<string>'}],
    stream: true,
    tools: [
      {
        type: '<string>',
        function: {name: '<string>', description: '<string>', parameters: {}}
      }
    ],
    tool_choice: '<string>',
    max_new_tokens: 123,
    reasoning: {effort: '<string>', summary: '<string>'},
    response_format: {type: '<string>'},
    temperature: 123,
    top_p: 123
  })
};

fetch('https://api2.matterai.so/v1/web/chat/completions', 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/web/chat/completions",
  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' => '<string>'
        ]
    ],
    'stream' => true,
    'tools' => [
        [
                'type' => '<string>',
                'function' => [
                                'name' => '<string>',
                                'description' => '<string>',
                                'parameters' => [
                                                                
                                ]
                ]
        ]
    ],
    'tool_choice' => '<string>',
    'max_new_tokens' => 123,
    'reasoning' => [
        'effort' => '<string>',
        'summary' => '<string>'
    ],
    'response_format' => [
        'type' => '<string>'
    ],
    '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/web/chat/completions"

	payload := strings.NewReader("{\n  \"model\": \"<string>\",\n  \"messages\": [\n    {\n      \"role\": \"<string>\",\n      \"content\": \"<string>\"\n    }\n  ],\n  \"stream\": true,\n  \"tools\": [\n    {\n      \"type\": \"<string>\",\n      \"function\": {\n        \"name\": \"<string>\",\n        \"description\": \"<string>\",\n        \"parameters\": {}\n      }\n    }\n  ],\n  \"tool_choice\": \"<string>\",\n  \"max_new_tokens\": 123,\n  \"reasoning\": {\n    \"effort\": \"<string>\",\n    \"summary\": \"<string>\"\n  },\n  \"response_format\": {\n    \"type\": \"<string>\"\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/web/chat/completions")
  .header("Content-Type", "application/json")
  .body("{\n  \"model\": \"<string>\",\n  \"messages\": [\n    {\n      \"role\": \"<string>\",\n      \"content\": \"<string>\"\n    }\n  ],\n  \"stream\": true,\n  \"tools\": [\n    {\n      \"type\": \"<string>\",\n      \"function\": {\n        \"name\": \"<string>\",\n        \"description\": \"<string>\",\n        \"parameters\": {}\n      }\n    }\n  ],\n  \"tool_choice\": \"<string>\",\n  \"max_new_tokens\": 123,\n  \"reasoning\": {\n    \"effort\": \"<string>\",\n    \"summary\": \"<string>\"\n  },\n  \"response_format\": {\n    \"type\": \"<string>\"\n  },\n  \"temperature\": 123,\n  \"top_p\": 123\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api2.matterai.so/v1/web/chat/completions")

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\": \"<string>\"\n    }\n  ],\n  \"stream\": true,\n  \"tools\": [\n    {\n      \"type\": \"<string>\",\n      \"function\": {\n        \"name\": \"<string>\",\n        \"description\": \"<string>\",\n        \"parameters\": {}\n      }\n    }\n  ],\n  \"tool_choice\": \"<string>\",\n  \"max_new_tokens\": 123,\n  \"reasoning\": {\n    \"effort\": \"<string>\",\n    \"summary\": \"<string>\"\n  },\n  \"response_format\": {\n    \"type\": \"<string>\"\n  },\n  \"temperature\": 123,\n  \"top_p\": 123\n}"

response = http.request(request)
puts response.read_body

{
  "400": {},
  "401": {},
  "429": {},
  "500": {},
  "id": "<string>",
  "object": "<string>",
  "created": 123,
  "model": "<string>",
  "choices": [
    {
      "index": 123,
      "message": {
        "role": "<string>",
        "content": "<string>"
      },
      "finish_reason": "<string>"
    }
  ],
  "usage": {
    "prompt_tokens": 123,
    "completion_tokens": 123,
    "total_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 chat completion. Available models: "axon-2-5-pro", "axon-2-5-mini".

array

required

An array of message objects that make up the conversation.

Show Message Object

string

required

The role of the message author. One of "system", "user", or "assistant".

string

required

The content of the message.

boolean

default:"false"

Whether to stream the response as it’s generated.

array

A list of tools the model may call. Currently, only functions are supported as a tool type.

Show Tool Object

string

required

The type of the tool. Currently, only "function" is supported.

object

required

The function definition.

Show Function Object

string

required

The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64.

string

A description of what the function does, used by the model to choose when and how to call the function.

object

The parameters the function accepts, described as a JSON Schema object.

string

default:"auto"

Controls which (if any) tool is called by the model. Options: "none" means the model will not call any tool and instead generates a message. "auto" means the model can pick between generating a message or calling one or more tools. "required" means the model must call one or more tools. Specifying a particular tool via {"type": "function", "function": {"name": "my_function"}} forces the model to call that tool.

integer

default:"2048"

The maximum number of tokens to generate in the completion.

object

Configuration for reasoning capabilities.

Show Reasoning Object

string

default:"high"

The level of reasoning effort. Options: "none", "low", "medium", "high".

string

default:"none"

The level of reasoning summary. Options: "none", "auto".

object

The format of the response.

Show Response Format Object

string

default:"text"

The type of response format. Currently supports "text" OR json.

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 chat completion.

string

The object type, which is always "chat.completion".

integer

The Unix timestamp (in seconds) of when the chat completion was created.

string

The model used for the chat completion. Available models: "axon-2-5-pro", "axon-2-5-mini".

array

A list of chat completion choices.

Show Choice Object

integer

The index of the choice in the list of choices.

object

The message generated by the model.

Show Message Object

string

The role of the author of this message. Always "assistant".

string

The contents of the message.

string

The reason the model stopped generating tokens. Possible values: "stop", "length", "content_filter".

object

Usage statistics for the completion request.

Show Usage Object

integer

Number of tokens in the prompt.

integer

Number of tokens in the generated completion.

integer

Total number of tokens used in the request (prompt + completion).

Example Request

curl --location 'https://api2.matterai.so/v1/web/chat/completions' 
--header 'Content-Type: application/json' 
--header 'Authorization: Bearer MATTERAI_API_KEY' 
--data '{
    "model": "axon-2-5-pro",
    "max_new_tokens": 2048,
    "temperature": 0.1,
    "messages": [
        {
            "role": "user",
            "content": "Hi"
        }
    ],
    "stream": true,
    "stream_options": {
        "include_usage": true
    }
}'

const response = await fetch('https://api2.matterai.so/v1/web/chat/completions', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer MATTERAI_API_KEY'
  },
  body: JSON.stringify({
    model: 'axon-2-5-pro',
    messages: [
      {
        role: 'user',
        content: 'Hi'
      }
    ],
    max_new_tokens: 2048,
    temperature: 0.1,
    stream: true,
    stream_options: {
      include_usage: true
    }
  })
});

const data = await response.json();
console.log(data);

import requests

url = "https://api2.matterai.so/v1/web/chat/completions"
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer MATTERAI_API_KEY"
}

payload = {
    "model": "axon-2-5-pro",
    "messages": [
        {
            "role": "user",
            "content": "Hi"
        }
    ],
    "max_new_tokens": 2048,
    "temperature": 0.1,
    "stream": True,
    "stream_options": {
        "include_usage": True
    }
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

Example Response

{
  "id": "chatcmpl-cd3ac60c-9746-457b-b4fa-aca53a993249",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Axon is an Agentic LLM Model for coding by MatterAI, designed as an elite software engineering assistant for architecting mission-critical systems."
      },
      "finish_reason": "stop"
    }
  ],
  "created": 1756372473,
  "model": "axon-2-5-pro",
  "object": "chat.completion",
  "usage": {
    "prompt_tokens": 47,
    "completion_tokens": 176,
    "total_tokens": 223,
    "completion_tokens_details": {
      "reasoning_tokens": 97
    },
    "prompt_tokens_details": {
      "cached_tokens": 25
    }
  }
}

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: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1677652288,"model":"axon-2-5-pro","choices":[{"index":0,"delta":{"content":"Hello"},"finish_reason":null}]}

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1677652288,"model":"axon-2-5-pro","choices":[{"index":0,"delta":{"content":"!"},"finish_reason":null}]}

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1677652288,"model":"axon-2-5-pro","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

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.

Example error response:

{
  "error": {
    "message": "Invalid API key provided",
    "type": "invalid_request_error",
    "code": "invalid_api_key"
  }
}

​Authentication

​Request

​Response

​Example Request

​Example Response

​Streaming

​Error Responses

Authentication

Request

Response

Example Request

Example Response

Streaming

Error Responses