No se encontraron secciones coincidentes.
Host-Tracker REST API v1
Una API HTTP estable, autenticada mediante token, para gestionar tareas de monitoreo de sitios web, contactos, suscripciones de alertas/informes, y leer estadísticas, caídas e incidentes.
URL base
Cada ruta de este documento es relativa a una URL base. Dos puntos de entrada sirven la misma API:
| Punto de entrada | URL base (BASE_URL) | Notas |
|---|---|---|
| Directo | https://api1.host-tracker.com/ | Recomendado para integraciones servidor a servidor. |
| A través del sitio principal | https://www.host-tracker.com/api/web/v1/ | Redirigido mediante proxy inverso al mismo servicio. Conveniente cuando ya se comunica con www.host-tracker.com. |
A lo largo de esta referencia, una llamada escrita como GET tasks significa
GET BASE_URL/tasks — por ejemplo, https://api1.host-tracker.com/tasks
o https://www.host-tracker.com/api/web/v1/tasks.
Tipo de contenido y métodos HTTP
Las solicitudes y respuestas son application/json de forma predeterminada (consulte
Convenciones para XML). La API utiliza los métodos HTTP estándar:
- GET — leer entidades (tareas, contactos, suscripciones, estadísticas, caídas, incidentes, agentes).
- POST — crear una entidad o iniciar una acción.
- PUT — actualizar entidades existentes.
- DELETE — eliminar entidades.
- PATCH — actualizaciones parciales (se usa para reenviar un código de confirmación de contacto).
Sobrescritura del método HTTP
Si su cliente no puede enviar PUT, DELETE o
PATCH, envíe un POST y agregue un encabezado
X-HTTP-Method-Override que indique el verbo deseado. Por ejemplo, para actualizar
tareas, envíe un POST a tasks con X-HTTP-Method-Override: PUT.
Convenciones
Serialización JSON
JSON utiliza nombres de propiedades en camelCase. Los campos nulos se omiten en las respuestas (los
arreglos vacíos igual se emiten como []). El orden de las propiedades es
estable: primero el identificador y la dirección/url, luego los campos heredados, y después los campos
específicos del tipo.
Fecha y hora
Las respuestas de creación/lectura de tareas llevan las marcas de tiempo como cadenas ISO-8601 UTC (por
ejemplo, 2024-06-21T22:26:23Z). Los endpoints de estadísticas, caídas,
incidentes y resultados además usan una representación dual: cada hora aparece tanto como un campo
entero en segundos Unix (sufijo Unix) como una cadena legible formateada según
el formato de fecha y la zona horaria del perfil de la cuenta. Los filtros de solicitud aceptan segundos
Unix y/o cadenas formateadas según el endpoint (documentado por endpoint más abajo). Todas las marcas de
tiempo Unix son segundos desde 1970-01-01T00:00:00Z.
Negociación de contenido XML
Todos los endpoints también pueden devolver XML. Envíe Accept: application/xml para
recibir un cuerpo XML en lugar de JSON; la respuesta usa la representación clásica de .NET
XmlSerializer del mismo grafo de objetos. JSON es el formato predeterminado y
recomendado.
CORS
Se permiten solicitudes de origen cruzado. Las solicitudes simples (sin credenciales) se aceptan desde
cualquier origen (Access-Control-Allow-Origin: *). Las solicitudes que envían
cookies/credenciales solo se aceptan desde orígenes *.host-tracker.com. Los
llamadores basados en token (que usan el encabezado Authorization, como se
documenta aquí) no se ven afectados por la restricción de origen con credenciales.
Autenticación
Todos los endpoints, excepto POST users/token y los endpoints anónimos de
listado de agentes, requieren autenticación. Se aceptan dos esquemas:
- Token Bearer — obtenido de
POST users/token, enviado comoAuthorization: bearer <token>. Este es el esquema principal. - HTTP Basic —
Authorization: Basic <base64(login:password)>. Las credenciales se decodifican como ISO-8859-1. Conveniente para pruebas rápidas; se prefiere el token bearer para la automatización.
POST users/token anónimo
Intercambia un login y una contraseña por un token bearer. El token es válido durante 48 horas.
Cuerpo de la solicitud
{
"login": "your-login",
"password": "your-password"
}
| Campo | Tipo | Descripción |
|---|---|---|
login | string | Login de la cuenta. Requerido. También se acepta el correo electrónico de la cuenta. |
password | string | Contraseña de la cuenta. Requerido. |
forLogin | string | Opcional. El login de la cuenta superior en cuyo nombre actuar (suplantación de subcuenta — vea más abajo). |
Respuesta — 200 OK
{
"ticket": "<bearer token>",
"expirationTime": "2024-06-23T22:26:23Z",
"expirationUnixTime": 1719181583
}
Si falla, la respuesta es 401 con el código de máquina
IncorrectLoginOrPassword (o AccessDenied si el
acceso a la API está deshabilitado para la cuenta) y un encabezado WWW-Authenticate: Bearer.
Uso del token
GET BASE_URL/tasks HTTP/1.1
Host: api1.host-tracker.com
Accept: application/json
Authorization: bearer 3DD135...5EE510417
Suplantación de subcuenta (forLogin)
Si una cuenta superior le otorgó a su subcuenta acceso a sus datos, inicie sesión como la subcuenta pero
pase el login de la cuenta superior en forLogin. El token devuelto le permite
entonces administrar la cuenta superior exactamente como si los endpoints se llamaran para su propia
cuenta, sujeto a los derechos que la cuenta superior otorgó. Por ejemplo, si otorgó acceso de solo lectura
a las tareas de monitoreo, las llamadas GET tienen éxito pero POST/PUT/PATCH/DELETE sobre tasks son
rechazadas.
# 1. Obtener un token de suplantación
POST BASE_URL/users/token HTTP/1.1
Content-Type: application/json
{
"login": "subaccount-login",
"password": "subaccount-password",
"forLogin": "superaccount-login"
}
# 2. Usa el ticket devuelto para leer las tareas de la cuenta SUPERIOR
GET BASE_URL/tasks HTTP/1.1
Authorization: bearer <ticket from step 1>
curl
# obtener un token y almacenarlo
TOKEN=$(curl -s -X POST https://api1.host-tracker.com/users/token \
-H "Content-Type: application/json" \
-d '{"login":"your-login","password":"your-password"}' \
| grep -o '"ticket":"[^"]*"' | cut -d'"' -f4)
# llamar a un endpoint autenticado
curl -s https://api1.host-tracker.com/tasks \
-H "Authorization: bearer $TOKEN"
Errores y códigos de máquina
Los errores devuelven un código de estado HTTP estándar más un código corto legible por máquina sobre el cual su integración puede ramificar la lógica. El cuerpo es una descripción en texto plano en inglés (no JSON), destinada a humanos/registros.
El código de máquina se entrega de dos maneras:
- Encabezado de respuesta
X-HT-Reason— lleva el código en cada respuesta y en cada versión de HTTP. Esta es la forma recomendada de detectar el tipo de error. - Frase de motivo HTTP/1.1 — la línea de estado se ve, por ejemplo, así:
HTTP/1.1 400 SimilarExists. Se conserva por compatibilidad con versiones anteriores, pero tenga en cuenta que HTTP/2 y HTTP/3 eliminaron las frases de motivo del protocolo, por lo que este campo puede estar vacío cuando la conexión negocia HTTP/2+. PrefieraX-HT-Reason.
HTTP/1.1 400 SimilarExists
X-HT-Reason: SimilarExists
Content-Type: text/plain; charset=utf-8
Same task allready exists
401 con
WWW-Authenticate: Bearer y uno de AccessDenied,
WrongTicket, TicketExpired o
IncorrectLoginOrPassword.
Referencia de códigos de error
Todos los códigos de máquina que la API puede devolver, agrupados por área, con el estado HTTP típico.
Salvo que se indique lo contrario, los errores son 400 Bad Request.
Autenticación
| Código | Estado | Significado |
|---|---|---|
AccessDenied | 401 | El acceso a la API está deshabilitado para esta cuenta, o el llamador no tiene los derechos necesarios. |
IncorrectLoginOrPassword | 401 | Login/contraseña rechazados en users/token. |
WrongTicket | 401 | El token bearer está malformado / es ilegible. |
TicketExpired | 401 | El token bearer ha expirado — obtenga uno nuevo. |
RequestThrottled | 429 | Se excedió el límite de tasa (consulte Límites de tasa). Incluye Retry-After. |
Tareas
| Código | Estado | Significado |
|---|---|---|
NotFound | 404 | La tarea solicitada no existe. |
SimilarExists | 400 | Ya existe una tarea con el mismo tipo y clave (a menos que la cuenta permita tareas similares). |
EmptyTaskData | 400 | No se proporcionaron datos de la tarea. |
UncomplitedData | 400 | Los datos de la tarea están incompletos. |
NoIdInTaskData | 400 | Se solicitó una actualización pero falta el id de la tarea. |
WrongEditableTaskDataType | 400 | El tipo del payload de edición no coincide con el tipo de la tarea objetivo. |
WrongTaskType | 400 | Tipo de tarea desconocido. |
WrongTaskStatus | 400 | Valor de status no compatible (se espera Enabled/Disabled). |
WrongInterval | 400 | El intervalo de monitoreo no es uno de los valores aceptados (consulte tasks/intervals). |
EmptyUrl | 400 | No se proporcionó URL/host para una tarea que lo requiere. |
WrongUrl | 400 | La URL no es válida. |
WrongSchema | 400 | Esquema de URL no compatible. |
BadIP | 400 | La URL resuelve a una dirección IP denegada o malformada. |
UrlInBlackList | 400 | La URL está en una lista de bloqueo interna. |
WrongHttpMethod | 400 | Método HTTP no compatible para una tarea HTTP (permitidos: Get, Post, Head). |
WrongKeywordMode | 400 | Modo de palabra clave no compatible. |
WrongPort | 400 | Puerto no válido para una tarea de puerto. |
WrongAgentPool | 400 | Uno o más pools de agentes solicitados no existen. El mensaje enumera los pools inválidos y los disponibles. |
SelectMoreAgents | 400 | Los pools de agentes seleccionados no contienen suficientes agentes (se requieren 7). El mensaje enumera los recuentos por pool. |
ApiFullLogNotAllowed | 400 | fullLog solo está disponible en paquetes avanzados. |
WrongExpectedSLA | 400 | expectedSLA debe estar entre 0 y 100. |
WrongDate | 400 | Fecha de inicio/fin no válida en un filtro. |
WrongDateFormat | 400 | Una cadena de fecha no coincidió con el formato requerido (indicado en el mensaje). |
EndDateIsGreaterThanStartDate | 400 | La fecha de inicio debe ser ≤ a la fecha de fin. |
StartEndIntervalIsTooBig | 400 | Una consulta de resultados devolvería más de 10 000 filas. El mensaje incluye el intervalo permitido (consulte GET tasks). |
WrongSubscription | 400 | Una suscripción en línea en el cuerpo de la tarea no es válida (el código/mensaje de la suscripción interna se transmite tal cual). |
EmptyFilter | 400 | Se envió un DELETE tasks masivo con un filtro vacío (rechazado para evitar eliminar toda la cuenta). |
Contactos
| Código | Estado | Significado |
|---|---|---|
NotFound | 404 | El contacto solicitado no existe. |
SimilarExists | 400 | Ya existe un contacto con el mismo tipo, gateway, dirección y retraso de alerta. |
EmptyContactData | 400 | No se proporcionaron datos del contacto. |
UncomplitedData | 400 | Los datos del contacto están incompletos. |
NoIdInContactData | 400 | Se solicitó una actualización pero falta el id del contacto. |
EmptyAddress | 400 | No se proporcionó dirección al crear un contacto. |
WrongContactType | 400 | Tipo de contacto desconocido (también se devuelve para la ruta retirada de creación/actualización de IM). |
WrongEditableContactDataType | 400 | El tipo del payload de edición no coincide con el tipo del contacto objetivo. |
WrongEmailFormat | 400 | Dirección de correo electrónico no válida, o formato de informe de correo no compatible. |
WrongPhoneFormat | 400 | Un número de teléfono debe contener solo dígitos (se permite un + inicial). |
WrongSmsGateway | 400 | Gateway de SMS desconocido. |
WrongIMGateway | 400 | Gateway de IM desconocido. |
WrongAlertDelay | 400 | alertDelay no es uno de los valores aceptados (consulte contacts/delays). |
WrongActivePeriodInterval | 400 | Inicio/fin de periodo activo no válido. |
WrongActiveDay | 400 | Nombre de día activo no compatible. |
EmptyFilter | 400 | Se envió un DELETE contacts masivo con un filtro vacío (rechazado). |
Suscripciones
| Código | Estado | Significado |
|---|---|---|
AlertsAndReportsAreEmpty | 400 | Una entrada de suscripción no especifica ni tipos de alerta ni tipos de informe. |
UnknownAlertType | 400 | Un tipo de alerta no es uno de Up, Down, RepeatedlyDown. |
UnknownReportType | 400 | Un tipo de informe no es uno de Day, Week, Month, Quarter, Year. |
Límites de tasa
Las solicitudes están limitadas en tasa por cliente y por endpoint. Exceder un límite devuelve
429 con el código de máquina RequestThrottled y un
encabezado Retry-After (en segundos).
| Alcance | Límite |
|---|---|
| Endpoints generales, por cuenta + endpoint | 6 solicitudes / segundo y 120 solicitudes / minuto |
Endpoints de código de confirmación (contacts/{id}/code), por cuenta + endpoint | 1 solicitud / segundo y 2 solicitudes / minuto |
| Endpoints anónimos | Los mismos 6/s + 120/min, calculados por dirección IP del cliente |
HTTP/1.1 429 RequestThrottled
X-HT-Reason: RequestThrottled
Retry-After: 1
Content-Type: application/json; charset=utf-8
"API calls quota exceeded! maximum admitted 6 per s."
Tareas de monitoreo
GET tasks/types
Devuelve el arreglo de nombres de tipos de tarea que el sistema conoce:
["API","CntCheck","Counter","DNSBL","Database","DomainExp","Http",
"Ping","Port","RusRegBL","SSLExp","Snmp","Tran","Waterfall","WebRisk"]
tasks/http, tasks/ping,
tasks/port, tasks/rusbl respectivamente).
GET tasks/intervals
Devuelve el arreglo de intervalos de monitoreo (en minutos) aceptados para su cuenta, por ejemplo
[1,5,15,30,60]. Use uno de estos valores para el campo
interval al crear una tarea; cualquier otro valor produce
WrongInterval.
GET tasks
Lista las tareas de monitoreo. Todos los parámetros de consulta son opcionales; sin ninguno, se devuelven
todas las tareas de la cuenta. Repita un parámetro para pasar un arreglo, por ejemplo
?ids=guid1&ids=guid2.
El parámetro info
Solicita datos adicionales incrustados en cada tarea. Combine valores con comas
(?info=stats,subscriptions) o pase el entero de máscara de bits equivalente:
| Valor | Bit | Efecto |
|---|---|---|
subscriptions | 1 | Incluye las suscripciones de alerta/informe de la tarea en subscriptions. |
stats | 2 | Incluye el tiempo de actividad diario/mensual/anual/total en stats. |
results | 4 | Incluye los resultados de comprobación para la ventana sdtu…edtu en results (el último resultado si se omite la ventana). |
attachedResults | — | Incluye los últimos resultados de comprobaciones adjuntas (certificado, expiración de dominio, DNSBL) en attached. Requiere los flags check… correspondientes en la tarea. |
?info=stats,subscriptions,results es equivalente a ?info=7.
Parámetros de filtro
| Parámetro | Tipo | Descripción |
|---|---|---|
ids | guid[] | Devuelve solo estos ids de tarea. Para un único id, prefiera GET tasks/{id}. |
excludeIds | bool | Con ids: devuelve todo excepto esos ids. |
taskType / taskTypes | string / string[] | Filtra por tipo de tarea (sensible a mayúsculas/minúsculas), por ejemplo Http. |
excludeTaskTypes | bool | Invierte el filtro de tipo. |
status | string | Enabled o Disabled (deshabilitación por el usuario). Por ejemplo, ?status=Disabled. |
url / urls | string / string[] | Filtra por URL. Los valores en urls deben estar codificados como URL. |
urlSearchLike | bool | Con url (no urls): coincidencia de subcadena en lugar de exacta. |
excludeUrls | bool | Invierte el filtro de URL. |
name / names | string / string[] | Filtra por nombre de tarea. name/names combinado con id/ids es un OR; combinado con otros filtros es un AND. |
nameSearchLike | bool | Con name: coincidencia de subcadena. |
excludeNames | bool | Invierte el filtro de nombre. |
interval / intervals | int / int[] | Filtra por intervalo de monitoreo (minutos). |
excludeIntervals | bool | Invierte el filtro de intervalo. |
openStat | bool | Tareas públicas (estadísticas/registro de eventos públicos). |
lastState | bool | true = actualmente activo, false = actualmente caído. |
tags | string[] | Filtra por etiqueta. |
overlimited | bool | Tareas con (true) o sin (false) un exceso de límite de facturación. |
active | bool | true = activa, false = deshabilitada por el sistema (exceso de límite, saldo bajo, …). Para deshabilitación por el usuario use status. |
sdtu / edtu | int64 | Inicio/fin en segundos Unix (UTC) de una ventana. Se usa solo cuando se establece info=results; proporcione ambos. edtu debe ser > sdtu. |
(edtu − sdtu) × (#tareas) / (intervalo promedio)
no debe exceder 10 000. De lo contrario, la respuesta es 400 StartEndIntervalIsTooBig,
cuyo mensaje incluye el mayor intervalo que encajaría. Este límite se aplica solo a las lecturas de resultados de tareas.
Respuesta — 200 OK
Un arreglo de objetos de tarea. Los campos exactos dependen del tipo de tarea; la base común incluye
id, name, taskType,
enabled, interval,
lastState, creationTime,
tags, agentPools, y (cuando se solicita mediante
info) subscriptions,
stats, results y
attached. Cuando se incluyen resultados, cada resultado lleva al menos
timestamp (segundos Unix UTC) y eventNumber; los
campos restantes son específicos del tipo de tarea (consulte la respuesta de creación más abajo para
conocer la forma de HTTP).
GET BASE_URL/tasks?info=stats,subscriptions&taskType=Http HTTP/1.1
Accept: application/json
Authorization: bearer <token>
GET tasks/{id:guid}
Obtiene una única tarea por id. Acepta el mismo parámetro info (y
sdtu/edtu cuando info=results).
Devuelve el objeto de tarea, o 404 NotFound si no existe.
POST tasks/http · tasks/ping · tasks/port · tasks/rusbl
Crea una tarea de monitoreo del tipo indicado. Si tiene éxito, devuelve 201 Created, un
encabezado relativo Location: /tasks/{id}, y el objeto completo de la tarea creada.
Cuerpo de la solicitud — tarea HTTP
{
// campos específicos de HTTP
"url": "https://www.example.com", // OBLIGATORIO
"httpMethod": "Get", // Get | Post | Head (por defecto Get)
"userAgent": "MyMonitor",
"referer": "https://www.google.com",
"acceptHeader": "application/json",
"followRedirect": false,
"treat300AsError": false, // si se activa, followRedirect se ignora
"checkDnsbl": false, // verifica el dominio contra listas de bloqueo DNS
"checkDomainExpiration": false, // monitorea la caducidad del dominio (solo dominios válidos)
"checkCertificateExpiration": false, // monitorea la caducidad del certificado TLS (solo https)
"checkRussianBlackLists": false,
"checkWebRisk": false,
"timeout": 40000, // ms antes de que una verificación falle
"keywords": ["error", "maintenance"],
"keywordMode": "ReverseAny", // ver los modos de palabra clave más abajo
"userName": "basic-auth-user", // credenciales para el recurso monitoreado
"password": "basic-auth-pass",
"postParameters": "a=1\r\nb=2", // solo con httpMethod=Post
"ignoredStatuses": [404, 500],
// campos comunes a todos los tipos de tarea
"interval": 5, // minutos; debe ser un intervalo aceptado
"enabled": true,
"fullLog": false, // solo paquetes avanzados
"openStat": true,
"name": "My website",
"tags": ["production", "web"],
"agentPools": ["westeurope", "asia"], // ver notas más abajo
"subscriptions": [ /* suscripciones en línea, ver más abajo */ ]
}
| Modo de palabra clave | La tarea está OK cuando… |
|---|---|
PresentAny | cualquier palabra clave está presente en la respuesta. |
PresentAll | todas las palabras clave están presentes. |
ReverseAny | todas las palabras clave están ausentes. |
ReverseAll | cualquier palabra clave está ausente. |
ReverseWithResult | todas las palabras clave están ausentes; el mensaje de fallo incluye el resto de la línea de respuesta donde apareció la primera palabra clave (se analizan los primeros 100 caracteres de cada línea). |
agentPools selecciona las ubicaciones de monitoreo. Es opcional (de lo
contrario se usa el valor predeterminado del perfil). Si se especifica, los pools deben contener en
conjunto al menos 7 agentes, o la solicitud falla con SelectMoreAgents. Los
ids de pool desconocidos fallan con WrongAgentPool. Los ids de pool provienen
de GET agents/pools.
Suscripciones en línea
El arreglo subscriptions suscribe contactos a las alertas/informes de esta
tarea en el momento de la creación. Cada entrada usa la forma de suscripción;
no establezca taskIds (queda fijado a la nueva tarea). Si se omite
contactIds, se suscriben todos sus contactos confirmados. Las suscripciones de
informes se aplican solo a contactos de tipo Email.
Otros tipos de tarea
tasks/ping— el cuerpo llevahostademás de los campos comunes.tasks/port— el cuerpo llevahostyportademás de los campos comunes.tasks/rusbl— comprobación de lista de bloqueo del registro ruso; el cuerpo llevaurl, además deignoreWarnings,doNotSendMsgOnWarnings,prefixMatchy los campos comunes.
Respuesta — 201 Created (tarea HTTP)
{
"id": "ef10cd12-93f9-e311-bec5-dc85de1f0bc2",
"url": "https://www.example.com",
"rawUrl": "https://www.example.com",
"name": "My website",
"creationTime": "2024-06-21T22:26:23Z",
"taskType": "Http",
"enabled": true,
"interval": 5,
"lastState": true,
"openStatEnabled": true,
"fullLogEnabled": false,
"tags": ["production", "web"],
"agentPools": ["westeurope", "asia"],
"subscriptions": [
{ "alertTypes": ["Up"], "taskIds": ["ef10cd12-...-0bc2"], "contactIds": ["4cedf037-...-0bc2"] },
{ "alertTypes": ["Down"], "taskIds": ["ef10cd12-...-0bc2"], "contactIds": ["4cedf037-...-0bc2"] },
{ "reportTypes": ["Month"], "taskIds": ["ef10cd12-...-0bc2"], "contactIds": ["4cedf037-...-0bc2"] }
],
"httpMethod": "Get",
"keywords": ["error"],
"keywordMode": "ReverseAny",
"timeout": 40000
}
curl
curl -s -X POST https://api1.host-tracker.com/tasks/http \
-H "Authorization: bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"url":"https://www.example.com","interval":5,"name":"My website"}'
PUT tasks y variantes tipadas
Actualiza tareas. Dos formas:
- Por id —
PUT tasks/{id}(solo campos comunes), o los tipadosPUT tasks/http/{id},tasks/ping/{id},tasks/port/{id},tasks/rusbl/{id}(también campos específicos del tipo). El cuerpo tiene la misma forma editable que en la creación; solo se modifican los campos que incluya. - Por filtro —
PUT tasks?<filter>(solo campos comunes) o el tipadoPUT tasks/{type}?<filter>(que fija el filtro a ese tipo). Usa los mismos parámetros de filtro que GET tasks. Devuelve la(s) tarea(s) actualizada(s).
El PUT tasks / PUT tasks/{id} sin tipar solo puede
modificar los campos comunes a todos los tipos de tarea — use un endpoint tipado para cambiar
configuraciones específicas del tipo.
DELETE tasks/{id:guid} & tasks
DELETE tasks/{id}— elimina una única tarea; devuelve la tarea eliminada.DELETE tasks?<filter>— elimina en bloque según el filtro de tareas (el filtro también puede proporcionarse en el cuerpo de la solicitud). Devuelve las tareas eliminadas.
DELETE tasks masivo sin filtro selectivo
devuelve 400 EmptyFilter en lugar de eliminar toda su cuenta. Para eliminar
todo intencionalmente, itere explícitamente.
POST tasks/$batch · task/$batch
Ejecuta varias operaciones de tareas en una sola solicitud. El cuerpo es un arreglo JSON de subsolicitudes;
la respuesta es un arreglo JSON de subrespuestas en el mismo orden. La suboperación se elige según el
último segmento de relativeUrl (por ejemplo, http →
POST tasks/http). El cuerpo de la solicitud debe ser JSON
(Content-Type: application/json). El mismo mecanismo existe para contactos en
contacts/$batch / contact/$batch.
| Campo de la solicitud | Tipo | Descripción |
|---|---|---|
method | string | Método HTTP de la subsolicitud (POST, PUT, DELETE…). |
relativeUrl | string | Subrecurso; el último segmento selecciona la operación (http, ping, port, rusbl…). |
contentType | string | Tipo de contenido de content, normalmente application/json. |
content | string | El cuerpo de la subsolicitud, como una cadena JSON. |
| Campo de la respuesta | Tipo | Descripción |
|---|---|---|
code | int | Código de estado HTTP de la subrespuesta (por ejemplo, 201, 400). |
status | string | Texto de motivo/estado (lleva el código de máquina en caso de errores). |
headers | object | Encabezados de respuesta de la suboperación (por ejemplo, Location). |
body | string | El cuerpo de la subrespuesta. |
POST BASE_URL/tasks/$batch HTTP/1.1
Authorization: bearer <token>
Content-Type: application/json
[
{
"method": "POST",
"relativeUrl": "http",
"contentType": "application/json",
"content": "{\"url\":\"https://a.example.com\",\"interval\":5}"
},
{
"method": "POST",
"relativeUrl": "ping",
"contentType": "application/json",
"content": "{\"host\":\"b.example.com\"}"
}
]
[
{ "code": 201, "status": "Created",
"headers": { "Location": "/tasks/ef10cd12-...-0bc2" },
"body": "{ ...created http task... }" },
{ "code": 201, "status": "Created",
"headers": { "Location": "/tasks/7a20de34-...-1cd3" },
"body": "{ ...created ping task... }" }
]
Contactos
Los contactos son los destinos que reciben alertas e informes (direcciones de correo electrónico, números de teléfono para SMS/voz). Los ids de contacto se usan al crear suscripciones.
GET contacts/types · contacts/delays · contacts/sms/gateways · contacts/im/gateways
Enumeraciones estáticas utilizadas por los endpoints de contacto:
| Endpoint | Devuelve |
|---|---|
contacts/types | ["Email","IM","SMS","VoiceCall"] — los tipos de contacto que esta API enumera. Los tipos que se pueden crear son Email, SMS y VoiceCall (IM está retirado — vea más abajo). |
contacts/delays | Los valores aceptados de alertDelay (minutos): [0,5,15,30,60,180,720,360,1440,3]. |
contacts/sms/gateways | Ids de gateway de SMS: ["clickatell","clickatella","infobip","skype","twiliosms"]. El predeterminado es twiliosms; las demás entradas son heredadas y pueden estar inactivas. |
contacts/im/gateways | Ids de gateway de IM: ["GTalk","SkypeChat"]. Se listan solo por compatibilidad — los contactos IM ya no se pueden crear (vea más abajo). |
GET contacts/im/gateways sigue
devolviendo la lista de gateways, pero POST contacts/im y
PUT contacts/im ahora devuelven 400 WrongContactType.
Los contactos IM existentes no se pueden crear a través de esta API.
GET contacts & contacts/{id:guid}
Lista los contactos (opcionalmente filtrados) u obtiene uno por id. Agregue ?info=subscriptions
para incrustar las suscripciones de cada contacto. Sin filtro, se devuelven todos los contactos de la cuenta.
| Parámetro de filtro | Tipo | Descripción |
|---|---|---|
ids / excludeIds | guid[] / bool | Selecciona o excluye por id. |
contactType / contactTypes | string / string[] | Filtra por tipo (Email, SMS, VoiceCall…). |
excludeContactTypes | bool | Invierte el filtro de tipo. |
confirmed | bool | Contactos confirmados frente a no confirmados. |
overlimited | bool | Contactos marcados por exceder el límite del paquete. |
acceptBillingNotifications | bool | Contactos usados para notificaciones de facturación. |
name / names / nameSearchLike / excludeNames | string(s) / bool | Filtra por nombre (exacto, lista, subcadena o excluido). |
address / addresses / addressSearchLike / excludeAddresses | string(s) / bool | Filtra por dirección. |
Objeto de contacto
Campos comunes: id, confirmed,
contactType, name,
address, alertDelay,
activePeriodStart/activePeriodEnd (HH:mm),
activeDays, sendCost. Los contactos de Email agregan
reportFormat (Text/ShortText),
sendNews, sendBillingNotifications; los contactos
SMS/IM agregan gateway.
POST contacts/email · contacts/sms · contacts/voice
Crea un contacto. Devuelve 201 Created, un encabezado relativo
Location: /contacts/{id}, y un ContactOperationResult
({ contact, status }) cuyo status informa el
resultado de la confirmación.
{
"address": "ops@@example.com", // OBLIGATORIO
"name": "Ops mailbox",
"alertDelay": 0, // minutos; uno de contacts/delays
"reportFormat": "Text", // Text | ShortText (solo email)
"activePeriodStart": "00:00", // ventana opcional de horas de silencio (HH:mm)
"activePeriodEnd": "23:59",
"activeDays": ["Monday", "Tuesday"], // opcional; por defecto todos los días
"subscriptions": [ /* suscripciones en línea opcionales */ ]
}
| Campo | Aplica a | Notas |
|---|---|---|
address | todos | Dirección de correo electrónico, o número de teléfono (dígitos, + inicial opcional) para SMS/voz. Requerido al crear. |
alertDelay | todos | Minutos a esperar antes de alertar. Debe ser uno de contacts/delays. |
activePeriodStart / activePeriodEnd | todos | HH:mm; la ventana durante la cual se entregan las alertas. |
activeDays | todos | Cualquiera de Sunday…Saturday; el valor predeterminado es todos los días. |
reportFormat, sendNews, sendBillingNotifications | Opciones de correo electrónico. | |
gateway | sms | Uno de contacts/sms/gateways; predeterminado twiliosms. |
Los contactos SMS y de voz usan de forma predeterminada los gateways twiliosms /
twiliovoice, obtienen un precio predeterminado por mensaje, y almacenan el
número con un + inicial. Cambiar la dirección o el gateway de un contacto
reinicia su estado de confirmación.
Valores de estado de confirmación
El campo status del resultado informa el resultado del envío del código de
confirmación:
| Estado | Significado |
|---|---|
Confirmed | Contacto creado ya confirmado (no se necesita código). |
CodeSent | Se envió un código de confirmación; el contacto se activa una vez confirmado. |
CodeSentEarlier | Ya se envió un código recientemente y sigue siendo válido. |
CodeFail | Contacto creado pero falló el envío del código; reintente más tarde. |
LowSmsBalance | No se pudo enviar el código porque el saldo de la cuenta es demasiado bajo. |
Overlimited | El contacto excede el límite del paquete. |
PUT contacts y variantes tipadas
- Por id —
PUT contacts/{id}(campos comunes), o los tipadosPUT contacts/email/{id},contacts/sms/{id},contacts/voice/{id}. Solo se modifican los campos que envíe. - Por filtro —
PUT contacts?<filter>o el tipadoPUT contacts/{type}?<filter>(que fija el filtro a ese tipo), usando el filtro de contactos.
PUT contacts/im (ambas formas) devuelve 400 WrongContactType.
DELETE contacts/{id:guid} & contacts
Elimina un contacto por id, o elimina en bloque según el filtro de contactos. Al
igual que con las tareas, una eliminación en bloque con un filtro vacío se rechaza con
400 EmptyFilter.
Códigos de confirmación
Los contactos no confirmados deben confirmar la propiedad con un código corto entregado a la dirección del contacto.
PATCH contacts/{id}/code— (re)emite y envía el código de confirmación. Devuelve unContactOperationResultcon un status comoCodeSent.POST contacts/{id}/code— confirma el contacto enviando el código. Cuerpo:{ "code": "12345" }. Si tiene éxito, el contacto queda confirmado.
Alertas y suscripciones
Una suscripción vincula una o más tareas y contactos con un conjunto de tipos de alerta y/o informe. Una única entrada de suscripción combina de forma cruzada sus tareas y contactos, produciendo una alerta/informe por cada (tarea, contacto, tipo).
Forma de la suscripción
{
"alertTypes": ["Up", "Down"], // cualquiera de Up, Down, RepeatedlyDown
"reportTypes": ["Day", "Month"], // cualquiera de Day, Week, Month, Quarter, Year
"taskIds": ["<task guid>"],
"contactIds": ["<contact guid>"]
}
- Se requiere al menos uno de
alertTypes/reportTypes, de lo contrarioAlertsAndReportsAreEmpty. - Omitir
taskIdsequivale a todas sus tareas; omitircontactIdsequivale a todos sus contactos. Un arreglo vacío explícito significa "ninguno". - Las suscripciones de informes se aplican solo a contactos de tipo Email — los tipos de informe en contactos que no son Email se ignoran silenciosamente (sus suscripciones de alerta sí se crean).
- Los ids que no le pertenecen se ignoran.
GET subscriptions/alertTypes · subscriptions/reportTypes
| Endpoint | Devuelve |
|---|---|
subscriptions/alertTypes | ["Up","Down","RepeatedlyDown"] |
subscriptions/reportTypes | ["Day","Week","Month","Quarter","Year"] |
GET subscriptions
Lista las suscripciones. Devuelve una entrada por cada suscripción de alerta o informe encontrada (nunca combinadas). Filtros opcionales:
| Parámetro | Tipo | Descripción |
|---|---|---|
taskId | guid | Solo suscripciones para esta tarea. |
contactId | guid | Solo suscripciones para este contacto. |
types | string[] | Solo estos tipos de alerta/informe. Aquí los nombres no reconocidos se ignoran (a diferencia de POST/DELETE, que los rechazan). |
POST subscriptions · DELETE subscriptions
Ambos toman un arreglo JSON de entradas de suscripción en el cuerpo. POST agrega las suscripciones
descritas (solo se insertan las filas nuevas); DELETE elimina las que existen. Ambos devuelven
200 OK con un cuerpo vacío. Los tipos de alerta/informe desconocidos se
rechazan con UnknownAlertType / UnknownReportType.
[
{ "alertTypes": ["Up", "Down"],
"taskIds": ["7ee87894-b8a9-e311-beb2-dc85de1f0bc2"],
"contactIds": ["4cedf037-d1d9-e311-bebc-dc85de1f0bc2"] },
{ "reportTypes": ["Month"],
"taskIds": ["7ee87894-b8a9-e311-beb2-dc85de1f0bc2"],
"contactIds": ["4cedf037-d1d9-e311-bebc-dc85de1f0bc2"] }
]
curl -s -X POST https://api1.host-tracker.com/subscriptions \
-H "Authorization: bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '[{"alertTypes":["Up","Down"],"taskIds":["<task>"],"contactIds":["<contact>"]}]'
Estadísticas y resultados
GET stats
Agregados de tiempo de actividad/inactividad por tarea en una ventana de tiempo. Acepta el filtro de tareas para seleccionar tareas, además de:
| Parámetro | Tipo | Descripción |
|---|---|---|
statsStartUnix / statsEndUnix | int64 | Inicio/fin de la ventana en segundos Unix (UTC). |
statsStart / statsEnd | string | Inicio/fin de la ventana como cadena de fecha formateada según el perfil (alternativa a los campos Unix). |
expectedSLA | double | 0–100. Cuando se establece, cada resultado informa slaExpectationSucceeded. |
fullTask | bool | Incluye el objeto completo de la tarea en lugar de solo su referencia. |
Respuesta
Un objeto Stats con la ventana resuelta (campos de fecha duales) y un arreglo
stats. Cada entrada lleva la referencia de la tarea y:
uptimeInMinutes/uptimeSpan,
downtimeInMinutes/downtimeSpan, los tiempos de
actividad/inactividad por mantenimiento, totalTimeInMinutes, los recuentos de
comprobaciones por bucket, y
uptimePercent/downtimePercent.
uptime% = (uptime + maintenanceUptime) / (totalTime − maintenanceDowntime).
Cuando el tiempo total es igual al tiempo de inactividad por mantenimiento, el porcentaje es null (indefinido).
slaExpectationSucceeded es uptime% ≥ expectedSLA.
GET outages
Intervalos de inactividad por tarea. Acepta el filtro de tareas además de:
| Parámetro | Tipo | Descripción |
|---|---|---|
startTimeUnix / endTimeUnix | int64 | Ventana en segundos Unix (UTC). |
startTime / endTime | string | Ventana como cadenas formateadas según el perfil. |
getInUtcTimeZone | int | Cuando se establece, las horas formateadas son UTC en lugar de la zona horaria del perfil. |
fullTask | bool | Incluye el objeto completo de la tarea. |
Respuesta: un objeto Outages con la ventana resuelta y un arreglo
taskOutages; cada elemento asocia una tarea con sus intervalos
outages (startTime/endTime
+ variantes Unix, números de evento, comentario opcional).
GET incident
Lista de incidentes (eventos de fallo) por tarea. Acepta el filtro de tareas más los mismos parámetros de ventana/zona horaria que outages, además de:
| Parámetro | Tipo | Descripción |
|---|---|---|
startTimeUnix / endTimeUnix / startTime / endTime | int64 / string | Ventana (Unix y/o formateada). |
getInUtcTimeZone | int | Formatea las horas en UTC. |
fullTask | bool | Incluye el objeto completo de la tarea. |
fullLog | bool | Incluye el registro detallado de reverificación por agente. Requiere un paquete avanzado; de lo contrario, ApiFullLogNotAllowed. |
Respuesta: un objeto Incidents con un arreglo
taskIncidents. Cada incidente lleva taskId,
checkId, las horas Unix de inicio/fin, la location
que falló, el error, hasSnapshot, y (con
fullLog) un bloque recheck que enumera las
ubicaciones OK y las ubicaciones con fallo por cada error.
GET incident/snapshot
Obtiene la instantánea de la respuesta almacenada capturada para un incidente. Parámetros:
| Parámetro | Tipo | Descripción |
|---|---|---|
taskId | guid | La tarea. Requerido. |
checkId | int64 | El id de la comprobación/evento. |
timestampUnixUtc | int64 | La marca de tiempo del incidente (segundos Unix UTC). |
Devuelve la instantánea (una marca de tiempo más los bytes capturados) cuando existe, o
null cuando no hay instantánea para el incidente indicado.
GET results/http
Métricas agregadas de tiempo HTTP por tarea. Fuerza el tipo de tarea Http.
Acepta el filtro de tareas además de:
| Parámetro | Tipo | Descripción |
|---|---|---|
resultStartUnix / resultEndUnix | int64 | Ventana en segundos Unix (UTC). |
resultStart / resultEnd | string | Ventana como cadenas formateadas según el perfil. |
fullTask | bool | Incluye el objeto completo de la tarea. |
Respuesta: un objeto AggregatedHttpResults; cada entrada de
taskResults informa la referencia de la tarea y los promedios de
responseTime, dnsTime,
headTime, dataTime (milisegundos).
GET cr/httpResponseTime
Serie temporal de tiempo de respuesta HTTP por tarea. Acepta el filtro de tareas
además de startDate, endDate y
groupBy. Devuelve un arreglo simple de objetos de serie:
[
{
"id": "ef10cd12-93f9-e311-bec5-dc85de1f0bc2",
"rawUrl": "https://www.example.com",
"name": "My website",
"results": [ [1719181583, 142], [1719177983, 138] ] // [unixSeconds, responseTimeMs], más recientes primero
}
]
Agentes
Los agentes son las ubicaciones de monitoreo distribuidas geográficamente. Los ids de pool devueltos aquí
son los valores que se pasan en el agentPools de una tarea.
GET agents
Lista los agentes de monitoreo. Parámetro de consulta opcional:
| Parámetro | Tipo | Descripción |
|---|---|---|
touched | int | Solo agentes que reportaron en los últimos N minutos. Valores ≤ 0 (o ausentes) significan sin filtro; de lo contrario se limita al rango 1–10. |
Cada agente lleva id, upFrom,
datacenter (name/city/country/state),
company (name/url), ip,
version, lon/lat, y
pools.
[
{
"id": "a1b2c3d4-...-0001",
"upFrom": "2024-06-20T08:00:00Z",
"datacenter": { "name": "Example Hosting", "city": "Frankfurt", "country": "DE", "state": "" },
"company": { "name": "Example Hosting", "url": "https://example-hosting.com" },
"ip": "203.0.113.10",
"version": "1.4.2",
"lon": 8.68, "lat": 50.11,
"pools": []
}
]
GET agents/pools
Lista los pools de agentes públicos (regiones geográficas). Cada pool lleva id,
desc, sus agents,
childPools, y hidden. Use los valores de
id de pool en el agentPools de una tarea.
GET agents/ips anónimo
Devuelve las direcciones IP actuales de los agentes de monitoreo — útil para incluir a Host-Tracker en
la lista blanca de un firewall. Este endpoint no requiere autenticación. De forma predeterminada devuelve
text/plain, una IP por línea; envíe Accept: application/json
para recibir en su lugar un arreglo JSON.
203.0.113.10
203.0.113.11
198.51.100.7
["203.0.113.10", "203.0.113.11", "198.51.100.7"]