Integration · Models
Claude API integration for long documents and tool use
We use Anthropic’s Claude API where a task means reading long documents, citing exactly where an answer came from, or calling your own tools in a loop. Your code runs every tool, so the model can only do what you have wired up and permitted.
Anthropic Claude
Models
Access
Authentication and least-privilege scopes
Workspace-scoped API keys in your Anthropic Console organisation, held by your gateway
- workspace: one per environment
- limits: workspace spend + rate
- tools: allowlist per feature
- keys: rotated on staff change
Workspaces keep test and production traffic apart, each with its own spend and rate limits, so a test run cannot use production capacity.
Objects
What we read and what we write
Messages request
Read: NoWrite: Yes
System prompt, documents, tool definitions and the conversation.
Document block (PDF or text)
Read: NoWrite: Yes
Sent with citations on, so answers point to pages or passages.
tool_use block
Read: YesWrite: No
Claude asks to call one of your tools with structured input.
tool_result block
Read: NoWrite: Yes
Your code returns the result, or an error flag, and Claude continues.
Citations
Read: YesWrite: No
Cited text with page or character ranges, shown as sources.
Usage + rate-limit headers
Read: YesWrite: No
Input, output and cache tokens per call; retry-after on a 429.
Data flow
System of record and write-back
Your document store and business systems stay the source of truth. The gateway assembles each request, runs any tool Claude asks for against your APIs and logs every step.
- The gateway sends the document and the question with citations on.
- Claude answers, or returns a tool_use block naming a tool and its input.
- Your code checks the tool against an allowlist, runs it and returns a tool_result.
- The final answer carries citations; write actions above your threshold wait for a person.
- Contract PDF
- User question
- Claude API
- Your order API
- Audit log
Worked example
Anthropic Claude in a build
- 00:00PLANGatewayGateway › Send the supplier contract PDF with citations on, plus the question.
- 00:02TOOLClaudeClaude › tool_use: get_open_orders { supplier_id: "S-104" }
- 00:03OKRunnerRunner › Allowlisted read tool; three open orders returned as tool_result.
- 00:05OKClaudeClaude › Notice period is 30 days, cited from page 7.
- 00:06APPROVALClaudeClaude › Proposes draft_cancellation for order 2231.
- 00:09APPROVEDReviewerReviewer › Procurement lead approves the draft; nothing is sent automatically.
- 00:09DONEGatewayGateway › Answer, citations and tool calls written to the audit log.
Sample workflows
What teams build with Anthropic Claude
Pattern 01
Contract and policy review
Long agreements are read with citations on, so every extracted clause links to its page and a reviewer checks the summary against the cited text.
Pattern 02
Support agents with tools
Claude answers from your help content and calls read-only tools such as order lookup. Refunds and account changes go through an approval step.
Pattern 03
Research briefs from many files
A folder of reports becomes a brief with a source for each claim, and gaps are listed instead of filled in.
Failure handling
What breaks, and what the build does about it
A tool returns an error
The tool_result carries an error flag and a short reason, so Claude can try another path or tell the user. Repeated errors end the loop and alert a person.
The document is too big for one request
Large files are uploaded through the Files API or split by section, and answers cite the section they came from.
Rate limits are reached
The gateway honours retry-after and caches stable prompt prefixes, because cached input tokens do not count towards the input-token limit on most models.
Fit · Anthropic Claude
When it is the wrong choice
- The answer depends on live data you have not exposed as a tool. Build the tool first, or the model will guess.
- Short, high-volume classification where a smaller, cheaper model passes your eval set.
- Data must stay inside your own network. Claude through your cloud provider covers your cloud account; for your own network, use an open-weight model.
Alternatives worth pricing
Strict JSON schemas, batch jobs and a wide choice of model sizes.
Mixed image, audio and video inputs in one request.
Inference that must run inside your own perimeter.
Where it is used
Related use cases, services and guides
Limits
Limits and common errors
Client tools run in your application: Claude stops with stop_reason "tool_use" and tool_use blocks, your code runs them and returns tool_result blocks. Server tools run on Anthropic’s side.
Source: Tool use with Claude (opens in a new tab) · Claude Developer Platform · accessed
A PDF request can be up to 32 MB and 600 pages (100 pages when the context window is under 1M tokens); password-protected PDFs are not supported.
Source: PDF support (opens in a new tab) · Claude Developer Platform · accessed
Citations work on PDF, plain-text and custom-content documents; PDF citations give 1-indexed page ranges, and cited text does not count towards output tokens.
Source: Citations (opens in a new tab) · Claude Developer Platform · accessed
Retained data is never used for training without express permission, and zero data retention covers eligible features. On Bedrock and Google Cloud the cloud provider processes the data.
Source: API and data retention (opens in a new tab) · Claude Developer Platform · accessed
Rate limits are set per model class in RPM, ITPM and OTPM; for most models cached input tokens do not count towards ITPM, and a 429 may carry retry-after.
Source: Rate limits (opens in a new tab) · Claude Developer Platform · accessed
Security
Security notes
- Tools are allowlisted per feature, read and write tools are separate, and write tools need approval above your thresholds.
- Document text and tool results are treated as untrusted, so instructions hidden in a file cannot widen what the model may do.
- Keys are workspace-scoped and live in the gateway; none reaches a browser.
FAQ
Frequently asked questions
How long a document can Claude read in one request?
Hundreds of pages, within the request-size limit cited below. For larger sets we split by section or upload through the Files API, and citations keep pointing at the right part.
Does Anthropic keep or train on what we send to the Claude API?
Anthropic states that retained data is never used for training without your express permission. Retention depends on the features and models you use, and zero data retention exists for eligible features; we confirm your organisation’s setting before launch.
Can Claude take actions in our systems?
Only through tools you define and your code runs. Claude asks to call a tool; the gateway checks it against an allowlist, runs it and returns the result. Anything that touches money, records or customer messages can require a person’s approval.
Why turn on citations instead of asking the model to quote its sources?
With citations on, the API returns the cited passage and its page or character range as part of the response. Your interface gets reliable links to the source rather than quotes the model wrote itself.
Can we use Claude through AWS or Google Cloud instead?
Yes. Claude is also offered on Amazon Bedrock and Google Cloud, where the cloud provider processes the data under your cloud agreement. Features differ by platform, so we check the ones your design needs.
Next step
Have a workflow in mind? Let’s scope it together.
Book a free 30-minute strategy call. Bring one process you want to automate and we will talk through scope, integrations and a sensible first step.
Free 30-minute call · no commitment