Skip to main content
POST /v1/responses takes an OpenAI Responses request, searches the indexes the call names for the user’s message, and returns a Response object or a stream of events. The Moss SDKs call this endpoint, and so can any OpenAI client with the Responses API.
Send the whole conversation in input on every call. Moss stores no responses, so previous_response_id and conversation return 400. See Conversations.

Base URL

Authentication

Send your project id and project key from the Moss portal as one bearer token:

Request

Only these fields are accepted. A field set to null counts as left out. Any other field returns 400. See Not supported. The request and reply headers are the same as on Chat Completions. So are the limits, listed in Errors and limits. On the Moss key, a vendor model refuses some fields with 400 and code unsupported_parameter. Models lists them.

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. moss/fastlane-1 reads text only, so send images to a vendor model that reads them.

Conversations

Moss 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 calling shows a full input.

Streaming

The events follow OpenAI’s streaming events. Moss sends only these types:
  • response.created and response.in_progress
  • response.output_item.added and response.output_item.done
  • response.content_part.added and response.content_part.done
  • response.output_text.delta and response.output_text.done
  • response.function_call_arguments.delta and response.function_call_arguments.done
  • response.mcp_call.in_progress, response.mcp_call_arguments.done, response.mcp_call.completed and response.mcp_call.failed, for each MCP call and each moss_search call
The stream ends with one event that carries the whole response: There is no data: [DONE]. Streaming shows how to read the events and stop early.

Response

Without stream, the body is the response that the final event carries, in OpenAI’s shape.

Examples

The Python and JavaScript tabs use OpenAI’s own clients. The Moss SDKs, such as Python and JavaScript, have their own client for this endpoint. SDKs lists the other platforms. Each example streams a reply grounded in the faq index from the Quickstart.

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, mcp and moss_search: 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. moss/fastlane-1 reads text only. OpenAI compatibility sums up every difference from OpenAI.

Tool calls

Function tools take OpenAI’s flat shape, and your code runs them. Tool calling shows the loop and the input to send back.

MCP servers

A tools entry of type mcp names a server that Moss runs for the model, and each call comes back as an mcp_call output item. MCP servers has the fields, the events and how to send mcp_call items back.

Moss search tool

A tools entry of type moss_search lets the model search your project’s indexes. Each search comes back as an mcp_call output item with server_label moss and name moss_search. It streams the same response.mcp_call.* events as an MCP call. Send the item back in input unchanged, like any mcp_call. Moss search tool has the fields and the billing.

Errors

An error before the stream starts uses OpenAI’s error shape, with the statuses and codes in Errors and limits. Never replay a request that failed with failed_after_tool_call.