> ## 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.

# Messages

> Create a message completion using the MatterAI API (Anthropic-compatible)

## 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 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 `"user"`, or `"assistant"`.
    </ParamField>

    <ParamField body="content" type="array" required>
      The content of the message, as an array of content blocks.

      <Expandable title="Content Block">
        <ParamField body="type" type="string" required>
          The type of content block. Use `"text"` for text content.
        </ParamField>

        <ParamField body="text" type="string" required>
          The text content.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="system" type="array">
  System prompts to provide context or instructions.

  <Expandable title="System Block">
    <ParamField body="type" type="string" required>
      The type of block. Use `"text"` for text content.
    </ParamField>

    <ParamField body="text" type="string" required>
      The system prompt text.
    </ParamField>
  </Expandable>
</ParamField>

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

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

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

  <Expandable title="Thinking Object">
    <ParamField body="type" type="string" default="enabled">
      The type of thinking. Use `"enabled"` to enable thinking.
    </ParamField>

    <ParamField body="budget_tokens" type="integer" default="8192">
      The maximum tokens to use for thinking.
    </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 message completion.
</ResponseField>

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

<ResponseField name="role" type="string">
  The role of the response, always `"assistant"`.
</ResponseField>

<ResponseField name="content" type="array">
  The content blocks in the response.

  <Expandable title="Content Block">
    <ResponseField name="type" type="string">
      The type of content block. Values: `"text"`, `"thinking"`.
    </ResponseField>

    <ResponseField name="text" type="string">
      The text content (for text blocks).
    </ResponseField>

    <ResponseField name="thinking" type="string">
      The thinking content (for thinking blocks).
    </ResponseField>

    <ResponseField name="thinking_latency_ms" type="number">
      The latency in milliseconds for the thinking process.
    </ResponseField>
  </Expandable>
</ResponseField>

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

<ResponseField name="stop_reason" type="string">
  The reason the model stopped generating tokens. Possible values: `"end_turn"`,
  `"stop_sequence"`, `"max_tokens"`.
</ResponseField>

<ResponseField name="stop_sequence" type="string">
  The stop sequence that triggered the stop, if any.
</ResponseField>

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

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

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

    <ResponseField name="cache_creation_input_tokens" type="integer">
      Number of tokens used for creating the cache.
    </ResponseField>

    <ResponseField name="cache_read_input_tokens" type="integer">
      Number of tokens read from cache.
    </ResponseField>
  </Expandable>
</ResponseField>

## Example Request

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

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

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

## Example Response

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

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

<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": {
    "type": "error",
    "error": {
      "type": "authentication_error",
      "message": "Invalid API key provided"
    }
  }
}
```