# ReCoDanse — API des applications tierces

> Les studios, organisateurs, développeurs et assistants se branchent sur ReCoDanse avec OAuth 2.0 / OpenID Connect.

Ce fichier n'est pas le contrat : il dit où le trouver, et ce qu'il faut savoir avant de le lire.

- Contrat OpenAPI : https://api.recodanse.fr/portail/openapi-tiers.yaml
- Découverte OpenID : https://connexion.recodanse.fr/.well-known/openid-configuration
- Mes applications (déclarer, garder son secret, copier le prompt pour son agent de code) : https://recodanse.fr/developpeur
- Cette documentation en Markdown : https://recodanse.fr/agents/portail.md
- Les conditions des développeurs en Markdown : https://recodanse.fr/developpeur/conditions.md
- Ressource protégée (RFC 9728) : https://api.recodanse.fr/.well-known/oauth-protected-resource
- Serveur MCP : https://api.recodanse.fr/mcp
- Bac à sable (rien n'y est réel, tout s'efface ; répondre « en tant que » un compte fictif) : https://bac-a-sable.recodanse.fr, émetteur https://connexion.bac-a-sable.recodanse.fr

## Portées

- openid : Identifiant OpenID Connect : `sub` est un pseudonyme STABLE et PROPRE à l'application.
- profile : Revendications `name` (prénom et initiale publics) et `preferred_username` (le @nom, sans arobase). (webhook d'effacement exigé)
- email : Revendications `email` et `email_verified` (vrai seulement si ReCoDanse a vérifié l'adresse). (webhook d'effacement exigé)
- offline_access : Délivre un jeton de rafraîchissement ; retiré dès que la personne retire l'application. (webhook d'effacement exigé)
- videos.lire : Lecture des MÉTADONNÉES des vidéos du compte (galerie, qualification, carnets). Aucun octet vidéo, aucune adresse de lecture. (webhook d'effacement exigé)
- videos.ranger : Écriture de la qualification des vidéos du compte (carnets de profs, de lieux, d'événements ; étiquettes). Ne supprime rien, ne partage rien, ne rattache à aucun cours.
- videos.deposer : Dépôt de fichiers vidéo dans la bibliothèque du compte, par la même porte que l'app : fiche, dépôt signé (en parts au-delà de 8 Mio), confirmation. Mêmes bornes, même quota, même revue ; aucune adresse de lecture ne revient.
- videos.annoter : Fusion du travail d'une vidéo du compte (séquences, explications, passages nommés) : additive, rien ne s'efface.
- programmes.poser : Pose d'un programme au carnet du compte, relu comme celui de l'app, marqué « posé par » l'application ; elle ne remplace que le sien, tant qu'aucun jour n'est fini.
- evenements.publier : Compte de service : publier, corriger et retirer les événements de SON propriétaire.
- creneaux.publier : Compte de service : publier, corriger et retirer les créneaux de SON propriétaire.

Sans webhook d'effacement (une app de téléphone, une page sans serveur) : openid et les écritures seulement ; la revue refuse le reste en 409 portee_sans_webhook_d_effacement.

## Les mots (chez nous → en anglais → Schema.org → chez les voisins)

Contexte JSON-LD (nos clés → Schema.org, à appliquer à nos objets) : https://recodanse.fr/contexte/v1.jsonld

- evenement → event → DanceEvent → event (Billetweb, Eventbrite, Weezevent)
- espece → event type → @type (+ rc:espece) → category
- titre → title → name → name
- debut → start → startDate → start / date_start
- fin → end → endDate → end / date_end
- lieu → venue → location → Place · SportsActivityLocation → venue
- danses → dance styles → about → DefinedTerm → tags
- prix_indicatif → indicative price → offers.description → price
- lien_billetterie → ticket link → offers.url → ticket url
- annule → cancelled → eventStatus = EventCancelled → status: canceled
- creneau → class slot → CourseInstance + Offer → session / class (bsport, Mindbody)
- capacite → capacity → maximumAttendeeCapacity → capacity
- niveau → level → rc:niveauVise → level
- tranche → price tier → UnitPriceSpecification → ticket class / tarif
- video → video → VideoObject → —
- duree_s → duration (seconds) → duration → —
- application → app → SoftwareApplication → app
- portees → scopes → — → scopes
- webhook → webhook → — → webhook / notification
- espace → course → Course → —
- CoDanse → social dance event → DanceEvent + rc:CoDanse → —
- inscrit → attendee → EventReservation → attendee / participant

## Publier un agenda

- Une référence STABLE par soirée (l'UID de l'iCal) : republier la même référence corrige, en changer duplique.
- Ne pousser que ce qui change (une empreinte par référence) ; les 30 prochains jours ; jamais le passé.
- Une soirée annulée : PUT avec "annule": true (la fiche reste et dit « annulée »). DELETE est définitif : la référence ne se republie plus.
- Une soirée absente de ta liste n'est pas forcément annulée : ne pas l'annoncer annulée sur une absence.
- Pas encore là : ReCoDanse ne tire pas de flux déclaré, une soirée ne nomme pas la personne qui l'a proposée, le statut « vérifié » d'un compte ne se lit pas.

## Routes

- GET /.well-known/oauth-protected-resource — Métadonnées de la ressource (RFC 9728) — le point d'entrée de la découverte MCP
- GET /.well-known/oauth-protected-resource/mcp — Les mêmes métadonnées, sous la forme « par chemin » (RFC 9728 §3.1)
- POST /mcp — Le serveur MCP des vidéos (Streamable HTTP, sans état) — un message JSON-RPC 2.0 par requête
- GET /v1/applications — Tes applications, la plus récente d'abord
- POST /v1/applications — Déclarer une application — elle naît EN DÉVELOPPEMENT ; le `client_secret` se montre UNE fois
- GET /v1/applications/{id} — Une de tes applications
- PATCH /v1/applications/{id} — Corriger nom, description, site, portées, adresses de retour
- DELETE /v1/applications/{id} — Retirer une application — ses jetons cessent de valoir à l'instant
- POST /v1/applications/{id}/revue — Soumettre à la revue (developpement → en_revue) ; le fondateur relit chaque application
- POST /v1/applications/{id}/secret — Changer le secret (rotation) — l'ancien cesse de valoir à l'instant ; le nouveau se montre une fois
- GET /v1/applications/{id}/webhooks — Les webhooks d'une de tes applications (sans secret), le catalogue des événements, le plafond
- POST /v1/applications/{id}/webhooks — Poser un webhook — le secret `whsec_…` se montre UNE fois
- GET /v1/creneaux — Les créneaux publiés par CETTE application, par pages
- PUT /v1/creneaux/{reference} — Publier ou corriger un créneau et sa grille de prix — idempotent
- DELETE /v1/creneaux/{reference} — Retirer un créneau
- GET /v1/danses — Le vocabulaire des danses — les clés que `danses` attend (public, sans jeton)
- POST /v1/enregistrement — Enregistrer un agent (RFC 7591) — annoncé par la découverte de la porte (`registration_endpoint`)
- GET /v1/evenements — Les événements publiés par CETTE application (essais compris), par pages
- PUT /v1/evenements/{reference} — Publier ou corriger un événement — idempotent
- DELETE /v1/evenements/{reference} — Retirer un événement (il disparaît de l'agenda ; sa référence ne se republie pas)
- PUT /v1/programmes/{cle} — Poser un programme dans les entraînements de la personne (L238)
- POST /v1/videos — Déposer un fichier vidéo dans la bibliothèque de la personne — la fiche (L238)
- POST /v1/videos/{id}/depot — Demander le dépôt signé des octets (L238)
- POST /v1/videos/{id}/depot/confirmer — Confirmer le dépôt — le magasin a le dernier mot sur la taille et le type (L238)
- POST /v1/videos/{id}/travail/fusion — Poser des passages et des explications sur une vidéo — par fusion, rien ne s'efface (L238)
- DELETE /v1/webhooks/{id} — Retirer un webhook (son journal part avec lui)