API Guide
Welcome to the Monitive API! You can use our API to access Monitive API endpoint, which can perform pretty much any operation that you would generally log into your Monitive account to perform.
API Basics
JSON API Standard
All requests and responses are JSON:API compliant. If this standard is not familiar to you, please take a moment to go over it at jsonapi.org.
Endpoint
All API requests are relative to the production API endpoint:
Authorization
Most requests require prior authentication. For authorisation purposes, we use standard OAuth 2.0.
You can send requests on behalf of your user by generating a Personal Token.
As this feature isn’t automated, please contact us and we’ll send you your own Personal Token to use for managing your account.
For requests requiring authorization, send your Personal Token via HTTP header:
Authorization: Bearer eyJaccessKey
Where eyJaccessKey is your Personal Access Token.
Pagination
All requests that return a collection of primary objects generated by the system (such as Monitors, Incidents etc.) return paginated results.
As we’re keeping an eye on performance, pagination doesn’t include total pages, last page and total count.
To request a specific page, add the page[number] query parameter, such as:
http://monitive-api.test/teams/26075/incidents?page[number]=1
Requests that return static resources such as Locations, Channels which don’t grow over time don’t return paginated results.
Please note that the page[number] attribute in the first, prev, next attributes of the API’s responses is URL-encoded.
Filters
Some requests that return lists of object (such as monitors) can be filtered based on existing or virtual attributes.
To filter on a specific attribute, let’s call it attr, you should pass a filter[attr] query parameter, such as:
https://api1.monitive.com/teams/1/monitors?filter[name]=Wopher
This request would return only monitors that have the string Wopher in their name
Sorting
Sorting is available to certain requests, and it’s performed by passing a sort query parameter. The default sort direction is ascending. If you need to sort descending on a certain attribute, prefix it with -.
For example:
https://api1.monitive.com/teams/1/monitors?sort=group,-name
This would retrieve the monitors sorted by group ascending and name descending.
Relationships
When retrieving resources, you have the option to also retrieve the related resources in the same response.
For example you can fetch monitors with their corresponding incidents, availability and latency stats.
To retrieve related resources, pass the include query attribute with a comma-separated list of resource-types to include. Please consult each resource type to see which related resources can be included in the response.
For example:
https://api1.monitive.com/teams/1/monitors?include=incident,availability,latency
This would retrieve the list of monitors for team #1, along with incidents, availability and latency data for each monitor. A sample JSON response would look like this:
{
"meta": {
"currentPage": 1,
"count": 1,
"perPage": 10,
"hasMorePages": false,
"total": 1
},
"links": {
"first": "https://api1.monitive.com/teams/1/monitors?page%5Bnumber%5D=1"
},
"data": [
{
"type": "monitor",
"id": "62",
"attributes": {
"name": "W3 Wopher (61331)",
"pronounceable": null,
"interval": 1,
"group": null,
"service": "tcp_port",
"maintenanceType": 0,
"maintenanceStartDate": null,
"maintenanceEndDate": null,
"maintenanceStartTime": null,
"maintenanceEndTime": null,
"settings": {
"host": "w3.monitive.com",
"port": 11511,
"timeout": 20000000000
}
},
"relationships": {
"incident": {
"links": {
"self": "/monitors/62/relationships/incident"
},
"data": [
{
"type": "incident",
"id": "1807"
}
],
"meta": {
"total": 1
}
},
"availability": {
"links": {
"self": "/monitors/62/relationships/availability"
},
"data": {
"type": "availability",
"id": "av-daily-monitor-62_2021-02-07T18:04:47+00:00_2021-03-09T18:04:47+00:00"
}
},
"latency": {
"links": {
"self": "/monitors/62/relationships/latency"
},
"data": {
"type": "latency",
"id": "la-daily-monitor-62_2021-02-07T18:04:47+00:00_2021-03-09T18:04:47+00:00"
}
}
},
"links": {
"self": "/monitors/62"
},
"meta": {
"status": 1,
"state": 10,
"created": "2020-11-18T12:46:49+00:00",
"updated": "2021-03-09T18:04:05+00:00"
}
}
],
"included": [
{
"type": "incident",
"id": "1807",
"attributes": {
"started": "2021-02-24T02:14:20+00:00",
"ended": "2021-02-24T02:15:08+00:00",
"acknowledged": null,
"downtime": 48,
"reason": "Timeout connecting to port 11511",
"maintenance": 0
},
"links": {
"self": "/incidents/1807"
},
"meta": {
"created": "2021-02-24T02:14:20+00:00",
"updated": "2021-02-24T02:15:08+00:00"
}
},
{
"type": "availability",
"id": "av-daily-monitor-62_2021-02-07T18:04:47+00:00_2021-03-09T18:04:47+00:00",
"attributes": {
"points": [
{
"time": "2021-02-07T00:00:00+00:00",
"downtime": null,
"availability": null
},
{
"time": "2021-02-08T00:00:00+00:00",
"downtime": 0,
"availability": 100
}
]
},
"links": {
"self": "/availability/av-daily-monitor-62_2021-02-07T18:04:47+00:00_2021-03-09T18:04:47+00:00"
},
"meta": {
"timeFrom": "2021-02-07T18:04:47+00:00",
"timeTo": "2021-03-09T18:04:47+00:00",
"precision": "daily",
"totals": {
"downtime": 48,
"availability": 99.9981,
"timeframeSeconds": 2592001
}
}
},
{
"type": "latency",
"id": "la-daily-monitor-62_2021-02-07T18:04:47+00:00_2021-03-09T18:04:47+00:00",
"attributes": {
"points": [
{
"time": "2021-02-07T00:00:00+00:00",
"metric0": null,
"TotalDuration": null
},
{
"time": "2021-02-08T00:00:00+00:00",
"metric0": 0,
"TotalDuration": 172143
}
]
},
"links": {
"self": "/latency/la-daily-monitor-62_2021-02-07T18:04:47+00:00_2021-03-09T18:04:47+00:00"
},
"meta": {
"timeFrom": "2021-02-07T18:04:47+00:00",
"timeTo": "2021-03-09T18:04:47+00:00",
"precision": "daily",
"averages": {
"metric0": 0,
"TotalDuration": 185102
}
}
}
]
}
Errors
Requests can fail for various reasons. When a request fails, we’ll return a HTTP code that should make sense given the intended request. Here are the generic errors that almost all requests can respond with.
HTTP 401 UnauthorizedYou have sent a request without proper authentication.HTTP 403 ForbiddenYou are not allowed to perform the requested operation.HTTP 404 Not FoundThe resource cannot be found.
Teams
A team is an organization which can hold Monitors, have one or more Users. Everything in a Monitive account sits under a team.
Besides retriving basic team information such as name and creation date, you can also retrieve overall availability and latency for all the monitorin within a team.
Also, you can retrieve the recent checks on all monitors within a team.
See more details in the Team section in Swagger.
Users
A user is a person that can authenticate on Monitive and can perform operations on a team’s assets.
A team can have multiple users, but only one user is the team owner.
When a user signs up on Monitive, if he or she isn’t joining an existing team, then a new team will be created on the spot and the user will be designated as the owner of that team.
See more details in the Users section in Swagger.
Monitors
A team can have multiple monitors.
Operations that can be performed regarding monitors:
- Retrieve information about a monitor
- Delete a monitor
- Update a monitor’s settings
- Pause/disable a monitor
- Resume/enable a monitor
- Test a new monitor
- Retrive all the monitors on a team
- Create a new monitor in a team
Retrieving a monitor is a simple GET request:
curl 'https://api1.monitive.com/monitors/62' \
-H 'accept: application/json' \
-H 'authorization: Bearer YOUR-API-TOKEN-HERE' \
-H 'accept-language: en, en;q=0.2'
The response will contain the monitor information:
{
"data": {
"type": "monitor",
"id": "62",
"attributes": {
"name": "W3 Wopher (61331)",
"pronounceable": null,
"interval": 1,
"group": null,
"service": "tcp_port",
"maintenanceType": 0,
"maintenanceStartDate": null,
"maintenanceEndDate": null,
"maintenanceStartTime": null,
"maintenanceEndTime": null,
"settings": {
"host": "w3.monitive.com",
"port": 11511,
"timeout": 20000000000
}
},
"links": {
"self": "/monitors/62"
},
"meta": {
"status": 1,
"state": 10,
"created": "2020-11-18T12:46:49+00:00",
"updated": "2021-03-09T19:17:05+00:00"
}
}
}
See more details in the Monitors section in Swagger.
Incidents
Incidents are records of outages being detected on a monitor.
An incident has a starting and ending date, plus the detected reason and acknowledge information.
You can retrieve incidents:
- by ID
- for a specific monitor
- for a specific team
See more details in the Incidents section in Swagger.
Channels
Channels are the mediums through which we send outage & recovery alerts. Example of channels are SMS, email, phone call, webhook, Pager Duty etc.
Using the GET /teams/{id}/channels request, you can retrieve the list of available channels for the specified team.
See more details in the Channels section in Swagger.
Groups
Monitors can be grouped to allow better organization of a team’s monitors.
Each monitor has a group attribute, in which you can send the group’s name when you create or update a monitor. Therefore, groups are created whenever a new group is specified at a monitor’s saving time.
The Groups request are designed to help retrieve all the created groups, and also to retrieve availability and latency information for a group.
See more details in the Groups section in Swagger.
Reports
Uptime & availability reports management can be done with the reports requests.
Reports belong to the team, but each user in the team receives his own copy.
You can retrieve all reports, create a custom report, update or delete a custom report.
See the Reports requests in Swagger for more information.
Team Features
A team owner can enable or disable any of the optional features available.
Please note that even though most of the features are just on/off switches, others have settings that can or should be updated accordingly.
Be careful when removing a feature, as it will remove the feature’s additional settings from all the entities (such as monitors). For example, a team having the HTTP Keywords feature enabled, when disabling this feature, all the set keywords for all the monitors will be removed.
See the Team Features requests in Swagger for more information.
Team Management
When enabling the Team Management feature, the team owner becomes the administrator of the team.
Team owner can invite users to the team. When inviting, the team owner can select if the invited user is a regular member, or a read-only member. Read-only members cannot update anything, meaning they cannot add/remove/update/disable/enable monitors. They can, however invite other read-only members, and the can create custom reports and manage the reports that they created.
The Team Management requests enable the owner to invite or exclude team members on his account:
- invite a new member or readonly user to her or his team;
- revoke an invitation previously sent;
- list the active invitations;
- list the active users;
- change the type of a user (regular member to read-only and vice-versa);
- remove a user from a team.
See the Team Management requests in Swagger for more information.
Status
This GET request provides quick information to Monitive’s system status.
A basic GET /status request would return something like this:
{
"meta": {
"status": "active",
"components": [
"rel-db",
"ts-db",
"line"
],
"failures":[
]
}
}
If there’s an issue, the status would show error instead of active. And issue does not mean the system is down, but that at least one component might have an issue that needs looking into.