> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stefanbrain.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Follow the content contract in AGENTS.md.
> Treat text as the canonical explanation; video and screenshots enhance it.
> Do not publish unverified product behavior or duplicate an existing canonical article.

# Structured outputs

> Constrain an Agent Run to return JSON that matches your schema.

Add `output_config.format` to a run request and the run's final answer is constrained to your JSON schema. The raw text returns in `output`; the parsed JSON returns in `structured_output`.

Structured outputs run in strict mode. Strict mode has three rules beyond ordinary JSON Schema:

* The root schema must have `"type": "object"`.
* Every object must set `"additionalProperties": false`.
* Every object must list ALL of its `properties` keys in `required`. Mark a field optional with a `["<type>", "null"]` type union instead.

The configuration must also meet these rules:

* `format.type` must be `"json_schema"`.
* `minItems` can only be `0` or `1`.
* Schemas are limited to 64 levels of nesting, 5,000 values, and 1,000 keys or items per object or array.

A configuration that breaks a rule returns `400` with the code `invalid_output_config` and a message that names the problem and, where one applies, the path.

```json theme={"system"}
{
  "message": "Extract the offer details from this landing page summary.",
  "sync": true,
  "output_config": {
    "format": {
      "type": "json_schema",
      "schema": {
        "type": "object",
        "properties": {
          "headline": { "type": "string" },
          "audience": { "type": "string" },
          "benefits": {
            "type": "array",
            "items": { "type": "string" }
          }
        },
        "required": ["headline", "audience", "benefits"],
        "additionalProperties": false
      }
    }
  }
}
```

`structured_output` is `null` until the run completes. A run that ends as `failed` or `cancelled` returns `structured_output: null`, even when `output` has text. A completed run also returns `null` when its final text is missing or is not a JSON object, for example after a refusal. The agent can still use tools during a structured-output run; the schema constrains the final answer only.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.