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 tonull 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:- 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 calling shows a full input.
Streaming
The events follow OpenAI’s streaming events. Moss sends only these types:response.createdandresponse.in_progressresponse.output_item.addedandresponse.output_item.doneresponse.content_part.addedandresponse.content_part.doneresponse.output_text.deltaandresponse.output_text.doneresponse.function_call_arguments.deltaandresponse.function_call_arguments.doneresponse.mcp_call.in_progress,response.mcp_call_arguments.done,response.mcp_call.completedandresponse.mcp_call.failed, for each MCP call and eachmoss_searchcall
There is no
data: [DONE]. Streaming shows how to read the events and stop early.
Response
Withoutstream, 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 thefaq index from the Quickstart.
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
function,mcpandmoss_search: 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/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 theinput to send back.
MCP servers
Atools 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
Atools 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 withfailed_after_tool_call.