Structured output

Require a Codex turn to return JSON that conforms to a schema.

Pass outputSchema to thread.run() when a caller needs machine-readable output. The SDK forwards a JSON Schema to the Codex CLI.

const turn = await thread.run("Summarize repository status", {
  outputSchema: {
    type: "object",
    properties: {
      summary: { type: "string" },
      status: { type: "string", enum: ["ok", "action_required"] },
    },
    required: ["summary", "status"],
    additionalProperties: false,
  } as const,
});

The final response is serialized according to the requested schema. Keep schemas small and explicit, and validate the result at your application boundary.

Updated Aug 31, 2026