Introduction
Register as a AdminLabs user and get your free API key.
API related credentials (api-key, account-id) can be found in Dashboard (Settings / API). Baseurl for API is https://api.adminlabs.com/v1.
Authentication
curl -X GET "https://api.adminlabs.com/v1/account"
-H "accept: application/json"
-H "account-id: ACCOUNT-ID"
-H "api-key: API-KEY"
At the moment, this API supports only pre-generated key based authentication. Key and account ID can be obtained from AdminLabs dashboard when API is enabled for account.
All API requests must contain the following headers:
account-id
Account IDapi-key
API Key
And all request bodies should have content type application/json and be valid JSON.
Rate limiting
AdminLabs API is not rate limited at the time being. Be aware that rate limiting might be added later on, to prevent abuses.
Versioning
Current API version is v1
and all calls should be made using that version. New versions will be released when we make backwards-incompatible changes to any of our endpoints.
Endpoints
Account
Account related endpoints.
Get account details
Get account details - Request example
curl -X GET "https://api.adminlabs.com/v1/account"
-H "accept: application/json"
-H "account-id: ACCOUNT-ID"
-H "api-key: API-KEY"
Get account details - Example response
{
"id": "f3282448-c32c-11e6-9b20-08002744557f",
"company": "The Best Company In The World Ltd",
"timeZone": "Europe/Helsinki",
"funds": 120
}
Get account details.
HTTP Request
GET https://api.adminlabs.com/v1/account
Get account users
Get account users - Example request
curl -X GET "https://api.adminlabs.com/v1/users"
-H "accept: application/json"
-H "account-id: ACCOUNT-ID"
-H "api-key: API-KEY"
Get account users - Example response
[
{
"id": "f3282448-c32c-11e6-9b20-08002744557f",
"name": "John Doe",
"email": "ex.ample@address.com",
"emailConfirmed": true,
"mobile": "+358401231234",
"mobileConfirmed": false,
"pushoverKey": "gsdsZPP3SdgjqPvNscyM2fgfkx2yn",
"slackWebhookUrl": "https://hooks.slack.com/services/T1234567/B12345678/KfuwefDFSGunwgsdfgsfd",
"slackChannel": "#testing",
"isAdmin": true
}
]
Get attached users (ascending by name).
HTTP Request
GET https://api.adminlabs.com/v1/users
Register new account
Send an invitation to register a new account. Account needs to be activated from the link sent to email used to register the new account. If your account has referral program active, new user will automatically be detected as referral after activation and you will receive the commission.
Note that this endpoint used API version v2
unlike other endpoints at the time being.
Register new account - Request example
curl -X GET "https://api.adminlabs.com/v2/account/register"
-H "accept: application/json"
-H "account-id: ACCOUNT-ID"
-H "api-key: API-KEY"
Register new account - Example parameters
{
"email": "john@acme.inc"
}
Register new account - Example response on success
{
"status": "success"
}
Register new account - Example response on failure
{
"code": 10001,
"message": "Account exist with given email"
}
HTTP Request
GET https://api.adminlabs.com/v2/account/register
Request parameters
Type | Required | Description | |
---|---|---|---|
email |
string | Yes | Email to use on registering new account. |
Return values on failure
Type | Description | |
---|---|---|
code |
integer | General error code or custom error code. |
message |
string | Explanation of error that caused the failure. |
Custom error code explanations
Error Code | Meaning |
---|---|
10001 | Account already exists with given email address. |
103 | The request was missing the email. |
104 | The request was unacceptable due to invalid parameter. |
Components
Component related endpoints.
Get components
Get components - Example request
curl -X GET "https://api.adminlabs.com/v1/components"
-H "accept: application/json"
-H "account-id: ACCOUNT-ID"
-H "api-key: API-KEY"
Get components - Example response
[
{
"id": "49739a11-a218-11e7-9187-08002744557f",
"parentComponentId": null,
"name": "Parent Component",
"description": "This is an example",
"state": "operational"
},
{
"id": "c952a5dd-023d-11e8-9b76-08002744557f",
"parentComponentId": "49739a11-a218-11e7-9187-08002744557f",
"name": "Child component 1",
"description": "This is an example",
"state": "degradedPerformance"
},
{
"id": "b952a5dd-023d-11e8-9b76-08002744557f",
"parentComponentId": "49739a11-a218-11e7-9187-08002744557f",
"name": "Child component 2",
"description": null,
"state": "partialOutage"
}
]
Get all components (ascending by name).
HTTP Request
GET https://api.adminlabs.com/v1/components
Request parameters
Type | Required | Description | |
---|---|---|---|
statusPageId |
string | No | Only return components that are attached to the given Status page. |
Return values
Type | Description | |
---|---|---|
state |
string | Component state. Possible values are 'operational', 'degradedPerformance', 'partialOutage', 'majorOutage'. |
Update component
Update component - Example request
curl -X PUT "https://api.adminlabs.com/v1/components/{id}"
-H "accept: application/json"
-H "account-id: ACCOUNT-ID"
-H "api-key: API-KEY"
Update component - Example parameters
{
"state": "operational"
}
Update component - Example response
{
"status": "success"
}
HTTP Request
PUT https://api.adminlabs.com/v1/components/{id}
Request parameters
Type | Required | Description | |
---|---|---|---|
state |
string | No | Possible values are 'operational', 'degradedPerformance', 'partialOutage', 'majorOutage'. |
Incidents
Incident related endpoints.
Get incidents
Get incidents (ascending by updated).
Get incidents - Example request
curl -X GET "https://api.adminlabs.com/v1/incidents"
-H "accept: application/json"
-H "account-id: ACCOUNT-ID"
-H "api-key: API-KEY"
Get incidents - Example response
[
{
"id": "f3cbfaf0-7eba-11e8-b2c7-4bc35b7606c6",
"title": "This is your incident's title",
"state": "open",
"updated": 1530620205,
"components": [
"f3cc1d70-7eba-11e8-bc0d-6349c57d781f",
"f3cc2cc0-7eba-11e8-9ba1-7d40143c3b0e"
],
"stateChangeHistory": [
{
"id": "f3cc0fb0-7eba-11e8-a1ba-b38c4f900ee0",
"state": "open",
"description": "Here you can describe the incident",
"created": 1530620205
}
]
}
]
HTTP Request
GET https://api.adminlabs.com/v1/incidents
Return values
Type | Description | |
---|---|---|
state |
string | Possible values are 'open', 'investigating', 'identified', 'resolutionInProgress', 'waiting', 'resolved', 'monitoring', 'closed'. |
updated |
integer | Timestamp of last state change. |
components |
array | List of attached components. |
stateChangeHistory |
array | Change history for the incident. |
Create new incident
Create new incident - Example request
curl -X POST "https://api.adminlabs.com/v1/incidents"
-H "accept: application/json"
-H "account-id: ACCOUNT-ID"
-H "api-key: API-KEY"
Create new incident - Example parameters
{
"time": 1530620205,
"state": "open",
"title": "This is your incident's title",
"description": "Here you can describe the incident",
"notifySubscribers": false,
"components": [
{
"id": "aaab8b27-3e21-11e8-b4a5-08002744557f"
},
{
"id": "cfff8665-3e21-11e8-b4a5-08002744557f",
"state": "partialOutage"
}
]
}
Create new incident - Example response
{
"status": "success"
}
HTTP Request
POST https://api.adminlabs.com/v1/incidents
Request parameters
Type | Required | Description | |
---|---|---|---|
time |
integer | No | Timestamp for the incident. If time is given, it must be less than 24 hours ago. If time isn't given, the current timestamp will be used. |
state |
string | Yes | Possible values are 'open', 'investigating', 'identified', 'resolutionInProgress', 'waiting', 'resolved', 'monitoring'. |
title |
string | Yes | The title for the incident. |
description |
string | Yes | The description for the incident. |
notifySubscribers |
boolean | Yes | If notifySubscribers is true (and there are status page subscribers), notifies will be sent. |
components |
array | No | List of attached components. Component's id is required. If 'state' is given, component state will be changed. |
Update incident
Update incident - Example request
curl -X PUT "https://api.adminlabs.com/v1/incidents/{id}"
-H "accept: application/json"
-H "account-id: ACCOUNT-ID"
-H "api-key: API-KEY"
Update incident - Example parameters
{
"time": 1530620205,
"state": "open",
"title": "This is your incident's title",
"description": "Here you can describe the incident",
"notifySubscribers": false,
"components": [
{
"id": "cfff8665-3e21-11e8-b4a5-08002744557f",
"state": "partialOutage"
}
]
}
Update incident - Example response
{
"status": "success"
}
HTTP Request
PUT https://api.adminlabs.com/v1/incidents/{id}
Request parameters
Type | Required | Description | |
---|---|---|---|
time |
integer | No | Timestamp for the incident state change. If time is given, it must be less than 24 hours ago (and after the previous state change). If time isn't given, the current timestamp will be used. |
state |
string | Yes | Possible values are 'open', 'investigating', 'identified', 'resolutionInProgress', 'waiting', 'resolved', 'monitoring'. |
title |
string | Yes | The title for the incident. |
description |
string | Yes | The description for the incident. |
notifySubscribers |
boolean | Yes | If notifySubscribers is true (and there are status page subscribers), notifies will be sent. |
components |
array | No | List of component state changes. Component's id is required. If 'state' is given, component state will be changed. It is not allowed to add new components in this request. |
Delete incident
Delete incident - Example request
curl -X DELETE "https://api.adminlabs.com/v1/incidents/{id}"
-H "accept: application/json"
-H "account-id: ACCOUNT-ID"
-H "api-key: API-KEY"
Delete incident - Example response
{
"status": "success"
}
HTTP Request
DELETE https://api.adminlabs.com/v1/incidents/{id}
Incident templates
Incident template related endpoints.
Get incident templates
Get incident templates.
Get incident templates - Example request
curl -X GET "https://api.adminlabs.com/v1/incident-templates"
-H "accept: application/json"
-H "account-id: ACCOUNT-ID"
-H "api-key: API-KEY"
Get incident templates - Example response
[
{
"id": "210edfe8-9be5-11ed-ba77-6a74103dd335",
"name": "Template 1",
"title": "Template 1 title",
"description": "Template 1 description"
},
{
"id": "25f4c936-9be5-11ed-ba77-6a74103dd335",
"name": "Template 2",
"title": "Template 2 title",
"description": "Template 2 description"
}
]
HTTP Request
GET https://api.adminlabs.com/v1/incident-templates
Return values
Type | Description | |
---|---|---|
id |
string | ID of the Incident template. |
name |
string | Name of the Incident template. |
title |
string | Title of the Incident template. |
description |
string | Description of the Incident template. |
Maintenances
Maintenance related endpoints.
Get maintenances
Get scheduled (and ongoing) maintenances (ascending by start).
Get maintenances - Example request
curl -X GET "https://api.adminlabs.com/v1/maintenances"
-H "accept: application/json"
-H "account-id: ACCOUNT-ID"
-H "api-key: API-KEY"
Get maintenances - Example response
[
{
"id": "f3282448-c32c-11e6-9b20-08002744557f",
"start": 1499226127,
"end": 1499228127,
"ongoing": true,
"title": "Database maintenance",
"description": "All database servers will be updated and restarted.",
"ignoreOutages": true,
"components": [
{
"id": "2983c5c2-ddd8-11e7-90ff-08002744557f"
},
{
"id": "bce463d3-c093-11e7-b0af-08002744557f"
}
],
"monitors": [
{
"id": "f3282448-c32c-11e6-9b20-08002744557f"
}
],
"comments": [
{
"id": "d3282448-c32c-11e6-9b20-08002744557f",
"userId": "g3282448-c32c-11e6-9b20-08002744557f",
"name": "John Doe",
"comment": "Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book.",
"showOnStatusPage": true,
"posted": 1499226127
}
]
}
]
HTTP Request
GET https://api.adminlabs.com/v1/maintenances
Monitors
Monitor related endpoints.
Get monitors
Get all monitors (ascending by name).
Get monitors - Example request
curl -X GET "https://api.adminlabs.com/v1/monitors"
-H "accept: application/json"
-H "account-id: ACCOUNT-ID"
-H "api-key: API-KEY"
Get monitors - Example response
[
{
"id": "f3282448-c32c-11e6-9b20-08002744557f",
"groupId": "h3282448-c32c-11e6-9b20-08002744557f",
"name": "High availability web site",
"interval": 1,
"retryInterval": 60,
"scannerLocationId": 1,
"outageId": null,
"lastScan": 1499226127,
"type": "url",
"health": "ok",
"state": "enabled",
"address": "http://www.yourpersonalwebsite.xyz"
}
]
HTTP Request
GET https://api.adminlabs.com/v1/monitors
Return values
Type | Description | |
---|---|---|
interval |
integer | Scanning interval - minutes. |
retryInterval |
integer | Retry interval (after first unsuccessful scan) - seconds. |
type |
string | Monitor type. Possible values are 'url', 'port', 'ping'. |
health |
string | Monitor health state. Possible values are 'ok', 'down'. |
state |
string | Monitors state. Possible values are 'enabled', 'disabled', 'paused'. |
Get monitor history
Get daily history details for selected year and month (ascending by date).
Get monitor history - Example request
curl -X GET "https://api.adminlabs.com/v1/monitors/{id}/history/{year}/{month}"
-H "accept: application/json"
-H "account-id: ACCOUNT-ID"
-H "api-key: API-KEY"
Get monitor history - Example response
[
{
"report-date": "2017-04-02",
"active-time": 1450,
"downtime-total": 360,
"downtime-maintenance-noticed": 180,
"outages-total": 4,
"outages-maintenance-noticed": 2,
"service-level": 98.12,
"service-level-maintenance-noticed": 99.99,
"scan-counter": 1450
}
]
HTTP Request
GET https://api.adminlabs.com/v1/monitors/{id}/history/{year}/{month}
Query Parameters
Required | Type | Description | |
---|---|---|---|
id |
true | string | Monitor ID. |
year |
true | integer | Numeric representation of a year. |
month |
true | integer | Numeric representation of a month, with leading zeros. |
Get monitor scan history
Get scans for defined date (ascending by runTime).
Get monitor scan history - Example request
curl -X GET "https://api.adminlabs.com/v1/monitors/{id}/scans/{date}"
-H "accept: application/json"
-H "account-id: ACCOUNT-ID"
-H "api-key: API-KEY"
Get monitor scan history - Example response
[
{
"runTime": 1499226127,
"loadTime": 10.12,
"wasSuccessful": true
}
]
HTTP Request
GET https://api.adminlabs.com/v1/monitors/{id}/scans/{date}
Query Parameters
Required | Type | Description | |
---|---|---|---|
id |
true | string | Monitor ID. |
date |
true | string | Date formatted YYYY-MM-DD (for example 2017-08-04). |
Get monitor outage history
Get all outages (ascending by started).
Get monitor outage history - Example request
curl -X GET "https://api.adminlabs.com/v1/monitors/{id}/outages"
-H "accept: application/json"
-H "account-id: ACCOUNT-ID"
-H "api-key: API-KEY"
Get monitor outage history - Example response
[
{
"id": "f3282448-c32c-11e6-9b20-08002744557f",
"maintenanceId": null,
"started": 1499226127,
"ended": 1499226327,
"comments": [
{
"id": "d3282448-c32c-11e6-9b20-08002744557f",
"userId": "g3282448-c32c-11e6-9b20-08002744557f",
"name": "John Doe",
"comment": "Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book.",
"showOnStatusPage": true,
"posted": 1499226127
}
]
}
]
HTTP Request
GET https://api.adminlabs.com/v1/monitors/{id}/outages
Request Parameters
Required | Type | Description | |
---|---|---|---|
id |
true | string | Monitor ID |
Get monitor maintenances
Get scheduled (and ongoing) maintenances (ascending by start).
Get monitor maintenances - Example request
curl -X GET "https://api.adminlabs.com/v1/monitors/{id}/maintenances"
-H "accept: application/json"
-H "account-id: ACCOUNT-ID"
-H "api-key: API-KEY"
Get monitor maintenances - Example response
[
{
"id": "f3282448-c32c-11e6-9b20-08002744557f",
"start": 1499226127,
"end": 1499228127,
"ongoing": false,
"title": "Database maintenance",
"description": "All database servers will be updated and restarted.",
"ignoreOutages": true,
"comments": [
{
"id": "d3282448-c32c-11e6-9b20-08002744557f",
"userId": "g3282448-c32c-11e6-9b20-08002744557f",
"name": "John Doe",
"comment": "Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book.",
"showOnStatusPage": true,
"posted": 1499226127
}
]
}
]
HTTP Request
GET https://api.adminlabs.com/v1/monitors/{id}/maintenances
Query Parameters
Required | Type | Description | |
---|---|---|---|
id |
true | string | Monitor ID |
Status Pages
Status page related endpoints.
Get status Pages
Get status pages (ascending by name).
Get status Pages - Example request
curl -X GET "https://api.adminlabs.com/v1/status-pages"
-H "accept: application/json"
-H "account-id: ACCOUNT-ID"
-H "api-key: API-KEY"
Get status Pages - Example response
[
{
"id": "41421d49-3e2e-11e8-b4a5-08002744557f",
"name": "Example - Business Status Page",
"nextCharge": 1539521104,
"plan": "Business",
"subscribers": 1,
"viewers": 0,
"type": "public",
"trial": false
},
{
"id": "520e109a-b631-11e8-810c-08002744557f",
"name": "Example - Confidential",
"nextCharge": 1539367311,
"plan": "Confidential",
"subscribers": 0,
"viewers": 0,
"type": "private",
"trial": false
}
]
HTTP Request
GET https://api.adminlabs.com/v1/status-pages
Return values
Type | Description | |
---|---|---|
plan |
string | Status page plan. |
nextCharge |
integer | Timestamp of next charge. |
subscribers |
integer | Amount of status page subscribers (null for private pages). |
viewers |
integer | Amount of status page viewers (null for private pages). |
type |
string | Status page type (possible values are 'public' and 'private'). |
trial |
boolean | True if trial is active, otherwise false. |
Get status page subscribers
Get status pages subscribers (ascending by email).
Get status page subscribers - Example request
curl -X GET "https://api.adminlabs.com/v1/status-pages/{id}/subscribers"
-H "accept: application/json"
-H "account-id: ACCOUNT-ID"
-H "api-key: API-KEY"
Get status page subscribers - Example response
[
{
"id": "119faaf0-4217-11e8-9cf2-57cde79403a2",
"email": "user1@example.com",
"source": "api",
"type": "partial",
"components": [
"aaab8b27-3e21-11e8-b4a5-08002744557f"
],
"state": "subscribed"
},
{
"id": "17f170c0-4217-11e8-b751-6bba8c43f963",
"email": "user2@example.com",
"source": "status-page",
"type": "all",
"components": [],
"state": "subscribed"
},
{
"id": "3ff170c0-4217-11e8-b751-6bba8c43f963",
"email": "user3@example.com",
"source": "status-page",
"type": "all",
"components": [],
"state": "unsubscribed"
}
]
HTTP Request
GET https://api.adminlabs.com/v1/status-pages/{id}/subscribers
Return values
Type | Description | |
---|---|---|
source |
string | Possible values are 'status-page', 'api', 'dashboard'. |
type |
string | Possible values are partial and all. |
components |
array | If subscription type is 'partial', list of component ids is returned here. If subscription type is 'all', array will be empty. |
state |
string | Possible values are 'subscribed', 'unsubscribed', 'blocked'. |
Create new subscriber to status page
Save new subscriber to Status Page.
Example 1: Save new subscriber and add it to all components.
Example 2: Save new subscriber and add it selected components.
Create new subscriber to status page - Example request
curl -X POST "https://api.adminlabs.com/v1/status-pages/{id}/subscribers"
-H "accept: application/json"
-H "account-id: ACCOUNT-ID"
-H "api-key: API-KEY"
Create new subscriber to status page - Example 1 parameters
{
"email": "user1@example.com",
"components": []
}
Create new subscriber to status page - Example 1 response
{
"status": "success"
}
Create new subscriber to status page - Example 2 parameters
{
"email": "user1@example.com",
"components": [
"h43cadb0-4221-11e8-854c-0b019918638d"
]
}
Create new subscriber to status page - Example 2 response
{
"status": "success"
}
HTTP Request
POST https://api.adminlabs.com/v1/status-pages/{id}/subscribers
Delete status page subscriber
Delete status page subscriber - Example request
curl -X DELETE "https://api.adminlabs.com/v1/status-pages/{id}/subscribers"
-H "accept: application/json"
-H "account-id: ACCOUNT-ID"
-H "api-key: API-KEY"
Delete status page subscriber - Example parameters
{
"email": "user1@example.com"
}
Delete status page subscriber - Example response
{
"success": true
}
HTTP Request
DELETE https://api.adminlabs.com/v1/status-pages/{id}/subscribers
Get status page viewers
Get status pages viewers (ascending by email).
Get status page viewers - Example request
curl -X GET "https://api.adminlabs.com/v1/status-pages/{id}/viewers"
-H "accept: application/json"
-H "account-id: ACCOUNT-ID"
-H "api-key: API-KEY"
Get status page viewers - Example response
[
{
"id": "119faaf0-4217-11e8-9cf2-57cde79403a2",
"email": "user1@example.com",
"source": "api",
"type": "partial",
"components": [
"aaab8b27-3e21-11e8-b4a5-08002744557f"
]
},
{
"id": "17f170c0-4217-11e8-b751-6bba8c43f963",
"email": "user2@example.com",
"source": "status-page",
"type": "all",
"components": []
}
]
HTTP Request
GET https://api.adminlabs.com/v1/status-pages/{id}/viewers
Return values
Type | Description | |
---|---|---|
source |
string | Possible values are 'status-page', 'api', 'dashboard'. |
type |
string | Possible values are partial and all. |
components |
array | If subscription type is 'partial', list of component ids is returned here. If subscription type is 'all', array will be empty. |
Create new viewer to status page
Save new viewer to Status Page.
Example 1: Save new viewer and add it to all components.
Example 2: Save new viewer and add it selected components.
Create new viewer to status page - Example request
curl -X POST "https://api.adminlabs.com/v1/status-pages/{id}/viewers"
-H "accept: application/json"
-H "account-id: ACCOUNT-ID"
-H "api-key: API-KEY"
Create new viewer to status page - Example 1 parameters
{
"email": "user1@example.com",
"password": "CDVd42sGGtBddZra3296",
"components": []
}
Create new viewer to status page - Example 1 response
{
"status": "success"
}
Create new viewer to status page - Example 2 parameters
{
"email": "user1@example.com",
"components": [
"h43cadb0-4221-11e8-854c-0b019918638d"
]
}
Create new viewer to status page - Example 2 response
{
"status": "success"
}
HTTP Request
POST https://api.adminlabs.com/v1/status-pages/{id}/viewers
Query Parameters
Required | Type | Description | |
---|---|---|---|
email |
true | string | Email address of the viewer. |
components |
false | array | List of components. It array is empty (or it is missing), viewer will be added to all components. |
password |
false | string | Password for viewer. Length of password must be at least 6 characters. If password field is missing, invite email will be sent. |
Delete status page viewer
Delete status page viewer - Example request
curl -X DELETE "https://api.adminlabs.com/v1/status-pages/{id}/viewers"
-H "accept: application/json"
-H "account-id: ACCOUNT-ID"
-H "api-key: API-KEY"
Delete status page viewer - Example parameters
{
"email": "user1@example.com"
}
Delete status page viewer - Example response
{
"success": true
}
HTTP Request
DELETE https://api.adminlabs.com/v1/status-pages/{id}/viewers
Errors
Example error response
{
"code": 110,
"message": "General error message"
}
AdminLabs API returns standard HTTP success or error status codes. For errors, we will also include extra information about what went wrong. The various HTTP status codes we might return are listed below.
Error Code | Meaning |
---|---|
400 | Bad Request - The request was unacceptable, often due to invalid or missing a required parameter. |
401 | Unauthorized - No valid API key (api-key) provided. |
402 | Request failed - The parameters were valid but the request failed. |
404 | Not found - The requested resource doesn’t exist. |
429 | Too Many Requests - Too many requests hit the API too quickly. We recommend an exponential backoff of your requests. |
500 | Server errors - Something went wrong on Admin Labs’ end. (Should never happed) |