CertSafari
    Anthropic Claude Certified Developer – Foundations (CCDV-F) - December 7 onwards· Lessons

    Domain 2 · Lesson 4/24

    Messages API mechanics: requests, stop reasons, tools, streaming and batch

    Messages API Mechanics

    23 min read
    5% of exam
    9 sources
    Published 18 Nov 2026
    Docs as of 18 Nov 2026

    What you will be able to do

    • Build a multi-turn Messages API request in which the client resends the full history, with system, max_tokens and typed content blocks
    • Choose request settings deliberately so that Claude produces the intended behavior, and verify the result through stop_reason
    • Decide what the application does next for each stop_reason value
    • Run a client tool loop and pick a tool_choice setting that gives the required guarantee, including when thinking is on
    • Read a streamed response event by event, including partial JSON for tool input and thinking deltas
    • Send images, enable prompt caching and request schema-constrained output in place of prefill
    • Choose between real-time Messages calls and the Batches API, and match batch results to requests

    Key concept

    Stateless request, block-structured response — Each Messages API call carries everything Claude will see: system prompt, the full conversation history, tools and settings. Each response comes back as an array of typed content blocks plus a stop_reason, and your code has to act on that stop_reason before it decides what to send next.

    1.Request shape and the stateless conversation

    A Messages API request names a model, sets max_tokens as a hard ceiling on the output, can carry a top-level system prompt, and holds a messages array of turns with the role user or assistant. The API stores nothing between calls, so Claude sees only what the current request contains. A request does not continue a session. A response id and an HTTP connection that stays open do not carry memory either.

    Multi-turn chat is therefore bookkeeping that your application does. After each reply, append Claude's assistant turn to your stored history, add the new user message as the last entry, and send the whole array again. A support bot that sends only the newest user message will look forgetful within a single exchange. Putting earlier turns into system on the first call and then leaving them out does not help either, because the next request no longer contains them. The history belongs to you, so you can also edit it. Assistant turns in it can be synthetic and do not have to be text Claude actually produced.

    A second-turn request resends the first exchange and puts the new user message lastpython
    message = anthropic.Anthropic().messages.create(
        model="claude-opus-5-5",
        max_tokens=1024,
        messages=[
            {"role": "user", "content": "Hello, Claude"},
            {"role": "assistant", "content": "Hello!"},
            {"role": "user", "content": "Can you describe LLMs to me?"},
        ],
    )

    The response is also a message. Its role is assistant, its content is an array of typed blocks, and it carries stop_reason, stop_sequence and usage token counts. A block can be text, tool_use or thinking. Branch on each block's type rather than assuming content[0] holds the answer: in a thinking response the text arrives at index 1, after the thinking block.

    The intended behavior has to be produced by the request, because the request is the only thing Claude sees. Standing rules such as tone or format belong in the top-level system field. A sized max_tokens keeps output from running past what the application can use, and stop_sequences end generation at a marker you choose; the response then reports stop_reason: "stop_sequence" and names the sequence that fired. Shaping the reply by prefilling a final assistant turn no longer works on current models and returns a 400, so format control moves to the system prompt or schema-constrained output. After each call, read stop_reason to confirm the response ended the way the request was designed to make it end.

    Checkpoint 1 of 12· Fill the gap

    This is the second request in a chat. The API keeps nothing between calls, so the request has to resend the first exchange before the new question. Which role belongs in the blank?

    message = anthropic.Anthropic().messages.create(
        model="claude-opus-5-5",
        max_tokens=1024,
        messages=[
            {"role": "user", "content": "Hello, Claude"},
            {"role": " ? ", "content": "Hello!"},
            {"role": "user", "content": "Can you describe LLMs to me?"},
        ],
    )

    Checkpoint 2 of 12· Exam question

    A support chatbot calls the Messages API once per user turn and sends only the newest user message each time. Customers complain that Claude forgets what was said a minute earlier. What is the correct fix?

    Sources12

    2.Acting on stop_reason

    Every successful response says why generation stopped, and your code has to branch on that value. A truncated answer still returns HTTP 200 and looks like any other response. A request sent with max_tokens: 1 returns a single token and stop_reason: "max_tokens". Code that ignores the field passes along a cut-off sentence as if it were complete. HTTP failures such as 429 or 529 are a separate channel, covered in error handling and retries.

    Each stop_reason and the application's next move
    stop_reasonWhen it occursWhat to do
    end_turnClaude completed its response naturallyUse the response
    max_tokensOutput reached your max_tokens limitRaise max_tokens or continue the response
    stop_sequenceClaude emitted one of your stop_sequencesRead stop_sequence to see which one fired
    tool_useClaude is calling a toolRun the tool and return the result
    pause_turnA server-tool loop reached its iteration limitSend the assistant content back to continue
    refusalClaude declined to respondRead stop_details and retry on a fallback model
    model_context_window_exceededThe response filled the model's context windowTreat the response as truncated

    Two values mean the work is unfinished rather than failed. pause_turn appears when Anthropic's server-side tool loop hits its iteration cap. Resend the conversation, including the paused assistant response, and Claude carries on from where it stopped. refusal responses include a stop_details object that names the policy category behind the refusal on every model. Log that category, and fall back or tell the user. Do not hand the reply to a parser.

    Checkpoint 3 of 12· Check yourself

    Your app enables the server-side web_search tool. A request returns HTTP 200 with stop_reason "pause_turn" and a partial answer. What should your code do next?

    Sources314

    3.The tool loop and tool_choice

    Tool use is a contract. You declare each tool's name, description and input_schema. Claude decides when to call one, and the model never executes anything itself. For a client tool, the response ends with stop_reason: "tool_use" and one or more tool_use blocks. Your code runs the operation and sends the output back in tool_result blocks inside the next user message. Server tools such as web_search and code_execution work differently: Anthropic runs them, and you never build their tool_result.

    The client loop is a while keyed on stop_reason. Each new request contains the original messages, Claude's assistant turn with its tool_use blocks, and a user message holding the results. The loop keeps going while the value is tool_use and exits on end_turn, max_tokens, stop_sequence or refusal. If you find yourself writing a regex to pull a decision out of Claude's prose, that decision should have been a tool call with a schema.

    tool_choice controls whether Claude must call a tool, and which one. The default, auto, leaves the choice to Claude, so an instruction in the system prompt only asks Claude to prefer a tool. It guarantees nothing. any forces a call to some tool but lets Claude pick which, which is not enough when three tools are defined and exactly one is acceptable. To guarantee one particular tool, name it: {"type": "tool", "name": "..."}. Several current models, including Claude Opus 5.5 and Claude Sonnet 5.5, reject both forced forms with a 400 error, so check support on the model you are pinned to.

    tool_choice values and the guarantee each gives
    tool_choiceEffectGuarantee
    auto (default)Claude decides whether to call a toolNone; prompt wording only nudges
    anyClaude must call a tool and chooses whichA tool call, but not a specific one
    tool with a nameClaude must call the named toolThat exact tool is called
    noneClaude does not call toolsNo tool call

    Checkpoint 4 of 12· Put it in order

    Put the steps of a client-tool loop in order, from the first request to Claude's final answer.

    1. 1.Claude responds with stop_reason "tool_use" and one or more tool_use blocks
    2. 2.Your code runs each requested tool and formats the outputs as tool_result blocks
    3. 3.Send a new request with the original messages, Claude's assistant turn, and a user message holding the tool_result blocks
    4. 4.Repeat while stop_reason is "tool_use", and exit on end_turn or another stop reason
    5. 5.Send a request that includes your tools array and the user message

    Checkpoint 5 of 12· Exam question

    An invoice pipeline defines three tools: extract_invoice, lookup_vendor and flag_fraud. For this endpoint, every request must end with Claude calling extract_invoice and nothing else. Which tool_choice setting guarantees that?

    Sources45

    4.Thinking blocks and their constraints

    You turn on thinking with the thinking parameter, for example {"type": "adaptive", "display": "summarized"}. The response then opens with a thinking content block before the text. Each thinking block carries a signature that verifies its integrity. That signature is why thinking blocks cannot be edited: in a tool loop, pass every thinking and redacted_thinking block back exactly as you received it, including blocks whose thinking field is empty. A filter that drops or rewrites them gets a 400 invalid_request_error. Choosing between thinking modes and budgets is covered in generation options.

    Thinking changes which tool_choice settings are legal. With manual extended thinking (thinking: {type: "enabled"}), both forcing modes, any and a named tool, cause an error, so switching from a named tool to any does not fix the 400. Raising max_tokens or moving the tool definition into the system prompt does not fix it either. The working options are auto with a prompt instruction to call the tool, or dropping thinking when a forced call is mandatory. Adaptive thinking does accept forced tool use on some models, but the forced call skips thinking and the response starts directly with the tool call.

    Checkpoint 6 of 12· Check yourself

    An agent uses adaptive thinking inside a client-tool loop. To save tokens, a filter edits Claude's assistant turn before it is sent back, and the next request fails with a 400 invalid_request_error. What should the filter do instead?

    Checkpoint 7 of 12· Exam question

    A team enables extended thinking on a classification endpoint and also sets tool_choice to force one specific tool so that output is always structured. Requests now fail with a 400 error. Which change resolves it while keeping thinking enabled?

    Sources526

    5.Streaming with server-sent events

    Setting "stream": true returns the response as server-sent events instead of a single JSON body. The order is fixed. First comes message_start, holding a Message with empty content. Each content block follows with a content_block_start, any number of content_block_delta events and a content_block_stop. Then come one or more message_delta events, which carry top-level changes such as stop_reason, and finally message_stop. ping events can appear anywhere. A block's index matches its position in the final content array.

    The end of a streamed tool call: a JSON fragment, the block stop, then stop_reason tool_use in message_deltatext
    event: content_block_delta
    data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":"o,"}}
    
    event: content_block_delta
    data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":" CA\"}"}}
    
    event: content_block_stop
    data: {"type":"content_block_stop","index":1}
    
    event: message_delta
    data: {"type":"message_delta","delta":{"stop_reason":"tool_use","stop_sequence":null},"usage":{"output_tokens":89}}

    Text arrives as text_delta and tool input as input_json_delta partial strings, while the final tool_use.input is always an object. Thinking arrives as thinking_delta, with a signature_delta just before the block stops. A stream can also deliver an error event mid-response, such as overloaded_error, which corresponds to HTTP 529 in a non-streaming call. New event types may be added, so ignore unknown ones instead of crashing. Streaming is also how large outputs avoid HTTP timeouts. With a big max_tokens, the SDK requires streaming, and stream.get_final_message() collects the events into the same Message that create() would return.

    To recover from an interrupted stream, keep what already arrived and ask for the rest. On Claude 4.6 and later, send a user message that contains the partial text and an instruction to continue. Placing the partial text in an assistant turn is the pre-4.6 method. Only text can be resumed this way, because tool use and thinking blocks cannot be partially recovered.

    Checkpoint 8 of 12· Fill the gap

    A streamed client-tool call ends with the events below. Which value in the message_delta tells your loop to run the tool and send back a tool_result?

    event: content_block_delta
    data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":"o,"}}
    
    event: content_block_delta
    data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":" CA\"}"}}
    
    event: content_block_stop
    data: {"type":"content_block_stop","index":1}
    
    event: message_delta
    data: {"type":"message_delta","delta":{"stop_reason":" ? ","stop_sequence":null},"usage":{"output_tokens":89}}

    Sources6

    6.Images as content blocks

    Vision input is not a separate endpoint. An image is one more block in a user message's content array, placed next to text blocks. The block's source takes one of three types: base64 with a media_type and the encoded data, url pointing to a hosted image, or file referencing an image uploaded through the Files API. The supported media types are image/jpeg, image/png, image/gif and image/webp. Images count as input tokens. The single-image example below reported 1,030 input tokens for a short question.

    A user turn whose content array holds an image block (url source) followed by a text blockpython
    message_from_url = anthropic.Anthropic().messages.create(
        model="claude-opus-5-5",
        max_tokens=1024,
        messages=[
            {
                "role": "user",
                "content": [
                    {
                        "type": "image",
                        "source": {
                            "type": "url",
                            "url": "https://platform.claude.com/docs/images/vision-example.jpg",
                        },
                    },
                    {"type": "text", "text": "What is in the above image?"},
                ],
            }
        ],
    )

    Checkpoint 9 of 12· Fill the gap

    You want Claude to describe a hosted photo. Vision does not have its own endpoint: the image goes into the user turn's content array as a typed block, before the text block. Which block type belongs in the blank?

    message_from_url = anthropic.Anthropic().messages.create(
        model="claude-opus-5-5",
        max_tokens=1024,
        messages=[
            {
                "role": "user",
                "content": [
                    {
                        "type": " ? ",
                        "source": {
                            "type": "url",
                            "url": "https://platform.claude.com/docs/images/vision-example.jpg",
                        },
                    },
                    {"type": "text", "text": "What is in the above image?"},
                ],
            }
        ],
    )

    Sources1

    7.Prompt caching in the request

    Prompt caching lets the API resume from a prompt prefix it has already processed, which cuts both latency and cost when requests repeat the same opening material. There are two ways to turn it on. Automatic caching uses one cache_control field at the top level of the request. The breakpoint then sits on the last cacheable block and moves forward as the conversation grows, which suits multi-turn chat. Explicit breakpoints put cache_control on individual content blocks, so you decide exactly where each cached prefix ends. Cache entries use a 5-minute or 1-hour TTL. Reading the cost effect in usage is covered in cost optimization.

    Automatic caching: a single top-level cache_control fieldpython
    response = client.messages.create(
        model="claude-opus-5-5",
        max_tokens=1024,
        cache_control={"type": "ephemeral"},
        system="You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.",
        messages=[
            {
                "role": "user",
                "content": "Analyze the major themes in 'Pride and Prejudice'.",
            }
        ],
    )

    Where you put new instructions decides whether the cache survives. Editing the top-level system field partway through a conversation changes the start of the prefix. A message with "role": "system" placed right after a user turn has the same authority but is appended to the end of the history, so it does not invalidate any cached prefix before it. It cannot be the first entry in messages. It works on current models, including Claude Opus 5.5, Claude Sonnet 5.5 and Claude Haiku 5.5. Use the top-level field for rules that apply from turn one and a mid-conversation system message for rules that only become relevant later.

    Checkpoint 10 of 12· Fill the gap

    A multi-turn literary-analysis chat should cache its growing prefix without you placing breakpoints by hand. The request below uses a single top-level field so the breakpoint moves forward as the conversation grows. Which field name belongs in the blank?

    response = client.messages.create(
        model="claude-opus-5-5",
        max_tokens=1024,
         ? ={"type": "ephemeral"},
        system="You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.",
        messages=[
            {
                "role": "user",
                "content": "Analyze the major themes in 'Pride and Prejudice'.",
            }
        ],
    )

    Sources71

    8.Structured output instead of prefill

    Asking for JSON in the prompt does not guarantee JSON. Claude can still return malformed syntax, leave out required fields or use the wrong types. Structured outputs enforce the schema through constrained decoding instead. There are two features. JSON outputs put a JSON Schema in output_config.format with type: "json_schema". Strict tool use (strict: true) validates tool names and inputs against their schemas. You can use them separately or in the same request. Parsing defensively beyond this is covered in defensive parsing.

    Prefill was the older way to shape output: you put the opening words of Claude's reply in a final assistant turn. On Claude 4.6 and later, that request fails with invalid_request_error, and the error message says the conversation must end with a user message. The replacements are structured outputs, output_config.format, or system prompt instructions. Even schema-constrained output can come back as a refusal. Check stop_reason before parsing, and when the value is refusal, read stop_details instead of feeding the apology into your model class.

    Checkpoint 11 of 12· Check yourself

    A ticket classifier on Claude Opus 5.5 sends a JSON Schema in output_config.format. One response comes back with stop_reason "refusal" and an apology. What should the code do before handing the content to its model class?

    Sources82

    9.Real-time calls or the Batches API

    The choice between real-time calls and the Batches API depends on whether anyone is waiting for the answer. A chat reply or an in-request classification needs the real-time Messages API. Nightly re-tagging of a document archive or a bulk evaluation run does not. The Batches API processes large volumes of requests asynchronously when you don't need real-time responses. A batch can take up to 24 hours, although many finish sooner.

    Real-time Messages calls compared with Message Batches
    ConcernReal-time Messages APIBatches API
    LatencyImmediate, streamableUp to 24 hours
    Matching output to inputOne response per callBy custom_id; result order is not guaranteed
    One request failsThat call errorsOther requests in the batch are unaffected
    Size limit symptomPer-request limitsOver 256 MB total returns 413 request_too_large
    Result lifetimeReturned in the responseDownloadable for 29 days after created_at

    Batch results do not come back in submission order. Give every request a unique, meaningful custom_id, such as the database key of the invoice it processes, and join results on that field rather than on line number. Each batch entry is an ordinary Messages request, so dry-run one request with the real-time API before submitting thousands, which catches validation errors early. Check results for failures and retry those individually. The 29-day download window starts at the batch's created_at, not at the time processing ended.

    Checkpoint 12 of 12· Check yourself

    Which of these workloads should go to the Batches API rather than real-time Messages calls?

    Sources69

    Sources

    (9)

    Every claim above is drawn from one of these pages, quoted as it was written on the date shown.

    1. 1.
      “The Messages API is stateless, which means that you always send the full conversational history to the API.”
      ↩︎ Request shape and the stateless conversation
      “Earlier conversational turns don’t necessarily need to actually originate from Claude.”
      ↩︎ Request shape and the stateless conversation
      “also include a stop_details object identifying the policy category that triggered the refusal, on every model.”
      ↩︎ Acting on stop_reason
      “You can supply images using the base64, url, or file source types.”
      ↩︎ Images as content blocks
      “Supported media types are image/jpeg, image/png, image/gif, and image/webp.”
      ↩︎ Images as content blocks
      “it does not invalidate any cached prefix that came before it.”
      ↩︎ Prompt caching in the request
      “The Messages API is stateless, which means that you always send the full conversational history to the API.”
      ↩︎ Key concept
      “The Messages API is stateless, which means that you always send the full conversational history to the API.”
      ↩︎ Exam trap 1
      “Refusal responses (stop_reason: "refusal") also include a stop_details object identifying the policy category that triggered the refusal, on every model.”
      ↩︎ Checkpoint
    2. 2.
      “Claude 4.6 and later models and Claude Mythos Preview do not support prefilling assistant messages.”
      ↩︎ Request shape and the stateless conversation
      “With tool use, pass back every thinking and redacted_thinking block from the assistant turn exactly as received, including blocks whose thinking field is empty.”
      ↩︎ Thinking blocks and their constraints
      “Claude 4.6 and later models and Claude Mythos Preview do not support prefilling assistant messages.”
      ↩︎ Structured output instead of prefill
      “Use structured outputs on models that support it, system prompt instructions, or output_config.format instead.”
      ↩︎ Exam trap 4
    3. 3.
      “Check this field to decide whether to use the response as-is, continue the conversation, retry, or fall back to another model.”
      ↩︎ Acting on stop_reason
      “Read stop_details and retry on a fallback model.”
      ↩︎ Acting on stop_reason
    4. 4.
      “A paused turn means the work isn’t complete; re-send the conversation (including the paused response) to let the model continue where it left off.”
      ↩︎ Acting on stop_reason
      “Send a new request containing the original messages, the assistant’s response, and a user message with the tool_result blocks.”
      ↩︎ The tool loop and tool_choice
      “if you’re writing a regex to extract a decision from model output, that decision should have been a tool call.”
      ↩︎ The tool loop and tool_choice
    5. 5.
      “You can do this by specifying the tool in the tool_choice field of the request.”
      ↩︎ The tool loop and tool_choice
      “any and tool return a 400 error.”
      ↩︎ The tool loop and tool_choice
      “any and tool are not supported and result in an error”
      ↩︎ Thinking blocks and their constraints
      “a forced call skips thinking: the response starts with the tool call and has no thinking block”
      ↩︎ Thinking blocks and their constraints
      “You can do this by specifying the tool in the tool_choice field of the request.”
      ↩︎ Exam trap 2
      “any and tool are not supported and result in an error”
      ↩︎ Exam trap 3
    6. 6.
      “This signature is used to verify the integrity of the thinking block.”
      ↩︎ Thinking blocks and their constraints
      “the deltas are partial JSON strings, whereas the final tool_use.input is always an object.”
      ↩︎ Streaming with server-sent events
      “This is especially useful for requests with large max_tokens values, where the SDK requires streaming to avoid HTTP timeouts.”
      ↩︎ Streaming with server-sent events
      “your code should handle unknown event types gracefully.”
      ↩︎ Streaming with server-sent events
      “Tool use and thinking blocks cannot be partially recovered.”
      ↩︎ Streaming with server-sent events
      “Process large volumes of requests asynchronously when you don’t need real-time responses.”
      ↩︎ Real-time calls or the Batches API
      “You can accumulate the string deltas and parse the JSON once you receive a content_block_stop event”
      ↩︎ Prediction
    7. 7.
      “Place cache_control directly on individual content blocks for fine-grained control over exactly what gets cached.”
      ↩︎ Prompt caching in the request
      “using automatic caching or explicit breakpoints with 5-minute or 1-hour TTLs.”
      ↩︎ Prompt caching in the request
    8. 8.
      “Structured outputs guarantee schema-compliant responses through constrained decoding:”
      ↩︎ Structured output instead of prefill
      “Without structured outputs, Claude can generate malformed JSON responses or invalid tool inputs that break your applications.”
      ↩︎ Structured output instead of prefill
    9. 9.
      “Use meaningful custom_id values to easily match results with requests, because order is not guaranteed.”
      ↩︎ Real-time calls or the Batches API
      “Batches might take up to 24 hours for processing, but many complete sooner.”
      ↩︎ Real-time calls or the Batches API
      “Dry run a single request shape with the Messages API to avoid validation errors.”
      ↩︎ Real-time calls or the Batches API
      “Use meaningful custom_id values to easily match results with requests, because order is not guaranteed.”
      ↩︎ Exam trap 5

    Ready to test yourself?

    Practise Anthropic Claude Certified Developer – Foundations (CCDV-F) - December 7 onwards in quiz mode.

    Spotted a mistake, or was something unclear? Tell us.