Task statement 2.3 · Applications and integration

2.3 · Claude API Mechanics

In Shelfwise, the course example, every turn of the stock agent is one Messages API request made by the Agent SDK, and every request costs against the $0.01 ceiling. The answers stay cheap and correct only when the team knows what each request carries, what comes back, and which work should not run in real time.

Why it's tested

Two habits from ordinary web APIs fail here. One assumes the server remembers the conversation, so the service sends only the newest question and Claude answers without the earlier turns. The other puts today's date at the top of a long system prompt, which changes the start of every request, so prompt caching never matches and every call costs full price. Both fail because Claude sees only what each request carries, in the order it carries it.

Start hereThree terms this section adds

content block
One typed piece of a message, such as text, image, tool_use or thinking. Requests and responses are lists of blocks.
stop_reason
The response field that says why Claude stopped: end_turn means it finished, max_tokens means it hit your output ceiling, and tool_use means it wants a tool run.
cache breakpoint
cache_control: the marker you set on a content block. The prompt from its start up to that block is what caching can reuse.

KnowledgeWhat a request carries and what comes back

The Messages API is stateless: it keeps nothing between requests, so every request carries the full conversation so far. A request names the model, sets max_tokens as the ceiling on output, and sends an optional system prompt plus a messages array of alternating user and assistant turns. For Shelfwise this means the service, not the API, holds each chat's history and appends Claude's reply and the next question before every call.

The Messages API data access patterns follow from that design. Content reaches Claude inline (text, or a base64-encoded image or PDF), by a URL to content hosted online, or by a file_id from the Files API, which uploads a file once for later requests to reference. Because each request resends the history, a base64 image from the first turn travels again on every later turn, growing payload and latency. A file_id keeps the request small, although the file's content is still priced as input tokens whenever a request uses it.

More precise than the guide. The docs have no section called "Messages API data access patterns" (as of 2026-10-03). They document a stateless request that resends the history, and three content sources: base64, URL and Files API file_id. Exam answer: your application stores the conversation and resends it on every call, with documents inline or by reference.

KnowledgeTools, streaming, vision and thinking

Tool use runs as a round trip. Your request lists tools, each with a name, a description and an input_schema, and when Claude calls one, the response ends with stop_reason: "tool_use" and a tool_use block holding the tool's input. Your code runs the tool and returns the output in the next request as a tool_result block carrying the call's tool_use_id. Server tools such as web search are the exception, because Anthropic runs them inside the same response. Shelfwise's stock lookup is a client tool, so each lookup takes at least two requests.

Streaming means receiving the response in pieces as Claude writes it, which changes when the answer arrives, not what it costs. With "stream": true the response comes back as server-sent events (SSE): message_start, then each content block as a start event, deltas and a stop event, then message_delta and message_stop. Shelfwise's widget shows each text_delta as it arrives, so staff watch the answer form. The SDKs also refuse a non-streaming request expected to run longer than about ten minutes, and an error can arrive as an event after HTTP 200, so the client must handle errors mid-stream.

Vision means images go into a user turn as image blocks, from the same three sources, placed before the question as the docs advise. An image over the model's resolution limit is scaled down before Claude sees it, so cropping first keeps small print readable, and downsampling further controls its token cost.

Thinking lets Claude reason before it answers, in thinking blocks ahead of the text. Those tokens are billed as output and count toward max_tokens, even when the thinking text is hidden or summarised. On the newest models thinking is adaptive: Claude decides whether and how much to think, steered by effort, a setting that trades thoroughness against tokens. The older fixed budget_tokens setting is rejected there. In a tool loop, thinking blocks must go back exactly as received, so code that keeps only the text and tool_use blocks breaks the next request.

KnowledgePrompt caching reuses a prefix

Prompt caching reuses the part of a prompt that repeats. The cache is keyed on a prefix built in a fixed order, tools, then system, then messages, up to a block marked with cache_control. A later request reads from the cache only if everything up to the breakpoint is identical, and a change at one level invalidates that level and every later one. An entry lives five minutes by default, refreshed on each use, with a one-hour option at a higher write price. Writes cost more than ordinary input and reads cost a small fraction of it, so put stable content first, the breakpoint after it, and anything that changes per request after the breakpoint.

Interactive · where the changing line sits decides what the cache can reuse

Two copies of the same Shelfwise request, read from top to bottom in prefix order. Left: the changing branch-and-date line sits second, so every block up to the breakpoint is written to the cache again. Right: the changing line sits after the breakpoint, so the tools and the stock rules are read from the cache and only the changing line and the question are ordinary input. Changing line at the top PREFIX ORDER tools: stock_lookup schema CACHE WRITE AGAIN system: "Branch: Leeds · 3 Oct" CHANGES EVERY REQUEST system: stock rules, 6,000 tokens CACHE WRITE AGAIN cache_control breakpoint user: "Any 4 mm drill bits?" ORDINARY INPUT second request: prefix differs at block 2 ≈6,000 TOKENS WRITTEN AT THE HIGHER WRITE PRICE Changing line after the breakpoint PREFIX ORDER tools: stock_lookup schema CACHE READ system: stock rules, 6,000 tokens CACHE READ cache_control breakpoint user: "Branch: Leeds · 3 Oct" CHANGES EVERY REQUEST user: "Any 4 mm drill bits?" ORDINARY INPUT second request: prefix identical to the breakpoint ≈6,000 TOKENS READ AT A SMALL FRACTION OF THE INPUT PRICE Both columns show the second request of a chat, within five minutes of the first.

Choose where the line that changes on every request sits.

At the top: the branch-and-date line is block 2, so the prefix differs from the last request before the breakpoint. All ≈6,000 tokens up to the breakpoint are written to the cache again, at the higher write price, on every request.

After the breakpoint: tools and stock rules are identical on every request, so the second request reads them from the cache. Only the changing line and the question are ordinary input.

Each column is one request, read downward in prefix order. Amber is written to the cache again, green is read from it, blue is ordinary input, and the thick outline marks the changing line.

More precise than the guide. The guide says "cache check-pointing", a phrase the prompt-caching docs do not use (as of 2026-10-03). The docs' term is a cache breakpoint: a cache_control marker on a content block, up to four per request, with the reusable prefix running from the start of the prompt to that block. Exam answer: cache check-pointing means placing cache breakpoints at the end of the content that repeats.

KnowledgeInvoking Claude through third-party vendors

Invoking Claude through a third-party vendor's Messages endpoint changes authentication, addressing and the feature list, not the shape of the request. Claude in Amazon Bedrock signs requests with AWS credentials and prefixes model IDs with anthropic.. Google Cloud takes the model in the endpoint URL and anthropic_version in the body, through SDK clients such as AnthropicVertex. The feature list is what catches teams out, because on both platforms the docs list the Message Batches endpoint, the Files API and URL sources as unsupported. Images therefore go in as base64. Each vendor also sets its own model retirement dates.

SkillChoosing between realtime and batch

The Message Batches API is an endpoint that takes many Messages requests in one call, each with your own custom_id and the usual params. Each request runs on its own, asynchronously, at half the standard price. Most batches finish within an hour, but results are promised only within 24 hours, after which unfinished requests expire, and they return in any order, so you match them by custom_id. A batch cannot stream, so stream: true inside one is a validation error. Prompt caching discounts stack with the batch discount, although cache hits inside a batch are best effort. The tradeoff between realtime and batch API selection therefore turns on who is waiting.

Someone is waiting

Real-time Messages API

Staff asking Shelfwise about stock, watching the reply stream in.

Result: full price, an answer in seconds.

Nobody is waiting

Message Batches API

Work whose result is read hours later, such as an overnight report.

Result: half price, results within 24 hours.

The guide's own example is a developer processing 10,000 documents overnight for a non-urgent analytics report, with cost first and nobody reading the results until morning:

# input: 10,000 documents at 18:00, report read at 09:00, cost first
batches.create(10,000 requests, custom_id "doc-00001" … "doc-10000")
# what happens: each request runs on its own, at half price
ended 18:52 → 9,994 succeeded, 6 errored → resubmit the 6 by custom_id
# outcome: report ready that evening at half the cost; the promise is
#   24 h, so a batch that used all of it would land after 09:00

The batch wins because nobody is waiting, although a hard deadline should be planned against the 24-hour promise, not the typical hour. Sending all 10,000 synchronously in parallel finishes sooner, but nobody needs that, and every request costs full price. Lowering max_tokens shortens each answer without changing the price per token, and it can cut the analysis off. The smallest model regardless of quality saves money by giving up the report's purpose.

Ask one question: is a person or a process waiting on this answer? Yes → the real-time Messages API, streamed when someone watches the text arrive. No → the Message Batches API at half price, provided the result can wait up to 24 hours and your platform offers the endpoint.
Takeaway
  • The Messages API keeps nothing between calls: your code stores the history and resends it, with documents inline, by URL or by file_id.
  • Put what repeats first and mark its end with cache_control; anything that changes per request goes after that breakpoint.
  • Streaming changes when the text arrives, not what it costs, and a batch cannot stream at all.

check yourself

0 / 4 answered

An insurer runs two Claude workloads. Claimants upload photos through a web form and wait on the page for a damage summary. Separately, 60,000 archived claims must be re-categorised for an audit due in two weeks. The finance lead wants the lowest total cost without making claimants wait any longer.Which design best meets both requirements?

Select one.

A report service calls the Python SDK's messages.create with max_tokens set to 100,000 so that long market reports are never cut off. Every call now raises a ValueError on the developer's laptop, and the Console's usage page shows no requests at all. With max_tokens at 4,000, the same call succeeds.What is the most likely root cause?

Select one.

A procurement agent runs its own tool loop on a model with thinking on. To save tokens, the loop rebuilds each assistant turn from only its text and tool_use blocks before appending the tool_result. The request after every tool call now fails with a 400 invalid_request_error that names a thinking block.Which change makes the follow-up requests valid while keeping thinking active throughout the loop?

Select one.

A nightly Message Batches job sends 8,000 requests that share 12,000 tokens of tools and system prompt, with cache_control after the system prompt, yet under 5% of requests read from the cache. A pool of worker processes builds the requests, each making the tool list from a Python set, and the batch takes about 40 minutes.Which TWO changes most raise the share of cache reads without giving up the batch discount?

Select two.

sources

  1. Claude Platform Docs, "Using the Messages API": the API is stateless and you send the full conversational history; synthetic assistant turns; image source types. Checked 2026-10-03.
  2. Claude Platform Docs, "Files API": upload once and reference by file_id; file content used in a request is priced as input tokens. Checked 2026-10-03.
  3. Claude Platform Docs, "Tool use with Claude": client tools return stop_reason: "tool_use" and your code sends a tool_result; server tools run on Anthropic's infrastructure. Checked 2026-10-03.
  4. Claude Platform Docs, "Streaming messages": "stream": true over server-sent events; the event flow; mid-stream error events. Checked 2026-10-03.
  5. Claude Platform Docs, "Claude API errors", Long requests: the SDKs refuse non-streaming requests expected to exceed 10 minutes; errors after a 200 response when streaming; thinking blocks must be passed back unchanged. Checked 2026-10-03.
  6. Claude Platform Docs, "Vision": three image source types; images before text; oversized images downscaled; base64 only on Amazon Bedrock and Google Cloud. Checked 2026-10-03.
  7. Claude Platform Docs, "Thinking" and "Extended thinking": thinking billed as output and counted toward max_tokens; adaptive thinking and effort; budget_tokens rejected on the newest models. And "Effort": trading response thoroughness against token efficiency. Checked 2026-10-03; "Effort" checked 2026-10-04.
  8. Claude Platform Docs, "Prompt caching": prefix order tools, system, messages; cache_control breakpoints, up to four; invalidation by level; five-minute lifetime refreshed on use and the one-hour option; write and read pricing. Checked 2026-10-03.
  9. Claude Platform Docs, "Claude in Amazon Bedrock" and "Claude on Google Cloud": credentials, model addressing, anthropic_version in the body, and the unsupported features list. Checked 2026-10-03.
  10. Claude Platform Docs, "Batch processing": 50% of standard prices; most batches within an hour; results at completion or 24 hours; expiry; results in any order matched by custom_id; stream: true not supported; caching discounts stack, hits best effort. Checked 2026-10-03.
  11. The 10,000-document overnight report and its four options: Claude Certified Developer – Foundations Exam Guide v1.0, §8 Sample 1. Shelfwise, its branch line, the 6,000-token rules and the batch timings are this course's example details.