Copy page

Guides

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

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

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

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

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.