<!-- BusyBot node reference — https://busybot.net/tools/claude-structured-output/ -->

> Node: Claude Structured Output (`claude_structured_output`) · Action · v1
> Category: AI · Credentials: Anthropic (`anthropic`)
> Updated: 2026-08-16

# Claude Structured Output

> Get structured JSON responses from Claude via tool-use extraction.

## Overview

Sends a user message to the Anthropic Messages API (POST /v1/messages) with a tool definition whose input_schema matches the desired output structure. By setting tool_choice to force a specific tool, Claude is compelled to return structured JSON as the tool's input parameters. This is the standard pattern for structured output with Claude models, and it is supported on the Claude Opus, Sonnet, and Haiku models. Each input item produces one API call. The parsed structured object is placed in a configurable output field (default: "structured") along with model name, token usage, and stop reason.

**Category:** AI  
**Tool Name:** `claude_structured_output`  
**Version:** 1

**Appearance:** Icon: `anthropic` | Color: `#d4a574`

## Node Type

**Action** — processes input items and produces output

## Input / Output

| Direction | Port(s) |
|-----------|--------|
| Input | `Input` |
| Output | `Output`, `Error` |

## Credentials

This tool requires **Anthropic** credentials.
See the [Credentials Guide](https://busybot.net/credentials/anthropic/) for setup instructions.

### Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Model | `options` | No | `Claude Sonnet` | The Claude model to use for structured output extraction. Always uses the latest version (auto-updated). |
| | | | | Options: Claude Opus (most capable — complex extraction, nuanced analysis and multi-step reasoning), Claude Sonnet (balanced — strong quality at lower cost and latency), Claude Haiku (fastest — simple extraction, classification and high-volume work). Each option tracks the current release of its tier, so the underlying model ID updates without any change to your node. |
| System Prompt | `string` | No | — | Optional system prompt to guide the model on extraction behavior. Leave empty for default behavior. Supports expressions. |
| User Message | `string` | Yes | — | The user message or text to extract structured data from. Falls back to item.message or item.prompt if empty. Supports expressions like {{ $json.text }}. |
| Attachment File ID | `string` | No | — | Optional Anthropic file_id from a previous Claude File Upload node. When set, the file is attached so Claude can extract structured data from it. Falls back to item.fileId if empty. Supports expressions. |
| Attachment Type | `options` | No | `document` | How Claude should interpret the attached file. Ignored when Attachment File ID is empty. |
| | | | | Options: `document` (PDF, plaintext, or other document file), `image` (JPG, PNG, GIF, or WebP image) |
| Schema Description | `string` | No | `Extract structured data` | Description of what data the tool should extract. Helps guide Claude on the extraction task. Supports expressions. |
| JSON Schema | `json` | Yes | `{ "type": "object", "properties": { "result": { "type": "string" } }, "required": ["result"] }` | JSON Schema defining the structure of the data to extract. This becomes the tool's input_schema. |
| Options | `collection` | No | `{}` | Advanced generation and output settings. |
| — Max Tokens | `number` | No | `4096` | Maximum number of tokens to generate in the response. |
| — Temperature | `number` | No | `1` | Sampling temperature (0-1). Use 0 for most deterministic structured extraction. |
| — Response Field Name | `string` | No | `structured` | The output field name where the extracted structured data will be placed. |
| Include Input | `boolean` | No | `false` | Whether to include the original input item fields in the output alongside the structured response. |
| Max Concurrency | `number` | No | `10` | Maximum number of items to process concurrently. |

## Output Data

One API call per input item, and one output item per input item. The extracted object — already parsed, not a JSON string — lands on the field named by Response Field Name (`structured` by default). Binary data on the input item is forwarded unchanged, and with Include Input on the original item fields are merged in alongside the result.

```json
{
  "structured": { "name": "Sarah Chen", "email": "sarah.chen@example.com", "company": "Acme Corp" },
  "model": "claude-...",
  "usage": { "input_tokens": 268, "output_tokens": 74 },
  "stopReason": "tool_use"
}
```

- The shape of the object under the response field is exactly the shape you defined in JSON Schema, so downstream expressions can address its properties directly.
- `model` is the model that actually answered, as reported by Anthropic.
- `usage` is the token accounting Anthropic returned for the call.
- `stopReason` is normally `tool_use`, since the model is forced to answer by filling in the schema.

Reference the result downstream by expression, e.g. `{{ $json.structured.email }}`.

## Usage Examples

- Extract contact details from unstructured text into a JSON object
- Classify support tickets into categories with priority and summary
- Parse product descriptions into structured attributes
- Extract entities (people, organizations, dates) from documents
- Convert natural language into structured database records

## Example Configuration

Extract contact details from a support email:

```json
{
  "type": "claude_structured_output",
  "parameters": {
    "systemPrompt": "You are a data extraction assistant. Extract contact information exactly as it appears in the text.",
    "userMessage": "{{ $json.emailBody }}",
    "schemaDescription": "Extract contact information from the message",
    "jsonSchema": {
      "type": "object",
      "properties": {
        "name":    { "type": "string", "description": "Full name of the sender" },
        "email":   { "type": "string", "description": "Email address" },
        "phone":   { "type": "string", "description": "Phone number" },
        "company": { "type": "string", "description": "Company name" }
      },
      "required": ["name", "email"]
    },
    "options": {
      "temperature": 0,
      "maxTokens": 512,
      "responseFieldName": "contact"
    }
  }
}
```

Classification with a tight enum schema, tuned for volume:

```json
{
  "type": "claude_structured_output",
  "parameters": {
    "systemPrompt": "Analyze the sentiment of the provided customer review.",
    "userMessage": "{{ $json.reviewText }}",
    "schemaDescription": "Classify sentiment and extract key topics from customer feedback",
    "jsonSchema": {
      "type": "object",
      "properties": {
        "sentiment":  { "type": "string", "enum": ["positive", "neutral", "negative"] },
        "confidence": { "type": "number", "description": "Confidence between 0 and 1" },
        "topics":     { "type": "array", "items": { "type": "string" } }
      },
      "required": ["sentiment", "confidence", "topics"]
    },
    "includeInput": true,
    "maxConcurrency": 20,
    "options": {
      "temperature": 0,
      "maxTokens": 256,
      "responseFieldName": "sentimentResult"
    }
  }
}
```

Only extract what is actually stated, using a nullable schema:

```json
{
  "type": "claude_structured_output",
  "parameters": {
    "systemPrompt": "Only extract information explicitly stated in the text. Do not infer or guess missing values — use null for any field that is not clearly present.",
    "userMessage": "{{ $json.document }}",
    "schemaDescription": "Extract document metadata fields",
    "jsonSchema": {
      "type": "object",
      "properties": {
        "title":    { "type": ["string", "null"] },
        "author":   { "type": ["string", "null"] },
        "date":     { "type": ["string", "null"] },
        "language": { "type": ["string", "null"] }
      },
      "required": ["title", "author", "date", "language"]
    },
    "options": {
      "temperature": 0,
      "responseFieldName": "metadata"
    }
  }
}
```

### Error Handling

| Mode | Behavior |
|------|----------|
| **stop** | Halts workflow on first error |
| **continue** | Skips failed items, passes successful ones through |
| **errorPort** | Routes failed items to Error output port |

## Tips

Claude Structured Output calls the Anthropic Messages API with a tool definition whose input_schema matches a desired JSON structure, forcing Claude to return data as typed tool parameters. Use it when workflow nodes require predictable, schema-validated JSON rather than free-form text from the Claude Opus, Sonnet, or Haiku models. Each input produces one API call, outputting the parsed structured object, model name, token usage, and stop reason to a configurable field.