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

# Structured output

> How to request a JSON result from the Seltz Agent API instead of Markdown

## Overview

To get an Agent run's answer as a JSON object matching your own schema instead of
freeform Markdown, request structured output by passing a schema when you
start the run.

## Provide a schema

Pass [`output_schema`](/api-reference/agent/start-run#body-output-schema-one-of-0)
(an OpenAI-style `response_format` object) to get
[`output.structured`](/api-reference/agent/start-run#response-output-one-of-1),
a JSON result shaped by your schema, in addition to the usual cited
[`output.text`](/api-reference/agent/start-run#response-output-one-of-1)
report.

<CodeGroup>
  ```python Python theme={null}
  OUTPUT_SCHEMA = {
      "type": "json_schema",
      "json_schema": {
          "name": "acquisitions",
          "schema": {
              "type": "object",
              "properties": {
                  "acquisitions": {
                      "type": "array",
                      "items": {
                          "type": "object",
                          "properties": {
                              "acquirer": {"type": "string"},
                              "target": {"type": "string"},
                          },
                          "required": ["acquirer", "target"],
                          "additionalProperties": False,
                      },
                  },
              },
              "required": ["acquisitions"],
              "additionalProperties": False,
          },
          "strict": True,
      },
  }

  run = client.agent.create_and_wait(
      "What are three notable AI-company acquisitions announced in 2026?",
      output_schema=OUTPUT_SCHEMA,
  )

  import json

  result = json.loads(run.output.structured)
  for deal in result["acquisitions"]:
      print(deal["acquirer"], "->", deal["target"])
  ```

  ```typescript TypeScript theme={null}
  const outputSchema = {
    type: "json_schema",
    json_schema: {
      name: "acquisitions",
      schema: {
        type: "object",
        properties: {
          acquisitions: {
            type: "array",
            items: {
              type: "object",
              properties: {
                acquirer: { type: "string" },
                target: { type: "string" },
              },
              required: ["acquirer", "target"],
              additionalProperties: false,
            },
          },
        },
        required: ["acquisitions"],
        additionalProperties: false,
      },
      strict: true,
    },
  };

  const run = await client.agent.createAndWait({
    query: "What are three notable AI-company acquisitions announced in 2026?",
    outputSchema,
  });

  const result = JSON.parse(run.output!.structured!);
  for (const deal of result.acquisitions) {
    console.log(deal.acquirer, "->", deal.target);
  }
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.seltz.ai/v1/agent/runs \
    -H "x-api-key: $SELTZ_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "query": "What are three notable AI-company acquisitions announced in 2026?",
      "output_schema": {
        "type": "json_schema",
        "json_schema": {
          "name": "acquisitions",
          "strict": true,
          "schema": {
            "type": "object",
            "properties": {
              "acquisitions": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "acquirer": {"type": "string"},
                    "target": {"type": "string"}
                  },
                  "required": ["acquirer", "target"],
                  "additionalProperties": false
                }
              }
            },
            "required": ["acquisitions"],
            "additionalProperties": false
          }
        }
      }
    }'
  ```
</CodeGroup>

A completion for the request above looks like this:

```json theme={null}
{
  "acquisitions": [
    { "acquirer": "SpaceX", "target": "Anysphere (Cursor)" },
    { "acquirer": "Zendesk", "target": "Forethought" },
    { "acquirer": "Palo Alto Networks", "target": "Console" }
  ]
}
```

The matching [`output.grounding`](/api-reference/agent/start-run#response-output-one-of-1) looks like the following,
one entry per groundable field, each citing back into
[`output.sources`](/api-reference/agent/start-run#response-output-one-of-1)
by `source_id`:

```json theme={null}
[
  {
    "field": "acquisitions.0.acquirer",
    "citations": [{ "source_id": 1, "url": "https://www.latestly.com/technology/spacex-to-acquire-ai-coding-startup-cursor-in-usd-60-billion-deal-7475967.html" }]
  },
  {
    "field": "acquisitions.0.target",
    "citations": [{ "source_id": 1, "url": "https://www.latestly.com/technology/spacex-to-acquire-ai-coding-startup-cursor-in-usd-60-billion-deal-7475967.html" }]
  }
]
```

## Schema validity

Create validates `output_schema`'s wrapper shape, including `type`, and
`json_schema.name` / `schema` / `strict` for type `json_schema`, before
billing anything, and rejects a malformed one there. It does not validate
the schema's *content*.

For `strict: true`, every object in the schema needs its own
`additionalProperties: false`, including nested ones like the array item
object above. Create accepts a schema missing it, but the run then fails
with `stop_reason: invalid_output`.

## Results

A run that produces no JSON output at all fails
with `stop_reason: invalid_output` rather than returning something
unparsable.

Ungroundable fields come back `null` in `output.structured`. This is the same "don't guess" contract
[Answer](/answer/guides/structured-response) follows.

## Next steps

* [Basic run](/agent/guides/basic-run): the full request/response cycle, including the cURL poll
* [Handle errors](/agent/guides/handle-errors): rejected requests versus failed runs
* [Reference](/agent/reference): endpoints, fields, limits and errors
* [Agent API Reference](/api-reference/agent/start-run#body-output-schema-one-of-0): full `output_schema` request and response specification