API Basics
API / API Basics

The StatusDashboard API is a RESTful API which exposes easy to understand, resource-oriented URLs.  The API makes managing your status dashboard and associated resources simple and intuitive and provides an easy way to integrate our system with your existing tools.  The API supports standard HTTP verbs, supports several different authentication methods, and uses HTTP response codes to indicate errors.  All API calls return JSON, including errors.  

There are many examples included with this tutorial to help you understand how to interact with our API.  For simplicity, most of our examples utilize the curl application but you are free to use any application or programming language you wish.


API Limits

Rate limited API calls are currently limited to 1000 calls per hour per user.  If you anticipate that your organization's needs are beyond this limit, please contact our support team.

Methods and Verbs

Most endpoints have both list and detail methods each of which accept specific HTTP verbs (e.g. DELETE, GET, POST, PUT).  List methods (e.g. /api/v1/service/) are used to either create resources, or to list all endpoint resources.  Detail methods (e.g. /api/v1/service/156/) are used to describe a specific resource, or to modify an existing resource.  For specifics on how to interact with each endpoint, please review the documentation that accompanies that endpoint.

Limits and Offsets

Each API endpoint has a maximum number of objects that can be retrieved on a single API call.  If you have more than the maximum number of objects to retrieve, the next parameter in the current API call results will be populated with the API URL for the next page of results.  For example, in the case of the service endpoint: /api/v1/service/?limit=10&offset=10 would provide 10 objects, starting at number 11.  You can also manipulate the limit and offset parameters to obtain the precise data that you want.

Resource URIs

Most API calls that result in the display of object data will include a resource_uri for each object, which is the location through which you can obtain further information about the object (through subsequent API calls).

Timezones

All times displayed in output from the API are in the UTC timezone.  All times input into the API should be converted to UTC time in the following format before being submitted: yyyy-mm-ddThh:mm:ss.

Filtering

Many API endpoints support filtering on specific values to produce more relevant results lists. Filters are added to API urls as standard arguments with relations represented as a double underscore "__".

Examples:

List Email Subscribers (Filtering on a specific email address):

curl --header "Authorization:ApiKey testuser:256ee09ded99b29036fac4de96acedb7e8af7bf7" https://www.statusdashboard.com/api/v1/subscribers/email/?email__email=user1@company1.com

{
    "meta": {
        "limit": 10, 
        "next": null, 
        "offset": 0, 
        "previous": null, 
        "total_count": 2
    }, 
    "objects": [
        {
            "confirmed": true, 
            "email": {
                "email": "user1@company1.com", 
                "resource_uri": "/api/v1/email/1001/"
            }, 
            "resource_uri": "/api/v1/subscribers/email/2001/", 
            "service": {
                "description": "", 
                "group": "default", 
                "hidden": false, 
                "resource_uri": "/api/v1/service/150/", 
                "service_name": "Web Site"
            }
        }, 
        {
            "confirmed": true, 
            "email": {
                "email": "user1@company1.com", 
                "resource_uri": "/api/v1/email/1001/"
            }, 
            "resource_uri": "/api/v1/subscribers/email/2002/", 
            "service": {
                "description": "http://owa.domain.com", 
                "group": "default", 
                "hidden": false, 
                "resource_uri": "/api/v1/service/151/", 
                "service_name": "Exchange Server"
            }
        }
    ]
}
                


List Incident Events In The Investigating State (Filtering on type and status):

curl --header "Authorization:ApiKey testuser:256ee09ded99b29036fac4de96acedb7e8af7bf7" https://www.statusdashboard.com/api/v1/event/list/?type__type=incident&status__status=investigating

{
    "meta": {
        "limit": 10, 
        "next": null, 
        "offset": 0, 
        "previous": null, 
        "total_count": 1
    }, 
    "objects": [
        {
            "auto": false,
            "coordinator": "", 
            "coordinator_md": false,
            "description": "We are currently experiencing a problem with email services in the North America region.  We are actively investigating the issue and will provide another update within 30 minutes.",
            "description_md": false,
            "end": null,
            "event_service": [
                {
                    "event": "/api/v1/event/list/71/",
                    "resource_uri": "/api/v1/event/service/64/",
                    "service": {
                        "description": "http://owa.domain.com",
                        "group": "North America DataCenter",
                        "hidden": false,
                        "resource_uri": "/api/v1/service/151/",
                        "service_name": "Exchange Server"
                    }
                },
                {
                    "event": "/api/v1/event/list/71/",
                    "resource_uri": "/api/v1/event/service/65/",
                    "service": {
                        "description": "",
                        "group": "North America DataCenter",
                        "hidden": false,
                        "resource_uri": "/api/v1/service/152/",
                        "service_name": "File Server"
                    }
                }
            ],
            "event_update": [],
            "hidden_admin_uptime": false, 
            "hidden_db": false,
            "impact": "",
            "impact_md": false,
            "resource_uri": "/api/v1/event/list/71/",
            "severity": null,
            "start": "2015-08-10T16:25:00",
            "status": {
                "resource_uri": "/api/v1/status/2/", 
                "status": "investigating"
            },
            "type": {
                "resource_uri": "/api/v1/type/1/",
                "type": "incident"
            },
            "user": "/api/v1/user/1002/"
        }
    ]
}
                

Still have questions?  Contact our support team.  We're always happy to help with any questions you might have.