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.
share
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_useorthinking. Requests and responses are lists of blocks. - stop_reason
- The response field that says why Claude stopped:
end_turnmeans it finished,max_tokensmeans it hit your output ceiling, andtool_usemeans 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
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.
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.
Real-time Messages API
Staff asking Shelfwise about stock, watching the reply stream in.
Result: full price, an answer in seconds.
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.
- 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.