No matching sections.

Host-Tracker REST API v1

A stable, token-authenticated HTTP API for managing website-monitoring tasks, contacts, alert/report subscriptions, and reading statistics, outages and incidents.

Base URL

Every path in this document is relative to a base URL. Two entry points serve the same API:

Throughout this reference, a call written as GET tasks means GET BASE_URL/tasks — e.g. https://api1.host-tracker.com/tasks or https://www.host-tracker.com/api/web/v1/tasks.

Content type & HTTP methods

Requests and responses are application/json by default (see Conventions for XML). The API uses standard HTTP methods:

• GET — read entities (tasks, contacts, subscriptions, stats, outages, incidents, agents).
• POST — create an entity or start an action.
• PUT — update existing entities.
• DELETE — remove entities.
• PATCH — partial updates (used for resending a contact confirmation code).

HTTP method override

If your client cannot send PUT, DELETE or PATCH, send a POST and add an X-HTTP-Method-Override header naming the intended verb. For example, to update tasks, POST to tasks with X-HTTP-Method-Override: PUT.

Conventions

JSON serialization

JSON uses camelCase property names. Null fields are omitted from responses (empty arrays are still emitted as []). Property ordering is stable: identifier and address/url first, then inherited fields, then type-specific fields.

Date & time

Task create/read responses carry timestamps as ISO-8601 UTC strings (e.g. 2024-06-21T22:26:23Z). The statistics, outages, incidents and results endpoints additionally use a dual representation: each time appears both as a Unix-seconds integer field (suffix Unix) and as a human-readable string formatted to the account's profile date format and time zone. Request filters accept Unix-seconds and/or formatted strings depending on the endpoint (documented per endpoint below). All Unix timestamps are seconds since 1970-01-01T00:00:00Z.

XML content negotiation

All endpoints can also return XML. Send Accept: application/xml to receive an XML body instead of JSON; the response uses the classic .NET XmlSerializer representation of the same object graph. JSON is the default and recommended format.

CORS

Cross-origin requests are allowed. Plain (non-credentialed) requests are accepted from any origin (Access-Control-Allow-Origin: *). Requests that send cookies/credentials are accepted only from *.host-tracker.com origins. Token-based callers (using the Authorization header, as documented here) are unaffected by the credentialed-origin restriction.

Authentication

Every endpoint except POST users/token and the anonymous agent-list endpoints requires authentication. Two schemes are accepted:

• Bearer token — obtained from POST users/token, sent as Authorization: bearer <token>. This is the primary scheme.
• HTTP Basic — Authorization: Basic <base64(login:password)>. Credentials are decoded as ISO-8859-1. Convenient for quick tests; the bearer token is preferred for automation.

POST users/token anonymous

Exchange a login and password for a bearer token. The token is valid for 48 hours.

Request body

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

Response — 200 OK

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

On failure the response is 401 with the machine code IncorrectLoginOrPassword (or AccessDenied if API access is disabled for the account) and a WWW-Authenticate: Bearer header.

Using the token

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

Subaccount impersonation (forLogin)

If a super-account granted your subaccount access to its data, log in as the subaccount but pass the super-account's login in forLogin. The returned token then lets you manage the super-account exactly as if the endpoints were called for your own account, subject to the rights the super-account granted. For example, if it granted read-only access to monitoring tasks, GET calls succeed but POST/PUT/PATCH/DELETE on tasks are rejected.

# 1. Obtain an impersonation token
POST BASE_URL/users/token HTTP/1.1
Content-Type: application/json

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

# 2. Use the returned ticket to read the SUPER-account's tasks
GET BASE_URL/tasks HTTP/1.1
Authorization: bearer <ticket from step 1>

curl

# fetch a token and store it
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)

# call an authenticated endpoint
curl -s https://api1.host-tracker.com/tasks \
  -H "Authorization: bearer $TOKEN"

Errors & machine codes

Errors return a standard HTTP status code plus a short machine-readable code your integration can branch on. The body is a plain-text English description (not JSON), intended for humans/logs.

The machine code is delivered two ways:

• X-HT-Reason response header — carries the code on every response and every HTTP version. This is the recommended way to detect the error type.
• HTTP/1.1 reason phrase — the status line reads e.g. HTTP/1.1 400 SimilarExists. Preserved for backward compatibility, but note that HTTP/2 and HTTP/3 removed reason phrases from the protocol, so this slot may be empty when the connection negotiates HTTP/2+. Prefer X-HT-Reason.

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

Same task allready exists

Error code reference

Every machine code the API can return, grouped by area, with the typical HTTP status. Unless noted, errors are 400 Bad Request.

Authentication

Tasks

Contacts

Subscriptions

Rate limits

Requests are rate-limited per client, per endpoint. Exceeding a limit returns 429 with machine code RequestThrottled and a Retry-After header (seconds).

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

Monitoring tasks

GET tasks/types

Returns the array of task-type names the system knows about:

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

GET tasks/intervals

Returns the array of monitoring intervals (in minutes) accepted for your account, e.g. [1,5,15,30,60]. Use one of these values for the interval field when creating a task; any other value yields WrongInterval.

GET tasks

List monitoring tasks. All query parameters are optional; with none, all of the account's tasks are returned. Repeat a parameter to pass an array, e.g. ?ids=guid1&ids=guid2.

The info parameter

Requests extra data embedded in each task. Combine values with commas (?info=stats,subscriptions) or pass the equivalent bitmask integer:

?info=stats,subscriptions,results is equivalent to ?info=7.

Filter parameters

Response — 200 OK

An array of task objects. The exact fields depend on the task type; the common base includes id, name, taskType, enabled, interval, lastState, creationTime, tags, agentPools, and (when requested via info) subscriptions, stats, results and attached. When results are included, each result carries at least timestamp (Unix-seconds UTC) and eventNumber; the remaining fields are task-type specific (see the create response below for the HTTP shape).

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

GET tasks/{id:guid}

Fetch a single task by id. Accepts the same info parameter (and sdtu/edtu when info=results). Returns the task object, or 404 NotFound if it does not exist.

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

Create a monitoring task of the given type. On success returns 201 Created, a relative Location: /tasks/{id} header, and the full created task object.

Request body — HTTP task

{
  // HTTP-specific fields
  "url": "https://www.example.com",        // REQUIRED
  "httpMethod": "Get",                       // Get | Post | Head (default Get)
  "userAgent": "MyMonitor",
  "referer": "https://www.google.com",
  "acceptHeader": "application/json",
  "followRedirect": false,
  "treat300AsError": false,                // if set, followRedirect is ignored
  "checkDnsbl": false,                       // check domain against DNS block lists
  "checkDomainExpiration": false,            // monitor domain expiry (valid domains only)
  "checkCertificateExpiration": false,       // monitor TLS cert expiry (https only)
  "checkRussianBlackLists": false,
  "checkWebRisk": false,
  "timeout": 40000,                          // ms before a check fails
  "keywords": ["error", "maintenance"],
  "keywordMode": "ReverseAny",             // see keyword modes below
  "userName": "basic-auth-user",          // credentials for the monitored resource
  "password": "basic-auth-pass",
  "postParameters": "a=1\r\nb=2",          // only with httpMethod=Post
  "ignoredStatuses": [404, 500],

  // fields common to every task type
  "interval": 5,                             // minutes; must be an accepted interval
  "enabled": true,
  "fullLog": false,                          // advanced packages only
  "openStat": true,
  "name": "My website",
  "tags": ["production", "web"],
  "agentPools": ["westeurope", "asia"],  // see notes below
  "subscriptions": [ /* inline subscriptions, see below */ ]
}

Inline subscriptions

The subscriptions array subscribes contacts to this task's alerts/reports at creation time. Each entry uses the subscription shape; do not set taskIds (it is fixed to the new task). If contactIds is omitted, all of your confirmed contacts are subscribed. Report subscriptions are applied to Email contacts only.

Other task types

• tasks/ping — body carries host plus the common fields.
• tasks/port — body carries host and port plus the common fields.
• tasks/rusbl — Russian-registry block-list check; body carries url, plus ignoreWarnings, doNotSendMsgOnWarnings, prefixMatch and the common fields.

Response — 201 Created (HTTP task)

{
  "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 & typed variants

Update tasks. Two forms:

• By id — PUT tasks/{id} (common fields only), or the typed PUT tasks/http/{id}, tasks/ping/{id}, tasks/port/{id}, tasks/rusbl/{id} (type-specific fields too). The body is the same editable shape as create; only the fields you include are changed.
• By filter — PUT tasks?<filter> (common fields only) or the typed PUT tasks/{type}?<filter> (which pins the filter to that type). Uses the same filter parameters as GET tasks. Returns the updated task(s).

The untyped PUT tasks / PUT tasks/{id} can only touch fields common to all task types — use a typed endpoint to change type-specific settings.

DELETE tasks/{id:guid} & tasks

• DELETE tasks/{id} — delete a single task; returns the deleted task.
• DELETE tasks?<filter> — bulk delete by the task filter (a filter may also be supplied in the request body). Returns the deleted tasks.

POST tasks/$batch · task/$batch

Run several task operations in one request. The body is a JSON array of sub-requests; the response is a JSON array of sub-responses in the same order. The sub-operation is chosen by the last segment of relativeUrl (e.g. http → POST tasks/http). The request body must be JSON (Content-Type: application/json). The same mechanism exists for contacts at 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... }" }
]

Contacts

Contacts are the destinations that receive alerts and reports (email addresses, phone numbers for SMS/voice). Contact ids are used when creating subscriptions.

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

Static enumerations used by the contact endpoints:

GET contacts & contacts/{id:guid}

List contacts (optionally filtered) or fetch one by id. Add ?info=subscriptions to embed each contact's subscriptions. With no filter, all of the account's contacts are returned.

Contact object

Common fields: id, confirmed, contactType, name, address, alertDelay, activePeriodStart/activePeriodEnd (HH:mm), activeDays, sendCost. Email contacts add reportFormat (Text/ShortText), sendNews, sendBillingNotifications; SMS/IM contacts add gateway.

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

Create a contact. Returns 201 Created, a relative Location: /contacts/{id}, and a ContactOperationResult ({ contact, status }) whose status reports the confirmation outcome.

{
  "address": "ops@@example.com",          // REQUIRED
  "name": "Ops mailbox",
  "alertDelay": 0,                        // minutes; one of contacts/delays
  "reportFormat": "Text",               // Text | ShortText (email only)
  "activePeriodStart": "00:00",        // optional quiet-hours window (HH:mm)
  "activePeriodEnd": "23:59",
  "activeDays": ["Monday", "Tuesday"],   // optional; default all days
  "subscriptions": [ /* optional inline subscriptions */ ]
}

SMS and voice contacts default to gateways twiliosms / twiliovoice, get a default per-message price, and store the number with a leading +. Changing a contact's address or gateway resets its confirmed state.

Confirmation status values

The status field of the result reports the confirmation-code send outcome:

PUT contacts & typed variants

• By id — PUT contacts/{id} (common fields), or typed PUT contacts/email/{id}, contacts/sms/{id}, contacts/voice/{id}. Only the fields you send are changed.
• By filter — PUT contacts?<filter> or typed PUT contacts/{type}?<filter> (pins the filter to that type), using the contact filter.

PUT contacts/im (both forms) returns 400 WrongContactType.

DELETE contacts/{id:guid} & contacts

Delete one contact by id, or bulk-delete by the contact filter. As with tasks, a bulk delete with an empty filter is rejected with 400 EmptyFilter.

Confirmation codes

Unconfirmed contacts must confirm ownership with a short code delivered to the contact address.

• PATCH contacts/{id}/code — (re)issue and send the confirmation code. Returns a ContactOperationResult with a status such as CodeSent.
• POST contacts/{id}/code — confirm the contact by submitting the code. Body: { "code": "12345" }. On success the contact becomes confirmed.

Alerts & subscriptions

A subscription links one or more tasks and contacts to a set of alert and/or report types. A single subscription entry cross-joins its tasks and contacts, producing one alert/report per (task, contact, type).

Subscription shape

{
  "alertTypes": ["Up", "Down"],       // any of Up, Down, RepeatedlyDown
  "reportTypes": ["Day", "Month"],     // any of Day, Week, Month, Quarter, Year
  "taskIds": ["<task guid>"],
  "contactIds": ["<contact guid>"]
}

• At least one of alertTypes / reportTypes is required, else AlertsAndReportsAreEmpty.
• Omitting taskIds defaults to all of your tasks; omitting contactIds defaults to all of your contacts. An explicit empty array means "none".
• Report subscriptions apply to Email contacts only — report types on non-Email contacts are silently ignored (their alert subscriptions are still created).
• Ids that you do not own are ignored.

GET subscriptions/alertTypes · subscriptions/reportTypes

GET subscriptions

List subscriptions. Returns one entry per matched alert or report subscription (never merged). Optional filters:

POST subscriptions · DELETE subscriptions

Both take a JSON array of subscription entries in the body. POST adds the described subscriptions (only new rows are inserted); DELETE removes those that exist. Both return 200 OK with an empty body. Unknown alert/report types are rejected with 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>"]}]'

Statistics & results

GET stats

Uptime/downtime aggregates per task over a time window. Accepts the task filter to select tasks, plus:

Response

A Stats object with the resolved window (dual date fields) and a stats array. Each entry carries the task reference and: uptimeInMinutes/uptimeSpan, downtimeInMinutes/downtimeSpan, maintenance up/down times, totalTimeInMinutes, the per-bucket check counts, and uptimePercent/downtimePercent.

GET outages

Down-time spans per task. Accepts the task filter plus:

Response: an Outages object with the resolved window and a taskOutages array; each element pairs a task with its outages spans (startTime/endTime + Unix variants, event numbers, optional comment).

GET incident

Incident (failure event) list per task. Accepts the task filter plus the same window/time-zone parameters as outages, and:

Response: an Incidents object with a taskIncidents array. Each incident carries taskId, checkId, start/end Unix times, the failing location, the error, hasSnapshot, and (with fullLog) a recheck block listing OK locations and per-error failing locations.

GET incident/snapshot

Fetch the stored response snapshot captured for an incident. Parameters:

Returns the snapshot (a timestamp plus the captured bytes) when one exists, or null when there is no snapshot for the given incident.

GET results/http

Aggregated HTTP timing metrics per task. Forces task type Http. Accepts the task filter plus:

Response: an AggregatedHttpResults object; each taskResults entry reports the task reference and averaged responseTime, dnsTime, headTime, dataTime (milliseconds).

GET cr/httpResponseTime

HTTP response-time series per task. Accepts the task filter plus startDate, endDate and groupBy. Returns a bare array of series objects:

[
  {
    "id": "ef10cd12-93f9-e311-bec5-dc85de1f0bc2",
    "rawUrl": "https://www.example.com",
    "name": "My website",
    "results": [ [1719181583, 142], [1719177983, 138] ]   // [unixSeconds, responseTimeMs], newest first
  }
]

Agents

Agents are the geographically distributed monitoring locations. Pool ids returned here are the values you pass in a task's agentPools.

GET agents

List monitoring agents. Optional query parameter:

Each agent carries id, upFrom, datacenter (name/city/country/state), company (name/url), ip, version, lon/lat, and 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

List the public agent pools (geo regions). Each pool carries id, desc, its agents, childPools, and hidden. Use the pool id values in a task's agentPools.

GET agents/ips anonymous

Return the current monitoring agent IP addresses — useful for whitelisting Host-Tracker in a firewall. This endpoint needs no authentication. By default it returns text/plain, one IP per line; send Accept: application/json to receive a JSON array instead.

203.0.113.10
203.0.113.11
198.51.100.7

["203.0.113.10", "203.0.113.11", "198.51.100.7"]