decision/docs/content/dev/3.api-reference.md

title, description

title	description
Reference API	Liste des endpoints de l'API Glibredecision

Reference API

Tous les endpoints sont prefixes par /api/v1. L'API est auto-documentee via OpenAPI/Swagger a l'adresse /docs en mode debug.

Authentification (/api/v1/auth)

Methode	Endpoint	Description	Auth
POST	/challenge	Generer un challenge Ed25519 pour une adresse Duniter	Non
POST	/verify	Verifier la signature du challenge et obtenir un token	Non
GET	/me	Retourner l'identite authentifiee courante	Oui
POST	/logout	Invalider la session courante	Oui

Documents (/api/v1/documents)

Methode	Endpoint	Description	Auth
GET	/	Lister les documents (filtres: doc_type, status)	Non
POST	/	Creer un nouveau document	Oui
GET	/{slug}	Obtenir un document par son slug	Non
PUT	/{slug}	Mettre a jour un document	Oui
POST	/{slug}/items	Ajouter un item au document	Oui
GET	/{slug}/items	Lister les items d'un document	Non
GET	/{slug}/items/{item_id}	Obtenir un item avec son historique	Non
PUT	/{slug}/items/{item_id}	Mettre a jour un item (titre, texte, position, type)	Oui
DELETE	/{slug}/items/{item_id}	Supprimer un item du document	Oui
POST	/{slug}/items/{item_id}/versions	Proposer une nouvelle version d'un item	Oui
GET	/{slug}/items/{item_id}/versions	Lister les versions d'un item	Non
PUT	/{slug}/items/{item_id}/versions/{version_id}/accept	Accepter une version proposee (applique le texte a l'item)	Oui
PUT	/{slug}/items/{item_id}/versions/{version_id}/reject	Rejeter une version proposee	Oui
PUT	/{slug}/items/reorder	Reordonner les items d'un document	Oui
POST	/{slug}/archive	Archiver le document dans le sanctuaire (hash SHA-256 + IPFS + on-chain)	Oui

Decisions (/api/v1/decisions)

Methode	Endpoint	Description	Auth
GET	/	Lister les decisions (filtres: decision_type, status)	Non
POST	/	Creer une nouvelle decision	Oui
GET	/{id}	Obtenir une decision avec ses etapes	Non
PUT	/{id}	Mettre a jour une decision	Oui
DELETE	/{id}	Supprimer une decision (brouillon uniquement)	Oui
POST	/{id}/steps	Ajouter une etape a une decision	Oui
POST	/{id}/advance	Avancer la decision a l'etape suivante	Oui
POST	/{id}/steps/{step_id}/create-vote-session	Creer une session de vote pour une etape	Oui

Votes (/api/v1/votes)

Methode	Endpoint	Description	Auth
POST	/sessions	Creer une session de vote	Oui
GET	/sessions	Lister les sessions de vote (filtres: status, protocol_id, decision_id)	Non
GET	/sessions/{id}	Obtenir une session de vote	Non
POST	/sessions/{id}/vote	Soumettre un vote (signe)	Oui
GET	/sessions/{id}/votes	Lister les votes d'une session	Non
GET	/sessions/{id}/result	Calculer et retourner le resultat courant	Non
POST	/sessions/{id}/close	Cloturer la session et calculer le resultat final	Oui
GET	/sessions/{id}/threshold	Obtenir le detail du calcul de seuil (formule, parametres, valeurs intermediaires)	Non
POST	/sessions/{id}/tally	Forcer un recomptage des votes et recalcul du seuil	Oui

Mandats (/api/v1/mandates)

Methode	Endpoint	Description	Auth
GET	/	Lister les mandats (filtres: mandate_type, status)	Non
POST	/	Creer un nouveau mandat	Oui
GET	/{id}	Obtenir un mandat avec ses etapes	Non
PUT	/{id}	Mettre a jour un mandat	Oui
DELETE	/{id}	Supprimer un mandat (brouillon uniquement)	Oui
POST	/{id}/steps	Ajouter une etape a un mandat	Oui
GET	/{id}/steps	Lister les etapes d'un mandat	Non
POST	/{id}/advance	Avancer le mandat a l'etape suivante	Oui
POST	/{id}/assign	Assigner un mandataire au mandat	Oui
POST	/{id}/revoke	Revoquer un mandat actif	Oui
POST	/{id}/steps/{step_id}/create-vote-session	Creer une session de vote pour une etape	Oui

Protocoles (/api/v1/protocols)

Methode	Endpoint	Description	Auth
GET	/	Lister les protocoles de vote	Non
POST	/	Creer un protocole de vote	Oui
GET	/{id}	Obtenir un protocole avec sa configuration formule	Non
PUT	/{id}	Mettre a jour un protocole (meta-gouvernance)	Oui
GET	/formulas	Lister les configurations de formules	Non
POST	/formulas	Creer une configuration de formule	Oui
GET	/formulas/{id}	Obtenir une configuration de formule par son ID	Non
PUT	/formulas/{id}	Mettre a jour une configuration de formule (meta-gouvernance)	Oui
POST	/simulate	Simuler le calcul d'une formule avec des parametres arbitraires	Non

Sanctuaire (/api/v1/sanctuary)

Methode	Endpoint	Description	Auth
GET	/	Lister les entrees du sanctuaire (filtre: entry_type)	Non
GET	/{id}	Obtenir une entree du sanctuaire	Non
POST	/	Creer une entree (hash SHA-256, CID IPFS, TX on-chain)	Oui
GET	/{id}/verify	Verifier l'integrite d'une entree (recalcul SHA-256, verification IPFS et on-chain)	Non
GET	/by-reference/{reference_id}	Obtenir les entrees liees a une entite source par son UUID	Non

WebSocket (/api/v1/ws)

Endpoint	Description
/ws	Connexion WebSocket pour notifications temps reel (votes, decisions)

Sante

Methode	Endpoint	Description
GET	/api/health	Verification de sante (hors versionning)

Details des endpoints Sprint 2

PUT /api/v1/documents/{slug}/items/{item_id} -- Mettre a jour un item

Met a jour les champs d'un item existant (titre, texte courant, position, type). Seuls les champs fournis sont mis a jour (mise a jour partielle).

Corps de la requete (tous les champs sont optionnels) :

{
  "title": "Nouveau titre",
  "current_text": "Texte mis a jour...",
  "position": "2.1",
  "item_type": "rule"
}

Reponse : 200 OK avec l'item mis a jour (DocumentItemOut).

---

DELETE /api/v1/documents/{slug}/items/{item_id} -- Supprimer un item

Supprime un item d'un document. La suppression est en cascade : toutes les versions associees sont egalement supprimees.

Reponse : 204 No Content.

---

GET /api/v1/documents/{slug}/items/{item_id}/versions -- Lister les versions d'un item

Retourne l'historique complet des versions proposees pour un item, ordonne par date de creation decroissante.

Parametres de requete : skip, limit (pagination standard).

Reponse : 200 OK avec une liste de ItemVersionOut.

---

PUT /api/v1/documents/{slug}/items/{item_id}/versions/{version_id}/accept -- Accepter une version

Accepte une version proposee. Le texte propose remplace le texte courant de l'item. Toutes les autres versions en statut proposed ou voting pour cet item sont automatiquement rejetees.

Reponse : 200 OK avec la version mise a jour (ItemVersionOut, statut accepted).

---

PUT /api/v1/documents/{slug}/items/{item_id}/versions/{version_id}/reject -- Rejeter une version

Rejette une version proposee. Le texte courant de l'item reste inchange.

Reponse : 200 OK avec la version mise a jour (ItemVersionOut, statut rejected).

---

PUT /api/v1/documents/{slug}/items/reorder -- Reordonner les items

Modifie l'ordre d'affichage des items dans un document en mettant a jour le champ sort_order de chaque item.

Corps de la requete :

{
  "items": [
    { "item_id": "uuid-1", "sort_order": 0 },
    { "item_id": "uuid-2", "sort_order": 1 },
    { "item_id": "uuid-3", "sort_order": 2 }
  ]
}

Reponse : 200 OK avec la liste des items reordonnes.

---

POST /api/v1/documents/{slug}/archive -- Archiver un document

Archive le document complet dans le sanctuaire. Le processus :

1. Le contenu integral du document (metadonnees + items) est serialise.
2. Un hash SHA-256 est calcule sur le contenu.
3. Le contenu est envoye sur IPFS (CID retourne).
4. Le hash est ancre on-chain via system.remark sur Duniter V2.
5. Une entree sanctuary_entries est creee avec les references.
6. Le statut du document passe a archived et les champs ipfs_cid et chain_anchor sont mis a jour.

Reponse : 200 OK avec le document mis a jour incluant ipfs_cid et chain_anchor.

---

GET /api/v1/sanctuary/{id}/verify -- Verifier l'integrite d'une entree

Verifie l'integrite d'une entree du sanctuaire en effectuant trois controles :

1. Hash SHA-256 : recalcul du hash a partir du contenu source et comparaison avec content_hash.
2. IPFS : verification que le CID IPFS pointe vers un contenu valide (si disponible).
3. On-chain : verification que le hash est present dans le system.remark du bloc reference (si disponible).

Reponse :

{
  "entry_id": "uuid",
  "hash_valid": true,
  "ipfs_valid": true,
  "chain_valid": true,
  "verified_at": "2026-02-28T12:00:00Z",
  "details": "Tous les controles sont valides."
}

---

GET /api/v1/sanctuary/by-reference/{reference_id} -- Entrees par reference

Retourne toutes les entrees du sanctuaire liees a une entite source (document, decision ou session de vote) identifiee par son UUID.

Parametres de requete : skip, limit (pagination standard).

Reponse : 200 OK avec une liste de SanctuaryEntryOut.

Details des endpoints Sprint 3

GET /api/v1/votes/sessions -- Lister les sessions de vote

Retourne la liste des sessions de vote avec pagination et filtres optionnels.

Parametres de requete :

Parametre	Type	Description
status	string	Filtrer par statut (open, closed, draft)
protocol_id	uuid	Filtrer par protocole de vote
decision_id	uuid	Filtrer par decision associee
skip	int	Offset de pagination (defaut 0)
limit	int	Nombre max de resultats (defaut 50, max 200)

Reponse : 200 OK avec une liste de VoteSessionOut.

---

POST /api/v1/votes/sessions/{id}/close -- Cloturer une session

Cloture une session de vote ouverte et calcule le resultat final. Le calcul inclut la formule WoT, les criteres Smith et TechComm le cas echeant. La session passe au statut closed et le resultat est fige.

Preconditions :

• La session doit etre au statut open.
• L'utilisateur doit etre le createur de la session ou un membre du Comite Technique.

Reponse :

{
  "session_id": "uuid",
  "status": "closed",
  "closed_at": "2026-02-28T12:00:00Z",
  "result": {
    "votes_for": 97,
    "votes_against": 23,
    "total_votes": 120,
    "wot_size": 7224,
    "threshold": 94,
    "adopted": true,
    "smith_threshold": 2,
    "smith_votes_for": 5,
    "smith_met": true,
    "techcomm_threshold": null,
    "techcomm_votes_for": null,
    "techcomm_met": null
  }
}

---

GET /api/v1/votes/sessions/{id}/threshold -- Detail du calcul de seuil

Retourne le detail complet du calcul de seuil pour une session de vote, incluant les valeurs intermediaires de la formule. Utile pour la transparence et le debug.

Reponse :

{
  "session_id": "uuid",
  "formula_config_id": "uuid",
  "mode_params": "D30M50B.1G.2",
  "parameters": {
    "constant_base": 0.0,
    "base_exponent": 0.1,
    "majority_pct": 50,
    "gradient_exponent": 0.2,
    "smith_exponent": null,
    "techcomm_exponent": null
  },
  "inputs": {
    "wot_size": 7224,
    "total_votes": 120,
    "smith_wot_size": 20,
    "techcomm_size": 5
  },
  "computation": {
    "base_term": 7.943e-08,
    "participation_ratio": 0.0166,
    "participation_ratio_powered": 0.4217,
    "inertia_factor": 0.7892,
    "effective_threshold": 94.70,
    "threshold_ceiled": 95,
    "threshold_final": 94
  },
  "criteria": {
    "smith_threshold": null,
    "techcomm_threshold": null
  }
}

---

POST /api/v1/votes/sessions/{id}/tally -- Forcer un recomptage

Force le recalcul du decompte des votes et du seuil pour une session. Utile si des votes ont ete invalides manuellement ou si la taille WoT a ete corrigee.

Preconditions :

• L'utilisateur doit etre le createur de la session ou un membre du Comite Technique.

Corps de la requete (optionnel) :

{
  "wot_size_override": 7250,
  "smith_wot_size_override": null,
  "techcomm_size_override": null
}

Si aucun corps n'est fourni, les tailles sont reprises du snapshot initial.

Reponse : 200 OK avec le meme format que le resultat de cloture.

---

PUT /api/v1/protocols/{id} -- Mettre a jour un protocole

Met a jour un protocole de vote existant. Les modifications de protocoles actifs (utilises par des sessions ouvertes) sont soumises a meta-gouvernance : une session de vote doit d'abord valider la modification.

Corps de la requete (champs optionnels) :

{
  "name": "Nouveau nom du protocole",
  "description": "Description mise a jour",
  "vote_type": "nuanced",
  "duration_days": 60,
  "formula_config_id": "uuid-de-la-nouvelle-formule"
}

Reponse : 200 OK avec le protocole mis a jour (ProtocolOut).

Code 409 : Si le protocole est utilise par une session ouverte et qu'aucune validation meta-gouvernance n'est fournie.

---

GET /api/v1/protocols/formulas/{id} -- Obtenir une formule

Retourne une configuration de formule par son identifiant, incluant tous les parametres et le mode_params encode.

Reponse : 200 OK avec un FormulaConfigOut.

---

PUT /api/v1/protocols/formulas/{id} -- Mettre a jour une formule

Met a jour une configuration de formule existante. Comme pour les protocoles, les formules actives sont protegees par la meta-gouvernance.

Corps de la requete (champs optionnels) :

{
  "name": "Configuration amendee",
  "majority_pct": 66,
  "base_exponent": 0.05,
  "gradient_exponent": 0.3,
  "constant_base": 0.0,
  "smith_exponent": 0.1,
  "techcomm_exponent": 0.1,
  "ratio_multiplier": null,
  "is_ratio_mode": false
}

Le champ mode_params est recalcule automatiquement a partir des valeurs fournies.

Reponse : 200 OK avec la formule mise a jour (FormulaConfigOut).

Code 409 : Si la formule est liee a un protocole actif sans validation meta-gouvernance.

---

POST /api/v1/protocols/simulate -- Simuler une formule

Simule le calcul de seuil d'une formule avec des parametres arbitraires, sans creer ni modifier aucune donnee. Endpoint ouvert (pas d'authentification requise) pour permettre l'experimentation.

Corps de la requete :

{
  "wot_size": 7224,
  "total_votes": 120,
  "majority_pct": 50,
  "base_exponent": 0.1,
  "gradient_exponent": 0.2,
  "constant_base": 0.0,
  "smith_wot_size": 20,
  "smith_exponent": 0.1,
  "techcomm_size": 5,
  "techcomm_exponent": 0.1,
  "votes_for": 97
}

Reponse :

{
  "threshold": 94,
  "inertia_factor": 0.7892,
  "participation_ratio": 0.0166,
  "base_term": 7.943e-08,
  "smith_threshold": 2,
  "techcomm_threshold": 2,
  "adopted": true,
  "details": {
    "wot_threshold_met": true,
    "smith_met": true,
    "techcomm_met": true
  }
}

Details des endpoints Sprint 4

POST /api/v1/decisions/{id}/advance -- Avancer une decision

Avance une decision a l'etape suivante de son workflow. Complete l'etape active courante et active la prochaine etape en attente. Si toutes les etapes sont terminees, le statut global de la decision avance au statut suivant dans le cycle de vie (draft -> qualification -> review -> voting -> executed -> closed).

Comportement :

• S'il y a une etape active : elle passe a completed, la prochaine etape pending est activee.
• S'il n'y a pas d'etape active : la premiere etape pending est activee. Si la decision est en draft, elle passe a qualification.
• Si toutes les etapes sont terminees : le statut global avance.

Preconditions :

• La decision ne doit pas etre au statut closed.
• L'utilisateur doit etre authentifie.

Reponse : 200 OK avec un DecisionAdvanceOut :

{
  "id": "uuid",
  "title": "Runtime upgrade v3.2.0",
  "description": "...",
  "context": "...",
  "decision_type": "runtime_upgrade",
  "status": "review",
  "voting_protocol_id": "uuid",
  "created_by_id": "uuid",
  "created_at": "2026-02-28T10:00:00Z",
  "updated_at": "2026-02-28T12:00:00Z",
  "steps": [
    {"id": "uuid", "step_order": 0, "step_type": "qualification", "status": "completed", "...": "..."},
    {"id": "uuid", "step_order": 1, "step_type": "review", "status": "active", "...": "..."},
    {"id": "uuid", "step_order": 2, "step_type": "vote", "status": "pending", "...": "..."}
  ],
  "message": "Etape 'Qualification' completee. Etape 'Examen' activee."
}

Code 400 : Si la decision est deja cloturee ou qu'aucun avancement n'est possible.

---

DELETE /api/v1/decisions/{id} -- Supprimer une decision

Supprime une decision. La suppression n'est autorisee que si la decision est au statut draft. Les etapes associees sont supprimees en cascade.

Preconditions :

• La decision doit etre au statut draft.
• L'utilisateur doit etre authentifie.

Reponse : 204 No Content.

Code 400 : Si la decision n'est pas au statut draft.

---

POST /api/v1/decisions/{id}/steps/{step_id}/create-vote-session -- Creer une session de vote pour une etape de decision

Cree une session de vote liee a une etape specifique d'une decision. La session est configuree automatiquement a partir du protocole de vote de la decision.

Comportement :

1. Verifie que la decision et l'etape existent.
2. Verifie que l'etape est de type vote et au statut active.
3. Cree une session de vote avec le protocole de la decision.
4. Fait un snapshot des tailles WoT, Smith et TechComm.
5. Calcule la date de fin a partir de la duree de la formule.
6. Rattache la session a l'etape via vote_session_id.

Reponse : 201 Created avec un VoteSessionOut.

Code 400 : Si l'etape n'est pas de type vote, n'est pas active, ou si une session est deja liee.

---

POST /api/v1/mandates/{id}/advance -- Avancer un mandat

Avance un mandat a l'etape suivante de son workflow. Fonctionne de maniere identique a l'avancement des decisions, avec le cycle de vie specifique aux mandats (draft -> candidacy -> voting -> active -> reporting -> completed).

Comportement :

• S'il y a une etape active : elle passe a completed, la prochaine etape pending est activee.
• S'il n'y a pas d'etape active : la premiere etape pending est activee. Si le mandat est en draft, il passe a candidacy.
• Si toutes les etapes sont terminees : le statut global avance.

Preconditions :

• Le mandat ne doit pas etre au statut completed ou revoked.
• L'utilisateur doit etre authentifie.

Reponse : 200 OK avec un MandateAdvanceOut :

{
  "id": "uuid",
  "title": "Membre Comite Technique 2026",
  "description": "...",
  "mandate_type": "techcomm",
  "status": "candidacy",
  "mandatee_id": null,
  "decision_id": null,
  "starts_at": null,
  "ends_at": null,
  "created_at": "2026-02-28T10:00:00Z",
  "updated_at": "2026-02-28T12:00:00Z",
  "steps": [
    {"id": "uuid", "step_order": 0, "step_type": "formulation", "status": "completed", "...": "..."},
    {"id": "uuid", "step_order": 1, "step_type": "candidacy", "status": "active", "...": "..."}
  ],
  "message": "Etape 'Formulation' completee. Etape 'Candidature' activee."
}

Code 400 : Si le mandat est deja en statut terminal (completed ou revoked).

---

POST /api/v1/mandates/{id}/assign -- Assigner un mandataire

Assigne un mandataire (membre elu) a un mandat apres un vote reussi.

Corps de la requete :

{
  "mandatee_id": "uuid-de-l-identite-duniter"
}

Comportement :

1. Verifie que le mandat existe et qu'il est dans un statut permettant l'assignation.
2. Definit le mandatee_id du mandat.
3. Le mandat peut ensuite etre avance vers le statut active.

Preconditions :

• L'utilisateur doit etre authentifie.
• Le mandatee_id doit correspondre a une identite Duniter existante.

Reponse : 200 OK avec un MandateOut mis a jour.

Code 404 : Si le mandat ou l'identite Duniter n'existe pas.

---

POST /api/v1/mandates/{id}/revoke -- Revoquer un mandat

Revoque un mandat actif de maniere anticipee. Le statut du mandat passe directement a revoked, mettant fin aux responsabilites du mandataire.

Preconditions :

• Le mandat doit etre au statut active ou reporting.
• L'utilisateur doit etre authentifie.

Reponse : 200 OK avec un MandateOut mis a jour (statut revoked).

Code 400 : Si le mandat n'est pas dans un statut permettant la revocation.

---

POST /api/v1/mandates/{id}/steps/{step_id}/create-vote-session -- Creer une session de vote pour une etape de mandat

Cree une session de vote liee a une etape specifique d'un mandat. Fonctionne de maniere identique a la creation de session pour les decisions.

Comportement :

1. Verifie que le mandat et l'etape existent.
2. Verifie que l'etape est de type vote et au statut active.
3. Cree une session de vote avec le protocole associe.
4. Fait un snapshot des tailles WoT, Smith et TechComm.
5. Calcule la date de fin a partir de la duree de la formule.
6. Rattache la session a l'etape via vote_session_id.

Reponse : 201 Created avec un VoteSessionOut.

Code 400 : Si l'etape n'est pas de type vote, n'est pas active, ou si une session est deja liee.

---

Pagination

Les endpoints de liste acceptent les parametres skip (offset, defaut 0) et limit (max 200, defaut 50).

Authentification

Les endpoints marques "Oui" dans la colonne Auth requierent un header :

Authorization: Bearer <token>

Le token est obtenu via le flux challenge-response (/auth/challenge puis /auth/verify).