> For the complete documentation index, see [llms.txt](https://docs.yoplanning.support/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.yoplanning.support/developpeur/api-agent-yoplanning.md). # API Agent Yoplanning Yoplanning propose une **API Agent**, qui permet de piloter Yoplanning par programme — ou via un assistant IA — exactement comme si vous étiez dans l'interface web. La référence technique complète (tous les endpoints, tous les champs) est disponible dans le Swagger : {% embed url="" %} Référence complète de l'API Agent Yoplanning {% endembed %} Cet article ne remplace pas cette référence technique : il explique le principe général, à quoi sert cette API, et surtout les précautions à prendre avant de la connecter à quoi que ce soit. ### Méthodologie L'API Agent suit quelques principes simples, mais qu'il faut avoir en tête avant de l'utiliser : * **C'est un pont direct vers le code interne de Yoplanning** — le même que celui que l'interface web appelle. Une écriture via l'API a exactement le même comportement, les mêmes validations et les mêmes effets de bord qu'une action faite à la main dans Yoplanning. Il n'y a pas de logique cachée : ce que l'interface autorise, l'API l'autorise ; ce que l'interface refuse, l'API le refuse aussi, avec la même erreur. * **Tout est rattaché à une équipe (team-scoped).** Presque chaque adresse commence par l'identifiant de votre équipe (`/teams/{teamId}/…`), et un token ne donne accès qu'à la team pour laquelle il a été créé. * **La règle du "round-trip" pour toute modification** : on récupère l'objet existant, on modifie le ou les champs voulus, puis on renvoie l'objet **en entier**. Une mise à jour n'est pas un correctif partiel : tout champ absent de l'envoi est réinitialisé. C'est une source d'erreur fréquente si l'on ne s'y attend pas. * **Authentification par token**, propre à un utilisateur et à une équipe, transmis dans chaque requête via l'en-tête `Authorization`. ### À quoi ça sert L'API Agent permet de créer, configurer, modifier ou supprimer à peu près tout ce que gère Yoplanning : clients, produits, sessions, commandes, paiements, staff, codes promo, moteur de réservation, revendeurs, etc. — avec les mêmes droits que la personne dont c'est le token. Concrètement, elle sert à connecter Yoplanning à un système externe (site web, outil interne, autre logiciel métier) ou à un assistant IA à qui l'on souhaite déléguer des tâches de configuration ou de gestion en langage naturel, plutôt que de tout faire à la main dans l'interface. ### Les risques à connaître avant de connecter un outil à cette API Ce n'est **pas** une API en lecture seule : c'est un accès aussi puissant qu'un compte utilisateur connecté à Yoplanning. Avant de la connecter à un outil, un script ou un assistant IA, gardez ces points en tête : {% hint style="danger" %} **Le token est une donnée strictement confidentielle — au même titre qu'un mot de passe.** Toute personne ou tout programme en sa possession peut agir sur votre équipe exactement comme vous : créer, modifier, supprimer. Ne le collez **jamais** dans un dépôt de code (même privé), un message non chiffré, un email, une capture d'écran ou un outil auquel vous n'accordez pas une confiance totale. S'il fuite, considérez-le compromis : régénérez-en un nouveau immédiatement depuis vos préférences avancées, ou contactez si vous avez un doute sur la marche à suivre. {% endhint %} * **Les effets de bord sont réels.** Une écriture peut envoyer un email de confirmation, enregistrer un paiement, envoyer une invitation, ou supprimer une donnée pour de vrai — une seule fois, comme le ferait l'interface. Un script ou un agent mal cadré peut donc déclencher des actions bien réelles auprès de vos clients ou de votre équipe, pas seulement modifier des données en interne. * **Une mise à jour remplace l'objet entier.** Si l'outil que vous connectez ne relit pas l'objet avant de le renvoyer modifié, il risque d'effacer des champs sans le vouloir plutôt que de les laisser tels quels. * **Le token porte les droits de la personne qui l'a créé.** Si vous connectez un assistant IA à cette API, il pourra faire — et défaire — tout ce que peut faire cette personne sur cette équipe. Cadrez précisément ce que vous lui demandez de faire, en particulier pour toute action irréversible (suppression, envoi d'email ou de SMS, encaissement), et privilégiez un token créé spécifiquement pour cet usage plutôt que votre token personnel principal si l'outil le permet. ### Pour aller plus loin Pour une intégration IA plus légère, en lecture et cadrée par vos propres droits, voir aussi l'article [Se connecter à Yoplanning via MCP](/developpeur/se-connecter-a-yoplanning-via-mcp.md). Pour le détail complet des ressources et des champs de l'API Agent, la référence à jour reste le [Swagger](https://yoplanning.pro/api/agent/v1/swagger/). --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.yoplanning.support/developpeur/api-agent-yoplanning.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.