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

# Structured outputs

> Get JSON responses, optionally matching a schema you supply

Use `response_format` when your code needs to parse the model's reply. The model then responds with JSON in `message.content`.

| `response_format.type` | Output |
| - | - |
| `text` | Plain text. This is the behavior when `response_format` is omitted. |
| `json_object` | A valid JSON object. |
| `json_schema` | JSON that matches the schema you supply. |

## JSON schema

Set `type` to `json_schema` and pass a `json_schema` object with a `name` (up to 64 characters) and a JSON Schema `schema`. You can also add a `description`. A `json_schema` request without the `json_schema` object returns a `400` error with code `missing_required_parameter`.

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.reflection.ai/openai/v1/chat/completions \
    -H "Authorization: Bearer $REFLECTION_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "Beam-501B-A23B",
      "messages": [
        {"role": "user", "content": "Extract the event: Team offsite in Lisbon on May 4, 2027."}
      ],
      "response_format": {
        "type": "json_schema",
        "json_schema": {
          "name": "event",
          "schema": {
            "type": "object",
            "properties": {
              "name": {"type": "string"},
              "city": {"type": "string"},
              "date": {"type": "string", "description": "ISO 8601 date"}
            },
            "required": ["name", "city", "date"],
            "additionalProperties": false
          }
        }
      }
    }'
  ```

  ```python Python theme={null}
  import json
  import os
  from openai import OpenAI

  client = OpenAI(
      base_url="https://api.reflection.ai/openai/v1",
      api_key=os.environ["REFLECTION_API_KEY"],
  )

  schema = {
      "type": "object",
      "properties": {
          "name": {"type": "string"},
          "city": {"type": "string"},
          "date": {"type": "string", "description": "ISO 8601 date"},
      },
      "required": ["name", "city", "date"],
      "additionalProperties": False,
  }

  completion = client.chat.completions.create(
      model="Beam-501B-A23B",
      messages=[
          {"role": "user", "content": "Extract the event: Team offsite in Lisbon on May 4, 2027."}
      ],
      response_format={
          "type": "json_schema",
          "json_schema": {"name": "event", "schema": schema},
      },
  )

  choice = completion.choices[0]
  if choice.finish_reason != "stop" or choice.message.refusal or not choice.message.content:
      raise RuntimeError(
          f"No structured output (finish_reason={choice.finish_reason}, "
          f"refusal={choice.message.refusal})"
      )

  event = json.loads(choice.message.content)
  print(event["city"])
  ```

  ```typescript TypeScript theme={null}
  import OpenAI from "openai";

  const client = new OpenAI({
    baseURL: "https://api.reflection.ai/openai/v1",
    apiKey: process.env.REFLECTION_API_KEY,
  });

  const completion = await client.chat.completions.create({
    model: "Beam-501B-A23B",
    messages: [
      { role: "user", content: "Extract the event: Team offsite in Lisbon on May 4, 2027." },
    ],
    response_format: {
      type: "json_schema",
      json_schema: {
        name: "event",
        schema: {
          type: "object",
          properties: {
            name: { type: "string" },
            city: { type: "string" },
            date: { type: "string", description: "ISO 8601 date" },
          },
          required: ["name", "city", "date"],
          additionalProperties: false,
        },
      },
    },
  });

  const choice = completion.choices[0];
  if (choice.finish_reason !== "stop" || choice.message.refusal || !choice.message.content) {
    throw new Error(
      `No structured output (finish_reason=${choice.finish_reason}, refusal=${choice.message.refusal})`,
    );
  }

  const event = JSON.parse(choice.message.content);
  console.log(event.city);
  ```
</CodeGroup>

```json Output theme={null}
{"name": "Team offsite", "city": "Lisbon", "date": "2027-05-04"}
```

## Strict mode

Set `json_schema.strict` to `true` to enable strict schema adherence. In strict mode, `schema` must be an object schema in which every object sets `additionalProperties: false` and lists all of its properties in `required`, as the example above does.

Strict schemas can't use these keywords: `allOf`, `oneOf`, `not`, `if`, `then`, `else`, `contains`, `minContains`, `maxContains`, `uniqueItems`, `unevaluatedItems`, `propertyNames`, `minProperties`, `maxProperties`, `unevaluatedProperties`, `dependentRequired`, `dependentSchemas`, `patternProperties`, `multipleOf`, `exclusiveMinimum`, and `exclusiveMaximum`. Some keyword combinations and `pattern` constructs are also refused.

The same rules apply to a tool's `parameters` when the tool sets `strict: true`. See [Tool calling](/tool-calling#strict-mode).

## JSON mode

`{"type": "json_object"}` asks for any valid JSON object, without a schema. Describe the shape you want in the prompt, and say that the answer should be JSON.

JSON mode doesn't apply a schema, so a request that sends `json_schema` with `type: "json_object"` or `type: "text"` returns a `400` error with code `unsupported_parameter`. To have the output match a schema, use `type: "json_schema"`.

## Handle edge cases

Before parsing `content`, check the response:

* `finish_reason: "length"` means the output was cut off and is probably not valid JSON. Raise `max_completion_tokens`.
* A non-null `message.refusal` means the model declined the request; `content` does not contain your JSON.

<Tip>
  To have the model return arguments for your own functions rather than a final answer, use [tool calling](/tool-calling) instead.
</Tip>