Skip to main content
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.
Moss Inference stores no responses. store is ignored, and previous_response_id and conversation are refused: send the whole conversation in input on every call, as Conversations shows. Background responses, OpenAI’s built-in tools such as web search and file search, file and audio input, and images on the moss model are not supported either. See Not supported for the full list.
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 to null 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:
  1. the earlier input items,
  2. the output items of the last response, unchanged,
  3. the new items: the next user message, or one function_call_output for 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

Without stream, 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, the function_call items unchanged, and one function_call_output for each call:
A 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

A tools 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:
A failed call has 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 return 400 with type invalid_request_error, code unsupported_parameter, and a message that names the field:
  • previous_response_id and conversation. Nothing is stored, so send the whole conversation in input.
  • background: true, a non-empty include, prompt, and truncation: "auto".
  • reasoning fields other than effort, such as summary, and text.verbosity other than medium.
  • Tools other than function and mcp: OpenAI’s built-in tools, such as web_search, file_search, code_interpreter, image_generation, computer use and shell, and custom tools. The same goes for a tool_choice that names one of them.
  • Content parts other than input_text, output_text and input_image with an image_url: files (input_file), audio (input_audio), and images given by file_id.
  • Input items other than those in Input items, such as item_reference.
  • Any field not listed under Request, such as max_tool_calls or top_logprobs.
400 - Bad Request
Images are not on this list because a vendor model can read them. The 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 with response.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).