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

# Structured output

> Get the session's result back as JSON in a shape you define.

Give a session a JSON Schema and the agent returns its result as JSON that follows it. Your code can then read the result without parsing prose.

Structured output is available on [sessions started without an agent](https://docs.lusor.ai/agents/send-a-turn.md#sessions-without-an-agent). Turns sent to an agent do not take a schema.

## Send a schema

Add `schema` to the request body:

```bash cURL theme={null}
curl https://api.lusor.ai/v1/workspaces/<workspace id>/devices/<device id>/sessions \
  -H "X-Api-Key: $LUSOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Find the price of a 12-pack of sparkling water in the grocery app.",
    "schema": {
      "type": "object",
      "properties": {
        "price": { "type": "number" },
        "currency": { "type": "string" }
      },
      "required": ["price", "currency"]
    }
  }'
```

```python Python theme={null}
import os, requests

r = requests.post(
    "https://api.lusor.ai/v1/workspaces/<workspace id>/devices/<device id>/sessions",
    headers={"X-Api-Key": os.environ["LUSOR_API_KEY"]},
    json={
        "prompt": "Find the price of a 12-pack of sparkling water in the grocery app.",
        "schema": {
            "type": "object",
            "properties": {"price": {"type": "number"}, "currency": {"type": "string"}},
            "required": ["price", "currency"],
        },
    },
)
session_id = r.json()["id"]
```

```javascript Node.js theme={null}
const res = await fetch(
  "https://api.lusor.ai/v1/workspaces/<workspace id>/devices/<device id>/sessions",
  {
    method: "POST",
    headers: { "X-Api-Key": process.env.LUSOR_API_KEY, "Content-Type": "application/json" },
    body: JSON.stringify({
      prompt: "Find the price of a 12-pack of sparkling water in the grocery app.",
      schema: {
        type: "object",
        properties: { price: { type: "number" }, currency: { type: "string" } },
        required: ["price", "currency"],
      },
    }),
  },
);
const { id: sessionId } = await res.json();
```

## Read the output

When the session is `completed`, read it:

```bash theme={null}
curl https://api.lusor.ai/v1/sessions/<session id> \
  -H "X-Api-Key: $LUSOR_API_KEY"
```

```json theme={null}
{
  "id": "…",
  "status": "completed",
  "outputSchema": { "type": "object", "properties": { … } },
  "output": { "price": 6.49, "currency": "USD" },
  "error": null
}
```

`output` follows your schema. `outputSchema` echoes the schema you sent. `output` is also in `GET /v1/sessions/{id}/artifacts`.

## Tips

* Describe the task in `prompt` and the result's shape in `schema`. The schema does not replace instructions.
* Mark the fields you always need as `required`.
* Use `description` on properties to say what each field means, for example the currency format you want.
* `output` is filled only when the session completes. A failed session has `error` instead.


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