POST /v1/responses: Responses

POST /v1/responses takes the OpenAI Responses request and answers in its objects and events. Behind it is the same pipeline as chat completions: the same routing, memory, connector tools, agent mode and allowances. It exists because some clients speak only this wire, the Codex CLI among them.

Memtro keeps no conversation state against a response id: send the whole input every turn, which is what these clients do anyway.

Example

Against https://platform.memtro.com, with your key in MEMTRO_API_KEY.

curl https://platform.memtro.com/v1/responses \ -H "Authorization: Bearer $MEMTRO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "auto", "instructions": "Answer in one line.", "input": "Who owns the billing migration?" }'

from openai import OpenAI client = OpenAI(base_url="https://platform.memtro.com/v1", api_key="sk-memtro-…") response = client.responses.create( model="auto", instructions="Answer in one line.", input="Who owns the billing migration?", ) print(response.output_text)

import OpenAI from "openai"; const client = new OpenAI({ baseURL: "https://platform.memtro.com/v1", apiKey: process.env.MEMTRO_API_KEY }); const response = await client.responses.create({ model: "auto", instructions: "Answer in one line.", input: "Who owns the billing migration?", }); console.log(response.output_text);

A non-streaming reply.

{
  "id": "resp-9cTz…",
  "object": "response",
  "created_at": 1794470400,
  "status": "completed",
  "model": "anthropic/claude-opus-5",
  "output": [
    {
      "id": "resp-9cTz…-msg",
      "type": "message",
      "status": "completed",
      "role": "assistant",
      "content": [{ "type": "output_text", "text": "Priya owns it.", "annotations": [] }]
    }
  ],
  "output_text": "Priya owns it.",
  "usage": { "input_tokens": 3120, "output_tokens": 9, "total_tokens": 3129 },
  "memtro": { "mode": "chat", "routing": { "requested": "auto", "model": "anthropic/claude-opus-5", "complexity": 1, "method": "heuristic", "reason": "…", "fallbacks": ["…"], "kind": "general" } }
}

Authentication

An API key, as Authorization: Bearer or x-api-key.

Every reply, errors included, carries x-request-id and request-id headers with the same id, starting resp-. Quote it to support.
Browsers may call it from any origin: it answers CORS preflights and allows the Authorization, x-api-key and Anthropic version headers.

Request body

JSON, with Content-Type: application/json.

modelstringOptional

A model id or routing id; see Model ids. The older brain alias for the memtro field is not read on this wire.

Default:

memtro

inputstring or array of objectsRequired

A string (one user turn), or an array of items. Items that are not turns (reasoning, item_reference, a built-in tool's call, a compaction marker) are skipped, which is what a client replaying its own history sends.

5 fields of input

typestringOptional

message (or absent), function_call or function_call_output.

rolestringOptional

For a message.

One of system, developer, user or assistant.

contentstring or array of objectsOptional

For a message: text, or parts of type input_text, output_text (with text) or input_image (with image_url, a URL string or {url}; a data: URI or absolute http(s) URL).

name, arguments, call_idstringOptional

For a function_call: the tool, its arguments as a JSON string, and the call's id (id is read when call_id is absent).

outputanyOptional

For a function_call_output, with its call_id: your tool's result.

instructionsstring or nullOptional

Becomes a system message.

toolsarray of objectsOptional

Function tools, {"type": "function", "name", "description", "parameters"}, returned to you as function_call output items. Other kinds (a custom freeform tool, built-ins such as web_search) cannot be carried and are left out of what the model is offered, without an error.

tool_choicestring or objectOptional

none, auto, required, or {"type": "function", "name": …}.

streambooleanOptional

Answer as named server-sent events. See Streaming.

Default:

false

temperaturenumber or nullOptional

Passed to the provider.

top_pnumber or nullOptional

Passed to the provider.

max_output_tokensinteger or nullOptional

A ceiling on the answer's tokens. An answer cut short by it ends incomplete.

reasoningobject or nullOptional

effort is read as chat completions' reasoning_effort.

1 field of reasoning

effortstring or nullOptional: high, xhigh, max, medium or low.

store, previous_response_idanyOptional

Accepted and ignored: nothing is stored against a response id.

memtroobjectOptional

Memtro's options, the same keys as on chat completions; see the memtro object.

Response

200application/json

A response object.

idstringOptional

resp-…, the same id as the x-request-id header.

object"response"Optional

Always response.

created_atintegerOptional

Unix time, in seconds.

statusstringOptional

incomplete when max_output_tokens cut the answer short.

One of completed or incomplete.

modelstringOptional

The model that was picked.

outputarray of objectsOptional

A message item with output_text content, and a function_call item (name, call_id, arguments) for each call to your tools.

output_textstringOptional

The answer's text, joined.

usageobjectOptional

input_tokens, output_tokens, total_tokens.

incomplete_detailsobjectOptional

When incomplete: {"reason": "max_output_tokens"}.

memtroobjectOptional

As on chat completions; see What comes back.

200text/event-stream

With stream: true: named events, each also carrying type and a sequence_number. See Streaming.

Streaming

Every event has an event: line and a data: line whose JSON repeats the name as type, with a sequence_number. The run opens with response.created and response.in_progress; the answer comes as response.output_item.added, response.content_part.added, response.output_text.delta events, then response.output_text.done, response.content_part.done and response.output_item.done. A call to one of your tools is its own output item, with response.function_call_arguments.delta and .done. In agent mode, progress arrives as a reasoning item's response.reasoning_summary_text.delta events. The stream ends with response.completed, response.incomplete (status: "incomplete", incomplete_details.reason: "max_output_tokens") or response.failed, whose error has the code upstream_error.

event: response.created
data: {"type":"response.created","sequence_number":0,"response":{"id":"resp-9cTz…","object":"response","status":"in_progress","output":[],…}}

event: response.in_progress
data: {"type":"response.in_progress","sequence_number":1,…}

event: response.output_item.added
data: {"type":"response.output_item.added","sequence_number":2,"output_index":0,"item":{"id":"resp-9cTz…-msg","type":"message","status":"in_progress","role":"assistant","content":[]}}

event: response.content_part.added
data: {"type":"response.content_part.added","sequence_number":3,…}

event: response.output_text.delta
data: {"type":"response.output_text.delta","sequence_number":4,"item_id":"resp-9cTz…-msg","output_index":0,"content_index":0,"delta":"Priya owns it."}

event: response.output_text.done
data: {"type":"response.output_text.done","sequence_number":5,…,"text":"Priya owns it."}

event: response.content_part.done
data: {"type":"response.content_part.done","sequence_number":6,…}

event: response.output_item.done
data: {"type":"response.output_item.done","sequence_number":7,…}

event: response.completed
data: {"type":"response.completed","sequence_number":8,"response":{"id":"resp-9cTz…","status":"completed","output_text":"Priya owns it.","usage":{"input_tokens":3120,"output_tokens":9,"total_tokens":3129},…}}

Errors

In the OpenAI envelope, {"error": {"message", "type", "param", "code"}}. What each code means and what to do about it is in the error catalogue.

Status	Code	When
400	none	The body failed validation, or an image URL cannot be used.
400	`invalid_as_of`	`memtro.as_of` is not a calendar date.
400	`routing_unavailable`	`auto` found no usable ladder.
400	`provider_not_configured`	No key for the provider the model needs.
400	`invalid_provider_base_url`	An OpenAI-compatible endpoint's base URL cannot be used: not a URL, not `https://`, a user name or password in it, or a port not accepted.
400	`provider_base_url_not_allowed`	An OpenAI-compatible endpoint's host is not approved for the organisation, is private or internal, does not resolve, or redirected, whether refused before the request or during it.
401	`invalid_api_key`	The key is missing, malformed, revoked or expired.
402	`subscription_inactive`	The organisation has no active subscription.
404	`model_not_found`	Unknown model id.
429	`allowance_exhausted`	The month's allowance for the request's level is spent.
provider's	`upstream_error`	The provider returned an error.
503	`engine_unavailable`	The CLI a `claude-code/` or `codex/` model needs is not installed.
500	none	An internal error.

Responses