Нет подходящих разделов.

Host-Tracker REST API v1

Стабильный HTTP API с токен-аутентификацией для управления задачами мониторинга сайтов, контактами, подписками на оповещения/отчёты, а также для чтения статистики, простоев и инцидентов.

Базовый URL

Каждый путь в этом документе указан относительно базового URL. Один и тот же API обслуживают две точки входа:

Далее в этом справочнике запись вида GET tasks означает GET BASE_URL/tasks — например, https://api1.host-tracker.com/tasks или https://www.host-tracker.com/api/web/v1/tasks.

Тип содержимого и методы HTTP

По умолчанию запросы и ответы имеют тип application/json (см. Соглашения про XML). API использует стандартные методы HTTP:

• GET — чтение сущностей (задачи, контакты, подписки, статистика, простои, инциденты, агенты).
• POST — создание сущности или запуск действия.
• PUT — обновление существующих сущностей.
• DELETE — удаление сущностей.
• PATCH — частичные обновления (используется для повторной отправки кода подтверждения контакта).

Переопределение метода HTTP

Если ваш клиент не может отправлять PUT, DELETE или PATCH, отправьте POST и добавьте заголовок X-HTTP-Method-Override с именем нужного метода. Например, чтобы обновить задачи, отправьте POST на tasks с заголовком X-HTTP-Method-Override: PUT.

Соглашения

Сериализация JSON

В JSON используются имена свойств в стиле camelCase. Пустые (null) поля не включаются в ответ (пустые массивы по-прежнему передаются как []). Порядок свойств стабилен: сначала идентификатор и адрес/url, затем унаследованные поля, затем поля, специфичные для типа.

Дата и время

В ответах на создание/чтение задач метки времени передаются в виде строк ISO-8601 UTC (например, 2024-06-21T22:26:23Z). Точки входа для статистики, простоев, инцидентов и результатов дополнительно используют двойное представление: каждое время присутствует и как поле целого числа в секундах Unix (с суффиксом Unix), и как удобочитаемая строка, отформатированная согласно формату даты и часовому поясу профиля аккаунта. Фильтры запроса принимают секунды Unix и/или отформатированные строки в зависимости от точки входа (описано ниже для каждой точки входа). Все метки времени Unix — это количество секунд с 1970-01-01T00:00:00Z.

Согласование содержимого XML

Все точки входа также могут возвращать XML. Отправьте заголовок Accept: application/xml, чтобы получить тело ответа в формате XML вместо JSON; в ответе используется классическое представление объектного графа через .NET XmlSerializer. JSON — формат по умолчанию и рекомендуемый.

CORS

Межсайтовые запросы разрешены. Обычные (без передачи учётных данных) запросы принимаются с любого источника (Access-Control-Allow-Origin: *). Запросы, передающие cookie/учётные данные, принимаются только с источников *.host-tracker.com. На вызовы по токену (с использованием заголовка Authorization, как описано здесь) ограничение по источникам с учётными данными не распространяется.

Аутентификация

Аутентификация требуется для каждой точки входа, кроме POST users/token и анонимных точек входа со списком агентов. Поддерживаются две схемы:

• Bearer-токен — получается через POST users/token, передаётся как Authorization: bearer <token>. Это основная схема.
• HTTP Basic — Authorization: Basic <base64(login:password)>. Учётные данные декодируются как ISO-8859-1. Удобно для быстрых тестов; для автоматизации предпочтителен bearer-токен.

POST users/token анонимно

Обменивает логин и пароль на bearer-токен. Токен действителен в течение 48 часов.

Тело запроса

{
  "login": "your-login",
  "password": "your-password"
}

Ответ — 200 OK

{
  "ticket": "<bearer token>",
  "expirationTime": "2024-06-23T22:26:23Z",
  "expirationUnixTime": 1719181583
}

При ошибке возвращается ответ 401 с машинным кодом IncorrectLoginOrPassword (или AccessDenied, если для аккаунта отключён доступ к API) и заголовком WWW-Authenticate: Bearer.

Использование токена

GET BASE_URL/tasks HTTP/1.1
Host: api1.host-tracker.com
Accept: application/json
Authorization: bearer 3DD135...5EE510417

Олицетворение субаккаунта (forLogin)

Если супераккаунт предоставил вашему субаккаунту доступ к своим данным, войдите как субаккаунт, но передайте логин супераккаунта в forLogin. Возвращённый токен позволит управлять супераккаунтом так, как если бы точки входа вызывались для вашего собственного аккаунта, в рамках прав, предоставленных супераккаунтом. Например, если он предоставил доступ только на чтение задач мониторинга, вызовы GET будут успешны, а POST/PUT/PATCH/DELETE для задач будут отклонены.

# 1. Получаем токен олицетворения
POST BASE_URL/users/token HTTP/1.1
Content-Type: application/json

{
  "login": "subaccount-login",
  "password": "subaccount-password",
  "forLogin": "superaccount-login"
}

# 2. Используем полученный ticket для чтения задач СУПЕРАККАУНТА
GET BASE_URL/tasks HTTP/1.1
Authorization: bearer <ticket from step 1>

curl

# получаем токен и сохраняем его
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)

# вызываем защищённую точку входа
curl -s https://api1.host-tracker.com/tasks \
  -H "Authorization: bearer $TOKEN"

Ошибки и машинные коды

Ошибки возвращаются со стандартным HTTP-кодом статуса и коротким машиночитаемым кодом, по которому ваша интеграция может ветвить логику. Тело ответа — обычный текст на английском языке (не JSON), предназначенный для людей/логов.

Машинный код передаётся двумя способами:

• заголовок ответа X-HT-Reason — содержит код в каждом ответе и при любой версии HTTP. Это рекомендуемый способ определения типа ошибки.
• фраза причины HTTP/1.1 — строка статуса выглядит, например, так: HTTP/1.1 400 SimilarExists. Сохранена для обратной совместимости, однако учтите, что в HTTP/2 и HTTP/3 фразы причины были удалены из протокола, поэтому это поле может быть пустым, если соединение согласовало HTTP/2+. Предпочитайте X-HT-Reason.

HTTP/1.1 400 SimilarExists
X-HT-Reason: SimilarExists
Content-Type: text/plain; charset=utf-8

Same task allready exists

Справочник кодов ошибок

Все машинные коды, которые может вернуть API, сгруппированные по областям, с типичным HTTP-статусом. Если не указано иное, ошибки возвращаются как 400 Bad Request.

Аутентификация

Задачи

Контакты

Подписки

Ограничения частоты запросов

Запросы ограничиваются по частоте для каждого клиента и каждой точки входа отдельно. При превышении лимита возвращается 429 с машинным кодом RequestThrottled и заголовком Retry-After (в секундах).

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

Задачи мониторинга

GET tasks/types

Возвращает массив известных системе имён типов задач:

["API","CntCheck","Counter","DNSBL","Database","DomainExp","Http",
 "Ping","Port","RusRegBL","SSLExp","Snmp","Tran","Waterfall","WebRisk"]

GET tasks/intervals

Возвращает массив интервалов мониторинга (в минутах), допустимых для вашего аккаунта, например [1,5,15,30,60]. Используйте одно из этих значений для поля interval при создании задачи; любое другое значение приведёт к WrongInterval.

GET tasks

Список задач мониторинга. Все параметры запроса необязательны; без параметров возвращаются все задачи аккаунта. Чтобы передать массив, повторите параметр, например ?ids=guid1&ids=guid2.

Параметр info

Запрашивает дополнительные данные, встраиваемые в каждую задачу. Значения можно объединять через запятую (?info=stats,subscriptions) либо передать эквивалентное целое число-битовую маску:

?info=stats,subscriptions,results эквивалентно ?info=7.

Параметры фильтра

Ответ — 200 OK

Массив объектов задач. Точный набор полей зависит от типа задачи; общая база включает id, name, taskType, enabled, interval, lastState, creationTime, tags, agentPools, а также (если запрошено через info) subscriptions, stats, results и attached. Если включены результаты, каждый результат содержит как минимум timestamp (секунды Unix, UTC) и eventNumber; остальные поля зависят от типа задачи (см. ниже пример ответа на создание HTTP-задачи).

GET BASE_URL/tasks?info=stats,subscriptions&taskType=Http HTTP/1.1
Accept: application/json
Authorization: bearer <token>

GET tasks/{id:guid}

Получить одну задачу по id. Принимает тот же параметр info (а также sdtu/edtu при info=results). Возвращает объект задачи либо 404 NotFound, если задача не существует.

POST tasks/http · tasks/ping · tasks/port · tasks/rusbl

Создаёт задачу мониторинга указанного типа. При успехе возвращается 201 Created, относительный заголовок Location: /tasks/{id} и полный объект созданной задачи.

Тело запроса — HTTP-задача

{
  // поля, специфичные для HTTP
  "url": "https://www.example.com",        // ОБЯЗАТЕЛЬНО
  "httpMethod": "Get",                       // Get | Post | Head (по умолчанию Get)
  "userAgent": "MyMonitor",
  "referer": "https://www.google.com",
  "acceptHeader": "application/json",
  "followRedirect": false,
  "treat300AsError": false,                // если задано, followRedirect игнорируется
  "checkDnsbl": false,                       // проверять домен по DNS-чёрным спискам
  "checkDomainExpiration": false,            // отслеживать истечение домена (только для валидных доменов)
  "checkCertificateExpiration": false,       // отслеживать истечение TLS-сертификата (только для https)
  "checkRussianBlackLists": false,
  "checkWebRisk": false,
  "timeout": 40000,                          // мс до фиксации ошибки проверки
  "keywords": ["error", "maintenance"],
  "keywordMode": "ReverseAny",             // см. режимы ключевых слов ниже
  "userName": "basic-auth-user",          // учётные данные для проверяемого ресурса
  "password": "basic-auth-pass",
  "postParameters": "a=1\r\nb=2",          // только с httpMethod=Post
  "ignoredStatuses": [404, 500],

  // поля, общие для всех типов задач
  "interval": 5,                             // минуты; должен быть допустимым интервалом
  "enabled": true,
  "fullLog": false,                          // только на расширенных тарифах
  "openStat": true,
  "name": "My website",
  "tags": ["production", "web"],
  "agentPools": ["westeurope", "asia"],  // см. примечания ниже
  "subscriptions": [ /* встроенные подписки, см. ниже */ ]
}

Встроенные подписки

Массив subscriptions подписывает контакты на оповещения/отчёты этой задачи в момент создания. Каждая запись использует форму подписки; не задавайте taskIds (он фиксирован на новую задачу). Если contactIds не указан, подписываются все ваши подтверждённые контакты. Подписки на отчёты применяются только к контактам типа Email.

Другие типы задач

• tasks/ping — в теле передаётся host плюс общие поля.
• tasks/port — в теле передаются host и port плюс общие поля.
• tasks/rusbl — проверка по чёрным спискам российского реестра; в теле передаётся url, а также ignoreWarnings, doNotSendMsgOnWarnings, prefixMatch и общие поля.

Ответ — 201 Created (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 & типизированные варианты

Обновление задач. Две формы:

• По id — PUT tasks/{id} (только общие поля), либо типизированные PUT tasks/http/{id}, tasks/ping/{id}, tasks/port/{id}, tasks/rusbl/{id} (также поля, специфичные для типа). Тело имеет ту же редактируемую форму, что и при создании; изменяются только присланные поля.
• По фильтру — PUT tasks?<filter> (только общие поля) либо типизированный PUT tasks/{type}?<filter> (закрепляет фильтр за этим типом). Используются те же параметры фильтра, что и у GET tasks. Возвращает обновлённые задачи.

Нетипизированный PUT tasks / PUT tasks/{id} может менять только поля, общие для всех типов задач — чтобы изменить настройки, специфичные для типа, используйте типизированную точку входа.

DELETE tasks/{id:guid} & tasks

• DELETE tasks/{id} — удаляет одну задачу; возвращает удалённую задачу.
• DELETE tasks?<filter> — массовое удаление по фильтру задач (фильтр также может быть передан в теле запроса). Возвращает удалённые задачи.

POST tasks/$batch · task/$batch

Выполняет несколько операций над задачами в одном запросе. Тело — JSON-массив вложенных запросов; ответ — JSON-массив вложенных ответов в том же порядке. Подоперация выбирается по последнему сегменту relativeUrl (например, http → POST tasks/http). Тело запроса должно быть в формате JSON (Content-Type: application/json). Тот же механизм существует для контактов на contacts/$batch / contact/$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\"}"
  }
]

[
  { "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... }" }
]

Контакты

Контакты — это адресаты, которые получают оповещения и отчёты (email-адреса, номера телефонов для SMS/голосовых звонков). Id контактов используются при создании подписок.

GET contacts/types · contacts/delays · contacts/sms/gateways · contacts/im/gateways

Статические перечисления, используемые точками входа для контактов:

GET contacts & contacts/{id:guid}

Список контактов (опционально с фильтром) или получение одного по id. Добавьте ?info=subscriptions, чтобы включить подписки каждого контакта. Без фильтра возвращаются все контакты аккаунта.

Объект контакта

Общие поля: id, confirmed, contactType, name, address, alertDelay, activePeriodStart/activePeriodEnd (HH:mm), activeDays, sendCost. Email-контакты дополнительно содержат reportFormat (Text/ShortText), sendNews, sendBillingNotifications; SMS/IM-контакты дополнительно содержат gateway.

POST contacts/email · contacts/sms · contacts/voice

Создаёт контакт. Возвращает 201 Created, относительный заголовок Location: /contacts/{id} и ContactOperationResult ({ contact, status }), чьё поле status сообщает об исходе подтверждения.

{
  "address": "ops@@example.com",          // ОБЯЗАТЕЛЬНО
  "name": "Ops mailbox",
  "alertDelay": 0,                        // минуты; одно из contacts/delays
  "reportFormat": "Text",               // Text | ShortText (только email)
  "activePeriodStart": "00:00",        // необязательное окно "тихих часов" (HH:mm)
  "activePeriodEnd": "23:59",
  "activeDays": ["Monday", "Tuesday"],   // необязательно; по умолчанию все дни
  "subscriptions": [ /* необязательные встроенные подписки */ ]
}

SMS- и голосовые контакты по умолчанию используют шлюзы twiliosms / twiliovoice, получают стандартную цену за сообщение и сохраняют номер с ведущим +. Изменение адреса или шлюза контакта сбрасывает его подтверждённое состояние.

Значения статуса подтверждения

Поле status результата сообщает об исходе отправки кода подтверждения:

PUT contacts & типизированные варианты

• По id — PUT contacts/{id} (общие поля), либо типизированные PUT contacts/email/{id}, contacts/sms/{id}, contacts/voice/{id}. Изменяются только присланные поля.
• По фильтру — PUT contacts?<filter> либо типизированный PUT contacts/{type}?<filter> (закрепляет фильтр за этим типом), с использованием фильтра контактов.

PUT contacts/im (в обеих формах) возвращает 400 WrongContactType.

DELETE contacts/{id:guid} & contacts

Удаляет один контакт по id либо выполняет массовое удаление по фильтру контактов. Как и для задач, массовое удаление с пустым фильтром отклоняется с кодом 400 EmptyFilter.

Коды подтверждения

Неподтверждённые контакты должны подтвердить владение коротким кодом, доставляемым на адрес контакта.

• PATCH contacts/{id}/code — (повторно) выпускает и отправляет код подтверждения. Возвращает ContactOperationResult со статусом, например CodeSent.
• POST contacts/{id}/code — подтверждает контакт, передавая код. Тело: { "code": "12345" }. При успехе контакт становится подтверждённым.

Оповещения и подписки

Подписка связывает одну или несколько задач и контактов с набором типов оповещений и/или отчётов. Одна запись подписки декартово перемножает свои задачи и контакты, порождая одно оповещение/отчёт на каждую пару (задача, контакт, тип).

Форма подписки

{
  "alertTypes": ["Up", "Down"],       // любые из Up, Down, RepeatedlyDown
  "reportTypes": ["Day", "Month"],     // любые из Day, Week, Month, Quarter, Year
  "taskIds": ["<task guid>"],
  "contactIds": ["<contact guid>"]
}

• Требуется хотя бы одно из alertTypes / reportTypes, иначе возникает AlertsAndReportsAreEmpty.
• Если taskIds не указан, по умолчанию берутся все ваши задачи; если contactIds не указан, по умолчанию берутся все ваши контакты. Явно заданный пустой массив означает "ни одного".
• Подписки на отчёты применяются только к Email-контактам — типы отчётов для не-Email контактов тихо игнорируются (их подписки на оповещения всё равно создаются).
• Id, которыми вы не владеете, игнорируются.

GET subscriptions/alertTypes · subscriptions/reportTypes

GET subscriptions

Список подписок. Возвращает по одной записи на каждую совпавшую подписку на оповещение или отчёт (никогда не объединяет их). Необязательные фильтры:

POST subscriptions · DELETE subscriptions

Оба метода принимают в теле JSON-массив записей подписки. POST добавляет описанные подписки (вставляются только новые строки); DELETE удаляет существующие. Оба метода возвращают 200 OK с пустым телом. Неизвестные типы оповещений/отчётов отклоняются с 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>"]}]'

Статистика и результаты

GET stats

Агрегаты аптайма/даунтайма по задачам за временное окно. Принимает фильтр задач для выбора задач, а также:

Ответ

Объект Stats с рассчитанным окном (поля даты в двойном представлении) и массивом stats. Каждая запись содержит ссылку на задачу и: uptimeInMinutes/uptimeSpan, downtimeInMinutes/downtimeSpan, время технического обслуживания (up/down), totalTimeInMinutes, количество проверок по интервалам и uptimePercent/downtimePercent.

GET outages

Периоды простоя по задачам. Принимает фильтр задач плюс:

Ответ: объект Outages с рассчитанным окном и массивом taskOutages; каждый элемент связывает задачу с её периодами outages (startTime/endTime + варианты в Unix, номера событий, необязательный комментарий).

GET incident

Список инцидентов (событий сбоя) по задачам. Принимает фильтр задач плюс те же параметры окна/часового пояса, что и outages, а также:

Ответ: объект Incidents с массивом taskIncidents. Каждый инцидент содержит taskId, checkId, время начала/окончания в Unix, location сбойной точки, error, hasSnapshot и (с fullLog) блок recheck со списком успешных локаций и локаций, упавших по каждому виду ошибки.

GET incident/snapshot

Получить сохранённый снимок ответа, зафиксированный для инцидента. Параметры:

Возвращает снимок (метку времени плюс захваченные байты), если он существует, либо null, если снимка для указанного инцидента нет.

GET results/http

Агрегированные метрики времени отклика HTTP по задачам. Принудительно фильтрует по типу задачи Http. Принимает фильтр задач плюс:

Ответ: объект AggregatedHttpResults; каждая запись taskResults содержит ссылку на задачу и усреднённые responseTime, dnsTime, headTime, dataTime (в миллисекундах).

GET cr/httpResponseTime

Ряды времени отклика HTTP по задачам. Принимает фильтр задач плюс startDate, endDate и groupBy. Возвращает простой массив объектов рядов:

[
  {
    "id": "ef10cd12-93f9-e311-bec5-dc85de1f0bc2",
    "rawUrl": "https://www.example.com",
    "name": "My website",
    "results": [ [1719181583, 142], [1719177983, 138] ]   // [секунды Unix, время отклика в мс], сначала новые
  }
]

Агенты

Агенты — это географически распределённые точки мониторинга. Id пулов, возвращаемые здесь, — это значения, которые вы передаёте в поле agentPools задачи.

GET agents

Список агентов мониторинга. Необязательный параметр запроса:

Каждый агент содержит id, upFrom, datacenter (название/город/страна/регион), company (название/url), ip, version, lon/lat и 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

Список публичных пулов агентов (гео-регионов). Каждый пул содержит id, desc, свои agents, childPools и hidden. Используйте значения id пула в поле agentPools задачи.

GET agents/ips анонимно

Возвращает текущие IP-адреса агентов мониторинга — полезно для добавления Host-Tracker в белый список файрвола. Эта точка входа не требует аутентификации. По умолчанию она возвращает text/plain, по одному IP на строку; отправьте заголовок Accept: application/json, чтобы получить 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"]