Json_schema Required in API Request Despite Documentation Stating Otherwise

[leventozkann]

The assistants API documentation specifies that when using the json_schema type in the response_format, only the name of the schema is required in the API request if the schema has already been pre-defined in the assistant settings. However, in practice, the API does not work unless the full json_schema definition is included in the request body. This behavior contradicts the documentation and creates unnecessary complexity.

Impact:

• Increased token usage due to redundant schema definitions in each request.
• Misalignment between the documentation and the actual API behavior.
• Unnecessary duplication of schema definitions, increasing maintenance overhead.

https://platform.openai.com/docs/api-reference/runs/createRun

current api response:

{
  "error": {
    "message": "Missing required parameter: 'response_format.json_schema.schema'.",
    "type": "invalid_request_error",
    "param": "response_format.json_schema.schema",
    "code": "missing_required_parameter"
  }
}

[_j]

Sorry, but the documentation says no such thing, and you fundamentally misunderstand how the placement of a schema works and how tokens are billed for it.

A run specification is an override of the default settings of an assistant. It must either be a valid enclosed schema that is a replacement for the one preconfigured, or you simply do not send the parameter.

The schema is part of the system message just like instructions. An AI model is stateless and has no “savings” - everything for an AI to understand must be placed into the model context on every run as billed input tokens: instructions, tool specification schemas, descriptions, and namespaces of internal tools and your functions and instructions of how to write multiple functions, past conversation by both the user and the AI, previous tool calls and the results, including the large results from file search.

[leventozkann]

Hello,

I would like to clarify my understanding of the schema behavior. In my assistant configuration, I have already defined a preconfigured schema. When I make API calls and include both the schema name and the schema definition in the request, it works as expected. However, when I only provide the schema name without the full schema definition, the API throws an error.

This behavior seems to contradict the documentation, where it states that the schema object is optional but the name is required. I’m having trouble understanding why the preconfigured schema is not being utilized in this case. Could you please confirm if this is the intended behavior or if there is something I might be missing?

Thank you for your guidance!