Study guide

3.2 Files API, Document Blocks & Citations

Claude Certified Developer - Foundations CCDV-F

Track your progress as you read

Finished sections get a check mark.

1 Chapter 1: Core Messages API & Streaming

1.1 Messages API Fundamentals & Request Lifecycle 1.2 Streaming & Server-Sent Events (SSE) 1.3 Thinking: Adaptive Mode, Effort & Reasoning Budgets

2 Chapter 2: Optimization & Asynchronous Batches

2.1 Prompt Caching Mechanics & Breakpoints 2.2 Message Batches API & Asynchronous Workloads

3 Chapter 3: Structured Outputs, Documents & Files API

3.1 Structured Outputs & JSON Extraction 3.2 Files API, Document Blocks & Citations

4 Chapter 4: Application Design, Resilience & Delivery Life Cycle

4.1 API Resilience, Error Handling & Retries 4.2 Production Backend Architecture & State Management 4.3 Requirements Analysis & Claude Application Design 4.4 The Claude Application Life Cycle & Configuration Management

5 Chapter 5: LLM Fundamentals, Model Selection & Versioning

5.1 LLM & Technical Fundamentals: Tokens, Context Windows & Sampling 5.2 Claude Model Family Selection 5.3 Model Versioning, Snapshot Pinning & Migration 5.4 Latency & Throughput Optimization

6 Chapter 6: Cost Engineering & Context Management

6.1 Production Cost Optimization Strategies 6.2 Context Window Management & Compaction

7 Chapter 7: Foundations of Workflows & Deterministic Patterns

7.1 Agent vs. Workflow Architectural Foundations 7.2 Workflow Patterns: Prompt Chaining & Routing 7.3 Workflow Patterns: Parallelization & Voting

8 Chapter 8: Autonomous Agents & Multi-Step Systems

8.1 Workflow Patterns: Orchestrator-Workers & Evaluator-Optimizer 8.2 Agent Loop Implementation & State Tracking 8.3 Agent Frameworks & Human-in-the-Loop (HITL)

9 Chapter 9: Prompt and Context Engineering

9.1 System Prompt Design & Role Framing 9.2 XML Tags & Structural Prompt Delimiters 9.3 Few-Shot Prompting & In-Context Learning 9.4 RAG Context Injection & Document Formatting

10 Chapter 10: Tool Calling & Model Context Protocol (MCP)

10.1 Tool Schema Design & Parameter Validation 10.2 Tool Execution, Multi-Tool Calls & Error Handling 10.3 MCP Architecture & Core Primitives 10.4 MCP Transports & Client/Server Integration 10.5 Agentic Customization: Built-in Tools, Custom Tools, Skills & MCP

11 Chapter 11: Security, Safety & Governance

11.1 Direct & Indirect Prompt Injection Defenses 11.2 Tool Permissions, Sandboxing & Least Privilege 11.3 Data Privacy, Redaction & Audit Logging 11.4 Identity, Secrets & API Key Management

12 Chapter 12: Claude Code Developer Tooling

12.1 Claude Code Architecture & Project Configuration 12.2 Permissions, Modes & Hooks

13 Chapter 13: Evaluation, Testing & Production Observability

13.1 Evaluation Design & Golden Datasets 13.2 Production Observability, Tracing & Debugging

3.2 Files API, Document Blocks & Citations

Key Takeaways Explain This Topic AI

Claude converts every PDF page into an image and supplies the page's extracted text alongside it, so a PDF costs text tokens (typically 1,500–3,000 per page, depending on density) plus image tokens for each page.

The Messages API supports inline base64 document blocks ( source.type: "base64" ) for transient single requests and the Files API ( /v1/files ) for uploading reusable documents referenced by file_id .

The token counting endpoint ( POST /v1/messages/count_tokens ) allows zero-inference pre-flight sizing of complex document payloads to verify context window fit and calculate costs before execution.

Enabling citations ( citations: {"enabled": true} ) produces structured provenance metadata ( cited_text , document_index , and a location: 0-indexed character offsets for plain text, 1-indexed page numbers for PDFs), which makes each claim checkable for compliance auditing.

Large documents benefit substantially from prompt caching ( cache_control: {"type": "ephemeral"} ): cache reads cost 0.1x base input on most models (0.05x on Claude Opus 5.5 and Claude Sonnet 5.5, 0.025x on Claude Fable 5.1), and time-to-first-token improves on repeated queries against the same file.

Last updated: October 2026

Multimodal Document Capabilities in Claude

Enterprise AI architectures frequently require reasoning over information-dense business documents—including corporate annual reports, regulatory filings, legal agreements, technical manuals, and financial audits. Anthropic's Claude provides native multimodal document intelligence, allowing developers to submit raw documents directly to the Messages API without requiring third-party optical character recognition (OCR) or lossy document conversion utilities.

Claude processes documents as follows:

Plain-text documents : a text/plain document block is tokenized as text.

PDFs (text plus image for every page) : the system converts each page of a PDF into an image and extracts the text from each page, providing both to Claude. This is why Claude can read charts, diagrams, multi-column layouts, and scanned pages as well as the text layer.

Token Consumption Mechanics for PDFs : a PDF page costs text tokens (typically 1,500–3,000 tokens per page , depending on content density) plus image tokens for the page image, calculated the same way as any other image. Page count, not just word count, drives the bill: a scanned contract with few words still pays the image cost on every page. Use the token counting endpoint to get the exact figure for a specific file when sizing context windows and estimating costs.

Document Content Blocks vs. The Files API

Developers can ingest documents into Claude using two primary architectural paradigms: inline base64 document blocks or the asynchronous Files API.

Pattern A: Inline Base64 Document Blocks

For transient, single-turn workflows where a document is processed once and immediately discarded, developers transmit documents inline within the content array of a user message turn: {

  • "role": "user",
  • "content": [
  • {
  • "type": "document",
  • "source": {
  • "type": "base64",
  • "media_type": "application/pdf",
  • "data": "JVBERi0xLjQKJ..."
  • },
  • "title": "Q3_Financial_Filing.pdf",
  • "context": "Quarterly filing submitted to regulatory authorities."
  • },
  • {
  • "type": "text",
  • "text": "What was the operating margin for the cloud infrastructure division?"
  • }
  • ]
  • }

Document content blocks accept:

PDF ( application/pdf ): The page ceiling is 600 pages per request when the request's context window is 1M tokens, and 100 pages when it is under 1M.

Plain text ( text/plain ): Files that are already plain text, such as .csv and .md files, can be sent or uploaded with an explicit text/plain content type.

Custom content : a list of content blocks you supply, useful for transcripts or lists where you want block-level citations.

File types the document block doesn't support, such as .docx and .xlsx , must be converted to plain text first.

Payload Size Limitations : Base64 encoding introduces an approximate 33% bandwidth expansion compared to raw binary data. Because the Anthropic Messages API enforces a strict 32 MB request body ceiling , raw unencoded files submitted via inline base64 must remain below ~24 MB.

Pattern B: The Files API ( /v1/files )

When documents are large, referenced repeatedly across multi-turn user conversations, or shared across parallel worker agents, transmitting multi-megabyte base64 strings in every API call wastes client bandwidth, increases network latency, and bloats payload sizes. The Files API decouples file upload from inference:

Upload Stage : The client uploads the raw document once via POST /v1/files using standard multipart/form-data . Anthropic processes and stores the file securely, returning a unique identifier (e.g., "file_011CNnbx8xyz" ).

Inference Stage : In subsequent calls to POST /v1/messages , the application references the file by ID within the document content block source: {

  • "type": "document",
  • "source": {
  • "type": "file",
  • "file_id": "file_011CNnbx8xyz"
  • }
  • }

Lifecycle Management : Applications manage their file storage footprint using standard REST endpoints: listing files ( GET /v1/files ), retrieving file metadata ( GET /v1/files/{file_id} ), and deleting stale assets ( DELETE /v1/files/{file_id} ).

Pre-Flight Payload Sizing with count_tokens

Ingesting large documents presents serious operational risks: an unexpectedly large document can breach the model's context window (1M tokens on every current model, including Claude Haiku 5.5; 200K on older models such as the legacy Claude Haiku 4.5), hit rate limits, or generate massive unintended API billing. To mitigate these risks, Anthropic provides the Token Counting Endpoint ( POST /v1/messages/count_tokens ).

Mechanics and Behavioral Contract

The count_tokens endpoint accepts the exact same payload schema as POST /v1/messages (including model , system , messages , tools , and document blocks). curl https://api.anthropic.com/v1/messages/count_tokens \

  • H "x-api-key: $ANTHROPIC_API_KEY" \
  • H "anthropic-version: 2023-06-01" \
  • H "content-type: application/json" \
  • d '{
  • "model": "claude-sonnet-5-5",
  • "messages": [
  • {
  • "role": "user",
  • "content": [
  • {
  • "type": "document",
  • "source": {
  • "type": "base64",
  • "media_type": "application/pdf",
  • "data": "JVBERi0xLjQKJ..."
  • }
  • },
  • {
  • "type": "text",
  • "text": "Extract all risk factors outlined in Section 3."
  • }
  • ]
  • }
  • ]
  • }'
  • Response: {
  • "input_tokens": 38420
  • }
  • Architectural Value for Production Systems

Zero-Inference Cost : Token counting executes server-side tokenization and visual page resolution without running model inference or generating output tokens. It incurs zero generation cost and minimal API latency.

Pre-Flight Context Verification : Verifies whether a complex payload—combining system prompts, tools, conversation history, and a 40-page PDF—fits comfortably inside the context window before committing expensive compute.

Dynamic Cost Governance : Computes exact input cost before triggering large batch jobs ( input_tokens * unit_price ). If token count is small, the orchestrator can dynamically route the query to Claude Haiku 5.5; if extensive context reasoning is needed, it routes to Claude Sonnet 5.5.

Dynamic Chunking Trigger : If input_tokens exceeds a predefined budget (e.g., 150,000 tokens), the ingestion engine automatically branches to a semantic chunking pipeline.

The Citations API: Verifiable Enterprise Provenance

In enterprise environments—such as legal discovery, clinical healthcare, financial compliance, and contract management—unsubstantiated claims and model hallucinations carry legal and financial liability. Stakeholders cannot act on AI-generated insights unless each assertion can be traced directly to an auditable source passage.

The Citations API provides native, verifiable source attribution: because the API extracts cited_text itself, citations are guaranteed to contain valid pointers to the documents you provided. By enabling citations directly on document blocks, Claude anchors its generation to verifiable text spans within the source documents.

  • Enabling Citations in the Request
  • Citations are activated on individual document blocks by configuring "citations": {"enabled": true} : {
  • "role": "user",
  • "content": [
  • {
  • "type": "document",
  • "source": {
  • "type": "text",
  • "media_type": "text/plain",
  • "data": "MASTER SERVICES AGREEMENT ..."
  • },
  • "title": "Master_Services_Agreement_2026.txt",
  • "citations": {
  • "enabled": true
  • }
  • },
  • {
  • "type": "text",
  • "text": "What are the termination provisions and notice requirements?"
  • }
  • ]
  • }
  • Structure of Citation Response Blocks
  • When citations are enabled, Claude annotates generated text blocks with structured citation objects: {
  • "role": "assistant",
  • "content": [
  • {
  • "type": "text",

"text": "Either party may terminate this Agreement without cause upon sixty (60) days prior written notice to the non-terminating party.",

  • "citations": [
  • {
  • "type": "char_location",

"cited_text": "Either party may terminate this Agreement without cause upon giving sixty (60) days prior written notice to the other party.",

  • "document_index": 0,
  • "document_title": "Master_Services_Agreement_2026.txt",
  • "start_char_index": 18450,
  • "end_char_index": 18575
  • }
  • ]
  • }
  • ]
  • }
  • Anatomy of a Citation Object

type : Indicates the citation anchoring mechanism, which depends on the document type: "char_location" for plain text (0-indexed character offsets), "page_location" for PDFs ( start_page_number / end_page_number , 1-indexed), and "content_block_location" for custom content (0-indexed block indices). End indices are exclusive.

cited_text : The verbatim quote extracted directly from the source document that proves the assertion.

document_index : Zero-based integer indicating which document block in the request array supplied the citation.

document_title : The title attribute supplied on the original document block.

start_char_index & end_char_index (plain text): Zero-based character offsets within the document text, with an exclusive end index.

Enterprise Applications of Citations

Automated Compliance Auditing : Background verification services programmatically verify that 100% of claims in a generated report contain matching citations with zero string edit distance from the source repository.

Interactive UI Highlighting : Document viewers use the character ranges (plain text) or page ranges (PDFs) to highlight the cited passage and show citation tooltips.

Easier Hallucination Review : Each cited claim points to a verbatim source passage, so reviewers can check it quickly; uncited sentences stand out as the ones that need scrutiny.

  • Document Handling Best Practices & Cost Optimization
  • Document Hard Boundaries

Page Ceiling per Request : 600 pages when the request's context window is 1M tokens, dropping to 100 pages when it is under 1M. The ceiling applies to the entire request payload , not to one document block, so several PDFs in one request share the budget. Dense pages can also exhaust the context window before the page ceiling is reached.

32 MB Request Size Limit : The 32 MB ceiling also covers the whole request payload. Larger documents must be uploaded through the Files API and referenced by file_id , which keeps the request itself small.

Multi-Document Concurrency : Applications can supply multiple document blocks in a single request (e.g., comparing three competing vendor contracts), provided cumulative tokens remain within the model context window.

Chunking Strategies for Massive Documents

When working with 500-page SEC 10-K filings or technical manuals that exceed the 100-page threshold:

Semantic Partitioning : Split documents along logical chapter or section headings rather than arbitrary byte offsets.

Overlapping Sliding Windows : Partition documents into 30-page windows with a 3-page overlap to prevent factual fragmentation across page boundaries.

Hierarchical Indexing : Extract high-level chapter summaries using Claude Haiku 5.5, and route targeted chapters to Claude Sonnet 5.5 for detailed analysis.

Combining Documents with Prompt Caching

Re-evaluating a 60-page document across multi-turn conversations can rapidly become cost-prohibitive if the document is re-tokenized on every turn. Combining document blocks with Prompt Caching ( cache_control: {"type": "ephemeral"} ) is the most impactful optimization available:

Cache Breakpoint Placement : Attach "cache_control": {"type": "ephemeral"} directly to the document content block or the preceding system message.

Cost Reductions : On the initial call, the document is tokenized and written to the cache (regular input token price + 25% cache write fee for the 5-minute TTL). On subsequent calls within the cache TTL, cached document tokens are read at 0.1x the regular input price on most models (0.05x on Claude Opus 5.5 and Claude Sonnet 5.5, 0.025x on Claude Fable 5.1).

Latency Reductions : Reading a cached document prefix generally improves time-to-first-token for long documents.

Comparison of Document Ingestion Strategies

Feature / Dimension Inline Base64 Document Block Files API ( /v1/files ) Traditional Text RAG Pipeline

Best For Ad-hoc single-turn document analysis Multi-turn chat & shared document pools Massive 1,000+ page document corpuses

Bandwidth Overhead High (+33% base64 inflation on every call) Low (uploaded once; referenced by file ID) Low (only retrieved top-k chunks sent)

Visual Layout & Charts Preserved (native visual page rendering) Preserved (native visual page rendering) Lost (traditional parsers strip images/charts)

Token Consumption PDF: text tokens plus image tokens for every page PDF: text tokens plus image tokens for every page Scales strictly with retrieved text tokens

Prompt Caching Supported via cache_control Supported via cache_control Supported on prompt / chunk prefixes

Citations API Native (page ranges for PDFs, character offsets for plain text) Native (page ranges for PDFs, character offsets for plain text) Requires custom chunk-offset tracking

Common CCDV-F Exam Traps & Pitfalls

Underestimating PDF Tokens : Assuming PDF token counts correlate strictly with word count. Every PDF page is also converted into an image and billed with image-token costs, so a sparse scanned page still costs tokens.

Passing Incomplete Payloads to count_tokens : Treating count_tokens as a simple string utility. The endpoint requires the full Messages API request structure (including model and messages ). Omitting required fields results in a 400 Bad Request.

Expecting Character Offsets for PDFs : PDF citations come back as page_location with 1-indexed page numbers. char_location with zero-based character offsets applies to plain-text documents, and the offsets are positions in the document text, not byte positions in a file.

Assuming a Fixed 100-Page Ceiling : The limit is 600 pages per request when the request's context window is 1M tokens and 100 pages below that, and it applies to the whole request payload rather than to a single document block.

Loading diagram... Enterprise Document Ingestion, Token Sizing & Verifiable Citations Pipeline