Especificación OpenAPI
Telemetry publica un Especificación OpenAPI 3.1 legible por máquina para el HTTP API documentado. Úselo para inspeccionar contratos de puntos finales, generar un cliente escrito como punto de partida, configurar un explorador API o validar solicitudes de ejemplo en CI.
La especificación cubre:
- ingesta de eventos estructurados con
POST /log; - SQL síncrono con
POST /query; - exportaciones asíncronas de JSON y Parquet con
POST /query/asyncyGET /query/async/{job_id}; - listado de tablas, inspección de esquemas, retención, columnas de partición y eliminación;
- listado, creación, actualizaciones de reemplazo y eliminación del panel de control;
- listado, creación, actualización parcial y eliminación de alertas;
- el punto final heredado de eliminación de filas, marcado como obsoleto.
Descargar la especificación
curl -fsS https://telemetry.sh/openapi.json -o telemetry-openapi.json
El documento utiliza https://api.telemetry.sh como servidor y describe ambos formularios de encabezado de autorización admitidos:
Authorization: YOUR_API_KEY
Authorization: Bearer YOUR_API_KEY
No incluya una clave API real en la especificación, el control de fuente, la documentación generada, los ejemplos, los registros o la configuración del cliente comprometidos en un repositorio.
Validar el documento
Utilice un validador compatible con OpenAPI 3.1. Por ejemplo, con una CLI de Redocly instalada localmente:
npx @redocly/cli lint telemetry-openapi.json
Fije la versión del validador en CI para que una actualización de la herramienta no cambie inesperadamente el comportamiento de la versión. Trate las advertencias sobre esquemas ambiguos como elementos de revisión en lugar de suprimirlas automáticamente.
Generar clientes con cuidado
Los clientes generados son un andamiaje, no un sustituto de las guías de puntos finales. Antes del uso en producción:
- verificar la autenticación y el alcance de la clave API;
- configurar tiempos de espera de conexión y respuesta;
- reintentar sólo fallos temporales con jitter y retroceso exponencial limitado;
- conservar un identificador de evento al volver a intentar la ingesta;
- imponer una fecha límite total de sondeo para trabajos de consulta asincrónicos;
- evitar que los fallos de telemetría agoten a los trabajadores de las aplicaciones;
- revise los métodos destructivos de tabla y eliminación de filas por separado.
El esquema OpenAPI deja intencionalmente cargas útiles de eventos flexibles y filas de resultados de consultas abiertas porque sus campos dependen de su contrato de evento y de la proyección SQL. Genere tipos de dominio para esas cargas útiles en su aplicación en lugar de asumir una forma de evento global.
Límite de la fuente de la verdad
La especificación refleja la documentación pública API en este repositorio. Las páginas legibles por humanos siguen siendo la fuente de orientación operativa, comportamiento de normalización, ejemplos y modos de error:
- Registro API
- Consulta API
- Tablas API
- Tablero API
- Alerta API
- Eliminar API
- Límites de tarifas y errores
Las cuotas específicas del plan pueden cambiar y no están codificadas como una tasa numérica global en la especificación. Verifique la configuración de producto y facturación para conocer los límites actuales de la cuenta. Si el documento OpenAPI y una respuesta API en vivo no están de acuerdo, capture una reproducción mínima segura e infórmela a [email protected]; no solucione la discrepancia registrando credenciales o cargas útiles privadas.