POST /v1/responses takes an OpenAI Responses request, searches your project’s indexes for the user’s question, adds what it finds to the prompt, and returns the reply as OpenAI’s streaming events or one Response object. Any OpenAI client with the Responses API works: change the base URL and the key. This page covers only where Moss Inference differs from OpenAI.
Base URL
Authentication
Send the project id and project key from the Moss portal as one bearer token:Request
These fields are accepted. A field set tonull counts as left out, and any other field returns 400, as Not supported lists.
The headers (
X-Moss-Indexes, X-Moss-Retrieve, X-Moss-Cache, X-Moss-Provider-Key), the reply headers such as X-Moss-Request-Id, and the limits are the same as on Chat Completions.
Input items
The search reads only the text of user messages, never images. An
input_image part, given by its image_url, goes to the model as it is. The moss model reads text only, so send images to a vendor model that reads them.
Conversations
Moss Inference keeps no conversation state. Each call sends the conversation so far, in order:- the earlier input items,
- the
outputitems of the last response, unchanged, - the new items: the next user message, or one
function_call_outputfor each function call.
instructions belongs to each call, so send it every time. Tool calls shows a full input.
Streaming
The events follow OpenAI’s streaming events. Moss Inference sends only these types:response.created, response.in_progress, response.output_item.added and .done, response.content_part.added and .done, response.output_text.delta and .done, response.function_call_arguments.delta and .done, and the mcp_call events under MCP servers. The stream ends with one event that carries the whole response: response.completed, response.incomplete for a reply cut by max_output_tokens or a content filter, or response.failed (see Errors). There is no data: [DONE].
Response
Withoutstream, the body is the response that the last event carries, in OpenAI’s shape. store is always false. output holds only message, function_call and mcp_call items. model is the name you sent, or moss when you sent none. status is incomplete for a reply cut short, and incomplete_details.reason says why: max_output_tokens or content_filter. tools leaves out MCP headers. usage.input_tokens includes the retrieved facts.
Examples
The Python and JavaScript examples below use OpenAI’s own clients. The Moss SDKs have their own client for this endpoint: Python, JavaScript, Swift, Android, Elixir, Browser, and C.Tool calls
Function tools take OpenAI’s flat shape, and your code runs them. Since nothing is stored, call again with the conversation, thefunction_call items unchanged, and one function_call_output for each call:
function_call item can carry fields beyond OpenAI’s, such as Gemini’s extra_content. Keep them: the model needs them on the next turn.
MCP servers
Atools entry of type mcp names an MCP server, with the fields listed on Chat Completions. Moss Inference connects to it, offers its tools to the model, runs the calls the model makes, and streams the final answer. It never asks for approval: require_approval can only be never. OpenAI’s connectors (connector_id) and its authorization field are not supported; send a token in headers.
Each MCP call is an mcp_call output item, streamed as response.output_item.added, response.mcp_call.in_progress, response.mcp_call_arguments.done, then response.mcp_call.completed or response.mcp_call.failed, and response.output_item.done:
status failed, output null, and an error of {"type": "mcp_tool_execution_error", "content": ...}.
Send mcp_call items back in input with the rest of the output. The model sees their results and does not run the tools again. An mcp_call with neither output nor error never finished, and its tool may have run, so it returns 400: check whether the tool ran, and send the outcome as a message in its place.
A tool may already have changed data when a call fails after it, so Moss Inference never retries that call. Without stream, it returns 424 with code failed_after_tool_call, the output items so far, and the header x-should-retry: false. On a stream, response.failed has error.code failed_after_tool_call. Do not replay such a call. The other MCP errors are listed under MCP errors.
Not supported
These return400 with type invalid_request_error, code unsupported_parameter, and a message that names the field:
previous_response_idandconversation. Nothing is stored, so send the whole conversation ininput.background: true, a non-emptyinclude,prompt, andtruncation: "auto".reasoningfields other thaneffort, such assummary, andtext.verbosityother thanmedium.- Tools other than
functionandmcp: OpenAI’s built-in tools, such asweb_search,file_search,code_interpreter,image_generation, computer use and shell, and custom tools. The same goes for atool_choicethat names one of them. - Content parts other than
input_text,output_textandinput_imagewith animage_url: files (input_file), audio (input_audio), and images given byfile_id. - Input items other than those in Input items, such as
item_reference. - Any field not listed under Request, such as
max_tool_callsortop_logprobs.
400 - Bad Request
moss model reads text only. See Input items.
Errors
An error before the stream starts has the same status, shape and cause as on Chat Completions. A failure after the stream starts ends it withresponse.failed. Its response.error has type, code and message, and its response.output holds the items so far. Without stream, the same failure returns 502 with the error shape, or 424 once an MCP call ran (see MCP servers).