D1 · Applications and Integration

This is by far the heaviest domain on the Developer exam – roughly 18 of 53 items. It tests whether you can integrate Claude correctly: knowing the exact shape of a Messages API request and response, handling every stop_reason, streaming with SSE, using vision/PDF/Files inputs, wiring prompt caching and batching for cost, dealing with errors and rate limits, and structuring an application so that instructions, configuration and secrets live in the right places. Most items are code-shaped scenarios where one option is subtly wrong about an API mechanic.

Learning objectives

By the end of this page you should be able to:

1. Describe the anatomy of a Messages API request and response, including roles, content blocks, system, max_tokens, temperature/top_p, stop_sequences and usage.
2. Handle every stop_reason value, including tool_use, pause_turn, refusal and max_tokens.
3. Maintain multi-turn history correctly and stream responses using the SSE event types in Python and TypeScript.
4. Send vision, PDF and Files API inputs, and enable extended / adaptive thinking.
5. Apply prompt caching with cache_control and compute the cost impact.
6. Use the Message Batches API lifecycle and its 50% discount.
7. Handle error codes, implement retry with backoff + jitter, use idempotency, and reason about rate limits (RPM/ITPM/OTPM) and timeouts.
8. Access Claude through Bedrock, Vertex AI and Foundry, and use the Python and TypeScript SDKs including async patterns.
9. Apply software-engineering foundations (REST, JSON, async, version control, refactoring) and sound application design and configuration management.

1.1 Requirements and the application lifecycle

Before any code, an integration has a lifecycle: define requirements → prototype → evaluate → harden → deploy → monitor → iterate. The exam expects you to know where Claude fits and what changes at each stage.

1.2 Anatomy of a Messages API request

A Messages request is a JSON body sent to POST /v1/messages. The core fields:

{
  "model": "claude-sonnet-5",
  "max_tokens": 1024,
  "system": "You are a precise assistant. Answer only from the provided context.",
  "messages": [
    { "role": "user", "content": "Summarise the attached report in 3 bullets." }
  ],
  "temperature": 0.2,
  "stop_sequences": ["\n\nHuman:"]
}

Key fields:

• model – a model ID; pin a snapshot in production (see 1.16).
• max_tokens – the maximum tokens Claude may generate (not the context window). Required. If output hits it, stop_reason is max_tokens.
• system – a top-level string (or array of blocks) for role/instructions. It is not a message with role: "system" in the messages array on current models (Sonnet 5 has no mid-conversation system messages).
• messages – an alternating list of user and assistant turns. Each has role and content.
• temperature (0–1) and top_p – sampling controls. Set one, not both. Lower temperature = more deterministic; temperature: 0 for maximum reproducibility.
• stop_sequences – strings that, if generated, halt output; stop_reason becomes stop_sequence.

Roles and content blocks

content is either a string (shorthand for a single text block) or an array of content blocks. Block types include text, image, document, tool_use, tool_result, and thinking.

{
  "role": "user",
  "content": [
    { "type": "text", "text": "What is in this image?" },
    { "type": "image", "source": { "type": "base64", "media_type": "image/png", "data": "iVBORw0KG..." } }
  ]
}

1.3 Anatomy of a Messages API response

{
  "id": "msg_01ABC...",
  "type": "message",
  "role": "assistant",
  "model": "claude-sonnet-5",
  "content": [
    { "type": "text", "text": "Here are three bullets: ..." }
  ],
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 2145,
    "output_tokens": 87,
    "cache_creation_input_tokens": 0,
    "cache_read_input_tokens": 0
  }
}

• id – log this (and the request-id response header) for support and debugging.
• content – array of output blocks; iterate rather than assuming a single text block (a response may contain thinking, text and tool_use blocks together).
• stop_reason – why generation stopped (see 1.4).
• usage – token accounting, including cache fields. Bill and budget from this.

1.4 stop_reason – the control signal

stop_reason is the single most important field for control flow. Never infer termination from the text.

resp = client.messages.create(model="claude-sonnet-5", max_tokens=1024, messages=msgs)

if resp.stop_reason == "tool_use":
    handle_tools(resp)          # execute, append tool_result, loop
elif resp.stop_reason == "pause_turn":
    msgs.append({"role": "assistant", "content": resp.content})
    resp = client.messages.create(model="claude-sonnet-5", max_tokens=1024, messages=msgs)
elif resp.stop_reason == "max_tokens":
    handle_truncation(resp)     # output is incomplete
elif resp.stop_reason == "refusal":
    handle_refusal(resp)        # policy path, not a retry loop

1.5 Multi-turn conversations

State is client-side: you resend the whole history each turn. Append the assistant’s response verbatim, then the next user turn.

messages = [{"role": "user", "content": "My name is Dana."}]
r1 = client.messages.create(model="claude-sonnet-5", max_tokens=256, messages=messages)
messages.append({"role": "assistant", "content": r1.content})   # append full blocks
messages.append({"role": "user", "content": "What is my name?"})
r2 = client.messages.create(model="claude-sonnet-5", max_tokens=256, messages=messages)

Because history grows every turn, so does input cost and latency. This is why prompt caching (1.9), context editing and compaction matter for long conversations.

1.6 Streaming with SSE

Streaming returns Server-Sent Events so you can render tokens as they arrive. The event sequence:

message_start
  content_block_start        (index 0)
  content_block_delta ...    (text_delta / input_json_delta / thinking_delta)
  content_block_stop
  [more content blocks ...]
message_delta                (carries stop_reason and final usage)
message_stop

from anthropic import Anthropic

client = Anthropic()

with client.messages.stream(
    model="claude-sonnet-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Write a haiku about tokens."}],
) as stream:
    for text in stream.text_stream:      # convenience: text deltas only
        print(text, end="", flush=True)
    final = stream.get_final_message()   # full Message with stop_reason + usage
print("\n", final.stop_reason, final.usage.output_tokens)

import Anthropic from '@anthropic-ai/sdk';

const client = new Anthropic();

const stream = client.messages.stream({
  model: 'claude-sonnet-5',
  max_tokens: 1024,
  messages: [{ role: 'user', content: 'Write a haiku about tokens.' }],
});

stream.on('text', (delta) => process.stdout.write(delta));
const final = await stream.finalMessage();
console.log('\n', final.stop_reason, final.usage.output_tokens);

with client.messages.stream(model="claude-sonnet-5", max_tokens=512,
                            messages=[{"role": "user", "content": "hi"}]) as stream:
    for event in stream:
        if event.type == "content_block_delta":
            if event.delta.type == "text_delta":
                print(event.delta.text, end="")
            elif event.delta.type == "input_json_delta":
                print(event.delta.partial_json, end="")  # tool args stream as JSON
        elif event.type == "message_delta":
            print("\nstop:", event.delta.stop_reason)

1.7 Vision, PDF and the Files API

Multimodal inputs are content blocks in a user message.

{
  "role": "user",
  "content": [
    { "type": "text", "text": "Extract the invoice total." },
    { "type": "image", "source": { "type": "url", "url": "https://example.com/invoice.png" } },
    { "type": "document", "source": { "type": "base64", "media_type": "application/pdf", "data": "JVBERi0..." } }
  ]
}

• Images: source.type may be base64 or url. Supported types include PNG, JPEG, GIF, WebP.
• PDFs: type: "document" with application/pdf; Claude reads text and page images.
• Files API: upload large or reused files once, then reference by file_id instead of re-sending bytes each turn – saves upload bandwidth and enables reuse.

uploaded = client.files.upload(file=("report.pdf", open("report.pdf", "rb"), "application/pdf"))
resp = client.messages.create(
    model="claude-sonnet-5", max_tokens=1024,
    messages=[{"role": "user", "content": [
        {"type": "text", "text": "Summarise."},
        {"type": "document", "source": {"type": "file", "file_id": uploaded.id}},
    ]}],
)

Citations can be enabled on documents so Claude returns grounded references to source spans.

1.8 Extended and adaptive thinking

Thinking lets Claude reason before answering; the reasoning appears as thinking content blocks.

{
  "model": "claude-opus-5",
  "max_tokens": 4096,
  "thinking": { "type": "adaptive" },
  "messages": [{ "role": "user", "content": "Prove sqrt(2) is irrational." }]
}

• All current models accept thinking: {"type": "adaptive"}.
• budget_tokens is only valid on Haiku 4.5; it returns 400 on Fable 5.x / Opus 5 / Sonnet 5.
• Effort levels low | medium | high (default) | xhigh tune reasoning depth (xhigh for the hardest coding/agentic work on Opus 5 / Fable 5.1). Haiku 4.5 has no effort parameter.
• Fable 5.1 always has thinking on; its thinking blocks are readable only by the producing model or newer (a silent fallback to an older model drops them).

# Haiku 4.5 – the only current model using budget_tokens
client.messages.create(
    model="claude-haiku-4-5", max_tokens=2048,
    thinking={"type": "enabled", "budget_tokens": 1024},
    messages=[{"role": "user", "content": "Plan the refactor."}],
)

1.9 Prompt caching mechanics and cost math

Prompt caching stores a prefix of the request so repeated calls skip re-processing it. Mark the end of the stable prefix with cache_control.

{
  "model": "claude-sonnet-5",
  "max_tokens": 512,
  "system": [
    { "type": "text", "text": "You are a support agent. Policies:\n<policies>...large...</policies>",
      "cache_control": { "type": "ephemeral" } }
  ],
  "messages": [{ "role": "user", "content": "How do I return an item?" }]
}

Rules:

• Put stable content first (system prompt, tool definitions, long documents), then variable content.
• Minimum cacheable prefix is ~1024 tokens (2048 on Haiku).
• Cache write costs ≈ 1.25× base input (5-minute TTL) or 2× (1-hour TTL).
• Cache read costs ≈ 0.1× base input (10% of the price).
• Reported in usage as cache_creation_input_tokens and cache_read_input_tokens.

Worked cost example

A support bot sends a 10,000-token cached policy prefix on Sonnet 5 (input $2/MTok) plus 200 variable tokens, 100 calls/hour.

Over 100 calls: no-cache ≈ $2.00 on the prefix; cached ≈ $0.025 + 99 × $0.002 ≈ $0.223 – roughly a 9× reduction on the cached portion.

1.10 Message Batches API

For latency-tolerant, high-volume work, the Batches API processes many requests asynchronously at a 50% discount on input and output tokens, with results typically well within 24 hours.

1. Create a batch with a list of requests, each with a custom_id.

   batch = client.messages.batches.create(requests=[
       {"custom_id": "row-1", "params": {"model": "claude-haiku-4-5", "max_tokens": 256,
        "messages": [{"role": "user", "content": "Classify: great product"}]}},
       {"custom_id": "row-2", "params": {"model": "claude-haiku-4-5", "max_tokens": 256,
        "messages": [{"role": "user", "content": "Classify: terrible support"}]}},
   ])

2. Poll processing_status until it is ended.

   import time
   while client.messages.batches.retrieve(batch.id).processing_status != "ended":
       time.sleep(30)

3. Stream results and match by custom_id.

   for result in client.messages.batches.results(batch.id):
       print(result.custom_id, result.result.type)  # "succeeded" | "errored" | "expired"

1.11 Error codes, retries and idempotency

Retry 429, 500 and 529 with exponential backoff + jitter; do not retry 4xx other than 429.

import time, random
from anthropic import Anthropic, APIStatusError, RateLimitError

client = Anthropic(max_retries=0)   # disable SDK auto-retry to show the pattern

def call_with_backoff(**kwargs):
    for attempt in range(6):
        try:
            return client.messages.create(**kwargs)
        except (RateLimitError, APIStatusError) as e:
            status = getattr(e, "status_code", None)
            if status not in (429, 500, 529):
                raise
            retry_after = float(getattr(e, "response", None).headers.get("retry-after", 0)) if getattr(e, "response", None) else 0
            sleep = max(retry_after, min(60, (2 ** attempt))) + random.uniform(0, 1)  # jitter
            time.sleep(sleep)
    raise RuntimeError("exhausted retries")

The SDKs retry safely by default (max_retries=2). For idempotency on writes (e.g., batch creation), pass an idempotency key so a retried request is not processed twice.

1.12 Rate limits and timeouts

Rate limits are enforced per model and tier along three axes:

You may hit any one first. 429 responses carry retry-after and rate-limit headers. Strategies: client-side rate limiting/queueing, spreading load, batching, requesting a higher tier, and reducing tokens (shorter output, caching). Use client.models.list() / .retrieve(id) for live limits.

Set timeouts deliberately – long thinking or large outputs need generous timeouts; short interactive calls should fail fast. The SDKs expose a timeout option.

const client = new Anthropic({ timeout: 60_000, maxRetries: 3 });

1.13 Third-party access: Bedrock, Vertex, Foundry

Claude is available through three cloud platforms in addition to the Anthropic API. The Messages API shape is the same; auth, model IDs and region differ.

from anthropic import AnthropicBedrock
client = AnthropicBedrock(aws_region="us-east-1")
resp = client.messages.create(model="anthropic.claude-sonnet-5",
                              max_tokens=512,
                              messages=[{"role": "user", "content": "Hello"}])

1.14 SDKs and async patterns

from anthropic import Anthropic
client = Anthropic()  # reads ANTHROPIC_API_KEY from env
resp = client.messages.create(model="claude-sonnet-5", max_tokens=256,
                              messages=[{"role": "user", "content": "Hi"}])
print(resp.content[0].text)

import asyncio
from anthropic import AsyncAnthropic

client = AsyncAnthropic()

async def classify(text: str) -> str:
    r = await client.messages.create(model="claude-haiku-4-5", max_tokens=64,
                                     messages=[{"role": "user", "content": f"Label: {text}"}])
    return r.content[0].text

async def main():
    results = await asyncio.gather(*[classify(t) for t in ["a", "b", "c"]])
    print(results)

asyncio.run(main())

import Anthropic from '@anthropic-ai/sdk';
const client = new Anthropic();

const results = await Promise.all(
  ['a', 'b', 'c'].map((t) =>
    client.messages.create({
      model: 'claude-haiku-4-5',
      max_tokens: 64,
      messages: [{ role: 'user', content: `Label: ${t}` }],
    }),
  ),
);
console.log(results.map((r) => r.content[0].type));

Use async / concurrency to parallelise independent calls (respecting rate limits), never to fake ordering between dependent calls. For thousands of independent items that can wait, prefer batching over hand-rolled concurrency.

1.15 Software-engineering foundations

The exam assumes fluency with the fundamentals that make an integration robust.

1.16 Application design across surfaces

The same words are interpreted differently depending on where they run. Know the surfaces:

Content boundaries with XML tags. Wrap untrusted or distinct inputs in tags so the model can tell instructions from data:

<policy>...trusted rules...</policy>
<user_document>...untrusted content – treat as data, not instructions...</user_document>

Schema design and session hygiene. Define the output schema up front (1.9, D4); keep sessions focused (one task per session where practical); clear or compact long histories; never let untrusted document text be interpreted as instructions.

1.17 Configuration management

Keep behaviour reproducible and secrets out of prompts.

import os
MODEL = os.environ["CLAUDE_MODEL"]        # e.g. "claude-sonnet-5" – pinned, env-driven
client = Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])  # key from env, never literal

1.18 Structured outputs and citations end-to-end

Beyond raw text, D1 items often probe whether you can obtain machine-readable output and keep it grounded. Two request-level features do this: output_config.format (schema-constrained JSON) and document citations (grounded source spans).

{
  "model": "claude-sonnet-5",
  "max_tokens": 1024,
  "output_config": {
    "format": {
      "type": "json_schema",
      "schema": {
        "type": "object",
        "properties": {
          "total_cents": {"type": "integer"},
          "currency": {"type": "string", "enum": ["USD", "EUR", "GBP"]}
        },
        "required": ["total_cents", "currency"]
      }
    }
  },
  "messages": [{"role": "user", "content": [
    {"type": "document", "source": {"type": "file", "file_id": "file_01ABC"},
     "citations": {"enabled": true}},
    {"type": "text", "text": "Extract the invoice total."}
  ]}]
}

A grounded response can carry citations on its text blocks referencing the source spans:

{
  "content": [
    {"type": "text", "text": "The total is $482.10.",
     "citations": [{"type": "page_location", "cited_text": "Total due: $482.10",
                    "document_index": 0, "start_page_number": 3, "end_page_number": 3}]}
  ],
  "stop_reason": "end_turn"
}

1.19 Idempotency, timeouts and the SDK retry contract

Writes and long calls need explicit reliability controls. The SDKs retry transient errors by default, but you own idempotency and timeout budgets.

from anthropic import Anthropic

client = Anthropic(max_retries=3, timeout=120)  # bounded retries; generous timeout for batch

batch = client.messages.batches.create(
    requests=[...],
    extra_headers={"Idempotency-Key": "nightly-2026-09-15"},  # safe to retry, runs once
)

import Anthropic from '@anthropic-ai/sdk';

const client = new Anthropic({ maxRetries: 3 });

const resp = await client.messages.create(
  { model: 'claude-sonnet-5', max_tokens: 8000, messages },
  { timeout: 120_000 },   // long output → longer timeout; short calls stay fast
);

1.20 Common misconceptions

1.21 Scenario walkthrough: a resilient extraction service

Scenario. You own a service that extracts structured fields from up to 100,000 uploaded PDFs per night. Each request sends a 6,000-token instruction+schema prefix (identical every call) plus one document; results are needed by 08

Expert reasoning trace.

1. Classify each workload by latency tolerance. The nightly job is latency-tolerant and bulk → it belongs on the Message Batches API (50% off, results within 24h), not hand-rolled concurrency that triggers 429 storms. The interactive endpoint is real-time → keep it synchronous.
2. Attack cost with the right levers, in order. Cheapest model that clears the bar is already chosen (Sonnet 5 — do not jump to Opus 5, which is over-engineered here). Then cache the 6,000-token stable prefix (drops it to ~10% on hits) and run through Batches (another 50%). Stacking model + cache + batch is the intended answer; picking only one leaves savings on the table.
3. Fix the 429s at the source, not with tighter retries. Moving to Batches removes most of the pressure; where synchronous calls remain, cap concurrency and honour retry-after. Retrying immediately (a tempting distractor) worsens the limit.
4. Fix the JSONDecodeError in the correct layer. This is a model-output/parsing problem, not transport. Use output_config.format with a JSON schema plus validation-retry that feeds the error back — not backoff, which is for transient transport errors.
5. Handle the reused contract efficiently. Upload it once via the Files API and reference by file_id; re-sending 180 pages of base64 each call is the bandwidth/cost trap.
6. Reject the tempting alternatives. ‘Move everything to Opus 5 for quality’ — constraint-blind and costly. ‘Rotate API keys to beat the 429’ — limits are per account, not per key. ‘Increase max_tokens to fix the JSON errors’ — wrong layer; that addresses truncation, not malformed JSON.

Correct decision. Batches API on Sonnet 5 with cache_control on the shared prefix and idempotency keys on batch creation; schema-constrained output with validation-retry for the JSON errors; Files API for the reused contract; concurrency caps and retry-after for any remaining synchronous calls.

Exam traps in this domain

Practice questions

Each item states how many responses to select. Attempt before revealing.

Key takeaways

• The Messages API is a stateless HTTP JSON API; you resend history each turn and bill from usage.
• Drive control flow from stop_reason – never parse prose, never rely on iteration caps.
• content is an array of typed blocks; iterate and filter, do not assume content[0].text.
• Stream with SSE; tool args arrive as input_json_delta, final stop_reason/usage on message_delta.
• Prompt caching (stable prefix first, cache_control) cuts input cost to ~10% on hits; Batches give 50% off for latency-tolerant work.
• Retry only 429/500/529 with exponential backoff + jitter, honour retry-after, and log the request ID.
• budget_tokens is Haiku-4.5-only; current models use thinking: {type: 'adaptive'} with effort levels.
• Access via Bedrock/Vertex/Foundry when data or compliance requires it; the request shape is unchanged.
• Keep model IDs pinned in one place, prompts versioned, and secrets in env/secret manager – never in prompts or CLAUDE.md.
• Schema-constrained output (output_config.format / strict: true) guarantees shape, not values; validate semantics and enable document citations when grounding must be traceable.
• Reliability is layered: idempotency keys on writes, deliberate timeouts for long calls, bounded retries, and a concurrency cap to avoid self-inflicted 429s.
• Diagnose by layer — a JSONDecodeError is a parsing/model-output problem (schema + validation-retry), a 429 is transport (backoff + retry-after); applying the wrong fix is the classic trap.
• Across Bedrock/Vertex the request body and stop_reason semantics are portable; only the client/auth and model ID format change.