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.

Esta es la API v1. No ejecuta comprobaciones instantáneas y utiliza un esquema de autenticación distinto al de la API v2 — ambas no son intercambiables. Para comprobaciones instantáneas automatizadas, utilice en su lugar la API v2.

URL base

Cada ruta de este documento es relativa a una URL base. Dos puntos de entrada sirven la misma API:

Punto de entradaURL 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 como Authorization: bearer <token>. Este es el esquema principal.
  • HTTP BasicAuthorization: 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

application/json
{
  "login": "your-login",
  "password": "your-password"
}
CampoTipoDescripción
loginstringLogin de la cuenta. Requerido. También se acepta el correo electrónico de la cuenta.
passwordstringContraseña de la cuenta. Requerido.
forLoginstringOpcional. El login de la cuenta superior en cuyo nombre actuar (suplantación de subcuenta — vea más abajo).

Respuesta — 200 OK

application/json
{
  "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

HTTP
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.

ejemplo de extremo a extremo
# 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

bash
# 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+. Prefiera X-HT-Reason.
ejemplo de respuesta de error
HTTP/1.1 400 SimilarExists
X-HT-Reason: SimilarExists
Content-Type: text/plain; charset=utf-8

Same task allready exists
Desafíos de autenticación. Un token faltante o inválido devuelve 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ódigoEstadoSignificado
AccessDenied401El acceso a la API está deshabilitado para esta cuenta, o el llamador no tiene los derechos necesarios.
IncorrectLoginOrPassword401Login/contraseña rechazados en users/token.
WrongTicket401El token bearer está malformado / es ilegible.
TicketExpired401El token bearer ha expirado — obtenga uno nuevo.
RequestThrottled429Se excedió el límite de tasa (consulte Límites de tasa). Incluye Retry-After.

Tareas

CódigoEstadoSignificado
NotFound404La tarea solicitada no existe.
SimilarExists400Ya existe una tarea con el mismo tipo y clave (a menos que la cuenta permita tareas similares).
EmptyTaskData400No se proporcionaron datos de la tarea.
UncomplitedData400Los datos de la tarea están incompletos.
NoIdInTaskData400Se solicitó una actualización pero falta el id de la tarea.
WrongEditableTaskDataType400El tipo del payload de edición no coincide con el tipo de la tarea objetivo.
WrongTaskType400Tipo de tarea desconocido.
WrongTaskStatus400Valor de status no compatible (se espera Enabled/Disabled).
WrongInterval400El intervalo de monitoreo no es uno de los valores aceptados (consulte tasks/intervals).
EmptyUrl400No se proporcionó URL/host para una tarea que lo requiere.
WrongUrl400La URL no es válida.
WrongSchema400Esquema de URL no compatible.
BadIP400La URL resuelve a una dirección IP denegada o malformada.
UrlInBlackList400La URL está en una lista de bloqueo interna.
WrongHttpMethod400Método HTTP no compatible para una tarea HTTP (permitidos: Get, Post, Head).
WrongKeywordMode400Modo de palabra clave no compatible.
WrongPort400Puerto no válido para una tarea de puerto.
WrongAgentPool400Uno o más pools de agentes solicitados no existen. El mensaje enumera los pools inválidos y los disponibles.
SelectMoreAgents400Los pools de agentes seleccionados no contienen suficientes agentes (se requieren 7). El mensaje enumera los recuentos por pool.
ApiFullLogNotAllowed400fullLog solo está disponible en paquetes avanzados.
WrongExpectedSLA400expectedSLA debe estar entre 0 y 100.
WrongDate400Fecha de inicio/fin no válida en un filtro.
WrongDateFormat400Una cadena de fecha no coincidió con el formato requerido (indicado en el mensaje).
EndDateIsGreaterThanStartDate400La fecha de inicio debe ser ≤ a la fecha de fin.
StartEndIntervalIsTooBig400Una consulta de resultados devolvería más de 10 000 filas. El mensaje incluye el intervalo permitido (consulte GET tasks).
WrongSubscription400Una 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).
EmptyFilter400Se envió un DELETE tasks masivo con un filtro vacío (rechazado para evitar eliminar toda la cuenta).

Contactos

CódigoEstadoSignificado
NotFound404El contacto solicitado no existe.
SimilarExists400Ya existe un contacto con el mismo tipo, gateway, dirección y retraso de alerta.
EmptyContactData400No se proporcionaron datos del contacto.
UncomplitedData400Los datos del contacto están incompletos.
NoIdInContactData400Se solicitó una actualización pero falta el id del contacto.
EmptyAddress400No se proporcionó dirección al crear un contacto.
WrongContactType400Tipo de contacto desconocido (también se devuelve para la ruta retirada de creación/actualización de IM).
WrongEditableContactDataType400El tipo del payload de edición no coincide con el tipo del contacto objetivo.
WrongEmailFormat400Dirección de correo electrónico no válida, o formato de informe de correo no compatible.
WrongPhoneFormat400Un número de teléfono debe contener solo dígitos (se permite un + inicial).
WrongSmsGateway400Gateway de SMS desconocido.
WrongIMGateway400Gateway de IM desconocido.
WrongAlertDelay400alertDelay no es uno de los valores aceptados (consulte contacts/delays).
WrongActivePeriodInterval400Inicio/fin de periodo activo no válido.
WrongActiveDay400Nombre de día activo no compatible.
EmptyFilter400Se envió un DELETE contacts masivo con un filtro vacío (rechazado).

Suscripciones

CódigoEstadoSignificado
AlertsAndReportsAreEmpty400Una entrada de suscripción no especifica ni tipos de alerta ni tipos de informe.
UnknownAlertType400Un tipo de alerta no es uno de Up, Down, RepeatedlyDown.
UnknownReportType400Un 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).

AlcanceLímite
Endpoints generales, por cuenta + endpoint6 solicitudes / segundo y 120 solicitudes / minuto
Endpoints de código de confirmación (contacts/{id}/code), por cuenta + endpoint1 solicitud / segundo y 2 solicitudes / minuto
Endpoints anónimosLos mismos 6/s + 120/min, calculados por dirección IP del cliente
respuesta 429
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:

200 OK
["API","CntCheck","Counter","DNSBL","Database","DomainExp","Http",
 "Ping","Port","RusRegBL","SSLExp","Snmp","Tran","Waterfall","WebRisk"]
Las tareas existentes de cualquiera de estos tipos se pueden leer a través de esta API. Las tareas se pueden crear/actualizar mediante los endpoints tipados solo para cuatro tipos: Http Ping Port RusRegBL (creadas en 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:

ValorBitEfecto
subscriptions1Incluye las suscripciones de alerta/informe de la tarea en subscriptions.
stats2Incluye el tiempo de actividad diario/mensual/anual/total en stats.
results4Incluye los resultados de comprobación para la ventana sdtuedtu en results (el último resultado si se omite la ventana).
attachedResultsIncluye 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ámetroTipoDescripción
idsguid[]Devuelve solo estos ids de tarea. Para un único id, prefiera GET tasks/{id}.
excludeIdsboolCon ids: devuelve todo excepto esos ids.
taskType / taskTypesstring / string[]Filtra por tipo de tarea (sensible a mayúsculas/minúsculas), por ejemplo Http.
excludeTaskTypesboolInvierte el filtro de tipo.
statusstringEnabled o Disabled (deshabilitación por el usuario). Por ejemplo, ?status=Disabled.
url / urlsstring / string[]Filtra por URL. Los valores en urls deben estar codificados como URL.
urlSearchLikeboolCon url (no urls): coincidencia de subcadena en lugar de exacta.
excludeUrlsboolInvierte el filtro de URL.
name / namesstring / string[]Filtra por nombre de tarea. name/names combinado con id/ids es un OR; combinado con otros filtros es un AND.
nameSearchLikeboolCon name: coincidencia de subcadena.
excludeNamesboolInvierte el filtro de nombre.
interval / intervalsint / int[]Filtra por intervalo de monitoreo (minutos).
excludeIntervalsboolInvierte el filtro de intervalo.
openStatboolTareas públicas (estadísticas/registro de eventos públicos).
lastStatebooltrue = actualmente activo, false = actualmente caído.
tagsstring[]Filtra por etiqueta.
overlimitedboolTareas con (true) o sin (false) un exceso de límite de facturación.
activebooltrue = activa, false = deshabilitada por el sistema (exceso de límite, saldo bajo, …). Para deshabilitación por el usuario use status.
sdtu / edtuint64Inicio/fin en segundos Unix (UTC) de una ventana. Se usa solo cuando se establece info=results; proporcione ambos. edtu debe ser > sdtu.
Límite de filas de resultados. Al solicitar resultados, el número estimado de filas (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).

ejemplo de solicitud
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

POST tasks/http · application/json
{
  // 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 claveLa tarea está OK cuando…
PresentAnycualquier palabra clave está presente en la respuesta.
PresentAlltodas las palabras clave están presentes.
ReverseAnytodas las palabras clave están ausentes.
ReverseAllcualquier palabra clave está ausente.
ReverseWithResulttodas 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 lleva host además de los campos comunes.
  • tasks/port — el cuerpo lleva host y port además de los campos comunes.
  • tasks/rusbl — comprobación de lista de bloqueo del registro ruso; el cuerpo lleva url, además de ignoreWarnings, doNotSendMsgOnWarnings, prefixMatch y los campos comunes.

Respuesta — 201 Created (tarea HTTP)

application/json
{
  "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

bash
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 idPUT tasks/{id} (solo campos comunes), o los tipados PUT 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 filtroPUT tasks?<filter> (solo campos comunes) o el tipado PUT 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.
Se rechaza el filtro vacío. Un 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, httpPOST 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 solicitudTipoDescripción
methodstringMétodo HTTP de la subsolicitud (POST, PUT, DELETE…).
relativeUrlstringSubrecurso; el último segmento selecciona la operación (http, ping, port, rusbl…).
contentTypestringTipo de contenido de content, normalmente application/json.
contentstringEl cuerpo de la subsolicitud, como una cadena JSON.
Campo de la respuestaTipoDescripción
codeintCódigo de estado HTTP de la subrespuesta (por ejemplo, 201, 400).
statusstringTexto de motivo/estado (lleva el código de máquina en caso de errores).
headersobjectEncabezados de respuesta de la suboperación (por ejemplo, Location).
bodystringEl cuerpo de la subrespuesta.
solicitud · POST tasks/$batch
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\"}"
  }
]
respuesta · 200 OK
[
  { "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:

EndpointDevuelve
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/delaysLos valores aceptados de alertDelay (minutos): [0,5,15,30,60,180,720,360,1440,3].
contacts/sms/gatewaysIds 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/gatewaysIds de gateway de IM: ["GTalk","SkypeChat"]. Se listan solo por compatibilidad — los contactos IM ya no se pueden crear (vea más abajo).
Los contactos IM están retirados. 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 filtroTipoDescripción
ids / excludeIdsguid[] / boolSelecciona o excluye por id.
contactType / contactTypesstring / string[]Filtra por tipo (Email, SMS, VoiceCall…).
excludeContactTypesboolInvierte el filtro de tipo.
confirmedboolContactos confirmados frente a no confirmados.
overlimitedboolContactos marcados por exceder el límite del paquete.
acceptBillingNotificationsboolContactos usados para notificaciones de facturación.
name / names / nameSearchLike / excludeNamesstring(s) / boolFiltra por nombre (exacto, lista, subcadena o excluido).
address / addresses / addressSearchLike / excludeAddressesstring(s) / boolFiltra 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.

POST contacts/email · application/json
{
  "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 */ ]
}
CampoAplica aNotas
addresstodosDirección de correo electrónico, o número de teléfono (dígitos, + inicial opcional) para SMS/voz. Requerido al crear.
alertDelaytodosMinutos a esperar antes de alertar. Debe ser uno de contacts/delays.
activePeriodStart / activePeriodEndtodosHH:mm; la ventana durante la cual se entregan las alertas.
activeDaystodosCualquiera de SundaySaturday; el valor predeterminado es todos los días.
reportFormat, sendNews, sendBillingNotificationsemailOpciones de correo electrónico.
gatewaysmsUno 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:

EstadoSignificado
ConfirmedContacto creado ya confirmado (no se necesita código).
CodeSentSe envió un código de confirmación; el contacto se activa una vez confirmado.
CodeSentEarlierYa se envió un código recientemente y sigue siendo válido.
CodeFailContacto creado pero falló el envío del código; reintente más tarde.
LowSmsBalanceNo se pudo enviar el código porque el saldo de la cuenta es demasiado bajo.
OverlimitedEl contacto excede el límite del paquete.

PUT contacts y variantes tipadas

  • Por idPUT contacts/{id} (campos comunes), o los tipados PUT contacts/email/{id}, contacts/sms/{id}, contacts/voice/{id}. Solo se modifican los campos que envíe.
  • Por filtroPUT contacts?<filter> o el tipado PUT 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 un ContactOperationResult con un status como CodeSent.
  • POST contacts/{id}/code — confirma el contacto enviando el código. Cuerpo: { "code": "12345" }. Si tiene éxito, el contacto queda confirmado.
Estos endpoints tienen un límite de tasa más estricto: 1 solicitud/segundo y 2 solicitudes/minuto.

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

subscription entry
{
  "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 contrario AlertsAndReportsAreEmpty.
  • Omitir taskIds equivale a todas sus tareas; omitir contactIds equivale 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

EndpointDevuelve
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ámetroTipoDescripción
taskIdguidSolo suscripciones para esta tarea.
contactIdguidSolo suscripciones para este contacto.
typesstring[]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.

POST subscriptions · cuerpo
[
  { "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
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ámetroTipoDescripción
statsStartUnix / statsEndUnixint64Inicio/fin de la ventana en segundos Unix (UTC).
statsStart / statsEndstringInicio/fin de la ventana como cadena de fecha formateada según el perfil (alternativa a los campos Unix).
expectedSLAdouble0–100. Cuando se establece, cada resultado informa slaExpectationSucceeded.
fullTaskboolIncluye 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.

Porcentaje de actividad: 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ámetroTipoDescripción
startTimeUnix / endTimeUnixint64Ventana en segundos Unix (UTC).
startTime / endTimestringVentana como cadenas formateadas según el perfil.
getInUtcTimeZoneintCuando se establece, las horas formateadas son UTC en lugar de la zona horaria del perfil.
fullTaskboolIncluye 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ámetroTipoDescripción
startTimeUnix / endTimeUnix / startTime / endTimeint64 / stringVentana (Unix y/o formateada).
getInUtcTimeZoneintFormatea las horas en UTC.
fullTaskboolIncluye el objeto completo de la tarea.
fullLogboolIncluye 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ámetroTipoDescripción
taskIdguidLa tarea. Requerido.
checkIdint64El id de la comprobación/evento.
timestampUnixUtcint64La 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ámetroTipoDescripción
resultStartUnix / resultEndUnixint64Ventana en segundos Unix (UTC).
resultStart / resultEndstringVentana como cadenas formateadas según el perfil.
fullTaskboolIncluye 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:

200 OK
[
  {
    "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ámetroTipoDescripción
touchedintSolo 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.

200 OK
[
  {
    "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.

text/plain (predeterminado)
203.0.113.10
203.0.113.11
198.51.100.7
con Accept: application/json
["203.0.113.10", "203.0.113.11", "198.51.100.7"]
Host-Tracker REST API v1 — host-tracker.com. Swagger/OpenAPI legible por máquina está disponible en BASE_URL/docs/v1 con un sandbox interactivo en BASE_URL/sandbox.