Responses API Reference | MatterAI Documentation

Responses

curl --request POST \
  --url https://api2.matterai.so/v1/responses \
  --header 'Content-Type: application/json' \
  --data '
{
  "model": "<string>",
  "input": {
    "role": "<string>",
    "content": {
      "type": "<string>",
      "text": "<string>",
      "image_url": "<string>"
    }
  },
  "instructions": "<string>",
  "max_output_tokens": 123,
  "stream": true,
  "reasoning": {
    "effort": "<string>",
    "summary": "<string>"
  },
  "temperature": 123,
  "top_p": 123,
  "text": {
    "format": {
      "type": "<string>",
      "name": "<string>",
      "schema": {},
      "strict": true
    },
    "verbosity": "<string>"
  },
  "store": true,
  "metadata": {}
}
'

import requests

url = "https://api2.matterai.so/v1/responses"

payload = {
    "model": "<string>",
    "input": {
        "role": "<string>",
        "content": {
            "type": "<string>",
            "text": "<string>",
            "image_url": "<string>"
        }
    },
    "instructions": "<string>",
    "max_output_tokens": 123,
    "stream": True,
    "reasoning": {
        "effort": "<string>",
        "summary": "<string>"
    },
    "temperature": 123,
    "top_p": 123,
    "text": {
        "format": {
            "type": "<string>",
            "name": "<string>",
            "schema": {},
            "strict": True
        },
        "verbosity": "<string>"
    },
    "store": True,
    "metadata": {}
}
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>',
    input: {
      role: '<string>',
      content: {type: '<string>', text: '<string>', image_url: '<string>'}
    },
    instructions: '<string>',
    max_output_tokens: 123,
    stream: true,
    reasoning: {effort: '<string>', summary: '<string>'},
    temperature: 123,
    top_p: 123,
    text: {
      format: {type: '<string>', name: '<string>', schema: {}, strict: true},
      verbosity: '<string>'
    },
    store: true,
    metadata: {}
  })
};

fetch('https://api2.matterai.so/v1/responses', 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/responses",
  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>',
    'input' => [
        'role' => '<string>',
        'content' => [
                'type' => '<string>',
                'text' => '<string>',
                'image_url' => '<string>'
        ]
    ],
    'instructions' => '<string>',
    'max_output_tokens' => 123,
    'stream' => true,
    'reasoning' => [
        'effort' => '<string>',
        'summary' => '<string>'
    ],
    'temperature' => 123,
    'top_p' => 123,
    'text' => [
        'format' => [
                'type' => '<string>',
                'name' => '<string>',
                'schema' => [
                                
                ],
                'strict' => true
        ],
        'verbosity' => '<string>'
    ],
    'store' => true,
    'metadata' => [
        
    ]
  ]),
  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/responses"

	payload := strings.NewReader("{\n  \"model\": \"<string>\",\n  \"input\": {\n    \"role\": \"<string>\",\n    \"content\": {\n      \"type\": \"<string>\",\n      \"text\": \"<string>\",\n      \"image_url\": \"<string>\"\n    }\n  },\n  \"instructions\": \"<string>\",\n  \"max_output_tokens\": 123,\n  \"stream\": true,\n  \"reasoning\": {\n    \"effort\": \"<string>\",\n    \"summary\": \"<string>\"\n  },\n  \"temperature\": 123,\n  \"top_p\": 123,\n  \"text\": {\n    \"format\": {\n      \"type\": \"<string>\",\n      \"name\": \"<string>\",\n      \"schema\": {},\n      \"strict\": true\n    },\n    \"verbosity\": \"<string>\"\n  },\n  \"store\": true,\n  \"metadata\": {}\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/responses")
  .header("Content-Type", "application/json")
  .body("{\n  \"model\": \"<string>\",\n  \"input\": {\n    \"role\": \"<string>\",\n    \"content\": {\n      \"type\": \"<string>\",\n      \"text\": \"<string>\",\n      \"image_url\": \"<string>\"\n    }\n  },\n  \"instructions\": \"<string>\",\n  \"max_output_tokens\": 123,\n  \"stream\": true,\n  \"reasoning\": {\n    \"effort\": \"<string>\",\n    \"summary\": \"<string>\"\n  },\n  \"temperature\": 123,\n  \"top_p\": 123,\n  \"text\": {\n    \"format\": {\n      \"type\": \"<string>\",\n      \"name\": \"<string>\",\n      \"schema\": {},\n      \"strict\": true\n    },\n    \"verbosity\": \"<string>\"\n  },\n  \"store\": true,\n  \"metadata\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api2.matterai.so/v1/responses")

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  \"input\": {\n    \"role\": \"<string>\",\n    \"content\": {\n      \"type\": \"<string>\",\n      \"text\": \"<string>\",\n      \"image_url\": \"<string>\"\n    }\n  },\n  \"instructions\": \"<string>\",\n  \"max_output_tokens\": 123,\n  \"stream\": true,\n  \"reasoning\": {\n    \"effort\": \"<string>\",\n    \"summary\": \"<string>\"\n  },\n  \"temperature\": 123,\n  \"top_p\": 123,\n  \"text\": {\n    \"format\": {\n      \"type\": \"<string>\",\n      \"name\": \"<string>\",\n      \"schema\": {},\n      \"strict\": true\n    },\n    \"verbosity\": \"<string>\"\n  },\n  \"store\": true,\n  \"metadata\": {}\n}"

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

{
  "400": {},
  "401": {},
  "429": {},
  "500": {},
  "id": "<string>",
  "object": "<string>",
  "status": "<string>",
  "created_at": 123,
  "model": "<string>",
  "output": [
    {
      "id": "<string>",
      "type": "<string>",
      "role": "<string>",
      "status": "<string>",
      "content": [
        {
          "type": "<string>",
          "text": "<string>",
          "annotations": [
            {}
          ]
        }
      ]
    }
  ],
  "output_text": "<string>",
  "usage": {
    "input_tokens": 123,
    "output_tokens": 123,
    "total_tokens": 123,
    "output_tokens_details": {
      "reasoning_tokens": 123
    },
    "input_tokens_details": {
      "cached_tokens": 123
    }
  },
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

POST

responses

Responses

curl --request POST \
  --url https://api2.matterai.so/v1/responses \
  --header 'Content-Type: application/json' \
  --data '
{
  "model": "<string>",
  "input": {
    "role": "<string>",
    "content": {
      "type": "<string>",
      "text": "<string>",
      "image_url": "<string>"
    }
  },
  "instructions": "<string>",
  "max_output_tokens": 123,
  "stream": true,
  "reasoning": {
    "effort": "<string>",
    "summary": "<string>"
  },
  "temperature": 123,
  "top_p": 123,
  "text": {
    "format": {
      "type": "<string>",
      "name": "<string>",
      "schema": {},
      "strict": true
    },
    "verbosity": "<string>"
  },
  "store": true,
  "metadata": {}
}
'

import requests

url = "https://api2.matterai.so/v1/responses"

payload = {
    "model": "<string>",
    "input": {
        "role": "<string>",
        "content": {
            "type": "<string>",
            "text": "<string>",
            "image_url": "<string>"
        }
    },
    "instructions": "<string>",
    "max_output_tokens": 123,
    "stream": True,
    "reasoning": {
        "effort": "<string>",
        "summary": "<string>"
    },
    "temperature": 123,
    "top_p": 123,
    "text": {
        "format": {
            "type": "<string>",
            "name": "<string>",
            "schema": {},
            "strict": True
        },
        "verbosity": "<string>"
    },
    "store": True,
    "metadata": {}
}
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>',
    input: {
      role: '<string>',
      content: {type: '<string>', text: '<string>', image_url: '<string>'}
    },
    instructions: '<string>',
    max_output_tokens: 123,
    stream: true,
    reasoning: {effort: '<string>', summary: '<string>'},
    temperature: 123,
    top_p: 123,
    text: {
      format: {type: '<string>', name: '<string>', schema: {}, strict: true},
      verbosity: '<string>'
    },
    store: true,
    metadata: {}
  })
};

fetch('https://api2.matterai.so/v1/responses', 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/responses",
  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>',
    'input' => [
        'role' => '<string>',
        'content' => [
                'type' => '<string>',
                'text' => '<string>',
                'image_url' => '<string>'
        ]
    ],
    'instructions' => '<string>',
    'max_output_tokens' => 123,
    'stream' => true,
    'reasoning' => [
        'effort' => '<string>',
        'summary' => '<string>'
    ],
    'temperature' => 123,
    'top_p' => 123,
    'text' => [
        'format' => [
                'type' => '<string>',
                'name' => '<string>',
                'schema' => [
                                
                ],
                'strict' => true
        ],
        'verbosity' => '<string>'
    ],
    'store' => true,
    'metadata' => [
        
    ]
  ]),
  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/responses"

	payload := strings.NewReader("{\n  \"model\": \"<string>\",\n  \"input\": {\n    \"role\": \"<string>\",\n    \"content\": {\n      \"type\": \"<string>\",\n      \"text\": \"<string>\",\n      \"image_url\": \"<string>\"\n    }\n  },\n  \"instructions\": \"<string>\",\n  \"max_output_tokens\": 123,\n  \"stream\": true,\n  \"reasoning\": {\n    \"effort\": \"<string>\",\n    \"summary\": \"<string>\"\n  },\n  \"temperature\": 123,\n  \"top_p\": 123,\n  \"text\": {\n    \"format\": {\n      \"type\": \"<string>\",\n      \"name\": \"<string>\",\n      \"schema\": {},\n      \"strict\": true\n    },\n    \"verbosity\": \"<string>\"\n  },\n  \"store\": true,\n  \"metadata\": {}\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/responses")
  .header("Content-Type", "application/json")
  .body("{\n  \"model\": \"<string>\",\n  \"input\": {\n    \"role\": \"<string>\",\n    \"content\": {\n      \"type\": \"<string>\",\n      \"text\": \"<string>\",\n      \"image_url\": \"<string>\"\n    }\n  },\n  \"instructions\": \"<string>\",\n  \"max_output_tokens\": 123,\n  \"stream\": true,\n  \"reasoning\": {\n    \"effort\": \"<string>\",\n    \"summary\": \"<string>\"\n  },\n  \"temperature\": 123,\n  \"top_p\": 123,\n  \"text\": {\n    \"format\": {\n      \"type\": \"<string>\",\n      \"name\": \"<string>\",\n      \"schema\": {},\n      \"strict\": true\n    },\n    \"verbosity\": \"<string>\"\n  },\n  \"store\": true,\n  \"metadata\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api2.matterai.so/v1/responses")

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  \"input\": {\n    \"role\": \"<string>\",\n    \"content\": {\n      \"type\": \"<string>\",\n      \"text\": \"<string>\",\n      \"image_url\": \"<string>\"\n    }\n  },\n  \"instructions\": \"<string>\",\n  \"max_output_tokens\": 123,\n  \"stream\": true,\n  \"reasoning\": {\n    \"effort\": \"<string>\",\n    \"summary\": \"<string>\"\n  },\n  \"temperature\": 123,\n  \"top_p\": 123,\n  \"text\": {\n    \"format\": {\n      \"type\": \"<string>\",\n      \"name\": \"<string>\",\n      \"schema\": {},\n      \"strict\": true\n    },\n    \"verbosity\": \"<string>\"\n  },\n  \"store\": true,\n  \"metadata\": {}\n}"

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

{
  "400": {},
  "401": {},
  "429": {},
  "500": {},
  "id": "<string>",
  "object": "<string>",
  "status": "<string>",
  "created_at": 123,
  "model": "<string>",
  "output": [
    {
      "id": "<string>",
      "type": "<string>",
      "role": "<string>",
      "status": "<string>",
      "content": [
        {
          "type": "<string>",
          "text": "<string>",
          "annotations": [
            {}
          ]
        }
      ]
    }
  ],
  "output_text": "<string>",
  "usage": {
    "input_tokens": 123,
    "output_tokens": 123,
    "total_tokens": 123,
    "output_tokens_details": {
      "reasoning_tokens": 123
    },
    "input_tokens_details": {
      "cached_tokens": 123
    }
  },
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

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 response. Available models: "axon-2-5-pro", "axon-2-5-mini".

string or array

required

Text or array of input items to the model, used to generate a response. Accepts a plain string (equivalent to a "user" message) or an array of input items.

Show Input Item (EasyInputMessage)

string

required

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

string or array

required

Text content or an array of content blocks.

Show Content Block

string

required

The type of content. Use "input_text" for text content, "input_image" for image URLs.

string

The text content (for input_text blocks).

string

The URL of the image (for input_image blocks).

string

A system (or developer) message inserted into the model’s context. When used with previous_response_id, instructions from a previous response are not carried over to the next response. Equivalent to the "system" role in chat completions.

integer

default:"512"

An upper bound for the number of tokens that can be generated for a response, including visible output tokens and reasoning tokens.

boolean

default:"false"

Whether to stream the response as it’s generated using server-sent events.

object

Configuration for reasoning capabilities.

Show Reasoning Object

string

default:"medium"

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

string

The level of reasoning summary. Options: "auto", "concise", "detailed".

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.

object

Configuration options for a text response from the model.

Show Text Config Object

object

An object specifying the format that the model must output.

Show Format Object

string

default:"text"

The type of response format. Options: "text", "json_schema", "json_object".

string

The name of the response format (for json_schema).

object

The JSON Schema for the response format (for json_schema).

boolean

Whether to enable strict schema adherence (for json_schema).

string

Constrains the verbosity of the model’s response. Options: "low", "medium", "high".

boolean

default:"true"

Whether to store the generated model response for later retrieval via API.

object

Set of up to 16 key-value pairs that can be attached to the response. Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters.

Response

string

Unique identifier for this response.

string

The object type, which is always "response".

string

The status of the response generation. One of "completed", "failed", "in_progress", "cancelled", or "incomplete".

integer

Unix timestamp (in seconds) of when this response was created.

string

The model used to generate the response. Available models: "axon-2-5-pro", "axon-2-5-mini".

array

An array of content items generated by the model.

Show Output Item (Message)

string

The unique ID of the output message.

string

The type of the output item. Always "message".

string

The role of the output message. Always "assistant".

string

The status of the message. One of "in_progress", "completed", "incomplete".

array

The content of the output message.

Show Content Block

string

The type of content. Values: "output_text", "refusal".

string

The text output from the model (for output_text blocks).

array

Annotations of the text output, such as citations.

string

SDK-only convenience property containing the aggregated text output from all output_text items in the output array.

object

Usage statistics for the response request.

Show Usage Object

integer

Number of tokens in the input.

integer

Number of tokens in the generated output.

integer

Total number of tokens used (input + output).

object

A detailed breakdown of the output tokens.

Show Output Tokens Details

integer

Number of tokens used for reasoning.

object

A detailed breakdown of the input tokens.

Show Input Tokens Details

integer

Number of tokens retrieved from cache.

object

An error object returned when the model fails to generate a response.

Show Error Object

string

The error code. Possible values: "server_error", "rate_limit_exceeded", "invalid_prompt", etc.

string

A human-readable description of the error.

Example Request

curl --location 'https://api2.matterai.so/v1/responses' \
--header 'content-type: application/json' \
--header 'Authorization: Bearer MATTERAI_API_KEY' \
--data '{
  "model": "axon-2-5-pro",
  "input": "Tell me a short story about a curious robot."
}'

const response = await fetch("https://api2.matterai.so/v1/responses", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Bearer MATTERAI_API_KEY",
  },
  body: JSON.stringify({
    model: "axon-2-5-pro",
    input: "Tell me a short story about a curious robot.",
  }),
});

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

import requests

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

payload = {
    "model": "axon-2-5-pro",
    "input": "Tell me a short story about a curious robot."
}

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

Example Response

{
  "id": "resp_abc123def456",
  "object": "response",
  "created_at": 1741476542,
  "status": "completed",
  "model": "axon-2-5-pro",
  "output": [
    {
      "id": "msg_abc123def456",
      "type": "message",
      "status": "completed",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "In a gleaming city of tomorrow, a small robot named Bolt was built to sort packages.",
          "annotations": []
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 27,
    "output_tokens": 94,
    "total_tokens": 121,
    "output_tokens_details": {
      "reasoning_tokens": 0
    },
    "input_tokens_details": {
      "cached_tokens": 0
    }
  }
}

Example: Multi-turn Conversation

To continue a conversation, pass the previous_response_id from the previous response:

curl --location 'https://api2.matterai.so/v1/responses' \
--header 'content-type: application/json' \
--header 'Authorization: Bearer MATTERAI_API_KEY' \
--data '{
  "model": "axon-2-5-pro",
  "input": "What happened next?",
  "previous_response_id": "resp_abc123def456"
}'

const response = await fetch("https://api2.matterai.so/v1/responses", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Bearer MATTERAI_API_KEY",
  },
  body: JSON.stringify({
    model: "axon-2-5-pro",
    input: "What happened next?",
    previous_response_id: "resp_abc123def456",
  }),
});

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

import requests

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

payload = {
    "model": "axon-2-5-pro",
    "input": "What happened next?",
    "previous_response_id": "resp_abc123def456"
}

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

Example: With Reasoning

curl --location 'https://api2.matterai.so/v1/responses' \
--header 'content-type: application/json' \
--header 'Authorization: Bearer MATTERAI_API_KEY' \
--data '{
  "model": "axon-2-5-pro",
  "instructions": "You are a helpful assistant that explains complex topics simply.",
  "input": "Explain quantum entanglement in one paragraph.",
  "reasoning": {
    "effort": "medium"
  }
}'

const response = await fetch("https://api2.matterai.so/v1/responses", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Bearer MATTERAI_API_KEY",
  },
  body: JSON.stringify({
    model: "axon-2-5-pro",
    instructions:
      "You are a helpful assistant that explains complex topics simply.",
    input: "Explain quantum entanglement in one paragraph.",
    reasoning: {
      effort: "medium",
    },
  }),
});

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

import requests

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

payload = {
    "model": "axon-2-5-pro",
    "instructions": "You are a helpful assistant that explains complex topics simply.",
    "input": "Explain quantum entanglement in one paragraph.",
    "reasoning": {
        "effort": "medium"
    }
}

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

Streaming

When stream is set to true, the API returns a stream of Server-Sent Events (SSE). The streaming events use the OpenAI Responses API format:

data: {"type":"response.created","response":{"id":"resp_abc123","object":"response","created_at":1741476542,"status":"in_progress","model":"axon-2-5-pro","output":[],"usage":null}}

data: {"type":"response.in_progress","response":{"id":"resp_abc123","object":"response","created_at":1741476542,"status":"in_progress","model":"axon-2-5-pro","output":[],"usage":null}}

data: {"type":"response.output_item.added","output_index":0,"item":{"id":"msg_abc123","type":"message","status":"in_progress","role":"assistant","content":[]}}

data: {"type":"response.content_part.added","item_id":"msg_abc123","output_index":0,"content_index":0,"part":{"type":"output_text","text":"","annotations":[]}}

data: {"type":"response.output_text.delta","item_id":"msg_abc123","output_index":0,"content_index":0,"delta":"Hello"}

data: {"type":"response.output_text.done","item_id":"msg_abc123","output_index":0,"content_index":0,"text":"Hello world!"}

data: {"type":"response.output_item.done","output_index":0,"item":{"id":"msg_abc123","type":"message","status":"completed","role":"assistant","content":[{"type":"output_text","text":"Hello world!","annotations":[]}]}}

data: {"type":"response.completed","response":{"id":"resp_abc123","object":"response","created_at":1741476542,"status":"completed","model":"axon-2-5-pro","output":[...],"usage":{"input_tokens":10,"output_tokens":12,"total_tokens":22}}}

Migrating from Chat Completions

The Responses API provides a cleaner interface for text generation. Key differences:

Chat Completions	Responses
`POST /v1/chat/completions`	`POST /v1/responses`
`messages` array	`input` (string or array)
`system` message role	`instructions` string parameter
`choices[0].message.content`	`output[].content[].text` or `output_text`
`max_tokens`	`max_output_tokens`
`finish_reason`	`status` field on response

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

​Example: Multi-turn Conversation

​Example: With Reasoning

​Streaming

​Migrating from Chat Completions

​Error Responses

Authentication

Request

Response

Example Request

Example Response

Example: Multi-turn Conversation

Example: With Reasoning

Streaming

Migrating from Chat Completions

Error Responses