Documentation API
REST, JSON, sans clé pour commencer. Le premier appel tient en une ligne.
Premier appel
Aucune inscription, aucune clé.
curl "https://aifr.ai/searchEntities?q=lyon&limit=3"Base : https://aifr.ai · Réponses en JSON · CORS ouvert · Spécification complète : /openapi.json
Trois paliers
Le quota est compté par identité et par jour, remis à zéro à minuit UTC.
Sans rien
Appelable sans compte. Quota compté par adresse IP.
Jeton Bearer
Jeton Firebase ou clé d’extension. Quota multiplié par cinq.
USDC ou crédits
Aucun quota gratuit : le règlement tient lieu d’entrée.
# Palier « compte »
curl -H "Authorization: Bearer <jeton>" \
"https://aifr.ai/getPublicFinances?siren=216901231"La clé d’extension se génère depuis votre profil.
Entités
| Endpoint | Paramètres | Rôle | Accès |
|---|---|---|---|
| GET/searchEntities | q, limit | Recherche parmi 24,4 M d’entités | public |
| GET/getActorDetails | siren | Fiche complète d’une entité | public |
| GET/getActorsOverview | — | Comptes par catégorie | public |
| GET/getActorsByCategory | category, limit, cursor | Entités d’une catégorie | public |
Argent public
| Endpoint | Paramètres | Rôle | Accès |
|---|---|---|---|
| GET/getSubsidiesByActor | siren, limit, offset, sort | Subventions d’une entité | compte |
| GET/getSubsidiesOverview | type, year | Synthèse des subventions | public |
| GET/getSubsidiesByPurpose | slug | purpose, limit | Bénéficiaires d’un objectif | payant |
| GET/getTopBeneficiaries | type, year, limit, search | Plus gros bénéficiaires | payant |
| GET/searchSubsidies | q, minAmount, maxAmount | Recherche dans les subventions | public |
| GET/getPublicFinances | siren | name | Comptes DGFiP sur 25 exercices | compte |
| GET/getTopRankings | metric, type, year, minPop | Classement sur un indicateur | payant |
Personnes publiques
| Endpoint | Paramètres | Rôle | Accès |
|---|---|---|---|
| GET/getOfficials | q, department, type | Déclarations HATVP | compte |
| GET/getOfficialDetail | slug | Détail d’un responsable | compte |
| GET/getEntityElus | siren, limit | Élus d’une collectivité | compte |
| GET/searchElus | q, mandat, nuance | Recherche d’élus | compte |
| GET/getLobbyists | q, limit | Représentants d’intérêts | compte |
Données ouvertes et ingestion
| Endpoint | Paramètres | Rôle | Accès |
|---|---|---|---|
| GET/datasets/search | q, organization, page | Chercher sur data.gouv.fr | public |
| GET/datasets/inspect | id | Ressources d’un jeu | public |
| GET/datasets/plan | url | Plan d’ingestion vers le modèle canonique | compte |
Découverte
| Endpoint | Paramètres | Rôle | Accès |
|---|---|---|---|
| GET/openapi.json | — | Spécification OpenAPI 3.1 | public |
| GET/pricing.json | — | Tarifs par capacité | public |
| GET/health | — | État du service | public |
| POST/mcp | JSON-RPC 2.0 | Serveur MCP | public |
Erreurs et limites
Toujours un code HTTP juste et un corps JSON portant un champ errorlisible par une machine — jamais un 200 contenant une excuse.
| 400 | Paramètre absent ou invalide. |
| 401 | Palier « compte » : jeton absent ou expiré. |
| 402 | Palier « payant » : le corps porte les rails de règlement et le montant exact. |
| 404 | Ressource inexistante. |
| 429 | Quota atteint. `retry_after_seconds` indique le délai. |
| 503 | Service dégradé. L’en-tête `Retry-After` indique le délai. |
Le palier dit qui peut appeler ; le quota dit combiend’appels sont offerts. Une fois le quota épuisé, tout endpoint devient payable : on répond 402 avec le prix et les rails. Le 429 ne subsiste que si aucun rail de règlement n’est configuré — réclamer un paiement sans pouvoir l’encaisser n’aurait pas de sens.
Pour aller plus loin
Données sous Licence Ouverte Etalab. Les montants publiés ne sont pas corrigés, même invraisemblables : les anomalies connues sont documentées.