What you will learn What an API actually is, what endpoint, key and SDK each refer to, and why you would call one when a perfectly good screen exists.
A bank has two. The one people queue at, and the dedicated line other banks' systems connect to. An API is the second one.
| Screen (UI) | API | |
|---|---|---|
| Used by | people | other programs |
| Shape | buttons and tables | addresses and JSON |
| Good at | looking and judging | repetition, volume, automation |
API (Application Programming Interface) — literally "the surface built for programs to use". There is nothing more to it.
An API is usually several addresses. One such address is an endpoint. Taking the list from Driving work over REST:
| What it does | Method + endpoint |
|---|---|
| List tasks | GET /api/v1/tasks |
| Create a task | POST /api/v1/tasks |
| View one task | GET /api/v1/tasks/{id} |
| Stop it | POST /api/v1/tasks/{id}/stop |
The method plus the address is the function. The same
/tasks reads with GET and creates with POST. {id} marks where a real
identifier goes.
Two words describe most of today's APIs.
How to read it continues in Shapes of data.
Screens have logins. APIs have keys.
| Password | API key | |
|---|---|---|
| Used by | a person | a program |
| How many | one | one per purpose |
| If lost | reset it | retire that key only |
One per purpose is the whole point. If one leaks, you delete one thing. It is also why Calling it via API key insists on real names — without them you cannot tell which one to delete.
Calling an API directly means building the URL, attaching headers and parsing the response. An SDK (library) is that work pre-wrapped per language.
They do the same thing. Which is how Your machine as a model server can say "change only the base URL of the OpenAI SDK" — same counter shape, same toolbox.
If the job is one case that needs human judgement, the screen is better. APIs are the tool for the opposite end.
| Concept | Meaning | When you meet it |
|---|---|---|
| Rate limit | how many calls per period | a 429 response |
| Timeout | how long you will wait | long-running work |
| Retry | calling again after failure | careful with duplicate POST |
| Version | the v1 in /api/v1 | the shape changes, the old one stays |
No. Only holders of a key can call it. But the key is the door, so key handling is the security question — see Accounts, passwords, API keys, permissions.
Something has to do the calling, yes. These days that something is often an agent writing the code, and MCP standardises the connection outright.
1. How do endpoints and methods relate?
The combination is the function. The same /tasks reads with GET and
creates with POST.
2. Why issue one API key per purpose?
So a leak costs you only that key. Which is also why each needs a recognisable name.
3. Is an SDK something other than an API?
It is a toolbox for calling the same API — URL building, headers and parsing wrapped up per language.
Now see all of it with your own eyes → Take one request apart
HyperTeams{ "id": "task_9f2", "status": "running", "prompt": "Summarise last week's returns data"}Authorization: Bearer sk_live_a1b2c3…by hand build the URL → attach headers → parse the JSON responseSDK client.tasks.create("…")□ The same job every day → a schedule calls it instead of a person clicking□ Another system needs it → the intranet or a Slack bot fetches it directly□ There are many of them → nobody clicks 300 times□ It has to be on the record → who called what is in the log