> ## 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"`, `"axon-mini"`, `"axon-2"`.
</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_tokens" type="integer" default="8192">
  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"`, `"axon-mini"`, `"axon-2"`.
</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://api.matterai.so/v1/chat/completions' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer MATTERAI_API_KEY' \
  --data '{
      "model": "axon-code",
      "messages": [
          {
              "role": "system",
              "content": "You are a helpful assistant"
          },
          {
              "role": "user",
              "content": "Hi"
          }
      ],
      "stream": true,
      "tools": [
          {
              "type": "function",
              "function": {
                  "name": "codebase_search",
                  "description": "`codebase_search`: semantic search that finds code by meaning, not exact text",
                  "parameters": {
                      "type": "object",
                      "properties": {
                          "explanation": {
                              "type": "string",
                              "description": "One sentence explanation as to why this tool is being used, and how it contributes to the goal."
                          },
                          "query": {
                              "type": "string",
                              "description": "A complete question about what you want to understand. Ask as if talking to a colleague: 'How does X work?', 'What happens when Y?', 'Where is Z handled?'"
                          },
                          "target_directories": {
                              "type": "array",
                              "items": {
                                  "type": "string"
                              },
                              "description": "Prefix directory paths to limit search scope (single directory only, no glob patterns)"
                          },
                          "search_only_prs": {
                              "type": "boolean",
                              "description": "If true, only search pull requests and return no code results."
                          }
                      },
                      "required": [
                          "explanation",
                          "query",
                          "target_directories"
                      ]
                  }
              }
          }
      ],
      "tool_choice": "auto",
      "max_tokens": 2000,
      "reasoning": {
          "effort": "none",
          "summary": "none"
      },
      "response_format": {
          "type": "text"
      },
      "temperature": 0.1,
      "top_p": 1
  }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.matterai.so/v1/chat/completions', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer MATTERAI_API_KEY'
      'X-MATTERAI-REASONING-EFFORT': 'high', // Optional header | 'none', 'low', 'medium', 'high', default is 'high'
      'X-MATTERAI-REASONING-SUMMARY': 'none' // Optional header | 'none', 'auto', default is 'none'
    },
    body: JSON.stringify({
      model: 'axon',
      messages: [
        {
          role: 'system',
          content: 'You are a helpful assistant'
        },
        {
          role: 'user',
          content: 'Hi'
        }
      ],
      stream: true,
      tools: [
        {
          type: 'function',
          function: {
            name: 'codebase_search',
            description: '`codebase_search`: semantic search that finds code by meaning, not exact text',
            parameters: {
              type: 'object',
              properties: {
                explanation: {
                  type: 'string',
                  description: 'One sentence explanation as to why this tool is being used, and how it contributes to the goal.'
                },
                query: {
                  type: 'string',
                  description: 'A complete question about what you want to understand. Ask as if talking to a colleague: \'How does X work?\', \'What happens when Y?\', \'Where is Z handled?\''
                },
                target_directories: {
                  type: 'array',
                  items: {
                    type: 'string'
                  },
                  description: 'Prefix directory paths to limit search scope (single directory only, no glob patterns)'
                },
                search_only_prs: {
                  type: 'boolean',
                  description: 'If true, only search pull requests and return no code results.'
                }
              },
              required: [
                'explanation',
                'query',
                'target_directories'
              ]
            }
          }
        }
      ],
      tool_choice: 'auto',
      max_tokens: 2000, // Optional parameter | default is 32768
      reasoning: {
        effort: 'none', // Optional parameter | 'none', 'low', 'medium', 'high', default is 'high'
        summary: 'none' // Optional parameter | 'none', 'auto', default is 'none'
      },
      response_format: {
        type: 'text'
      },
      temperature: 0.1, // Optional parameter | default is 0.1
      top_p: 1 // Optional parameter | default is 0.95
    })
  });

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

  ```python Python theme={null}
  import requests

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

  payload = {
      "model": "axon",
      "messages": [
          {
              "role": "system",
              "content": "You are a helpful assistant"
          },
          {
              "role": "user",
              "content": "What is MatterAI Axon?"
          }
      ],
      "stream": True,
      "tools": [
          {
              "type": "function",
              "function": {
                  "name": "codebase_search",
                  "description": "`codebase_search`: semantic search that finds code by meaning, not exact text",
                  "parameters": {
                      "type": "object",
                      "properties": {
                          "explanation": {
                              "type": "string",
                              "description": "One sentence explanation as to why this tool is being used, and how it contributes to the goal."
                          },
                          "query": {
                              "type": "string",
                              "description": "A complete question about what you want to understand. Ask as if talking to a colleague: 'How does X work?', 'What happens when Y?', 'Where is Z handled?'"
                          },
                          "target_directories": {
                              "type": "array",
                              "items": {
                                  "type": "string"
                              },
                              "description": "Prefix directory paths to limit search scope (single directory only, no glob patterns)"
                          },
                          "search_only_prs": {
                              "type": "boolean",
                              "description": "If true, only search pull requests and return no code results."
                          }
                      },
                      "required": [
                          "explanation",
                          "query",
                          "target_directories"
                      ]
                  }
              }
          }
      ],
      "tool_choice": "auto",
      "max_tokens": 2000,
      "reasoning": {
          "effort": "none",
          "summary": "none"
      },
      "response_format": {
          "type": "text"
      },
      "temperature": 0.1,
      "top_p": 1
  }

  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-code",
  "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","choices":[{"index":0,"delta":{"content":"Hello"},"finish_reason":null}]}

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

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1677652288,"model":"axon","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"
  }
}
```