Contrat OpenAPI interactif
La référence consultable est générée depuis les tables de routes REST et d’authentification. Elle publie chaque opération publique prise en charge et exclut volontairement les routes d’administration, du port de modération, de fédération et des services internes. Téléchargez le document OpenAPI 3.1 pour générer du code, tester le contrat ou configurer un client API.
Une seule source de vérité
La CI régénère le contrat et échoue si le document commité diverge de la table de routes du serveur.
Conventions
Les endpoints REST utilisent https://beta.lyra.social/api/v1. L’authentification utilise https://beta.lyra.social/auth et le Gateway temps réel wss://beta.lyra.social/ws. Les requêtes et réponses sont en JSON sauf indication contraire.
{
"error": {
"code": "FORBIDDEN",
"message": "You do not have permission to perform this action"
}
}Surface d’intégration prise en charge
Cette référence couvre les endpoints destinés aux applications, bots et webhooks. Les endpoints internes du client web ne constituent pas un contrat tiers stable.
Ressources principales des SDK
Ces endpoints forment la surface REST stable utilisée par les ressources des SDK officiels. Leur accès reste soumis à l’appartenance aux communautés, aux rôles et aux permissions des salons.
| Méthode | Chemin | Fonction |
|---|---|---|
| GET | /users/@me | Lire l’identité authentifiée |
| GET | /users/:user_id | Lire un profil utilisateur public |
| GET | /users/@me/guilds | Lister les communautés rejointes |
| GET | /guilds/:guild_id | Lire une communauté |
| GET | /guilds/:guild_id/channels | Lister les salons visibles |
| GET | /channels/:channel_id | Lire un salon |
| GET | /channels/:channel_id/messages | Lister l’historique des messages |
| POST | /channels/:channel_id/messages | Envoyer un message |
| PATCH | /channels/:channel_id/messages/:message_id | Modifier un message possédé |
| DELETE | /channels/:channel_id/messages/:message_id | Supprimer un message possédé ou modéré |
| POST | /channels/:channel_id/typing | Publier un indicateur de saisie |
Applications et bots
| Méthode | Chemin | Authentification |
|---|---|---|
| GET | /applications | Propriétaire Bearer |
| POST | /applications | Propriétaire Bearer |
| GET | /applications/:app_id | Propriétaire Bearer |
| GET | /applications/:app_id/public | Public si public_bot est activé |
| PATCH | /applications/:app_id | Propriétaire Bearer |
| DELETE | /applications/:app_id | Propriétaire Bearer |
| GET | /applications/:app_id/bot | Propriétaire Bearer |
| PATCH | /applications/:app_id/bot | Propriétaire Bearer |
| POST | /applications/:app_id/bot/reset-token | Propriétaire Bearer |
| GET | /applications/:app_id/bot/invite-url | Propriétaire Bearer |
| POST | /guilds/:guild_id/bot-authorize | Bearer humain + MANAGE_GUILD |
Commandes et interactions
| Méthode | Chemin | Authentification |
|---|---|---|
| GET | /applications/:app_id/commands | Propriétaire Bearer |
| POST | /applications/:app_id/commands | Propriétaire Bearer |
| PUT | /applications/:app_id/commands | Propriétaire Bearer |
| DELETE | /applications/:app_id/commands/:cmd_id | Propriétaire Bearer |
| GET | /guilds/:guild_id/commands | Bearer ou Bot |
| GET | /guilds/:guild_id/commands/:app_id | Bearer ou Bot |
| PUT | /guilds/:guild_id/commands/:app_id | Propriétaire Bearer |
| POST | /interactions/:interaction_id/callback | Bot |
| POST | /interactions/modal-submit | Utilisateur Bearer |
Webhooks
| Méthode | Chemin | Authentification |
|---|---|---|
| GET | /guilds/:guild_id/webhooks | Bearer + permission |
| POST | /guilds/:guild_id/webhooks | Bearer + permission |
| GET | /webhooks/:webhook_id | Bearer + permission |
| PATCH | /webhooks/:webhook_id/:token | Jeton du webhook |
| DELETE | /webhooks/:webhook_id/:token | Jeton du webhook |
| POST | /webhooks/:webhook_id/:token | Jeton du webhook |
| POST | /webhooks/:webhook_id/:token/reset-token | Jeton du webhook |
Observabilité des applications
La console développeur journalise les appels REST authentifiés par Bot sans conserver les adresses IP clientes. Les propriétaires peuvent consulter les requêtes paginées et un résumé borné sur 24 heures du trafic, des erreurs, de la latence, des statuts et de la santé des livraisons webhook sortantes. Les données sont conservées 30 jours.
| Méthode | Chemin | Fonction |
|---|---|---|
| GET | /applications/:app_id/api-logs | Journal paginé des requêtes Bot |
| GET | /applications/:app_id/metrics | Métriques API et livraisons sur 24 heures |
Erreurs et limites de débit
Les erreurs utilisent une enveloppe stable { error: { code, message } }. Une réponse 429 comprend Retry-After : attendez cette durée et ajoutez un léger aléa avant de réessayer. Ne relancez pas automatiquement les erreurs de validation ou de permission.
| Statut | Signification |
|---|---|
| 400 | Saisie ou état invalide |
| 401 | Authentification absente ou invalide |
| 403 | Authentifié mais interdit |
| 404 | Ressource absente ou masquée |
| 409 | Conflit avec l’état actuel |
| 429 | Limite de débit dépassée |
| 500 | Erreur serveur inattendue |