Was the Responses API designed by AI?

I appreciate the attempt to create a grand unifying API that covers all past and future approaches, but the level of complexity has exploded considerably.

I extracted the inner convex hull of items describing the Responses API from the much larger OpenAPI spec for all OpenAI APIs. Even this condensed version spans more than 4000 lines of YAML.

The specification includes references such as “#/components/schemas/CreateResponse” which, while intended to describe the request body of the “createResponse” operation, actually serves as a compendium of schemas describing what the end user should provide as input, properties that may have been returned by the model on prior turns, and other, more generic response properties.

This is just one example of design choices that significantly increase the cognitive load imposed on the end user.

The specification defines the API Reference page. That is why it is so huge. Auto-generated, more likely.

What is needed is a swagger validation specification of the API, but it seems that possible JSON bodies change day-by-day and model-by-model.

No. It’s 4000 lines of OpenAPI spec for the Responses API alone.
The OpenAPI spec for the whole API Reference is more than 1 MB of YAML.

Further, I understand that response schemas routinely become input schemas due to the back-and-forth nature of the interaction with models, but labeling as input something that is conceptually an output…is unsound.

In any case, that is my feedback…it’s easy to ignore and I do not wish to debate it, even though I just did in this reply. :innocent:

What you observe about the relationship between large input schema and large output is the correct cause in a way, but not related to developer’s response_format parameters.

That in streaming, there’s over a dozen events, and many of them are just reporting back inputs. response.completed will essentially dump your entire API call back at you with new keys. Thus, just right there, you get a specification larger than an API call.


You might find interesting the SDK’s overlooked version of turning chat completions into an event-emitter with response collector client-side: openai-python/helpers.md at main · openai/openai-python · GitHub