# Getting started

The SmaCH API serves artworks, their monitorings, the events those monitorings record, the
equipment that records them, and the organizations that own all of it. Every path below is
relative to `https://api.smach.science`.

## 1. Sign in

Every call carries a bearer token from the SmaCH identity provider. To try the API from
this portal, sign in with the button at the top right with your SmaCH account, then pick
**My account** in the playground of any operation.

## 2. First call

```bash
curl -s "https://api.smach.science/artworks?size=10" \
  -H "Authorization: Bearer $TOKEN"
```

An account that belongs to one organization needs nothing more. An account that belongs to
several names the one it works on: `X-Organization: bayeux`.

## 3. Lists

Every list takes `page` (from 0), `size` (at most 200), `search` and `sort` (`-created`
for descending). The total is in the `X-Total-Count` header, and the `Link` header gives
the next page, relative to the current address:

```http
X-Total-Count: 57
Link: <?page=1&size=10>; rel="next"
```

Stop when there is no `rel="next"`.

## 4. Errors

Errors are `application/problem+json`:

```json
{ "type": "about:blank", "title": "Forbidden", "status": 403,
  "detail": "Access denied to organization: bayeux" }
```

| Status | Meaning | What to do |
|---|---|---|
| 400 | A parameter is invalid, `detail` says which | Fix the request |
| 401 | No token, or an expired one | Get a new token |
| 403 | The account does not reach this organization or this action | Check its organization and role |
| 404 | No such resource in this organization | |
| 409 | The resource is in use, or the identifier is taken | Read `detail` |

## 5. Versions

The addresses carry no version number. The API changes without breaking what already
calls it: a field is never removed and a parameter never becomes required within a
version. If a breaking change ever becomes necessary, a client chooses its version with
the `Api-Version` header. Without it, a request gets version 1.