The big idea
An API is just a menu of requests a service will accept, and reading its documentation is far easier with an AI translator at your side than alone. Once you can make one successful call, you can feed live data into an AI prompt — combining current information with reasoning is where automation stops being static.
Deep dive
What an API actually is
Strip away the jargon and an API (Application Programming Interface) is a menu: a defined list of requests a service will accept, and the shapes of data it will hand back in response. When you call a weather API asking for "current conditions in Lisbon," you're not touching some mysterious internal system — you're ordering off a menu the service's developers published specifically so outside programs could ask for exactly that.
This reframe matters because it demystifies the whole topic: you don't need to understand how the weather service computes forecasts, any more than you need to know how a kitchen works to order off a restaurant menu. You just need to know what's on the menu (the endpoints), how to place an order (the request format), and how the food arrives (the response format).
Reading API docs with AI as your translator
API documentation is written for programmers, in a dense, jargon-heavy style that can make a five-minute task feel like an afternoon of confusion. The move that changes everything: paste the relevant docs page into your AI assistant and ask for exactly what you need — "I want to fetch all invoices from March. Which endpoint, what parameters, and show me the exact request."
This works because AI is extremely good at translating dense technical reference material into a concrete, specific answer for your specific use case, rather than making you read the whole page and mentally assemble the request yourself. You still need to sanity-check what it gives you against the real docs, but it turns docs-reading from a slog into a five-minute conversation.
Authentication basics: keys and where they live
Almost every real API requires authentication, most commonly an API key — a long string that proves you're allowed to make requests, usually tied to your account and your usage limits. The key rule that saves you from disaster: API keys go in a credential store or environment settings built for that purpose, never in a prompt, never in a chat conversation, never in a screenshot, and never in shared team chat.
If a key ever touches a chat conversation — even briefly, even by accident — treat it as burned and rotate it immediately. AI chat logs, screenshots, and shared documents have a way of persisting and being seen by more people than you intended, and a live key in the wrong hands can rack up charges or access data on your behalf.
Your first call: an HTTP step or a snippet
You don't need to write code to make an API call. Most automation platforms have an "HTTP Request" step (n8n, Zapier's Webhooks app) where you fill in the URL, method (usually GET for reading data), and any required parameters or headers — including your API key, placed in the credential fields the platform provides, not typed loosely into a text box.
If you're comfortable with a lightweight code snippet, AI can write you a five-line script to make the same call — useful for one-off exploration outside a full automation platform. Either way, your first goal is simple: get one successful response back, and confirm you understand what you asked for and what came back.
Reading the JSON response
API responses typically arrive as JSON — nested key-value data that can look intimidating at first glance, full of brackets and quotation marks. The good news: you rarely need to parse it by eye. Paste the raw response into your AI assistant and ask it to summarize the structure and pull out the specific fields you care about.
Over time you'll start recognizing the common shapes — a list of records, each with consistent fields, sometimes nested inside another layer for pagination or metadata — but there's no shame in leaning on AI to translate JSON into plain English every single time, especially for an API you use only occasionally.
Feeding API data into an AI prompt
The real payoff of connecting an API isn't the raw data — it's combining that live data with reasoning. A currency API alone just gives you numbers; paired with an AI step prompted "if EUR/USD moved more than 1% versus yesterday's stored value, write a one-line alert with context," you get judgment applied to fresh information, running unattended every morning.
This pattern — live data plus a reasoning step — is where automations stop feeling like plumbing and start feeling like a small analyst working for you. The API supplies the facts; the AI step supplies the interpretation and the decision about whether anything is even worth surfacing to you.
Rate limits, errors, and API politeness
Every API imposes rate limits — a cap on how many requests you can make in a given time window — and exceeding them gets you throttled or temporarily blocked. Build in reasonable pacing (most automation platforms let you schedule calls rather than firing them in a tight loop) and read error responses when they occur; a 429 status code specifically means "you're calling too fast, slow down."
Beyond rate limits, politeness also means only requesting the data you actually need, caching results you don't need to re-fetch every time, and reading the terms of service for any API you're relying on for a real workflow — some explicitly restrict automated or commercial use in ways worth knowing before you build on top of them.
How to run it
- Credentials live in a credential store. No API key ever appears in a prompt, chat log, screenshot, or shared document — only in the platform's dedicated secure fields.
- Reads before writes. You've made at least one successful read call against this API before attempting any write, so you understand the data shape.
- Writes have a human gate. Any write to a real system pauses for human approval until the automation has a track record of correctness.
- Rate limits are respected. Calls are paced on a schedule rather than fired in a tight loop, and 429 responses trigger a backoff, not a retry storm.
- Error responses are read, not ignored. You've seen at least one real error response from this API and know what the specific failure codes mean.
In the field
A freelance ops manager wires an automation that reads new form submissions from Tally, asks AI to classify the inquiry type, then writes a new contact into HubSpot via its API — but only after a Slack approval button is clicked, since a bad write would create a messy duplicate contact that someone would have to manually clean up later.
When not to use it
Skip direct API integration when a no-code connector already exists for both the source and destination inside your automation platform — hand-rolling an HTTP call to replicate what a native Gmail-to-Notion connector already does adds maintenance burden for no benefit. Also avoid building write access into an automation for data you don't yet trust the AI step to classify correctly; prove the read-and-classify step's accuracy with a manual review period before letting it write anywhere automatically.
Pitfalls and takeaways
- Pasting API keys into chat conversations, where they should be treated as burned the moment they're exposed
- Hardcoding credentials directly inside shared workflows instead of using a credential store
- Trying to read raw API docs cover-to-cover instead of asking AI for the one exact call you need
- Ignoring rate limits and hammering an API until it starts throwing errors
- Assuming a JSON response is self-explanatory instead of having AI summarize it in plain English
- An API is a menu of requests a service accepts — you don't need to understand its internals to use it
- API keys belong only in credential stores/environment settings, never in prompts, chats, or screenshots
- Live API data feeding into an AI reasoning step is where automation gets genuinely powerful
Do the work
Goal: Make a second API call that writes data (not just reads it), with a human-approval gate, so you feel the real difference between read and write risk. (30 min)
- Choose a safe write target. Pick an API action that creates or updates something low-stakes — a test contact in your CRM, a new row in a scratch spreadsheet, a page in a personal Notion workspace. Never practice writes against production customer data.
- Ask AI for the exact write request. Paste the relevant docs page into your AI assistant and ask: "Show me the exact POST/PATCH request to create a record with these fields: [list them]." Get the full request shape — method, URL, headers, body — before touching anything.
- Add a human-approval step before the write fires. In your automation platform, insert a manual-approval or "wait for confirmation" step between building the request and sending it. If scripting it standalone, simply run the write call only after you've printed and read the request body.
- Fire the write and verify in the source system. Approve the step, let the write fire, then go check the actual system (not just the API's success response) to confirm the record looks right.
- Deliberately send a malformed write. Now send one write with a missing required field or wrong data type on purpose, and read the resulting error response closely.
- Write your two-line safety rule. Based on what you just saw, write a one- or two-line personal rule for when you'll allow an automation to write without human approval versus when you'll always require a human gate.
Deliverable: One successful, verified API write with a human-approval gate, one deliberately-triggered write error with its exact error message recorded, and a written personal rule for when writes need human approval.
Sources
- OpenAI Cookbook (cookbook.openai.com)
- n8n docs (docs.n8n.io — HTTP request node)
- Simon Willison (simonwillison.net) on APIs + LLMs
- OpenAI API deprecations (platform.openai.com/docs/deprecations)