tai/research/muse-responses-openai-transpiler/openai-responses-api-reference.md

# Responses | OpenAI API Reference

## Metadata

| Field | Value |
|---|---|
| Institute | Molodetz Institute — Research & Retrieval Division |
| Subject | muse-responses-openai-transpiler |
| Document type | Source Dossier |
| Tier | 1 |
| Source title | Responses |
| Source URL | https://developers.openai.com/api/reference/resources/responses |
| Source publisher / author | OpenAI |
| Source type | vendor docs |
| Source date (published) | Unknown — not stated |
| Date researched | 2026-10-11 |
| Researched by | tai (agent), model: Muse Spark (Muse Code), on behalf of retoor |
| Research method | direct page fetch |
| Confidence | High |
| Status | Active |

## Summary

The full Responses API reference. It defines `POST /responses` body parameters, the `EasyInputMessage` input shape, internally-tagged function tools, `function_call` / `function_call_output` Items correlated by `call_id`, output messages with `output_text` / `refusal` parts, and the typed SSE event vocabulary. Every Meta request field in the local capture has a documented counterpart here except the `muse` namespace tool.

## Key findings

- Create call is `POST /responses` with body parameters including `input`, `instructions`, `tools`, `tool_choice`, `text`, `stream`, `store`, `previous_response_id`, `max_output_tokens`, `reasoning`, `include`, `prompt_cache_key`, `parallel_tool_calls`, `temperature`, `top_p`, `truncation`, `metadata`, and `user`.
- `instructions` is "A system (or developer) message inserted into the model's context." and "When using along with `previous_response_id`, the instructions from a previous response will not be carried over to the next response."
- `EasyInputMessage` roles are exactly `user`, `assistant`, `system`, `developer`; string content or part lists of `input_text`, `input_image`, `input_file`.
- Function tools are internally tagged: `{type: "function", name, parameters, strict, description, ...}`.
- `function_call` Items carry string `arguments`, a `call_id` ("The unique ID of the function tool call generated by the model"), and `name`; `function_call_output` answers with the same `call_id` plus string or part-list `output`.
- Output messages contain `output_text` (`{text, annotations, logprobs, type}`) or `refusal` (`{refusal, type}`) parts.
- Streaming vocabulary includes `response.created`, `response.in_progress`, `response.output_text.delta` (`{item_id, output_index, content_index, delta}`), `response.function_call_arguments.delta` / `.done`, and `response.completed` carrying the full response object with `usage {input_tokens, output_tokens, total_tokens}`.
- `include` supports `reasoning.encrypted_content`: "Includes an encrypted version of reasoning tokens in reasoning item outputs. This enables reasoning items to be used in multi-turn conversations when using the Responses API statelessly".

## Pros / strengths

- Authoritative schema detail down to field optionality, with request and SSE examples.
- `include` / `store: false` / encrypted-reasoning semantics directly explain the Meta client's stateless posture.
- Documents both lifecycle events and delta events, which is exactly what a stream transpiler needs.

## Cons / limitations / caveats

- The page is about 5 MB; the fetch was truncated and the dossier rests on targeted excerpts (create params, input/tool/output/streaming sections), not a full read.
- No `namespace` tool type is documented, confirming Meta's `muse` tool set is a vendor extension with no portable mapping.
- Fast-moving surface: newer built-in tools and programmatic-calling fields postdate any fixed summary.

## Relevance to tai

- Supplies the exact request, object, and event shapes the transpiler emits and parses.
- Verifies the absence of `n`, `stop`, `seed`, and sampling-penalty parameters, which become documented transpile-time drops.
- The `prompt_cache_key` parameter exists upstream too, so Meta's cache keys transpile as scalars rather than extensions.

## Changelog

| Date | Change |
|---|---|
| 2026-10-11 | Initial dossier created. |