# API

The API is at `https://api.usejinn.com/v1`. It takes and returns JSON. The [OpenAPI document](/openapi.json) describes every route and field.

## Keys

Send an account key as a bearer token:

```sh
curl https://api.usejinn.com/v1/functions -H "Authorization: Bearer $JINN_KEY"
```

An owner makes keys in the console, under **Account**. `jinn login` makes one for the CLI. A key belongs to one account and shows once. An owner can revoke it at any time, and it stops at once.

| Scope | What it can do |
|---|---|
| `admin` | Everything in the account's functions, providers and runs. |
| `run` | Upload files, start the functions it names, and read their runs. |

Use a `run` key in services that only start runs.

## Routes

| Route | What it does |
|---|---|
| `POST /v1/files` | Start an upload: send `bytes` and `sha256`, then `PUT` the file to the returned `url` with the returned `headers`. |
| `GET /v1/bases` | List the bases. |
| `GET /v1/functions` | List functions, each with its latest definition and last run. |
| `POST /v1/functions` | Make a function and its first version: `name` and a definition. |
| `GET /v1/functions/{id}` | A function and its versions. |
| `POST /v1/functions/{id}/versions` | Publish the next version. |
| `POST /v1/functions/{id}/runs` | Start a run. |
| `GET /v1/runs` | List runs, newest first. Filter with `function` and `state` (`active`, `succeeded`, `failed`). Page with `before` (the `next` of the last page). |
| `GET /v1/runs/{id}` | Read a run. |
| `GET /v1/runs/{id}/log` | Links to the run's log parts. |
| `GET /v1/providers` | List providers and their versions. |
| `POST /v1/providers` | Make a provider: `name`, `model` and `key`. |
| `POST /v1/providers/{id}/versions` | Publish a provider's next version. |
| `POST /v1/catalog` | List the models a vendor key can use. |
| `GET /v1/webhooks/public-key` | The account's webhook public key. |

The console uses the same API with a person's sign-in. Routes for members, invites, keys and credit take a person's sign-in, not a key.

## Errors

An error has a status and a JSON body: `{"error": "what went wrong"}`.

| Status | Meaning |
|---|---|
| `400` | The request is not valid. The error says which field. |
| `401` | No key, or the key is wrong or revoked. |
| `402` | The account has no credit. |
| `403` | The key cannot do this, or the account is suspended. |
| `404` | No such resource in this account. |
| `409` | Two writes met. Try again. |
| `429` | The account's runs would pass its memory limit. |