OpenAI staff, please, take a look at your API Reference pages. I’ve detected that the Responses API is badly documented: The current version says that all the fields in the request body are optional! In previous versions at least the fields input and model were required. https://platform.openai.co…

That is because prompts were introduced. If a prompt is supplied, it already has the input and model references. Before input and model being optional, when supplied a prompt it would still require these fields, which was why now they are optional. It’s not like we don’t need to supply any parame…

Hey @aprendendo.next , thanks for the advice. I think OpenAI’s staff could add a note in the documentation to explain this situation.

Agreed, @sashirestela , especially when the example shared by @aprendendo.next itself shows a model parameter being passes within the API call, making it ambiguous as to whether it’s a required field or not.

Is it correct the following statement when creating a Response object? You must provide either the prompt field or the input + model fields, but not both at the same time.

[image] sashirestela: You must provide either the prompt field or the input + model fields, but not both at the same time. That cannot be correct if the example in documentation is assumed to actually work: response = client.responses.create( model="gpt-4.1", prompt={ "id": "…

When providing a prompt, you can also optionally provide a model to override it. And if provided with an input, it will be appended to the conversation defined in the prompt template before running.

Has anyone gotten this to work? I get this error: TypeError: Missing required arguments; Expected either (‘input’ and ‘model’) or (‘input’, ‘model’ and ‘stream’) arguments to be given. <a class="lightbox" href="https://us1.discourse-cdn.com/openai1/original/4X/5/f/7/5f703fdf65caf2ed91d464ba765d9268baecf85c.png" data-download-href="/uploads/short-url/dChQTtMUihSEHC0qkMbNfJ1ZoWE.png?dl=1" title="A code snippet shows a function call to 'client.responses.create' with several parameters including 'prompt', 'input', 'reasoning', 'max_output_tokens', and 'store'. (Captioned by AI)" rel="noopener nofollow ugc">[A code snippet shows a function call to 'client.responses.create' with several parameters including 'prompt', …

[image] Mark_mj: I get this error: TypeError: Missing required arguments; Expected either (‘input’ and ‘model’) or (‘input’, ‘model’ and ‘stream’) arguments to be given. you need to upgrade your package pip install --upgrade openai

Upgrading my package was what was needed. Thanks!

⚠ Responses API is badly documented

Documentation

sashirestela July 1, 2025, 11:31pm 5

You are right @jai

Topic		Replies	Views
Responses API documentation on structured outputs is lacking Documentation structured-output , responses-api	7	2486	December 20, 2025
GPT 5.2 not working with reusable prompts in responses api Bugs	16	2363	December 18, 2025
Does Batch API support Responses endpoint with reusable prompts? API batch-api , responses-endpoint , responses-api	4	402	November 30, 2025
There's no Response documentation for any API calls Documentation api	6	1868	July 6, 2023
Feedback on Chat Prompts in API: Decoupling Prompts from Models Feedback prompts	2	215	August 23, 2025

⚠ Responses API is badly documented

Related topics