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 The model to use for completion. Currently supports "axon".
An array of message objects that make up the conversation. The role of the message author. One of "system", "user", or
"assistant".
The content of the message.
Whether to stream the response as it’s generated.
A list of tools the model may call. Currently, only functions are supported as
a tool type. The type of the tool. Currently, only "function" is supported.
The function definition. 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.
A description of what the function does, used by the model to choose
when and how to call the function.
The parameters the function accepts, described as a JSON Schema
object.
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.
The maximum number of tokens to generate in the completion.
Configuration for reasoning capabilities. The level of reasoning effort. Options: "none", "low", "medium",
"high".
The level of reasoning summary. Options: "none", "auto".
The format of the response. Show Response Format Object
The type of response format. Currently supports "text" OR json.
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.
Controls diversity via nucleus sampling. Range: 0.0 to 1.0.
Response A unique identifier for the chat completion.
The object type, which is always "chat.completion".
The Unix timestamp (in seconds) of when the chat completion was created.
The model used for the chat completion.
A list of chat completion choices. The index of the choice in the list of choices.
The message generated by the model. The role of the author of this message. Always "assistant".
The contents of the message.
The reason the model stopped generating tokens. Possible values: "stop",
"length", "content_filter".
Usage statistics for the completion request. Number of tokens in the prompt.
Number of tokens in the generated completion.
Total number of tokens used in the request (prompt + completion).
Example Request 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 }'
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-code" , "object" : "chat.completion" , "usage" : { "prompt_tokens" : 34 , "completion_tokens" : 1031 , "total_tokens" : 1065 , "completion_tokens_details" : { "reasoning_tokens" : 1001 }, "prompt_tokens_details" : { "cached_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: { "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:
Invalid request parameters or malformed JSON.
Invalid or missing API key.
Too many requests. Please slow down.
Server error. Please try again later.
Example error response:
{ "error" : { "message" : "Invalid API key provided" , "type" : "invalid_request_error" , "code" : "invalid_api_key" } } 
