# API Overview

> The run API your server or page calls, how it authenticates, and what its limits answer

The run API is how your own server or interface starts and talks to runs of a **published**
loop. Every path begins with `/api` on `https://plutonium.io`. A loop is named by its **public
id** (`pl_…`), shown on the loop's **Keys** tab once the loop is published.

## Authentication

Every call carries one header:

```
Authorization: Bearer <credential>
```

The credential is one of two things. A console session cookie is refused on the run routes.

- **An API key** (`rk_…`) for your server. An owner mints it on the loop's **Keys** tab
  (`POST /api/loops/{loopId}/keys`) with one or more scopes: `create_runs`, `read_runs` and
  `read_collections`. The key text is shown once and cannot be shown again; revoke it and mint
  another if it is lost. A key's scopes must be ones the loop's delivery allows. A
  `read_collections` key names the API it serves: choose it under **Serves** on the loop's **Keys**
  tab, press the **Mint a key for** button in the API's detail on **Schedules**, or send `claim_name` when
  you mint it through the API.
- **A user token** for one of your users, minted by one of the loop's
  [identity doors](/docs/api/identity.md). The loop's identity scheme decides which door it has.

## Limits

Routes are rate limited, and a refused request answers `429 Too Many Requests` with a sentence
that names which limit and a `Retry-After` header with the seconds to wait. There are several:

- **Each route's own limit**, per account and across all callers.
- **The loop's per-address limit**, on the identity doors and on starting a run.
- **The loop's per-subject run cap and its concurrent-run cap**, on starting a run.

A route that spends money refuses with `503` rather than let a request through when its limit
cannot be checked.

## The reference

- [Identity](/docs/api/identity.md): the doors that mint a user token, and your own OpenID issuer.
- [Runs](/docs/api/runs.md): start a run, read it, talk to it, follow it.
- [Search](/docs/api/search.md): search your indexes with a search key, or what a loop searches.
- [Collections](/docs/api/collections.md): read a collection's records from your server.
- [Webhooks](/docs/api/webhooks.md): start a run with a signed request, and receive a loop's outputs.
