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

# Structured output

> Get JSON that matches a schema.

Ask for JSON that follows a JSON Schema. Each endpoint uses its own field:

| Endpoint | Field |
| - | - |
| Chat Completions | `response_format`: `{"type": "json_schema", "json_schema": {"name", "schema", "strict"}}`, or `{"type": "json_object"}` for any JSON |
| Responses | `text.format` |
| Messages | `output_config.format`: `{"type": "json_schema", "schema": …}`. The JSON comes back as a `text` block |

```python Chat Completions theme={null}
import json

reply = client.chat.completions.create(
    model="a1",
    messages=[{"role": "user", "content": "Capital and population (millions) of Saudi Arabia?"}],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "country",
            "strict": True,
            "schema": {
                "type": "object",
                "properties": {"capital": {"type": "string"}, "population_millions": {"type": "number"}},
                "required": ["capital", "population_millions"],
                "additionalProperties": False,
            },
        },
    },
)
data = json.loads(reply.choices[0].message.content)
```

```python Messages theme={null}
import json

message = client.messages.create(
    model="a1",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Capital and population (millions) of Saudi Arabia?"}],
    output_config={
        "format": {
            "type": "json_schema",
            "schema": {
                "type": "object",
                "properties": {"capital": {"type": "string"}, "population_millions": {"type": "number"}},
                "required": ["capital", "population_millions"],
                "additionalProperties": False,
            },
        }
    },
)
data = json.loads(next(b.text for b in message.content if b.type == "text"))
```

## Tips

* Keep schemas simple: objects, arrays, strings, numbers, booleans, `enum`, `required`, and `additionalProperties: false`. Check ranges and formats in your code.
* If the model can't honor a schema, the request fails with `400 upstream_invalid_request`, and `param` names the field when known.
* Set `max_tokens` high enough for the whole object. Output cut off by the limit isn't valid JSON (`finish_reason: "length"` / `stop_reason: "max_tokens"`).


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