The API
Everything the site shows can be read as JSON. Access is free, but goes through a token tied to a confirmed account.
Why a token
An API open to anyone without an account is an open door to bots that submit a thousand projects or vote in a loop. The token ties every call to a confirmed address: one vote stays one vote per person, and the load stays reasonable.
Getting a token
- Sign in with your email address: you receive a six-digit code by email, no password.
- In My account, create a token. It is shown only once; we keep only a hash of it.
- Send it with every request:
Authorization: Bearer maub_…
Up to 5 tokens per account, revocable at any time.
600 calls per hour per account, and
5 contributions per hour. Beyond that, the response is
429 with a Retry-After header. Without a valid token:
401.
The API returns the directory's original French text. Project, theme and need objects, and
a need's steps, also carry a traductions field holding the English version when
there is one.
Reading
| Request | Returns |
|---|---|
GET /api/moi | your account, to check a token |
GET /api/themes | the directory's themes |
GET /api/projets | published projects. Filters theme, q, mis_en_avant; tri=une|votes|recents |
GET /api/projets/{slug} | a project's full entry |
GET /api/besoins | public needs. theme, tri=soutiens|recents |
GET /api/besoins/{slug} | a need, its status, its supporters and its work in progress |
GET /api/articles | the articles |
GET /api/articles/{slug} | an article, rendered as HTML |
A need's work in progress
A need under study or in development has a work space (chantier), and keeps it
once delivered. Needs carry it in the fields below; while chantier is
false, they are empty.
| Field | Content |
|---|---|
chantier | true once the work space is open, even before anything is written in it |
cahier | the brief, as plain text; null until it is written |
roles | the skills wanted, among code, donnees (data) and terrain (field work) |
depot | the code repository's address, once it exists |
etapes | the steps, oldest first: jour (YYYY-MM-DD), titre, texte, traductions |
traductions | the English version of the brief: {"en": {"cahier": "…"}} |
Who supports a need and who receives its steps by email stays private: the API only gives
their number, nb_soutiens.
Taking part
| Request | Effect |
|---|---|
POST /api/projets | suggests a project, published after review |
PUT /api/projets/{slug}/vote | votes for a project. One vote per account: repeating it changes nothing |
DELETE /api/projets/{slug}/vote | removes your vote |
POST /api/besoins | describes a need, published after review |
PUT /api/besoins/{slug}/soutien | supports a need, once per account |
DELETE /api/besoins/{slug}/soutien | removes your support |
Examples
export MAUB_JETON=maub_…
curl -s -H "Authorization: Bearer $MAUB_JETON" \
"https://maub.subalpine.it/api/projets?theme=biodiversite&tri=votes"
curl -s -X PUT -H "Authorization: Bearer $MAUB_JETON" \
https://maub.subalpine.it/api/projets/plantnet/vote
curl -s -X POST -H "Authorization: Bearer $MAUB_JETON" \
-H 'Content-Type: application/json' \
-d '{"titre": "Map drinking water points", "description": "…", "theme": "sante"}' \
https://maub.subalpine.it/api/besoinsThe full schema is published in OpenAPI format:
/api/openapi.json. Published data can be reused
freely, with credit to MAUB.
Atom feeds
To follow what gets published without a token or an account, add one of these Atom feeds to a feed reader or a monitoring tool:
/en/flux/articles.xml: the articles, in full;/en/flux/projets.xml: recently published projects, with the role of AI and their AI label.
The French versions are at /flux/.