APIs, how systems talk to each other

Twenty minutes into the scoping review for your support-ticket summary feature, the engineering lead is reading the integration plan your AI coding tool drafted and you forwarded with a recommendation to build. The plan's operative sentence says the feature is one POST to the provider's text-generation endpoint and the cost per request is negligible. She asks two questions before staffing it: what exactly does each request carry, and what does negligible become at two thousand tickets a day? The plan does not answer, and neither can you. The number that decides the build, one request's price multiplied by every ticket, sits inside a request you have never seen.

That request is an API call. This chapter prints one in full and walks it line by line, so the next plan gets a yes you can defend.

What an API is

You land at a hotel front desk at midnight with a missing reservation. You do not walk around the counter and fix the booking system yourself; you state your case in the form the desk expects, a name, a confirmation number, a card, and you get back a room key or a polite no with a reason. Connected software works the same way: no system reaches into another's code or database; it hands a front desk a request in an agreed form and takes what comes back. That desk is an API, and every AI feature you will ever scope depends on at least one.

An API call is the round trip you traced in the journey of a request, usually made by your backend, the machine holding the credential.

The call from the plan, printed in full

Here is the request behind the plan's operative sentence, sent when an agent opens a ticket. It is written in JSON, a plain-text format of labeled fields, a name in quotes with its value, which nearly every API uses in both directions because people and code can both read it.

POST https://api.provider.example/v1/generate
Authorization: Bearer (your API key, attached on your server)

{
  "model": "(the model you chose)",
  "instructions": "Summarize this ticket in one sentence
    for the agent picking it up.",
  "input": "Checkout fails at the payment step, two cards
    tried, order 58214 still stuck as pending.",
  "max_output_tokens": 60
}

Read it against the desk. The first line states your case: POST is the verb, asking for new work, where GET would ask for a lookup. The address beside it is the endpoint, the name of the one door for this one job; a payments service keeps separate doors for charging and refunding, and this one generates text. The Authorization line is the card you put down: the API key you met a chapter ago, attached on your server and never in the browser.

The body lists the job's details: model picks which of the provider's models runs the work, instructions states the job in your own words, input carries the material it runs on, and max_output_tokens caps the reply's length, and with it the cost. A token is a chunk of text the model counts, a short word or a piece of a longer one; a page of English runs a few hundred.

Here is what the desk hands back, also JSON:

{
  "output_text": "Checkout is failing at the payment step
    for order 58214 after two cards were tried.",
  "stop_reason": "complete",
  "usage": { "input_tokens": 61, "output_tokens": 19 }
}

output_text is the room key: that sentence is what the support agent reads. stop_reason says why the reply ended; a reply cut short by the sixty-token cap would say so here. usage is the meter on the desk: 61 tokens handed in, 19 taken away, the entire bill for the call. A malformed request, a required field missing or a key that bills no account, gets an error code and a reason instead, the polite no in writing.

An API is the front desk of a service: you hand in a request in the form it asks for and get back the result it promised, or a refusal with a reason.

Model APIs meter the work in tokens

The usage block is the part model APIs add. Everything you send is counted in, instructions and input alike, everything generated is counted out, and the two directions are priced separately per million tokens, with output costing more. The rates change too often to print here; the provider's pricing page has the current numbers.

At this size the meter is nearly invisible: 61 in and 19 out cost a small fraction of a cent. The bill that reaches finance is that fraction multiplied by every ticket, every day, for a month, the multiplication the engineering lead was waiting on.

A model API meters the work in tokens, in both directions, and the monthly bill is that fraction of a cent multiplied by every user, every day.

One more line of small print sits on the desk: rate limits, the bouncer at the door, capping how fast one account can knock, usually requests and tokens per minute; going past it gets a refusal meaning slow down and retry. The spending alert that catches a runaway bill is a pre-flight step in Keep secrets, money, and data safe, and you will run this meter on a live call in Make your first model call.

The obvious objection: your tools write these calls for you

The obvious objection is that you will never type that request by hand, because Claude Code or its equivalent writes the integration, so reading one can feel like studying plumbing you will never touch. But the plan in your scoping review came from such a tool, and in our own builds these drafts go wrong in ways only a reader catches.

A door that does not exist as written. The draft calls a plausible endpoint the provider renamed or never had, and the first real call fails loudly.
An expensive default. The draft picks the provider's most capable model when a mid-tier one would do, and nothing fails until the invoice.
Missing small print. The draft sets no reply cap and no plan for the slow-down refusal, which holds up in a demo and breaks under real traffic.

The tool drafts and you approve, so an approval you do not understand repeats your scoping meeting's failure at machine speed.

Check the call against the docs page

Checking the plan takes reading, not engineering. Every endpoint has a documentation page, the sign posted at its desk, and you only need three things from it.

The form. The verb and address at the top, then the table of fields with the required ones marked. A renamed door or a missing required field shows up here.
The worked example. Nearly every docs page prints one complete request and response, the pair this chapter printed. Read it first; it says in seconds what the field tables take paragraphs to say.
The limits. Rate limits, maximum sizes, and the link to pricing. The reply cap and the volume math get their real numbers here.

None of this was invented for AI; payment and email desks post the same sign, so the skill transfers to every integration your product makes.

Try it now

This drill takes about fifteen minutes and spends nothing on either path.

No setup: For each line of the printed request and response, write one sentence on what the feature loses if that line disappears: the address, the key, then model, instructions, input, and max_output_tokens, then output_text, stop_reason, and usage in the reply. Every answer is in this chapter, and any line whose loss you cannot state is the one to reread; the same reading works on any call your tools propose.

With your tools: Open a real provider quickstart in your browser; searching "Anthropic API quickstart" or "OpenAI API quickstart" lands on one. Expect a wall of code, install commands, language tabs, and options this chapter never covered; ignore everything except two blocks: the request carrying a model name, instructions, and input, and the block showing what comes back. Ask Claude Code to match that request to our printed call field by field, then check its matching against your own reading; the labels differ by provider, but the parts do not. Same move in Codex or Cursor: paste the quickstart's request into the chat and ask for the field-by-field match. If nothing is installed yet, the Setup Clinic gets you running.

Chapter Summary

An API is the front desk of a service: you hand in a request in the form it asks for, and you get back the work or a refusal with a reason.
One system never reaches into another's code or database; everything arrives as a request at the desk and comes back as a reply.
JSON is the plain-text format of labeled fields that nearly every API uses in both directions.
A model call carries a verb and an address (the endpoint, one door for one job), an API key saying whose account pays, and a body with the model, your instructions, the input, and a reply cap.
The reply carries the product in output_text, the reason generation ended in stop_reason, and the meter in usage: tokens counted in and out.
A token is a chunk of text the model counts, priced per million in both directions with output above input, and one request costs a fraction of a cent.
The real bill is that fraction multiplied by every user, every day, for a month, so run the multiplication before the build starts.
Rate limits cap how fast one account can call; past the cap the answer is slow down and retry.
AI tools draft these calls and you approve them, so check the provider's docs page for the form, the worked example, and the limits before saying yes.
Everything these desks hand back has to live somewhere, and where it lives comes next in data, where information lives.

Sources

Anthropic Messages API documentation and quickstart (last verified July 2026).
OpenAI API reference and quickstart (last verified July 2026).
OpenAI, Anthropic, and Google pricing pages for per-token rates (last verified July 2026).