Principle:Openai Openai node Parsed API Invocation
| Knowledge Sources | |
|---|---|
| Domains | Schema_Validation, NLP |
| Last Updated | 2026-02-15 00:00 GMT |
Overview
A principle for invoking language model APIs with automatic parsing of structured responses into typed objects using attached schema parsers.
Description
Parsed API Invocation extends the standard API call by automatically detecting AutoParseable format objects in the request and using their $parseRaw methods to parse the response content. This eliminates the manual JSON.parse + validation step, providing end-to-end type safety from schema definition to response consumption.
The parse method works by: (1) making the standard API call, (2) checking if response_format or tools carry $parseRaw methods, (3) calling those parsers on the raw content, and (4) attaching the parsed result to a parsed property on the response.
Usage
Use completions.parse() instead of completions.create() when your request includes a zodResponseFormat or zodFunction tool definitions. The parsed response will have a message.parsed property with the typed result.
Theoretical Basis
The parsing follows a Post-Processing Pipeline:
function parse(params):
// 1. Make standard API call
completion = await create(params)
// 2. For each choice, check for auto-parseable format
for choice in completion.choices:
if choice.message.refusal:
choice.message.parsed = null
continue
if params.response_format has $parseRaw:
choice.message.parsed = params.response_format.$parseRaw(choice.message.content)
// 3. Also parse tool call arguments if tools have $parseRaw
for tool_call in choice.message.tool_calls:
if tool has $parseRaw:
tool_call.function.parsed_arguments = tool.$parseRaw(tool_call.function.arguments)
return completion // with .parsed properties