[Index de la documentation](https://prescriptio.fr/docs/llms.txt) # Référence API La référence API de Prescriptio décrit les outils du connecteur MCP et les opérations REST qui donnent accès à la donnée publique du bâti et à votre espace : adresses, authentification, paramètres, quotas et erreurs. ## Les adresses Un seul registre d'outils, organisé en plusieurs profils : la même action passe par le même code, mais la forme de la réponse dépend du profil. > **Note :** Les 91 fiches MCP et 61 fiches REST proviennent des projections présentes dans le dépôt. Cinq outils supplémentaires du code local ont leur fiche « En préparation ». Ces deux ensembles ne prouvent pas le déploiement actuel : voir [État des sources](https://prescriptio.fr/docs/reference/etat-des-sources). | Adresse | Ce qu'elle sert | Pour qui | |---|---|---| | `https://prescriptio.fr/api/mcp` | Le registre complet, filtré par les portées de votre accès ; les trois mutations d'abonnements d'événements exigent explicitement `mcp:write`, même avec l'accès historique | L'adresse de connexion complète ; la liste effective se lit avec `tools/list` dans votre assistant autorisé | | `https://prescriptio.fr/api/mcp/v1/{opération}` | Les opérations REST (61), un `POST` en JSON | Make, Zapier, vos scripts | | `https://prescriptio.fr/api/mcp/connectors` | Quatre outils de lecture, avec la carte de résultats | Profil restreint défini dans le code ; disponibilité actuelle non vérifiée ici | | `https://prescriptio.fr/api/mcp/chatgpt` | Tous les outils sauf les deux de l'abonnement, filtrés par vos portées ; carte de résultats sur les recherches d'entreprises et de marchés | Profil de distribution ChatGPT ; sa présence dans le code ne prouve pas la publication d'un plugin | > **Attention :** Branchez votre agent sur `https://prescriptio.fr/api/mcp`. L'adresse `…/api/mcp/connectors` ne porte que quatre outils (`annuaire_entreprises`, `marches_rechercher`, `marches_dce`, `marches_dce_lien_obtenir`) : un agent branché dessus ne verra pas le reste du catalogue. ## Authentification L'accès se fait par **OAuth 2.1 avec PKCE** et des jetons opaques, que votre client révoque, et que vous retirez aussi depuis Paramètres › Accès IA. Il n'y a pas de clé d'API à copier. Votre client découvre seul le serveur d'autorisation à partir de l'adresse ; vous n'avez qu'à accepter la page d'autorisation de Prescriptio. ```bash curl -sS https://prescriptio.fr/api/mcp/v1/entreprises.search \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ -d '{"naf":["71.11Z"],"localisation":{"dept":"69"},"limit":20}' ``` Cet exemple cherche les architectes (code NAF 71.11Z) du Rhône. Les portées, le parcours complet et les plafonds sont dans [Authentification et quotas](https://prescriptio.fr/docs/reference/authentification). ## Codes de réponse Les routes REST répondent avec des codes HTTP ; le connecteur MCP renvoie les mêmes situations en erreurs JSON-RPC. | Code | Erreur | Ce que ça veut dire | |---|---|---| | `200` | | L'appel a réussi ; une liste vide veut dire zéro résultat | | `400` | `invalid_arguments`, `invalid_cursor` | Un argument manque ou sort du schéma ; le message le nomme | | `401` | `unauthenticated` | Jeton absent, expiré ou révoqué | | `403` | `insufficient_scope`, `access_denied`, `organization_required`, `role_denied` | La portée ou le droit manque pour cette action | | `404` | `not_found` | L'objet demandé est introuvable dans votre espace | | `405` | `method_not_allowed` | L'opération s'appelle en `POST` | | `409` | `conflict` | L'action entre en conflit avec l'état de l'objet | | `413` | `invalid_body` | Le corps dépasse 3 Mio | | `415` | `unsupported_media_type` | Le corps doit être en `application/json` | | `429` | `quota_exceeded` | Un plafond est atteint ; attendez le délai de `Retry-After` quand il est donné | | `503`, `504` | `unavailable`, `timeout` | Une dépendance ne répond pas ; ne rejouez pas une écriture sans vérifier | Le détail, et la conduite à tenir pour chaque cas, est dans [Codes d'erreur](https://prescriptio.fr/docs/reference/erreurs). ## Quotas Un appel compte pour une unité, que vous passiez par le connecteur ou par l'API REST. | Compteur | Compte gratuit | Abonné | |---|---|---| | Appels par 24 heures glissantes | 100 | 5 000 | | Appels par minute | 5 | 30 | | Dossiers lus par jour (heure de Paris) | 5 | 500 | Chercher ne consomme aucune unité de dossier. Le corps d'une requête est borné à 3 Mio, et une opération REST à 35 secondes. ## Contrats lisibles par les machines - [OpenAPI 3.1](https://prescriptio.fr/openapi.json) : Le schéma des opérations REST - [Index pour agents](https://prescriptio.fr/docs/llms.txt) : Un outil par ligne, rangés par module - [Documentation en un fichier](https://prescriptio.fr/llms-full.txt) : Tous les outils, leurs paramètres et les recettes - [Manifeste](https://prescriptio.fr/agents/manifest.json) : Les versions du contrat, du catalogue et de la documentation ## Toute la référence - [Authentification et quotas](https://prescriptio.fr/docs/reference/authentification) : OAuth 2.1, les portées, les plafonds - [Conventions](https://prescriptio.fr/docs/reference/conventions) : Territoire, une requête un sujet, liste et fiche - [Codes d'erreur](https://prescriptio.fr/docs/reference/erreurs) : JSON-RPC, HTTP, et quoi faire - [Pagination](https://prescriptio.fr/docs/reference/pagination) : Le curseur et les totaux - [Événements d'alerte](https://prescriptio.fr/docs/reference/evenements) : S'abonner, relever, acquitter - [Versions et compatibilité](https://prescriptio.fr/docs/reference/versions) : Le contrat 3.0.0 et les anciens noms - [OpenAPI](https://prescriptio.fr/docs/reference/openapi) : Le schéma des opérations REST - [Catalogue des outils](https://prescriptio.fr/docs/api) : Les 91 fiches MCP projetées, les 61 fiches REST et les compléments locaux - [État des sources](https://prescriptio.fr/docs/reference/etat-des-sources) : Ce qui vient des projections, du code local et ce qui reste à vérifier ## Questions ### Faut-il une clé d'API ? Non. L'accès passe par OAuth 2.1 : votre client obtient un jeton lié à votre compte, qu'il peut révoquer (`POST /oauth/revoke`, RFC 7009). ### Le compte gratuit suffit-il pour appeler l'API ? Oui pour commencer : l'offre gratuite ne filtre pas les noms du registre général, à profil et portées identiques. La réussite d'une action dépend aussi de ses droits et conditions métier. Le rapport de marque et l'envoi d'e-mails demandent notamment un accès payant ou offert admissible ; les quotas continuent de s'appliquer. L'abonnement à 12 € HT par mois et par utilisateur relève les plafonds d'appels et de dossiers. ### Prescriptio envoie-t-il des webhooks ? Non. Les événements d'alerte se relèvent : une automatisation s'abonne à une alerte, lit les événements par pages de 100 et les acquitte après traitement. Voir [Événements d'alerte](https://prescriptio.fr/docs/reference/evenements).