Full API-Spec — Complete JSON and Every Field Explained
This is the complete Messages API learning atlas for this KB. Start with one order lookup, then expand optional feature requests. Every attribute in the displayed JSON has a path, meaning, owner, and learning link. Examples use illustrative IDs, token counts, and outcomes; they are not captured live responses. Features and model support change: the official reference remains authoritative for additional provider-specific and beta variants.
Next: SDK implementation and the JSON behind it · Earlier field reference.
When a setting is not provided
A full picture includes omissions. Each request example has a folded “Not supplied” note. An optional field can be absent because the feature is unused, because a documented default applies, or because an SDK helper supplies it. Those are different cases.
| Case | How to read it |
|---|---|
| Not supplied | The complete displayed body/call omits the setting. Read the stated behavior. |
| Not visible | A fragment or **request hides the enclosing fields. Do not conclude the feature is off. |
| Generated by SDK | For example, parse(output_format=Invoice) produces output_config.format. |
| Model-dependent default | Check the selected model; do not assume a universal thinking/effort setting. |
The notes cover the shared Messages settings used in this KB. Feature-specific defaults remain linked to their detailed glossary and current documentation. Required fields such as model, messages, and max_tokens are not optional defaults to guess. Likewise, omitted context_management does not mean “compact at 100,000”; that threshold only applies when configured.
Official Messages reference↗ · Tool selection defaults↗.
Read the envelope first
New to betas? It lists the exact beta feature names this request opts into. The SDK sends them in a header. Decode the name, date, and values · Read the plain explanation.
An HTTP request has a destination, headers, and a JSON body. Headers do not belong inside messages. The Python helper's arguments are not always JSON body fields.
HTTP
POST https://api.anthropic.com/v1/messages
Content-Type: application/json
x-api-key: <configured credential>
anthropic-version: 2023-06-01
anthropic-beta: compact-2026-01-12| Header or setting | Meaning | When sent |
|---|---|---|
| URL and POST | Send a Messages request to Claude's service. | Every API call. |
| Content-Type | The body is JSON. | Every JSON request. |
| x-api-key | Authentication credential managed by your application. Never put it in the prompt. | API-key authentication; SDK can set it. |
| anthropic-version | API contract version, not the selected model version. | Required API version header; SDK sets it. |
| anthropic-beta | Opt in to the specific feature named here. | The compaction example; omit for the ordinary order example. |
Set once in Python does not mean sent only once. A shared system variable may be configured once, but it is included in each relevant HTTP request. messages changes as your application appends turns. Compaction header and body documentation↗.
Request body versus conversation messages
You are not missing anything: context_management is request input. The first order example omits it because that short lookup does not need compaction. An example request shows selected fields; it is not the complete list of optional API fields.
| Location | What belongs here | Open the explanation |
|---|---|---|
| HTTP headers | Authentication, API version, and the compaction beta identifier. | betas |
| JSON body, top level | model, max_tokens, system, tools, messages, and optional settings such as context_management or output_config. |
Request field catalog |
messages[] |
Individual conversation turns, each with role and content. |
Messages |
context_management.edits[] |
Context operations, such as the compaction strategy and its threshold. | Context management |
Complete request with context_management — see its position beside messages
JSON
{
"model": "claude-sonnet-4-6",
"max_tokens": 4096,
"messages": [
{
"role": "user",
"content": [
{
"type": "text",
"text": "Help me plan a long research task."
}
]
}
],
"context_management": {
"edits": [
{
"type": "compact_20260112",
"trigger": {
"type": "input_tokens",
"value": 100000
}
}
]
}
}Not supplied in this example — defaults and disabled features
| Setting not supplied or not visible | Meaning for this example |
|---|---|
| output_config — not supplied here | No output_config schema or effort override is supplied. A prompt asking for JSON does not provide schema enforcement. |
| tools — not supplied here | No tools are offered through this field. |
| tool_choice — not supplied here | With tools supplied, the default is auto: the model chooses whether to request a tool. Without tools, no supplied tool can be selected. |
| system — not supplied here | No application system instructions are supplied through this field. User messages still provide task text. |
| stop_sequences — not supplied here | No custom stop strings are configured. Generation can still stop for end_turn, tool_use, max_tokens, or another documented reason. |
| stream — not supplied here | For a direct non-streaming create/parse call, the result is one message rather than an event stream. A stream helper configures this separately. |
| thinking — not supplied here | No explicit thinking override is shown. Behavior depends on the selected model; omission does not universally mean thinking is off. |
| cache_control — not supplied here | No top-level automatic cache marker is supplied. Check nested system/tool/content blocks for separate cache_control markers. |
| metadata — not supplied here | No application user reference is supplied through metadata. Authentication still comes from the request credentials. |
Full request catalog and omission rules. JSON has no comments; these notes are outside the payload.
For this configuration, send anthropic-beta: compact-2026-01-12 as a header. The short input will not trigger compaction; this example shows where to enable it. Explain every nested field.
The naming trap: “Messages API request” means the whole request body. The field named messages is only one part of that body. There is no messages[0].context_management in this configuration.
One order through the complete exchange
sequenceDiagram participant App as Your application participant API as Claude Messages API participant Tool as get_order function App->>API: Request 1: instructions + tool definition + question API-->>App: Response 1: tool_use with order_id App->>Tool: Validate access, then execute Tool-->>App: Order status App->>API: Request 2: previous turns + linked tool_result API-->>App: Response 2: answer text, end_turn
Request 1 — ask about an order
JSON
{
"model": "claude-sonnet-4-6",
"max_tokens": 1024,
"system": "You help customers check order status. Use get_order for order facts. Never invent a status.",
"tools": [
{
"name": "get_order",
"description": "Read the status of an order the signed-in customer may access.",
"input_schema": {
"type": "object",
"properties": {
"order_id": {
"type": "string",
"description": "The order identifier, for example O-104."
}
},
"required": [
"order_id"
],
"additionalProperties": false
},
"strict": true
}
],
"tool_choice": {
"type": "auto"
},
"messages": [
{
"role": "user",
"content": [
{
"type": "text",
"text": "Where is order O-104?"
}
]
}
],
"stream": false
}Not supplied in this example — defaults and disabled features
| Setting not supplied or not visible | Meaning for this example |
|---|---|
| context_management — not supplied here | No server compaction strategy is enabled by this body. Host/manual compaction is separate. |
| output_config — not supplied here | No output_config schema or effort override is supplied. A prompt asking for JSON does not provide schema enforcement. |
| stop_sequences — not supplied here | No custom stop strings are configured. Generation can still stop for end_turn, tool_use, max_tokens, or another documented reason. |
| thinking — not supplied here | No explicit thinking override is shown. Behavior depends on the selected model; omission does not universally mean thinking is off. |
| cache_control — not supplied here | No top-level automatic cache marker is supplied. Check nested system/tool/content blocks for separate cache_control markers. |
| metadata — not supplied here | No application user reference is supplied through metadata. Authentication still comes from the request credentials. |
Full request catalog and omission rules. JSON has no comments; these notes are outside the payload.
Explain every attribute in request 1
| Exact JSON path | Meaning and use | Set or change | Learn more |
|---|---|---|---|
model |
Model ID selected by your application; use one supporting the enabled features. | Usually fixed; changes for deliberate routing | Glossary · Domain 5 |
max_tokens |
Maximum generated output tokens for this call, not input size or money. | Tune per task/turn | Glossary · Domain 5 |
system |
Standing instructions supplied by the application. String or text-block list. | Usually fixed and re-sent | Glossary · Domain 3 |
tools |
List of available tool definitions. This JSON does not contain Python function code. | Usually fixed; narrow to needed tools | Glossary · Domain 4 |
tools[] |
List of available tool definitions. This JSON does not contain Python function code. | Usually fixed; narrow to needed tools | Glossary · Domain 4 |
tools[].name |
Tool identifier used to dispatch the returned request to your function. | Per request or application configuration | Glossary · Domain 4 |
tools[].description |
Explains when the model should select the tool. | Per request or application configuration | Glossary · Domain 4 |
tools[].input_schema |
Schema for tool arguments, not the final answer. | Per request or application configuration | Glossary · Domain 4 |
tools[].input_schema.type |
object means the model supplies a JSON object. | Per request or application configuration | Glossary · Domain 3 |
tools[].input_schema.properties |
Named application fields and their definitions. These names are chosen by us. | Per request or application configuration | Glossary · Domain 3 |
tools[].input_schema.properties.order_id |
Schema for our order_id application field. It is not an Anthropic API parameter. | Per request or application configuration | Glossary · Domain 3 |
tools[].input_schema.properties.order_id.type |
string means text; integer means a whole number. Here the type applies to order_id. | Per request or application configuration | Glossary · Domain 3 |
tools[].input_schema.properties.order_id.description |
Human explanation of this application field for the model. | Per request or application configuration | Glossary · Domain 3 |
tools[].input_schema.required |
Lists fields that must be present; being required does not make a value factually correct. | Per request or application configuration | Glossary · Domain 3 |
tools[].input_schema.required[] |
Lists fields that must be present; being required does not make a value factually correct. | Per request or application configuration | Glossary · Domain 3 |
tools[].input_schema.additionalProperties |
false disallows extra keys not defined in properties. | Per request or application configuration | Glossary · Domain 3 |
tools[].strict |
API generation must follow this tool input schema where supported; still check authorization. | Per request or application configuration | Glossary · Domain 4 |
tool_choice |
auto allows the model to choose a tool or answer without one. It does not run the function. | Per request or application configuration | Glossary · Domain 4 |
tool_choice.type |
auto allows the model to choose a tool or answer without one. It does not run the function. | Per request or application configuration | Glossary · Domain 4 |
messages |
Ordered conversation being sent now. Store it in your application. | Changes as turns and results are appended | Glossary · Domain 1 |
messages[] |
Ordered conversation being sent now. Store it in your application. | Changes as turns and results are appended | Glossary · Domain 1 |
messages[].role |
user supplies task/tool results; assistant carries previous model content. | Set for each appended turn | Glossary · Domain 1 |
messages[].content |
Text or typed blocks belonging to this conversation turn. | Changes each turn | Glossary · Domain 1 |
messages[].content[] |
Text or typed blocks belonging to this conversation turn. | Changes each turn | Glossary · Domain 1 |
messages[].content[].type |
Discriminator: tells the API how to read this block, such as text, tool_result, or document. | Per request or application configuration | Glossary · Domain 4 |
messages[].content[].text |
Actual instruction or task text; surrounding JSON keys describe its location. | Per request or application configuration | Glossary · Domain 3 |
stream Not on CCAR-F |
false returns a completed message JSON; true requests a sequence of server-sent events. | Usually fixed by UI needs | Glossary · Domain 1 |
Response 1 — Claude requests a tool
JSON
{
"id": "msg_demo_1",
"type": "message",
"role": "assistant",
"model": "claude-sonnet-4-6",
"content": [
{
"type": "tool_use",
"id": "toolu_demo_1",
"name": "get_order",
"input": {
"order_id": "O-104"
}
}
],
"stop_reason": "tool_use",
"stop_sequence": null,
"usage": {
"input_tokens": 180,
"output_tokens": 35,
"cache_creation_input_tokens": 0,
"cache_read_input_tokens": 0
}
}Explain every attribute in response 1
| Exact JSON path | Meaning and use | Set or change | Learn more |
|---|---|---|---|
id |
API-generated message identifier; not a customer/order ID. | Returned each response | Glossary · Domain 5 |
type |
message identifies the outer response envelope. | Returned by API | Glossary · Domain 1 |
role |
assistant identifies the model response. | Returned by API | Glossary · Domain 1 |
model |
Model ID selected by your application; use one supporting the enabled features. | Usually fixed; changes for deliberate routing | Glossary · Domain 5 |
content |
List of response blocks. Inspect block.type rather than assuming element zero is text. | Returned by API | Glossary · Domain 1 |
content[] |
List of response blocks. Inspect block.type rather than assuming element zero is text. | Returned by API | Glossary · Domain 1 |
content[].type |
text or tool_use in these examples; other feature-specific blocks are possible. | Returned by API | Glossary · Domain 1 |
content[].id |
Unique tool-call identifier used by the matching tool_result.tool_use_id. | Returned by API | Glossary · Domain 4 |
content[].name |
Requested tool name. Your code maps it to an allowed implementation. | Returned by API | Glossary · Domain 4 |
content[].input |
Requested arguments, already a JSON object. order_id is our application-defined property. | Returned by API; validate before execution | Glossary · Domain 4 |
content[].input.order_id |
Requested arguments, already a JSON object. order_id is our application-defined property. | Returned by API; validate before execution | Glossary · Domain 4 |
stop_reason |
Why this model turn ended. Branch on this before treating the content as complete. | Returned by API | Glossary · Domain 1 |
stop_sequence |
The matched custom string, or null when none matched. Request name is plural: stop_sequences. | Returned by API | Glossary · Domain 1 |
usage |
Measurements of this model call; use for accounting and context monitoring. Sample values are illustrative. | Per request or application configuration | Glossary · Domain 5 |
usage.input_tokens |
Input tokens outside separately reported cache categories. Do not mistake this for cumulative conversation cost. | Per request or application configuration | Glossary · Domain 5 |
usage.output_tokens |
Tokens generated for this response; often less than max_tokens. | Per request or application configuration | Glossary · Domain 5 |
usage.cache_creation_input_tokens |
Input tokens used to write a cache entry on this call. | Per request or application configuration | Glossary · Domain 5 |
usage.cache_read_input_tokens |
Input tokens served from cache on this call; cached input still occupies context. | Per request or application configuration | Glossary · Domain 5 |
Request 2 — send the real tool result
The application checks access, reads its backend, preserves the assistant blocks, and appends a matching user-role tool result. A tool result is input to the next model call.
Complete second request and every path
JSON
{
"model": "claude-sonnet-4-6",
"max_tokens": 1024,
"system": "You help customers check order status. Use get_order for order facts. Never invent a status.",
"tools": [
{
"name": "get_order",
"description": "Read the status of an order the signed-in customer may access.",
"input_schema": {
"type": "object",
"properties": {
"order_id": {
"type": "string",
"description": "The order identifier, for example O-104."
}
},
"required": [
"order_id"
],
"additionalProperties": false
},
"strict": true
}
],
"tool_choice": {
"type": "auto"
},
"messages": [
{
"role": "user",
"content": [
{
"type": "text",
"text": "Where is order O-104?"
}
]
},
{
"role": "assistant",
"content": [
{
"type": "tool_use",
"id": "toolu_demo_1",
"name": "get_order",
"input": {
"order_id": "O-104"
}
}
]
},
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_demo_1",
"content": "{\"order_id\": \"O-104\", \"status\": \"shipped\"}",
"is_error": false
}
]
}
],
"stream": false
}Not supplied in this example — defaults and disabled features
| Setting not supplied or not visible | Meaning for this example |
|---|---|
| context_management — not supplied here | No server compaction strategy is enabled by this body. Host/manual compaction is separate. |
| output_config — not supplied here | No output_config schema or effort override is supplied. A prompt asking for JSON does not provide schema enforcement. |
| stop_sequences — not supplied here | No custom stop strings are configured. Generation can still stop for end_turn, tool_use, max_tokens, or another documented reason. |
| thinking — not supplied here | No explicit thinking override is shown. Behavior depends on the selected model; omission does not universally mean thinking is off. |
| cache_control — not supplied here | No top-level automatic cache marker is supplied. Check nested system/tool/content blocks for separate cache_control markers. |
| metadata — not supplied here | No application user reference is supplied through metadata. Authentication still comes from the request credentials. |
Full request catalog and omission rules. JSON has no comments; these notes are outside the payload.
| Exact JSON path | Meaning and use | Set or change | Learn more |
|---|---|---|---|
model |
Model ID selected by your application; use one supporting the enabled features. | Usually fixed; changes for deliberate routing | Glossary · Domain 5 |
max_tokens |
Maximum generated output tokens for this call, not input size or money. | Tune per task/turn | Glossary · Domain 5 |
system |
Standing instructions supplied by the application. String or text-block list. | Usually fixed and re-sent | Glossary · Domain 3 |
tools |
List of available tool definitions. This JSON does not contain Python function code. | Usually fixed; narrow to needed tools | Glossary · Domain 4 |
tools[] |
List of available tool definitions. This JSON does not contain Python function code. | Usually fixed; narrow to needed tools | Glossary · Domain 4 |
tools[].name |
Tool identifier used to dispatch the returned request to your function. | Per request or application configuration | Glossary · Domain 4 |
tools[].description |
Explains when the model should select the tool. | Per request or application configuration | Glossary · Domain 4 |
tools[].input_schema |
Schema for tool arguments, not the final answer. | Per request or application configuration | Glossary · Domain 4 |
tools[].input_schema.type |
object means the model supplies a JSON object. | Per request or application configuration | Glossary · Domain 3 |
tools[].input_schema.properties |
Named application fields and their definitions. These names are chosen by us. | Per request or application configuration | Glossary · Domain 3 |
tools[].input_schema.properties.order_id |
Schema for our order_id application field. It is not an Anthropic API parameter. | Per request or application configuration | Glossary · Domain 3 |
tools[].input_schema.properties.order_id.type |
string means text; integer means a whole number. Here the type applies to order_id. | Per request or application configuration | Glossary · Domain 3 |
tools[].input_schema.properties.order_id.description |
Human explanation of this application field for the model. | Per request or application configuration | Glossary · Domain 3 |
tools[].input_schema.required |
Lists fields that must be present; being required does not make a value factually correct. | Per request or application configuration | Glossary · Domain 3 |
tools[].input_schema.required[] |
Lists fields that must be present; being required does not make a value factually correct. | Per request or application configuration | Glossary · Domain 3 |
tools[].input_schema.additionalProperties |
false disallows extra keys not defined in properties. | Per request or application configuration | Glossary · Domain 3 |
tools[].strict |
API generation must follow this tool input schema where supported; still check authorization. | Per request or application configuration | Glossary · Domain 4 |
tool_choice |
auto allows the model to choose a tool or answer without one. It does not run the function. | Per request or application configuration | Glossary · Domain 4 |
tool_choice.type |
auto allows the model to choose a tool or answer without one. It does not run the function. | Per request or application configuration | Glossary · Domain 4 |
messages |
Ordered conversation being sent now. Store it in your application. | Changes as turns and results are appended | Glossary · Domain 1 |
messages[] |
Ordered conversation being sent now. Store it in your application. | Changes as turns and results are appended | Glossary · Domain 1 |
messages[].role |
user supplies task/tool results; assistant carries previous model content. | Set for each appended turn | Glossary · Domain 1 |
messages[].content |
Text or typed blocks belonging to this conversation turn. | Changes each turn | Glossary · Domain 1 |
messages[].content[] |
Text or typed blocks belonging to this conversation turn. | Changes each turn | Glossary · Domain 1 |
messages[].content[].type |
Discriminator: tells the API how to read this block, such as text, tool_result, or document. | Per request or application configuration | Glossary · Domain 4 |
messages[].content[].text |
Actual instruction or task text; surrounding JSON keys describe its location. | Per request or application configuration | Glossary · Domain 3 |
messages[].content[].id |
Copy the tool call ID from the assistant response; do not invent it. | Copied from response | Glossary · Domain 4 |
messages[].content[].name |
The tool the assistant requested; preserve its returned name. | Copied from response | Glossary · Domain 4 |
messages[].content[].input |
Arguments from the previous model tool request; order_id is a field we defined. | Copied from response | Glossary · Domain 4 |
messages[].content[].input.order_id |
Arguments from the previous model tool request; order_id is a field we defined. | Copied from response | Glossary · Domain 4 |
messages[].content[].tool_use_id |
Matches the particular assistant tool_use.id that this result answers. | Copy exactly from that tool call | Glossary · Domain 4 |
messages[].content[].content |
Tool outcome serialized as text here. The runner or harness supplies it, not Claude. | New tool result | Glossary · Domain 4 |
messages[].content[].is_error |
Whether your tool execution failed; this is not the model answer being incorrect. | Set from tool outcome | Glossary · Domain 4 |
stream Not on CCAR-F |
false returns a completed message JSON; true requests a sequence of server-sent events. | Usually fixed by UI needs | Glossary · Domain 1 |
Response 2 — the final answer
JSON
{
"id": "msg_demo_2",
"type": "message",
"role": "assistant",
"model": "claude-sonnet-4-6",
"content": [
{
"type": "text",
"text": "Order O-104 has shipped."
}
],
"stop_reason": "end_turn",
"stop_sequence": null,
"usage": {
"input_tokens": 180,
"output_tokens": 35,
"cache_creation_input_tokens": 0,
"cache_read_input_tokens": 0
}
}Explain every attribute in the final response
| Exact JSON path | Meaning and use | Set or change | Learn more |
|---|---|---|---|
id |
API-generated message identifier; not a customer/order ID. | Returned each response | Glossary · Domain 5 |
type |
message identifies the outer response envelope. | Returned by API | Glossary · Domain 1 |
role |
assistant identifies the model response. | Returned by API | Glossary · Domain 1 |
model |
Model ID selected by your application; use one supporting the enabled features. | Usually fixed; changes for deliberate routing | Glossary · Domain 5 |
content |
List of response blocks. Inspect block.type rather than assuming element zero is text. | Returned by API | Glossary · Domain 1 |
content[] |
List of response blocks. Inspect block.type rather than assuming element zero is text. | Returned by API | Glossary · Domain 1 |
content[].type |
text or tool_use in these examples; other feature-specific blocks are possible. | Returned by API | Glossary · Domain 1 |
content[].text |
Actual answer text. With structured outputs this string contains JSON that must be parsed. | Returned by API | Glossary · Domain 3 |
stop_reason |
Why this model turn ended. Branch on this before treating the content as complete. | Returned by API | Glossary · Domain 1 |
stop_sequence |
The matched custom string, or null when none matched. Request name is plural: stop_sequences. | Returned by API | Glossary · Domain 1 |
usage |
Measurements of this model call; use for accounting and context monitoring. Sample values are illustrative. | Per request or application configuration | Glossary · Domain 5 |
usage.input_tokens |
Input tokens outside separately reported cache categories. Do not mistake this for cumulative conversation cost. | Per request or application configuration | Glossary · Domain 5 |
usage.output_tokens |
Tokens generated for this response; often less than max_tokens. | Per request or application configuration | Glossary · Domain 5 |
usage.cache_creation_input_tokens |
Input tokens used to write a cache entry on this call. | Per request or application configuration | Glossary · Domain 5 |
usage.cache_read_input_tokens |
Input tokens served from cache on this call; cached input still occupies context. | Per request or application configuration | Glossary · Domain 5 |
Optional features — full requests, not detached fragments
These are separate configurations. Do not merge every example into one call. Use the model and SDK support appropriate to each feature. A feature's absence from the first request means it was not needed for that task.
Automatic compaction
Your triggering example goes here: top-level context_management beside messages, plus the beta header above. This short message enables compaction but is too small to trigger it. Preserve returned compaction blocks when continuing. Compaction explanation.
Full compaction request and all nested settings
JSON
{
"model": "claude-sonnet-4-6",
"max_tokens": 4096,
"messages": [
{
"role": "user",
"content": [
{
"type": "text",
"text": "Help me plan a long research task."
}
]
}
],
"context_management": {
"edits": [
{
"type": "compact_20260112",
"trigger": {
"type": "input_tokens",
"value": 100000
}
}
]
}
}Not supplied in this example — defaults and disabled features
| Setting not supplied or not visible | Meaning for this example |
|---|---|
| output_config — not supplied here | No output_config schema or effort override is supplied. A prompt asking for JSON does not provide schema enforcement. |
| tools — not supplied here | No tools are offered through this field. |
| tool_choice — not supplied here | With tools supplied, the default is auto: the model chooses whether to request a tool. Without tools, no supplied tool can be selected. |
| system — not supplied here | No application system instructions are supplied through this field. User messages still provide task text. |
| stop_sequences — not supplied here | No custom stop strings are configured. Generation can still stop for end_turn, tool_use, max_tokens, or another documented reason. |
| stream — not supplied here | For a direct non-streaming create/parse call, the result is one message rather than an event stream. A stream helper configures this separately. |
| thinking — not supplied here | No explicit thinking override is shown. Behavior depends on the selected model; omission does not universally mean thinking is off. |
| cache_control — not supplied here | No top-level automatic cache marker is supplied. Check nested system/tool/content blocks for separate cache_control markers. |
| metadata — not supplied here | No application user reference is supplied through metadata. Authentication still comes from the request credentials. |
Full request catalog and omission rules. JSON has no comments; these notes are outside the payload.
| Exact JSON path | Meaning and use | Set or change | Learn more |
|---|---|---|---|
model |
Model ID selected by your application; use one supporting the enabled features. | Usually fixed; changes for deliberate routing | Glossary · Domain 5 |
max_tokens |
Maximum generated output tokens for this call, not input size or money. | Tune per task/turn | Glossary · Domain 5 |
messages |
Ordered conversation being sent now. Store it in your application. | Changes as turns and results are appended | Glossary · Domain 1 |
messages[] |
Ordered conversation being sent now. Store it in your application. | Changes as turns and results are appended | Glossary · Domain 1 |
messages[].role |
user supplies task/tool results; assistant carries previous model content. | Set for each appended turn | Glossary · Domain 1 |
messages[].content |
Text or typed blocks belonging to this conversation turn. | Changes each turn | Glossary · Domain 1 |
messages[].content[] |
Text or typed blocks belonging to this conversation turn. | Changes each turn | Glossary · Domain 1 |
messages[].content[].type |
Discriminator: tells the API how to read this block, such as text, tool_result, or document. | Per request or application configuration | Glossary · Domain 4 |
messages[].content[].text |
Actual instruction or task text; surrounding JSON keys describe its location. | Per request or application configuration | Glossary · Domain 3 |
context_management |
Top-level request object enabling supported context editing. It is outside messages. | Per request or application configuration | Glossary · Domain 5 |
context_management.edits |
List of context operations to apply; this example enables summarization. | Per request or application configuration | Glossary · Domain 5 |
context_management.edits[] |
List of context operations to apply; this example enables summarization. | Per request or application configuration | Glossary · Domain 5 |
context_management.edits[].type |
compact_20260112 selects the compaction strategy/version. | Per request or application configuration | Glossary · Domain 5 |
context_management.edits[].trigger |
Threshold rule that determines when compaction should start. | Per request or application configuration | Glossary · Domain 5 |
context_management.edits[].trigger.type |
input_tokens means compare the current request input size, not lifetime token spending. | Per request or application configuration | Glossary · Domain 5 |
context_management.edits[].trigger.value |
100000 is the trigger threshold, not max_tokens. The short sample will not trigger it. | Configure below model limits; not a per-turn counter | Glossary · Domain 5 |
Structured invoice output
The schema controls answer text. It does not change the outer API envelope. Structured-output lesson.
Full extraction request and schema fields
JSON
{
"model": "claude-sonnet-4-6",
"max_tokens": 512,
"messages": [
{
"role": "user",
"content": "Extract invoice INV-104, total USD 12.50. Return the amount in cents."
}
],
"output_config": {
"format": {
"type": "json_schema",
"schema": {
"type": "object",
"properties": {
"invoice_number": {
"type": "string"
},
"total_cents": {
"type": "integer"
}
},
"required": [
"invoice_number",
"total_cents"
],
"additionalProperties": false
}
}
}
}Not supplied in this example — defaults and disabled features
| Setting not supplied or not visible | Meaning for this example |
|---|---|
| context_management — not supplied here | No server compaction strategy is enabled by this body. Host/manual compaction is separate. |
| tools — not supplied here | No tools are offered through this field. |
| tool_choice — not supplied here | With tools supplied, the default is auto: the model chooses whether to request a tool. Without tools, no supplied tool can be selected. |
| system — not supplied here | No application system instructions are supplied through this field. User messages still provide task text. |
| stop_sequences — not supplied here | No custom stop strings are configured. Generation can still stop for end_turn, tool_use, max_tokens, or another documented reason. |
| stream — not supplied here | For a direct non-streaming create/parse call, the result is one message rather than an event stream. A stream helper configures this separately. |
| thinking — not supplied here | No explicit thinking override is shown. Behavior depends on the selected model; omission does not universally mean thinking is off. |
| cache_control — not supplied here | No top-level automatic cache marker is supplied. Check nested system/tool/content blocks for separate cache_control markers. |
| metadata — not supplied here | No application user reference is supplied through metadata. Authentication still comes from the request credentials. |
Full request catalog and omission rules. JSON has no comments; these notes are outside the payload.
| Exact JSON path | Meaning and use | Set or change | Learn more |
|---|---|---|---|
model |
Model ID selected by your application; use one supporting the enabled features. | Usually fixed; changes for deliberate routing | Glossary · Domain 5 |
max_tokens |
Maximum generated output tokens for this call, not input size or money. | Tune per task/turn | Glossary · Domain 5 |
messages |
Ordered conversation being sent now. Store it in your application. | Changes as turns and results are appended | Glossary · Domain 1 |
messages[] |
Ordered conversation being sent now. Store it in your application. | Changes as turns and results are appended | Glossary · Domain 1 |
messages[].role |
user supplies task/tool results; assistant carries previous model content. | Set for each appended turn | Glossary · Domain 1 |
messages[].content |
Text or typed blocks belonging to this conversation turn. | Changes each turn | Glossary · Domain 1 |
output_config |
Output settings. This object can hold a response schema and supported effort settings. | Per request or application configuration | Glossary · Domain 3 |
output_config.format |
json_schema enables a structured final answer on a supported model. | Per request or application configuration | Glossary · Domain 3 |
output_config.format.type |
json_schema enables a structured final answer on a supported model. | Per request or application configuration | Glossary · Domain 3 |
output_config.format.schema |
Schema for the final answer text, independent of tools[].input_schema. | Per request or application configuration | [Glossary](term:structured outputs) · Domain 3 |
output_config.format.schema.type |
object means the model supplies a JSON object. | Per request or application configuration | Glossary · Domain 3 |
output_config.format.schema.properties |
Named application fields and their definitions. These names are chosen by us. | Per request or application configuration | Glossary · Domain 3 |
output_config.format.schema.properties.invoice_number |
Schema for our invoice_number application field. It is not an Anthropic API parameter. | Per request or application configuration | Glossary · Domain 3 |
output_config.format.schema.properties.invoice_number.type |
string means text; integer means a whole number. Here the type applies to invoice_number. | Per request or application configuration | Glossary · Domain 3 |
output_config.format.schema.properties.total_cents |
Schema for our total_cents application field. It is not an Anthropic API parameter. | Per request or application configuration | Glossary · Domain 3 |
output_config.format.schema.properties.total_cents.type |
string means text; integer means a whole number. Here the type applies to total_cents. | Per request or application configuration | Glossary · Domain 3 |
output_config.format.schema.required |
Lists fields that must be present; being required does not make a value factually correct. | Per request or application configuration | Glossary · Domain 3 |
output_config.format.schema.required[] |
Lists fields that must be present; being required does not make a value factually correct. | Per request or application configuration | Glossary · Domain 3 |
output_config.format.schema.additionalProperties |
false disallows extra keys not defined in properties. | Per request or application configuration | Glossary · Domain 3 |
Full extraction response — JSON inside text
JSON
{
"id": "msg_demo_3",
"type": "message",
"role": "assistant",
"model": "claude-sonnet-4-6",
"content": [
{
"type": "text",
"text": "{\"invoice_number\":\"INV-104\",\"total_cents\":1250}"
}
],
"stop_reason": "end_turn",
"stop_sequence": null,
"usage": {
"input_tokens": 180,
"output_tokens": 35,
"cache_creation_input_tokens": 0,
"cache_read_input_tokens": 0
}
}| Exact JSON path | Meaning and use | Set or change | Learn more |
|---|---|---|---|
id |
API-generated message identifier; not a customer/order ID. | Returned each response | Glossary · Domain 5 |
type |
message identifies the outer response envelope. | Returned by API | Glossary · Domain 1 |
role |
assistant identifies the model response. | Returned by API | Glossary · Domain 1 |
model |
Model ID selected by your application; use one supporting the enabled features. | Usually fixed; changes for deliberate routing | Glossary · Domain 5 |
content |
List of response blocks. Inspect block.type rather than assuming element zero is text. | Returned by API | Glossary · Domain 1 |
content[] |
List of response blocks. Inspect block.type rather than assuming element zero is text. | Returned by API | Glossary · Domain 1 |
content[].type |
text or tool_use in these examples; other feature-specific blocks are possible. | Returned by API | Glossary · Domain 1 |
content[].text |
Actual answer text. With structured outputs this string contains JSON that must be parsed. | Returned by API | Glossary · Domain 3 |
stop_reason |
Why this model turn ended. Branch on this before treating the content as complete. | Returned by API | Glossary · Domain 1 |
stop_sequence |
The matched custom string, or null when none matched. Request name is plural: stop_sequences. | Returned by API | Glossary · Domain 1 |
usage |
Measurements of this model call; use for accounting and context monitoring. Sample values are illustrative. | Per request or application configuration | Glossary · Domain 5 |
usage.input_tokens |
Input tokens outside separately reported cache categories. Do not mistake this for cumulative conversation cost. | Per request or application configuration | Glossary · Domain 5 |
usage.output_tokens |
Tokens generated for this response; often less than max_tokens. | Per request or application configuration | Glossary · Domain 5 |
usage.cache_creation_input_tokens |
Input tokens used to write a cache entry on this call. | Per request or application configuration | Glossary · Domain 5 |
usage.cache_read_input_tokens |
Input tokens served from cache on this call; cached input still occupies context. | Per request or application configuration | Glossary · Domain 5 |
Document input and caching
For an actual PDF, no custom PDF parser is required. Your code can read and encode its bytes, then send them in messages[].content[].source inside a document block. The SDK sends the request; the API processes the PDF. Follow the complete local PDF input → API response example.
This text document avoids an unreadable base64 dump. For PDFs, use a supported document source; the placement remains in the message content list. Cache minimum size still applies. Document block · Caching.
Full document request, cache settings, and metadata
JSON
{
"model": "claude-sonnet-4-6",
"max_tokens": 1024,
"system": [
{
"type": "text",
"text": "Summarize documents using only supplied facts.",
"cache_control": {
"type": "ephemeral",
"ttl": "5m"
}
}
],
"metadata": {
"user_id": "user_demo_opaque_104"
},
"messages": [
{
"role": "user",
"content": [
{
"type": "document",
"source": {
"type": "text",
"media_type": "text/plain",
"data": "Order O-104 shipped on Monday."
},
"title": "Order record",
"citations": {
"enabled": true
}
},
{
"type": "text",
"text": "When did this order ship? Cite the record."
}
]
}
]
}Not supplied in this example — defaults and disabled features
| Setting not supplied or not visible | Meaning for this example |
|---|---|
| context_management — not supplied here | No server compaction strategy is enabled by this body. Host/manual compaction is separate. |
| output_config — not supplied here | No output_config schema or effort override is supplied. A prompt asking for JSON does not provide schema enforcement. |
| tools — not supplied here | No tools are offered through this field. |
| tool_choice — not supplied here | With tools supplied, the default is auto: the model chooses whether to request a tool. Without tools, no supplied tool can be selected. |
| stop_sequences — not supplied here | No custom stop strings are configured. Generation can still stop for end_turn, tool_use, max_tokens, or another documented reason. |
| stream — not supplied here | For a direct non-streaming create/parse call, the result is one message rather than an event stream. A stream helper configures this separately. |
| thinking — not supplied here | No explicit thinking override is shown. Behavior depends on the selected model; omission does not universally mean thinking is off. |
| cache_control — not supplied here | No top-level automatic cache marker is supplied. Check nested system/tool/content blocks for separate cache_control markers. |
Full request catalog and omission rules. JSON has no comments; these notes are outside the payload.
| Exact JSON path | Meaning and use | Set or change | Learn more |
|---|---|---|---|
model |
Model ID selected by your application; use one supporting the enabled features. | Usually fixed; changes for deliberate routing | Glossary · Domain 5 |
max_tokens |
Maximum generated output tokens for this call, not input size or money. | Tune per task/turn | Glossary · Domain 5 |
system |
Standing instructions supplied by the application. String or text-block list. | Usually fixed and re-sent | Glossary · Domain 3 |
system[] |
Standing instructions supplied by the application. String or text-block list. | Usually fixed and re-sent | Glossary · Domain 3 |
system[].type |
Discriminator: tells the API how to read this block, such as text, tool_result, or document. | Per request or application configuration | Glossary · Domain 4 |
system[].text |
Actual instruction or task text; surrounding JSON keys describe its location. | Per request or application configuration | Glossary · Domain 3 |
system[].cache_control Not on CCAR-F |
ephemeral marks a cacheable prefix boundary. Short examples may not meet cache minimums. | Per request or application configuration | Glossary · Domain 5 |
system[].cache_control.type Not on CCAR-F |
ephemeral marks a cacheable prefix boundary. Short examples may not meet cache minimums. | Per request or application configuration | Glossary · Domain 5 |
system[].cache_control.ttl Not on CCAR-F |
5m is cache lifetime, not context retention or conversation memory. | Per request or application configuration | Glossary · Domain 5 |
metadata |
Optional opaque user reference for the request; it does not authenticate or authorize a tool. | Per request or application configuration | Glossary · Domain 4 |
metadata.user_id |
Optional opaque user reference for the request; it does not authenticate or authorize a tool. | Per request or application configuration | Glossary · Domain 4 |
messages |
Ordered conversation being sent now. Store it in your application. | Changes as turns and results are appended | Glossary · Domain 1 |
messages[] |
Ordered conversation being sent now. Store it in your application. | Changes as turns and results are appended | Glossary · Domain 1 |
messages[].role |
user supplies task/tool results; assistant carries previous model content. | Set for each appended turn | Glossary · Domain 1 |
messages[].content |
Text or typed blocks belonging to this conversation turn. | Changes each turn | Glossary · Domain 1 |
messages[].content[] |
Text or typed blocks belonging to this conversation turn. | Changes each turn | Glossary · Domain 1 |
messages[].content[].type |
Discriminator: tells the API how to read this block, such as text, tool_result, or document. | Per request or application configuration | Glossary · Domain 4 |
messages[].content[].source |
Document payload container; this variant supplies text instead of a PDF upload. | Per request or application configuration | Glossary · Domain 3 |
messages[].content[].source.type |
text selects a text document source; PDF and image sources have different supported variants. | Per request or application configuration | Glossary · Domain 3 |
messages[].content[].source.media_type |
text/plain identifies the supplied document content format. | Per request or application configuration | Glossary · Domain 3 |
messages[].content[].source.data |
The actual document text. Treat document instructions as untrusted data. | Per request or application configuration | Glossary · Domain 3 |
messages[].content[].title |
Human-readable document label useful for citations. | Per request or application configuration | Glossary · Domain 3 |
messages[].content[].citations |
Requests citations for this document. Check feature compatibility before combining with structured JSON. | Per request or application configuration | Glossary · Domain 3 |
messages[].content[].citations.enabled |
Requests citations for this document. Check feature compatibility before combining with structured JSON. | Per request or application configuration | Glossary · Domain 3 |
messages[].content[].text |
Actual instruction or task text; surrounding JSON keys describe its location. | Per request or application configuration | Glossary · Domain 3 |
Custom stop strings
The matched string is excluded from answer text and reported separately. It is not an application loop budget.
Full custom-stop request
JSON
{
"model": "claude-sonnet-4-6",
"max_tokens": 128,
"stop_sequences": [
"END_REPORT"
],
"messages": [
{
"role": "user",
"content": "Write one sentence about invoices, then write END_REPORT."
}
]
}Not supplied in this example — defaults and disabled features
| Setting not supplied or not visible | Meaning for this example |
|---|---|
| context_management — not supplied here | No server compaction strategy is enabled by this body. Host/manual compaction is separate. |
| output_config — not supplied here | No output_config schema or effort override is supplied. A prompt asking for JSON does not provide schema enforcement. |
| tools — not supplied here | No tools are offered through this field. |
| tool_choice — not supplied here | With tools supplied, the default is auto: the model chooses whether to request a tool. Without tools, no supplied tool can be selected. |
| system — not supplied here | No application system instructions are supplied through this field. User messages still provide task text. |
| stream — not supplied here | For a direct non-streaming create/parse call, the result is one message rather than an event stream. A stream helper configures this separately. |
| thinking — not supplied here | No explicit thinking override is shown. Behavior depends on the selected model; omission does not universally mean thinking is off. |
| cache_control — not supplied here | No top-level automatic cache marker is supplied. Check nested system/tool/content blocks for separate cache_control markers. |
| metadata — not supplied here | No application user reference is supplied through metadata. Authentication still comes from the request credentials. |
Full request catalog and omission rules. JSON has no comments; these notes are outside the payload.
| Exact JSON path | Meaning and use | Set or change | Learn more |
|---|---|---|---|
model |
Model ID selected by your application; use one supporting the enabled features. | Usually fixed; changes for deliberate routing | Glossary · Domain 5 |
max_tokens |
Maximum generated output tokens for this call, not input size or money. | Tune per task/turn | Glossary · Domain 5 |
stop_sequences |
Custom output strings that stop generation when produced. They are not tool results or loop counters. | Per request or application configuration | Glossary · Domain 1 |
stop_sequences[] |
Custom output strings that stop generation when produced. They are not tool results or loop counters. | Per request or application configuration | Glossary · Domain 1 |
messages |
Ordered conversation being sent now. Store it in your application. | Changes as turns and results are appended | Glossary · Domain 1 |
messages[] |
Ordered conversation being sent now. Store it in your application. | Changes as turns and results are appended | Glossary · Domain 1 |
messages[].role |
user supplies task/tool results; assistant carries previous model content. | Set for each appended turn | Glossary · Domain 1 |
messages[].content |
Text or typed blocks belonging to this conversation turn. | Changes each turn | Glossary · Domain 1 |
Full matched-stop response
JSON
{
"id": "msg_demo_1",
"type": "message",
"role": "assistant",
"model": "claude-sonnet-4-6",
"content": [
{
"type": "text",
"text": "An invoice records an amount due.\n"
}
],
"stop_reason": "stop_sequence",
"stop_sequence": "END_REPORT",
"usage": {
"input_tokens": 180,
"output_tokens": 35,
"cache_creation_input_tokens": 0,
"cache_read_input_tokens": 0
}
}| Exact JSON path | Meaning and use | Set or change | Learn more |
|---|---|---|---|
id |
API-generated message identifier; not a customer/order ID. | Returned each response | Glossary · Domain 5 |
type |
message identifies the outer response envelope. | Returned by API | Glossary · Domain 1 |
role |
assistant identifies the model response. | Returned by API | Glossary · Domain 1 |
model |
Model ID selected by your application; use one supporting the enabled features. | Usually fixed; changes for deliberate routing | Glossary · Domain 5 |
content |
List of response blocks. Inspect block.type rather than assuming element zero is text. | Returned by API | Glossary · Domain 1 |
content[] |
List of response blocks. Inspect block.type rather than assuming element zero is text. | Returned by API | Glossary · Domain 1 |
content[].type |
text or tool_use in these examples; other feature-specific blocks are possible. | Returned by API | Glossary · Domain 1 |
content[].text |
Actual answer text. With structured outputs this string contains JSON that must be parsed. | Returned by API | Glossary · Domain 3 |
stop_reason |
Why this model turn ended. Branch on this before treating the content as complete. | Returned by API | Glossary · Domain 1 |
stop_sequence |
The matched custom string, or null when none matched. Request name is plural: stop_sequences. | Returned by API | Glossary · Domain 1 |
usage |
Measurements of this model call; use for accounting and context monitoring. Sample values are illustrative. | Per request or application configuration | Glossary · Domain 5 |
usage.input_tokens |
Input tokens outside separately reported cache categories. Do not mistake this for cumulative conversation cost. | Per request or application configuration | Glossary · Domain 5 |
usage.output_tokens |
Tokens generated for this response; often less than max_tokens. | Per request or application configuration | Glossary · Domain 5 |
usage.cache_creation_input_tokens |
Input tokens used to write a cache entry on this call. | Per request or application configuration | Glossary · Domain 5 |
usage.cache_read_input_tokens |
Input tokens served from cache on this call; cached input still occupies context. | Per request or application configuration | Glossary · Domain 5 |
Thinking and effort
This example uses adaptive thinking on a supporting model. Other models and historical SDKs may require different options. Thinking glossary.
Full adaptive-thinking request
JSON
{
"model": "claude-sonnet-4-6",
"max_tokens": 4096,
"thinking": {
"type": "adaptive"
},
"output_config": {
"effort": "medium"
},
"messages": [
{
"role": "user",
"content": "Compare two approaches for safely retrying an order lookup."
}
]
}Not supplied in this example — defaults and disabled features
| Setting not supplied or not visible | Meaning for this example |
|---|---|
| context_management — not supplied here | No server compaction strategy is enabled by this body. Host/manual compaction is separate. |
| tools — not supplied here | No tools are offered through this field. |
| tool_choice — not supplied here | With tools supplied, the default is auto: the model chooses whether to request a tool. Without tools, no supplied tool can be selected. |
| system — not supplied here | No application system instructions are supplied through this field. User messages still provide task text. |
| stop_sequences — not supplied here | No custom stop strings are configured. Generation can still stop for end_turn, tool_use, max_tokens, or another documented reason. |
| stream — not supplied here | For a direct non-streaming create/parse call, the result is one message rather than an event stream. A stream helper configures this separately. |
| cache_control — not supplied here | No top-level automatic cache marker is supplied. Check nested system/tool/content blocks for separate cache_control markers. |
| metadata — not supplied here | No application user reference is supplied through metadata. Authentication still comes from the request credentials. |
Full request catalog and omission rules. JSON has no comments; these notes are outside the payload.
| Exact JSON path | Meaning and use | Set or change | Learn more |
|---|---|---|---|
model |
Model ID selected by your application; use one supporting the enabled features. | Usually fixed; changes for deliberate routing | Glossary · Domain 5 |
max_tokens |
Maximum generated output tokens for this call, not input size or money. | Tune per task/turn | Glossary · Domain 5 |
thinking |
adaptive asks a supported model to decide how much internal reasoning to use. | Per request or application configuration | Glossary · Domain 3 |
thinking.type |
adaptive asks a supported model to decide how much internal reasoning to use. | Per request or application configuration | Glossary · Domain 3 |
output_config |
Output settings. This object can hold a response schema and supported effort settings. | Per request or application configuration | Glossary · Domain 3 |
output_config.effort |
Requested reasoning effort level; not an exact token count or guaranteed quality score. | Per request or application configuration | Glossary · Domain 3 |
messages |
Ordered conversation being sent now. Store it in your application. | Changes as turns and results are appended | Glossary · Domain 1 |
messages[] |
Ordered conversation being sent now. Store it in your application. | Changes as turns and results are appended | Glossary · Domain 1 |
messages[].role |
user supplies task/tool results; assistant carries previous model content. | Set for each appended turn | Glossary · Domain 1 |
messages[].content |
Text or typed blocks belonging to this conversation turn. | Changes each turn | Glossary · Domain 1 |
Response handling — decide before acting
| Signal | Application behavior | Deep explanation |
|---|---|---|
end_turn |
Read the completed answer; validate data before accepting it. | Stop reasons |
tool_use |
Validate and execute allowed tools, then return linked results. | Domain 4 loop |
max_tokens |
Output reached its cap. Do not treat incomplete JSON as a valid answer. | Output budget |
stop_sequence |
Inspect the singular response field to see which custom marker matched. | Stop strings |
pause_turn |
Follow the supported continuation procedure; it is not a completed answer. | Stop reasons |
| Refusal or other stop signal | Handle the documented reason explicitly. Never assume every non-tool response succeeded. | Stop details |
| HTTP error | Handle an error envelope, not a normal message. Retry only appropriate failures with limits. | Reliability |
Error response example — a different outer shape
JSON
{"type":"error","error":{"type":"rate_limit_error","message":"Rate limit exceeded"},"request_id":"req_demo"}type identifies the error envelope; error.type identifies the category; error.message describes it; request_id supports troubleshooting. The HTTP status and response headers also matter. For a rate limit, honor applicable retry guidance. Do not access content as if this were a successful message. Official errors↗.
Other fields and block families
The atlas shows complete examples, not every possible union variant in Anthropic's evolving specification. Use these entry points when a specialized feature appears. Do not add fields simply because they exist.
| Family | What it introduces | Explanation |
|---|---|---|
| Streaming Not on CCAR-F | Event type, content-block index, deltas, and terminal message state instead of one immediate response object. |
Streaming |
| Images and PDFs | source selects URL/base64/file representations; source fields depend on the selected variant. |
Images · Documents |
| Thinking response | thinking, signature, or opaque redacted data; preserve required blocks unchanged. |
Thinking blocks · Redacted blocks |
| Server tools | Server-tool-use and corresponding result blocks; execution happens on the service. | Server tools |
| Compaction response | A compaction block in content; retain it in subsequent history. |
Compaction blocks |
| Usage extensions | Cache TTL breakdown, server-tool counts, tier, or other feature-specific metrics. | Usage |
| Container and skills | Execution container identity and selected skills; not a replacement for your whole conversation history. | Current API reference↗ |
| Service tier and inference geography | Service/processing controls, separate from task instructions and tool permissions. | Current API reference↗ |
| Historical sampling controls | temperature, top_p, and top_k depend on model and SDK version; do not blindly copy old examples. |
Migration explanation |
Recall without memorizing JSON
Explain the whole exchange in your own words
“I configure the model and limits, send instructions and the current conversation, then inspect the response. A tool request is a proposal. My application checks and executes it, appends the result, and asks again. Optional features such as compaction live in named request fields; helper options and headers have separate locations.”
Locate context_management.edits[0].trigger.value, tools[0].strict, and content[0].input.order_id. For each, say request or response, who supplies it, and what the application does with it.
Continue to the complete SDK walkthrough.
PDF reading and processing checkpoints
Read the complete PDF ingestion walkthrough: local file bytes versus extracted text, URL fetching, exact request fields, duplicate checks, and per-document resume records. Reading bytes is not PDF parsing; prompt caching is not a completed-files ledger.
Where does
cache_controlgo?system[0].cache_controlrequiressystemto be a list of content blocks. With a plain system string, use a top-level automatic marker or change to blocks for explicit placement. See complete examples inside the glossary and the request-by-request walkthrough. Caching can start on the first eligible request; there is no wait-for-several-turns rule.