API builder

Output schemas

Define the JSON your endpoint returns, with nested objects and arrays, or use text, CSV or XML.

Formats

`output.format`	`data` in the response
`json`	The parsed JSON, matching `output.schema`.
`text`	A string.
`csv`	`{"columns": [...], "rows": [[...], ...]}` using `output.csv_columns`.
`xml`	A string shaped like `output.xml_template`.

With variations above 1, data is an array with one of those per answer.

The JSON schema subset

The schema is a subset of JSON Schema:

type: object, array, string, number, integer, boolean
properties and required for objects
items, minItems, maxItems for arrays
enum and description anywhere

Objects and arrays nest to any depth. $ref, oneOf and additionalProperties aren't supported; objects never allow extra properties.

{
  "type": "object",
  "properties": {
    "vendor": { "type": "string" },
    "total": { "type": "number", "description": "Grand total in the invoice currency" },
    "line_items": {
      "type": "array",
      "minItems": 1,
      "items": {
        "type": "object",
        "properties": {
          "description": { "type": "string" },
          "quantity": { "type": "integer" },
          "amount": { "type": "number" }
        },
        "required": ["description", "amount"]
      }
    }
  },
  "required": ["vendor", "total", "line_items"]
}

The console's output builder edits exactly this subset: add fields with a name, type, description, required flag and allowed values; give objects child fields; give arrays an item type, which can itself be an object. A live preview shows the JSON Schema and an example.

Validation and repair

The gateway asks the model for structured output and checks the answer against the schema. If it doesn't match, the gateway makes one repair attempt, sending the model its answer and the problems. If the second answer still doesn't match, the call fails with 502 invalid_model_output, and you're not handed data that breaks your contract.

Keep schemas small and descriptive. description on a field is sent to the model and is often the cheapest way to improve answers.