API MaProg

Connectez un agent IA ou un script à votre compte — la documentation complète vit sur /v1/docs.

L'API MaProg permet de piloter la plateforme par programme — connecter un agent IA, un script d'export ou un outil maison. Elle couvre tout ce que le site sait faire : consulter les programmations publiques, gérer vos manifestations, vos médias, votre blog et vos statistiques.

  • Base de l'API : https://api.maprog.app/v1
  • Spécification complète (OpenAPI 3.1) : /v1/openapi.json
  • Documentation interactive : /v1/docs

Obtenir une clé API

L'API s'utilise avec une clé personnelle mpk_…, à créer depuis le site :

  1. Connectez-vous à votre compte organisateur sur maprog.app ;
  2. Ouvrez Profil → API & clés ;
  3. Choisissez les permissions et la durée, puis créez la clé.

La clé s'affiche une seule fois : copiez-la immédiatement et gardez-la secrète — elle donne accès à votre compte dans la limite des permissions choisies. Vous pouvez la révoquer à tout moment depuis la même page ; la révocation prend effet en moins d'une minute.

Deux permissions sont disponibles :

Scope Ce qu'il permet
orga.read Consulter vos structures, manifestations, programme, statistiques
orga.write Créer et modifier des manifestations, publier, gérer médias et blog

La lecture publique (catalogue, programmation des manifestations publiées, FAQ, blog) ne nécessite aucune clé.

Premiers pas

Toutes les requêtes authentifiées passent la clé dans l'en-tête Authorization :

# Qui suis-je ? — vérifie la clé et affiche le compte lié
curl https://api.maprog.app/v1/me \
  -H "Authorization: Bearer mpk_votre_cle"

Réponse en cas de succès (extrait) :

{
  "realm": "users",
  "cle": { "nom": "agent prod", "scopes": ["orga.read", "orga.write"] },
  "compte": { "email": "vous@exemple.fr" }
}

Vos manifestations, puis la programmation complète d'une d'entre elles (événements normalisés, prêts à consommer) :

# Les manifestations de mes structures
curl https://api.maprog.app/v1/me/manifestations \
  -H "Authorization: Bearer mpk_votre_cle"

# La programmation d'une manifestation publique (sans clé)
curl "https://api.maprog.app/v1/manifestations/demo/evenements?per_page=10"

Et un exemple en JavaScript :

const reponse = await fetch("https://api.maprog.app/v1/me", {
  headers: { Authorization: `Bearer ${cle}` },
});
if (!reponse.ok) {
  const erreur = await reponse.json(); // { "error": { "code", "message" } }
  throw new Error(`${erreur.error.code} : ${erreur.error.message}`);
}
const moi = await reponse.json();

Ce que l'API couvre

Domaine Exemples d'endpoints
Public (sans clé) GET /manifestations (catalogue, recherche, autour de moi) · GET /manifestations/{id}/evenements (filtres de la page programme, facettes) · /faq · /blog · /lieux · export .ics
Organisateur structures, création/modification/publication de manifestations, synchronisation du Google Sheet, rapport de validation, checklist, blog, statistiques d'audience
Médias upload de vidéos (transcodage HLS) et d'images, attribution aux événements
Abonnement produits et prix, état de l'abonnement, liens de paiement Stripe
Contact formulaires de contact

Conventions utiles

  • Erreurs : toujours { "error": { "code", "message" } } avec un code stable (UNAUTHORIZED, NOT_FOUND, VALIDATION_ERROR, SUBSCRIPTION_REQUIRED…). Une manifestation non publiée répond 404 (jamais 403) pour ne pas révéler son existence.
  • Horaires : debut et fin sont des timestamps en millisecondes UTC — les champs date / horaireDebut ne sont que des formats d'affichage.
  • Pagination : ?page=&per_page= (200 résultats max par requête), la réponse contient items, page, total_items, total_pages.
  • Changements de programme : les réponses d'événements portent un ETag — renvoyez-le via If-None-Match pour payer un 304 bon marché au lieu de re-télécharger la programmation.
  • Limites : 300 requêtes/minute par clé (10/minute sur la connexion) ; la publication d'une manifestation exige un abonnement actif (sinon 402).
  • Maintenance : l'API peut être momentanément désactivée par l'administrateur — toutes les routes répondent alors 503 API_DISABLED. L'état se lit sur cette page ou directement sur GET /v1.
  • Durée de vie : une clé fonctionne jusqu'à sa date d'expiration, même après une longue période d'inactivité.

Aller plus loin

La référence exhaustive de chaque endpoint (paramètres, réponses, exemples) vit dans la spécification OpenAPI, consultable en JSON ou dans l'interface interactive :

Une question, un besoin non couvert ? Écrivez-nous.