# What an API is

> **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 counter for people, a counter for programs

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](/guide/it-data-formats) |
| 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.

## Endpoints — the individual counters

An API is usually several addresses. One such address is an endpoint. Taking the
list from [Driving work over REST](/guide/ht-rest-api):

| 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](/guide/it-http) plus the address is the function.** The same
`/tasks` reads with `GET` and creates with `POST`. `{id}` marks where a real
identifier goes.

## REST and JSON

Two words describe most of today's APIs.

- **REST** — the convention of "addresses are things, methods are actions". The
  table above is that shape.
- **JSON** — the notation for what is exchanged. Text, readable by people too.

```json
{
  "id": "task_9f2",
  "status": "running",
  "prompt": "Summarise last week's returns data"
}
```

How to read it continues in [Shapes of data](/guide/it-data-formats).

## The key

Screens have logins. APIs have **keys.**

```
Authorization: Bearer sk_live_a1b2c3…
```

| | 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](/guide/cn-api) insists on real names —
without them you **cannot tell which one to delete.**

## SDK — someone else's toolbox

Calling an API directly means building the URL, attaching headers and parsing
the response. An SDK (library) is that work pre-wrapped per language.

```
by hand   build the URL → attach headers → parse the JSON response
SDK       client.tasks.create("…")
```

**They do the same thing.** Which is how
[Your machine as a model server](/guide/ht-model-api) can say "change only the
base URL of the OpenAI SDK" — same counter shape, same toolbox.

## Why call an API when a screen exists

```
□ 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
```

**If the job is one case that needs human judgement, the screen is better.** APIs
are the tool for the opposite end.

## What you have to respect when calling

| 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 |

## Common misconceptions

### "Does opening an API expose our data?"

**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](/guide/it-accounts).

### "Does having an API mean I need a developer?"

Something has to do the calling, yes. These days that something is often an
agent writing the code, and [MCP](/guide/mcp-why-standard) standardises the
connection outright.

---

## Check yourself

**1. How do endpoints and methods relate?**

<details>
<summary>Answer</summary>

**The combination is the function.** The same `/tasks` reads with `GET` and
creates with `POST`.
</details>

**2. Why issue one API key per purpose?**

<details>
<summary>Answer</summary>

**So a leak costs you only that key.** Which is also why each needs a
recognisable name.
</details>

**3. Is an SDK something other than an API?**

<details>
<summary>Answer</summary>

**It is a toolbox for calling the same API** — URL building, headers and parsing
wrapped up per language.
</details>

---

Now see all of it with your own eyes →
[Take one request apart](/guide/it-try-http)