All requests are made with BASE_URL: https://api1.host-tracker.com/
Content type of requests and responses: application/json. Supported HTTP methods:All operations but user token retrieving require authentication information in http headers. Authentication performed by using Authorization Http header with specified bearer token. Token is created by POST request with login, password data to BASE_URL/users/token. See details on user operations help page.
Example of token usage:
GET BASE_URL/task/7EE87894-B8A9-E311-BEB2-DC85DE1F0BC2 HTTP/1.1
User-Agent: Fiddler
Host: www.host-tracker.com
Content-Type: application/json
Authorization: bearer your token here
Content-Length: 0
CORS is enabled for all origins (response contains header Access-Control-Allow-Origin: *). This allows, for example, API access via JQuery AJAX requests.
If you could not use DELETE, PUT, PATCH requests for accessing API use X-HTTP-Method-Override header with POST request to resourse.
For example, for task updating you could send PUT request to BASE_URL/tasks or send POST to BASE_URL/tasks with X-HTTP-Method-Override: PUT
get authorization token for requests to other API
{
"login": "your login here",
"password": "your password here"
}
To login for a management of an account to which you were given permissions (a.k.a. as subaccount), use "forLogin" field.
{"login":"subaccount login",
"password":"subaccount pwd",
"forLogin": "superaccount login"}
In this case, returned token allows you to manage superaccount information in same way as you work with API methods directly for your own account. The corresponding rights have to been granted by superaccount in order for operation to succeed. For example, if superaccount grants read only rights to monitoring tasks, the returned token will allow you to fetch monitoring information, but POST, PUT, PATCH, DELETE methods that alter monitoring state will be prohibited.
{
"ticket":"your token here",
"expirationTime":"token expiration",
"expirationUnixTime":int value - token expiration unix time
}
401 IncorrectLoginOrPassword - incorect login or password
POST BASE_URL/users/token HTTP/1.1
User-Agent: MyClient
Content-Type: application/json
Content-Length: 37
{"login":"login", "password":"password"}
BASE_URL: https://api1.host-tracker.com
get array of accepted task intervals.
[1,5,15,30,60]
get array of accepted task types. Currently ["Http","Ping","Port"] for all operations, ["Database","Snmp"] - read only, "Counter" - in development
["Counter","DNSBL","Database","Http","Ping","Port","Snmp"]
get task by id (GUID).
Task data
get all tasks or filtered via query string parameters.
TODO
Note0: if results are requested with
info=results and (sdtu,
edtu)
response will contain array of results: [result1, result2, ...]
Results are task type dependent.
For sure they have:
timestamp - int64, unix timestamp, UTC
eventNumber - int32, sequential number of task check
GET BASE_URL/tasks HTTP/1.1
User-Agent: Fiddler
Accept: application/json
Host: www.host-tracker.com
Authorization: bearer 3DD135...5EE510417
Content-Length: 0
create http task.
{
//fields specific for http task
"url": "<your url. Required>",
"httpMethod": "<Get, Post or Head. Optional - default is Get>",
"userAgent": "<user agent for request. Optional.>",
"referer": "<referrer for request. Optional>",
"acceptHeader": "<accept header. Optional>",
"followRedirect": <bool: true or false(default). Optional>,
"treat300AsError": <bool: true or false(default). Optional. If set, followRedirect is ignored>,
//if true then redirects will be followed.
"checkDnsbl": <bool: true or false(default). Optional>,
/*if true then domain will be checked agains DNS black lists and if it is there,
notification will be send according to subscriptions.*/
"checkDomainExpiration": <bool: true or false(default). Optional>,
/*if true then domain expiration date will be monitored.
Notifications will be sent 30,7 and 1 day before expiration and every day after it according to subscriptions.*/
/*Note: expiration monitoring will be created only for valid domain (not IP)*/
"checkCertificateExpiration": <bool: true or false(default). Optional>,
/*if true then certificate expiration date of provided endpoint will be monitored.
Notifications will be sent 30,7 and 1 day before expiration and every day after it according to subscriptions.
Available only for https endpoints and ignored in other cases.*/
"timeout": <int: ms for site response before fail. Optional>,
"keywords":
[
"keyword1", "keyword2", ...
],
//keywords to search for in response body. Optional
"keywordMode": "<PresentAny, PresentAll, ReverseAny, ReverseAll, ReverseWithResult. Optional>",
/*
Keyword mode specifies how to use keywords:
- PresentAny - task will be Ok if any of specified keywords are present in response
- PresentAll - task will be Ok if all specified keywords are present in response
- ReverseAny - task will be Ok if all specified keywords are absent in response
- ReverseAll - task will be Ok if any of specified keywords are absent in response
-
ReverseWithResult - task will be Ok if all specified keywords are absent in response.
Fail contains rest of response line where first keyword was detected.
This text is sent in alerts. Usefull, for example, in scenarios when your response contains
some status information - each line has error status and object with this status.
In such case you will retrieve on email, SMS, ... information of objects with fail status.
WARN. In this mode only first 100 characters of every response line will be analyzed.
*/
"userName": "<userName for credentials to your resourse. Optional>",
"password": "<password for credentials to your resourse. Optional>",
"postParameters":"paramKey1=paramValue1\r\nparamKey2=paramValue2\r\n...",
/*postParameters are Optional and specified with Post httpMethod*/
//fields same for all task types
"interval": <int: 1(default),5,15,30,60 - interval of monitoring. Optional>,
"enabled": <bool: true(default) or false. Optional>,
"fullLog": <bool: true or false(default). Optional>,
"openStat": <bool: true(default) or false. Optional>,
"name": "<your task name here. Optional>",
"tags":
[
"tag1", "tag2", ...
],
/*tags are Optional and can be used for task filtering*/
"agentPools":
[
"poolId1", "poolId2", ...
],
/*agentPools is Optional. It specifies monitoring locations for task. Default is taken from profile.
Requirements if specified: 7 agents in all pools. If condition is not met error SelectMoreAgents with details will arise. */
"subscriptions":
[
<subscription1>, <subscription2>, ...
]
/*
subscriptions are Optional. You could subscribe contacts for alerts and reports about this task using this field.
In every subscription structure in array you should not specify taskIds. Specifying contactIds will create subscriptions only for this contacts.
If you do not specify contactIds then all your existing confirmed contacts will be subscribed.
For details of subscription structure see subscription service and examples.
*/
}
{
"id":"ef10cd12-93f9-e311-bec5-dc85de1f0bc2",
"url":"http://www.myprivateresource6.com",
"rawUrl":"http://www.myprivateresource6.com",
"name":"testing web api on private resourse",
"creationTime":"2014-06-21T22:26:23.6780166Z",
"taskType":"Http",
"enabled":true,
"interval":1,
"upFromTime":"2014-06-21T22:26:23.6780166Z",
"lastState":true,
"lastStateChangeTime":"2014-06-21T22:26:23.6780166Z",
"openStatEnabled":false,
"fullLogEnabled":false,
"disablenceReason":null,
"disablenceTime":null,
"holdResults":true,
"agentStat":false,
"billingOverlimits":[],
"tags":["privateResource","testApi"],
"subscriptions":
[
{
"alertTypes":["Up"],
"reportTypes":null,
"taskIds":["ef10cd12-93f9-e311-bec5-dc85de1f0bc2"],
"contactIds":["4cedf037-d1d9-e311-bebc-dc85de1f0bc2"]
},
{
"alertTypes":["Down"],
"reportTypes":null,
"taskIds":["ef10cd12-93f9-e311-bec5-dc85de1f0bc2"],
"contactIds":["4cedf037-d1d9-e311-bebc-dc85de1f0bc2"]
},
{
"alertTypes":["Up"],
"reportTypes":null,
"taskIds":["ef10cd12-93f9-e311-bec5-dc85de1f0bc2"],
"contactIds":["afc5e2c8-3d42-e311-bea5-3085a980e898"]
},
{
"alertTypes":["Down"],
"reportTypes":null,
"taskIds":["ef10cd12-93f9-e311-bec5-dc85de1f0bc2"],
"contactIds":["afc5e2c8-3d42-e311-bea5-3085a980e898"]
},
{
"alertTypes":["Up"],"reportTypes":null,
"taskIds":["ef10cd12-93f9-e311-bec5-dc85de1f0bc2"],"contactIds":["e48409ff-bbf7-e311-bec5-dc85de1f0bc2"]},
{"alertTypes":["Down"],"reportTypes":null,"taskIds":["ef10cd12-93f9-e311-bec5-dc85de1f0bc2"],"contactIds":["e48409ff-bbf7-e311-bec5-dc85de1f0bc2"]},
{"alertTypes":null,"reportTypes":["Monthly"],"taskIds":["ef10cd12-93f9-e311-bec5-dc85de1f0bc2"],"contactIds":["4cedf037-d1d9-e311-bebc-dc85de1f0bc2"]},
{"alertTypes":null,"reportTypes":["Daily"],"taskIds":["ef10cd12-93f9-e311-bec5-dc85de1f0bc2"],"contactIds":["afc5e2c8-3d42-e311-bea5-3085a980e898"]},
{"alertTypes":null,"reportTypes":["Monthly"],"taskIds":["ef10cd12-93f9-e311-bec5-dc85de1f0bc2"],"contactIds":["afc5e2c8-3d42-e311-bea5-3085a980e898"]}
],
"stats":null,
"agentPools":["asia","westeurope"],
"deleted":false,
"httpMethod":"Post",
"userAgent":"mybot",
"referer":"http://www.google.com",
"acceptHeader":"application/json",
"keywords":["error","wrong"],
"keywordMode":"ReverseAny",
"maxResponsePageSize":2097152,
"timeout":40000,
"userName":"public",
"password":"xxx",
"postParameters":"param1=test\r\nparam2=test\r\nuser=public"
}
POST BASE_URL/tasks/http HTTP/1.1
User-Agent: Fiddler
Content-Type: application/json
Host: www.host-tracker.com
Content-Length: 823
Authorization: bearer ECFB190B3...653C1E78
{
"url": "http://www.myprivateresource.com",
"httpMethod": "Post",
"userAgent": "mybot",
"referer": "http://www.google.com",
"acceptHeader": "application/json",
"keywords": ["error", "wrong"],
"keywordMode": "ReverseAny",
"timeout": 10000,
"userName": "public",
"password": "xxx",
"postParameters":"param1=test\r\nparam2=test\r\nuser=public",
"interval": 1,
"enabled": true,
"fullLog": false,
"openStat": false,
"name": "testing web api on private resourse",
"tags": ["testApi", "privateResource"],
"agentPools": ["asia", "westeurope"],
"subscriptions":
[
{"alertTypes": ["Up", "Down"]},
{"reportTypes": ["Daily"], contactIds:["AFC5E2C8-3D42-E311-BEA5-3085A980E898"]},
{"reportTypes": ["Monthly"]}
]
}
create ping task.
POST BASE_URL/tasks/ping HTTP/
User-Agent: Fiddler
Content-Type: application/json
Host: www.host-tracker.com
Content-Length: 430
Authorization: bearer your auth.token here
{
"interval": 1,
"enabled": true,
"fullLog": false,
"openStat": false,
"name": "testing web api on private resourse",
"tags": ["testApi", "privateResource"],
"agentPools": [],
"subscriptions":
[
{"alertTypes": ["Up", "Down"]},
{"reportTypes": ["Daily"], contactIds:[]},
{"reportTypes": ["Monthly"]}
],
"host":"91.197.255.62"
}
create port task.
POST BASE_URL/tasks/port HTTP/1.1
User-Agent: Fiddler
Content-Type: application/json
Host: www.host-tracker.com
Authorization: bearer your auth.token here
Content-Length: 400
{
"host":"my.some.site.com",
"port":"123",
"interval": 1,
"enabled": true,
"fullLog": false,
"openStat": false,
"name": "porttest2",
"tags": ["tag1"],
"agentPools": [],
"subscriptions":
[
{"alertTypes": ["Up", "Down"]},
{"reportTypes": ["Daily"], contactIds:["AFC5E2C8-3D42-E311-BEA5-3085A980E898"]},
{"reportTypes": ["Monthly"]}
]
}
- update general task parameters.
create port task.
PUT BASE_URL/tasks/http/guid of task HTTP/1.1
User-Agent: Fiddler
Content-Type: application/json
Host: www.host-tracker.com
Content-Length: 659
Authorization: bearer your auth.token here
{
"url": "http://www.myprivateresource.com",
"httpMethod": "Post",
"userAgent": "mybot",
"referer": "http://www.google.com",
"acceptHeader": "application/json",
"keywords": ["error", "wrong"],
"keywordMode": "ReverseAny",
"userName": "public",
"timeout": 5000,
"password": "xxx",
"postParameters":"param1=test\r\nparam2=test\r\nuser=public",
"interval": 1,
"enabled": true,
"fullLog": false,
"openStat": false,
"name": "test33",
"tags": [],
"agentPools": [],
"subscriptions":
[
{"alertTypes": ["Up", "Down"]},
{"reportTypes": ["Daily"], contactIds:[]},
{"reportTypes": ["Monthly"]}
]
}
update ping task.
PUT BASE_URL/tasks/ping/guid of task HTTP/1.1
User-Agent: Fiddler
Content-Type: application/json
Host: www.host-tracker.com
Content-Length: 344
Authorization: bearer your auth.token here
{
"host":"91.197.255.62"
"interval": 1,
"enabled": true,
"fullLog": false,
"openStat": false,
"name": "testing web api on private resourse",
"tags": ["testApi", "privateResource"],
"agentPools": [],
"subscriptions":
[
{"alertTypes": ["Up", "Down"]},
{"reportTypes": ["Daily"], contactIds:[]},
{"reportTypes": ["Monthly"]}
],
}
update port task.
PUT BASE_URL/tasks/port/guid of task HTTP/1.1
User-Agent: Fiddler
Content-Type: application/json
Host: www.host-tracker.com
Content-Length: 399
Authorization: bearer your auth.token here
{
"host":"my.some.site.com",
"port":"123",
"interval": 1,
"enabled": true,
"fullLog": false,
"openStat": false,
"name": "porttest2",
"tags": ["tag1"],
"agentPools": [],
"subscriptions":
[
{"alertTypes": ["Up", "Down"]},
{"reportTypes": ["Daily"], contactIds:["AFC5E2C8-3D42-E311-BEA5-3085A980E898"]},
{"reportTypes": ["Monthly"]}
]
}
delete task specified by id (GUID).
TODO
delete tasks by filter specified in query string.
TODO
perform batched tasks creation and/or update.
TODO
get array of accepted contact types.
["Email","IM","SMS","VoiceCall"]
get array of accepted contact alert delays in minutes.
[0,5,15,30,60,180,720]
get array of accepted sms gateways.
["clickatell","clickatella","infobip","skype","twiliosms"]
get all contacts, possible filltered by url query str
Optional filters(via URL,URL filter keywords are case sensitive!):
GET BASE_URL/contacts?acceptBillingNotifications=True HTTP/1.1
User-Agent: Fiddler
Content-Type: application/json
Host: www.host-tracker.com
Authorization: bearer <your token here>
GET BASE_URL/contacts?address=test@mail.com HTTP/1.1
User-Agent: Fiddler
Content-Type: application/json
Host: www.host-tracker.com
Authorization: bearer <your token here>
GET BASE_URL/contacts?addresses=test@mail.com&addresses=1122334455 HTTP/1.1
User-Agent: Fiddler
Content-Type: application/json
Host: www.host-tracker.com
Authorization: bearer <your token here>
GET BASE_URL/contacts?contactType=SMS HTTP/1.1
User-Agent: Fiddler
Content-Type: application/json
Host: www.host-tracker.com
Authorization: bearer <your token here>
GET BASE_URL/contacts?confirmed=True HTTP/1.1
User-Agent: Fiddler
Content-Type: application/json
Host: www.host-tracker.com
Authorization: bearer <your token here>
GET BASE_URL/contacts?addresses=3333333334&addresses=222222221&addresses="gord_den+5@gmail.com"&excludeAddresses=True HTTP/1.1
User-Agent: Fiddler
Content-Type: application/json
Host: www.host-tracker.com
Authorization: bearer <your token here>
GET BASE_URL/contacts?ids=092a2bc9-58d1-e411-80c3
-00155d36955e&ids=695dc35a-59d1-e411-80c3-00155d36955e HTTP/1.1
User-Agent: Fiddler
Content-Type: application/json
Host: www.host-tracker.com
Authorization: bearer <your token here>
GET BASE_URL/contacts?overlimited=False HTTP/1.1
User-Agent: Fiddler
Content-Type: application/json
Host: www.host-tracker.com
Authorization: bearer <your token here>
contact data
{
"id":"Contact id",
"address":"Contact address",
"confirmed":"True or false",
"contactType":"Type of contact",
"name":"Name of contact",
"sendCost":"Cost to send",
"alertDelay":"Delay of alert",
"activePeriodStart":"Start of active period",
"activePeriodEnd":"End of active period",
"activeDays":"Active days",
"billingOverlimit":"Billing overlimit here",
"subscriptions":"Subscriptions here",
"reportFormat":"Format of report",
"sendNews":"True or false",
"sendPressRelease":"True or false",
"sendBillingNotifications":"True or false"
}
get contact by id (GUID)
GET BASE_URL/contacts/092a2bc9-58d1-e411-80c3-00155d36955e HTTP/1.1
User-Agent: Fiddler
Content-Type: application/json
Host: www.host-tracker.com
Content-Length: 0
Authorization: bearer
Contact data
create email contact
{"address":"example@example.com","name":"name of you contact"}
create email contact
{"address":"number","name":"name of you contact","gateway":"type of gateway"}
Contact data
create instant messaging contact
{"address":"123api", "name":"im contact","gateway":"SkypeChat"}
Contact data
create voice call contact
{
"address":"123123123",
"name":"voice contact",
"gateway":"twiliovoice"
}
Contact data
update email contact
PUT BASE_URL/contacts/email/id of contact HTTP/1.1
User-Agent: Fiddler
Content-Type: application/json
Host: www.host-tracker.com
Authorization: bearer your ticket here
{"reportFormat":"ShortText"}
Contact data
update sms contact
{"address":"222222221","name":"sms contact2","gateway":"twiliosms"}
Contact data
update instant messaging contact
PUT BASE_URL/contacts/im/695dc35a-59d1-e411-80c3-00155d36955e HTTP/1.1
User-Agent: Fiddler
Content-Type: application/json
Host: www.host-tracker.com
Authorization: bearer
Content-Length: 79
{"address":"222222224","name":"im contact2","gateway":"GTalk"}
Contact data
Currently has no additional field. VoiceCall gateway is twiliovoice. Send cost: $0.04 for US carriers, $0.222 for other.
delete contact specified by id (GUID)
DELETE BASE_URL/contacts/id of contact HTTP/1.1
User-Agent: Fiddler
Content-Type: application/json
Host: www.host-tracker.com
Authorization: bearer your ticket here
Contact data
delete contacts specified by filter or all contacts
confirm contact by sending confirmation code
POST BASE_URL/contacts/id of contact/code HTTP/1.1
User-Agent: Fiddler
Content-Type: application/json
Host: www.host-tracker.com
Authorization: bearer your token here
{"code":"64700"}
Contact data
possible regenerate confirmation code and resend it to contact address
Contact data
get uptime statistics for tasks. You usually filter stats by query string parameters explained bellow.
get outages for tasks
get incidents for tasks.
get array of HostTracker world monitoring points
[
{
"id":"guid - monitoring point id",
"upFrom":"date - monitoring point starting date",
"datacenter":
{
"name":"datacenter name",
"city":"datacenter city",
"country":"datacenter country",
"state":"datacenter state"
},
"company":
{
"url":"company site",
"name":"company name",
"language":"company site language",
"country":"company country"
},
"ip":"agent ip address",
"version":"agent version",
"lon":agent longitude, ex. -97.14667,
"lat":agent latitude, ex. 31.549333,
"pools":[array of pools, currently empty. reserved for future use]
},
{
"id":"5625d028-7c78-482f-9d8d-2c41fbc752f1",
"upFrom":"2013-04-17T15:02:38",
"datacenter":
{
"name":"Waco ITG",
"url":"http://guiahosting.com",
"city":"Waco",
"country":"US",
"state":"TX"
},
"company":
{
"name":"GuiaHosting",
"language":"ES",
"country":"US"
},
"ip":"91.197.251.251",
"version":"0.0.5230.0",
"lon":-98.14667,
"lat":33.549333,
"pools":[]
}
...
]
GET BASE_URL/agents HTTP/1.1
User-Agent: Fiddler
Accept: application/json
Host: www.host-tracker.com
Authorization: bearer 3DD135...5EE510417
Content-Length: 0
- get array of agent regions (Asia, Europe, America) (used for configuring tasks)
[
{
"id":"string - id of region",
"desc":"readable region description",
"hidden":false,
"childPools":["child1 pool id", "child1 pool id", ... ],
"agents":["array of this region agents"],
},
...
]
GET BASE_URL/agents/pools HTTP/1.1
User-Agent: Fiddler
Content-Type: application/json
Host: www.host-tracker.com
Content-Length: 0
Authorization: bearer ECFB190B3...653C1E78