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
POST	/{id}/steps	Ajouter une etape a une decision	Oui

Votes (/api/v1/votes)

Methode	Endpoint	Description	Auth
POST	/sessions	Creer une session de vote	Oui
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

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

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
GET	/formulas	Lister les configurations de formules	Non
POST	/formulas	Creer une configuration de formule	Oui

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.

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).