> ## Documentation Index
> Fetch the complete documentation index at: https://docs.matterai.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Chat

> Create a chat completion using the MatterAI API

## Authentication

All API requests require authentication using a Bearer token. You can obtain your API key from the [MatterAI Console](https://app.matterai.so).

```bash theme={null}
Authorization: Bearer MATTERAI_API_KEY
```

<Warning>
  Keep your API key secure and never expose it in client-side code. Get your API
  key from the MatterAI console.
</Warning>

## Request

<ParamField body="model" type="string" required>
  The model used for the chat completion. Available models: `"axon-2-5-pro"`, `"axon-2-5-mini"`.
</ParamField>

<ParamField body="messages" type="array" required>
  An array of message objects that make up the conversation.

  <Expandable title="Message Object">
    <ParamField body="role" type="string" required>
      The role of the message author. One of `"system"`, `"user"`, or
      `"assistant"`.
    </ParamField>

    <ParamField body="content" type="string" required>
      The content of the message.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="stream" type="boolean" default="false">
  Whether to stream the response as it's generated.
</ParamField>

<ParamField body="tools" type="array">
  A list of tools the model may call. Currently, only functions are supported as
  a tool type.

  <Expandable title="Tool Object">
    <ParamField body="type" type="string" required>
      The type of the tool. Currently, only `"function"` is supported.
    </ParamField>

    <ParamField body="function" type="object" required>
      The function definition.

      <Expandable title="Function Object">
        <ParamField body="name" type="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.
        </ParamField>

        <ParamField body="description" type="string">
          A description of what the function does, used by the model to choose
          when and how to call the function.
        </ParamField>

        <ParamField body="parameters" type="object">
          The parameters the function accepts, described as a JSON Schema
          object.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="tool_choice" type="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.
</ParamField>

<ParamField body="max_new_tokens" type="integer" default="2048">
  The maximum number of tokens to generate in the completion.
</ParamField>

<ParamField body="reasoning" type="object">
  Configuration for reasoning capabilities.

  <Expandable title="Reasoning Object">
    <ParamField body="effort" type="string" default="high">
      The level of reasoning effort. Options: `"none"`, `"low"`, `"medium"`,
      `"high"`.
    </ParamField>

    <ParamField body="summary" type="string" default="none">
      The level of reasoning summary. Options: `"none"`, `"auto"`.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="response_format" type="object">
  The format of the response.

  <Expandable title="Response Format Object">
    <ParamField body="type" type="string" default="text">
      The type of response format. Currently supports `"text"` OR `json`.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="temperature" type="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.
</ParamField>

<ParamField body="top_p" type="number" default="1">
  Controls diversity via nucleus sampling. Range: 0.0 to 1.0.
</ParamField>

## Response

<ResponseField name="id" type="string">
  A unique identifier for the chat completion.
</ResponseField>

<ResponseField name="object" type="string">
  The object type, which is always `"chat.completion"`.
</ResponseField>

<ResponseField name="created" type="integer">
  The Unix timestamp (in seconds) of when the chat completion was created.
</ResponseField>

<ResponseField name="model" type="string">
  The model used for the chat completion. Available models: `"axon-2-5-pro"`, `"axon-2-5-mini"`.
</ResponseField>

<ResponseField name="choices" type="array">
  A list of chat completion choices.

  <Expandable title="Choice Object">
    <ResponseField name="index" type="integer">
      The index of the choice in the list of choices.
    </ResponseField>

    <ResponseField name="message" type="object">
      The message generated by the model.

      <Expandable title="Message Object">
        <ResponseField name="role" type="string">
          The role of the author of this message. Always `"assistant"`.
        </ResponseField>

        <ResponseField name="content" type="string">
          The contents of the message.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="finish_reason" type="string">
      The reason the model stopped generating tokens. Possible values: `"stop"`,
      `"length"`, `"content_filter"`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="usage" type="object">
  Usage statistics for the completion request.

  <Expandable title="Usage Object">
    <ResponseField name="prompt_tokens" type="integer">
      Number of tokens in the prompt.
    </ResponseField>

    <ResponseField name="completion_tokens" type="integer">
      Number of tokens in the generated completion.
    </ResponseField>

    <ResponseField name="total_tokens" type="integer">
      Total number of tokens used in the request (prompt + completion).
    </ResponseField>
  </Expandable>
</ResponseField>

## Example Request

<CodeGroup>
  ```bash cURL theme={null}
  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
      }
  }'
  ```

  ```javascript JavaScript theme={null}
  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);
  ```

  ```python Python theme={null}
  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())
  ```
</CodeGroup>

## Example Response

```json theme={null}
{
  "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:

```json theme={null}
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:

<ResponseField name="400" type="Bad Request">
  Invalid request parameters or malformed JSON.
</ResponseField>

<ResponseField name="401" type="Unauthorized">
  Invalid or missing API key.
</ResponseField>

<ResponseField name="429" type="Rate Limited">
  Too many requests. Please slow down.
</ResponseField>

<ResponseField name="500" type="Internal Server Error">
  Server error. Please try again later.
</ResponseField>

Example error response:

```json theme={null}
{
  "error": {
    "message": "Invalid API key provided",
    "type": "invalid_request_error",
    "code": "invalid_api_key"
  }
}
```