Plugging in real data
APIs make research better, not possible. Build every one with a fallback so a dead key never stops the work.
7 min read
Curious
0 XPClaude Code can search and fetch pages out of the box. Adding APIs gets you better data: real search volumes, cleaner page text, Reddit threads you cannot reach by searching.
The source system uses four:
| What | Used for | If it dies |
|---|---|---|
| SERP API | The top 15 results and what type each one is | Fall back to built-in WebSearch |
| Reader API | Clean page text, and it gets past blocks that stop plain requests | Fall back to built-in WebFetch |
| Reddit archive | Real comments from real threads | Skip the Reddit section, note it in the report |
| Screenshots | Pricing-page captures for reviews | Skip the screenshot, note it in the report |
Require the outcome, not the vendor
Write your rules as "the article needs a SERP-informed research pass and two authoritative sources", never as "use this specific API". Then a dead key downgrades the research instead of blocking it.
Where keys go
Never in CLAUDE.md. That file gets shared, screenshotted, and committed to git. Keys go in a file that git ignores.
# .gitignore references/api-keys.local.md .env.local # references/api-keys.local.md <- ignored by git SERP_KEY=... READER_KEY=...
Check before you commit
Exported workflow files from automation tools bundle real credentials inside the export. If you save one into your project to show Claude, it goes in an ignored folder. This has bitten real projects.
The failure that looks like success
The nastiest thing about a fallback is that it works. The page renders, the article ships, and nothing tells you the good data source has been down for a week.
Two directories quietly serving the wrong data
Two data-backed pages were switched from a bundled backup file to a live database. The keys were added, the deploy ran, the pages loaded fine. They were still serving the backup file, and they did so through two more deploys before anyone checked. The keys had been correct the entire time. The deploy command was reusing a cached build, so the pages were never actually rebuilt.
Cost: Three deploys and half a day, chasing a config problem that did not exist.
The rule that came out of it. A silent fallback renders an identical page, so a working page proves nothing. Prove a live connection by changing one value at the source and watching it appear, then changing it back.
Do this now
- 1
Create the ignored keys file before you have any keys to put in it.
mkdir -p references echo "references/api-keys.local.md" >> .gitignore touch references/api-keys.local.md
Doing it in this order means there is never a window where a key sits in a tracked file.
- 2
Add one line to your CLAUDE.md naming the outcome, not the tool.
Research must be SERP-informed and cite 2 authoritative sources. Preferred tools: <yours>. If a key is missing or the API fails, fall back to WebSearch and WebFetch and say so in the report.
- 3
Test the fallback on purpose. Rename your keys file and run a research task.
You want to see the downgrade happen once while you are watching, rather than discover it in a batch.
Finished reading?
Mark it done to bank the XP and keep your streak alive. Any challenges on this page score separately, so you can come back for a perfect run later.