API REST

Chaque site utilisant Kulturae Agenda expose une API REST publique en lecture seule, pour réutiliser vos événements et vos lieux dans une application mobile, un écran d’affichage ou un autre site. Disponible avec les offres Pro et Multi-sites.

Introduction

Tous les endpoints sont préfixés par le domaine de votre site :

BASEhttps://votre-site.fr/wp-json/kulturae-agenda/v1

Lecture seule — uniquement des requêtes GET. L’API ne modifie jamais vos données.
Sans authentification — seuls les événements publiés et les lieux publics sont exposés.
Réponses JSON, champs en français, dates au format AAAA-MM-JJ et heures HH:MM.

Liste des événements

GET/events

Renvoie les événements à venir, triés par date croissante. Par défaut, de la date du jour jusqu’à un an plus tard.

Paramètres de requête

Paramètre	Type · défaut	Description
`page`	entier · 1	Numéro de page.
`per_page`	entier · 12	Résultats par page (maximum 100).
`from`	date · aujourd’hui	Date de début de la plage (AAAA-MM-JJ).
`to`	date · +1 an	Date de fin de la plage.
`search`	texte · —	Filtre sur le titre de l’événement.
`type`	slug · —	Filtre sur le type d’événement (ex. concert).

Exemple

curl "https://votre-site.fr/wp-json/kulturae-agenda/v1/events?type=concert&per_page=3"

{ "data": [ { "id": 128, "titre": "Jazz au fil de l'eau", "url": "https://votre-site.fr/evenement/jazz-au-fil-de-l-eau/", "image": "https://votre-site.fr/wp-content/uploads/…-medium.jpg", "dates": { "date": "2026-07-18", "heure_debut": "20:30" } } ] }

Le total et le nombre de pages sont renvoyés dans les en-têtes HTTPX-WP-Total etX-WP-TotalPages.

Détail d’un événement

GET/events/{id}

Renvoie la fiche complète d’un événement : lieu, classification, tarif et réservation.

{ "id": 128, "titre": "Jazz au fil de l'eau", "description": "Un concert en plein air au bord du canal…", "image": "https://votre-site.fr/wp-content/uploads/…-large.jpg", "url": "https://votre-site.fr/evenement/jazz-au-fil-de-l-eau/", "dates": { "date": "2026-07-18", "heure_debut": "20:30", "heure_fin": "23:00" }, "lieu": { "nom": "Parc du Château", "adresse": "1 allée du Parc", "ville": "Lyon", "lat": 45.764043, "lng": 4.835659 }, "types": ["Concert"], "public": ["Tout public"], "reservation": { "gratuit": true, "tarif": null, "url": null } }

Un événement introuvable ou non publié renvoie un code404 avec le corps{ "code": "ka_not_found", … }.

Liste des lieux

GET/venues

Renvoie tous les lieux, triés par nom.

{ "data": [ { "id": 4, "nom": "Parc du Château", "adresse": "1 allée du Parc", "ville": "Lyon", "code_postal": "69005", "lat": 45.764043, "lng": 4.835659, "telephone": "04 00 00 00 00", "site_web": "https://…" } ] }

Pagination et erreurs

Parcourez les pages avec page et per_page, en vous appuyant sur l’en-tête X-WP-TotalPages.
Les réponses suivent les conventions HTTP de l’API REST de WordPress : 200 en cas de succès, 404 pour une ressource inexistante.

API de licence (interne)

Distincte de l’API publique ci-dessus. Ces endpoints sont appelés uniquement par le plugin lui-même pour activer et vérifier sa licence — jamais par une intégration tierce. Aucune donnée d’événement ou de lieu n’y transite.

POST/wp-json/kulturae-api/v1/license/{activate|verify|deactivate}

L’authentification se fait par la clé de licence seule. Chaque réponse est signée (Ed25519) et renvoyée en HTTP 200 avec un statut métier : le plugin n’accorde l’accès Pro que si la signature est valide, ce qui empêche d’usurper le serveur de licence.

// Requête (JSON) { "license_key": "KULT-XXXX-XXXX-XXXX-XXXX", "domain": "mon-site.fr", "plugin": "kulturae-agenda-pro", "version": "1.0.0", "nonce": "…aléatoire, réémis dans la réponse…" } // Réponse 200 — licence active { "plan": "pro", "status": "valid", "expires_at": "2027-06-30T00:00:00.000Z", "domains_allowed": 1, "domains_used": 1, "issued_at": 1784400000, "nonce": "…", "signature": "…base64…" } // Réponse 200 — accès refusé (clé inconnue, expirée, quota atteint) { "plan": "free", "status": "invalid", "signature": "…" }

Un statut non-200 est interprété par le plugin comme « serveur injoignable » : il conserve alors son état en cache, jusqu’à 14 jours, avant de repasser en version gratuite. Aucune donnée n’est jamais supprimée.