Authentification
Deux types de clé
Utilisez une session de tableau de bord connectée, une clé d'API ou une clé secrète. Une clé combine un key_id public et un secret privé. Envoyez les deux comme une seule valeur de porteur, jamais dans la chaîne de requête :
Authorization: Bearer ctr_<key_id>.<secret>
Une clé d'API (ctr_...) permet seulement la lecture. Une clé secrète (ctr_mgmt_...) permet aussi de gérer les sites, les clés de mesure, les objectifs, les liens de partage, les rapports, les exportations et les autres clés. Les réglages du compte et la surveillance de disponibilité exigent toujours une session de navigateur. Créez vos clés dans Outils de site.
Une clé peut viser un seul site ou tout le compte. Une clé limitée à un site ne peut ni créer de sites ni gérer les clés d'API, car ces actions visent l'ensemble du compte.
Contrat de réponse
Une seule enveloppe, toujours
Chaque réponse, en cas de succès comme d'échec, est un JSON de même forme. Vérifiez ok ; le code d'état HTTP fait foi.
{"ok": true, "data": {}}
{"ok": false, "error": {"code": "bad_range", "message": "end must be later than start"}}
Le contrat OpenAPI définit le contenu de data pour chaque opération. Les ressources listées utilisent un champ id ; les paramètres de route nomment la ressource, par exemple {key_id}. Les horodatages sont en ISO-8601 avec un décalage +00:00, sauf /realtime, /visitors, /visitor-map, /session/{id}, qui renvoient des dates HTTP RFC 1123.
Plages et pagination
Lire les données analytiques
Les lectures analytiques acceptent une plage prédéfinie range (today, yesterday, 7d, 30d, 90d, 6mo, 12mo) ou une paire ISO-8601 start/end. Les plages sont semi-ouvertes : start <= timestamp < end.
Les flux de visiteurs et de carte des visiteurs utilisent des curseurs opaques. Renvoyez next_cursor tel quel et arrêtez-vous lorsque has_more est faux. Ne décodez pas et ne fabriquez pas de curseurs.
Exemples
Copiez, collez, adaptez
curl -H 'Authorization: Bearer ctr_REDACTED.REDACTED' \
'https://webcounter.ca/api/v1/sites'
curl -H 'Authorization: Bearer ctr_REDACTED.REDACTED' \
'https://webcounter.ca/api/v1/s/example/overview?range=30d'
curl -X POST -H 'Authorization: Bearer ctr_mgmt_REDACTED.REDACTED' \
-H 'Content-Type: application/json' \
-d '{"slug":"example","name":"Example","timezone":"UTC"}' \
'https://webcounter.ca/api/v1/sites'
Utilisez un identifiant de site et un domaine d'essai distincts pour vos expérimentations. N'envoyez jamais une clé de production, un identifiant de client ni des données brutes de visiteur à un outil tiers.
Exportations de données
Télécharger les données CSV brutes
Utilisez une clé secrète pour mettre en file une exportation events ou sessions avec POST /s/{slug}/exports. Interrogez GET .../exports/{export_id}, puis récupérez .../download lorsque l'état est done. Les exportations expirent automatiquement.
Ce qui reste réservé à la session
Inaccessible à toute clé
Les clés porteuses ne donnent pas accès aux identifiants du compte, aux réglages ou à l'historique de la surveillance de disponibilité, ni à l'inscription Web Push. Ces fonctions exigent une session de navigateur connectée.
Pour les agents IA
Points d'entrée lisibles par machine
Commencez par /llms.txt, puis lisez /static/openapi.yaml pour les chemins, les paramètres, les schémas et les exigences d'authentification.