NAV Navbar
curl
  • Introduction
  • Authentication
  • Rate limiting
  • Versioning
  • Endpoints
  • Errors
  • 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.

    Contact Technical Support

    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:

    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

    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

    Return values

    Type Description
    state string Component state. 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

    PUT https://api.adminlabs.com/v1/incidents/{id}

    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

    Query 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"
            ]
    
        },
        {
            "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}/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.

    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)