Autenticación
Dos tipos de claves
Usa una sesión iniciada del panel, una clave de API, o una clave secreta. Una clave combina un key_id público con el secreto secret. Envía ambos como un único valor de portador, nunca en la cadena de consulta:
Authorization: Bearer ctr_<key_id>.<secret>
Una clave de API (ctr_...) solo puede leer. Una clave secreta (ctr_mgmt_...) también puede administrar sitios, claves de medición, objetivos, enlaces para compartir, informes, exportaciones y otras claves. La configuración de la cuenta y la supervisión de disponibilidad siempre requieren una sesión de navegador. Emite claves desde Herramientas del sitio.
Las claves pueden abarcar un sitio o toda la cuenta. Una clave limitada a un sitio no puede crear sitios ni administrar claves de API porque esas acciones se aplican a toda la cuenta.
Contrato de respuesta
Un único envoltorio, siempre
Todas las respuestas, correctas o fallidas, tienen la misma estructura JSON. Comprueba ok; el estado HTTP es el valor definitivo.
{"ok": true, "data": {}}
{"ok": false, "error": {"code": "bad_range", "message": "end must be later than start"}}
El contrato OpenAPI define el contenido de data para cada operación. Los recursos enumerados utilizan id como campo; los parámetros de ruta nombran el recurso, como {key_id}. Las marcas de tiempo utilizan ISO-8601 con +00:00 como desplazamiento, excepto /realtime, /visitors, /visitor-map, /session/{id}, que devuelven fechas HTTP RFC 1123.
Intervalos y paginación
Consultar la analítica
Las consultas de analítica aceptan un range preestablecido (today, yesterday, 7d, 30d, 90d, 6mo, 12mo) o un par de valores ISO-8601 start/end para definir el intervalo. Los intervalos son semiabiertos: start <= timestamp < end.
Los flujos de visitantes y del mapa de visitantes utilizan cursores opacos. Devuelve next_cursor sin cambios y detente cuando has_more sea falso. No decodifiques ni construyas cursores.
Ejemplos
Copia, pega y ajusta
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'
Utiliza un slug de sitio y un dominio de prueba independientes para los experimentos. Nunca envíes una clave de producción, un identificador de cliente ni datos sin procesar de visitantes a una herramienta de terceros.
Exportaciones de datos
Descargar datos CSV sin procesar
Usa una clave secreta para poner en cola una exportación de events o de sessions con POST /s/{slug}/exports. Consulta periódicamente GET .../exports/{export_id}, y después, descarga .../download cuando el estado sea done. Las exportaciones caducan automáticamente.
Lo que sigue siendo exclusivo de la sesión
No disponible para ninguna clave
Las claves de portador no pueden acceder a las credenciales de la cuenta, la configuración o el historial del monitor de disponibilidad ni la inscripción en Web Push. Esas funciones requieren una sesión iniciada en el navegador.
Para agentes de IA
Puntos de entrada legibles por máquina
Empieza por /llms.txt, y después, lee /static/openapi.yaml para conocer las rutas, los parámetros, los esquemas y los requisitos de autenticación.