Skip to main content

/api/v1/event/list/

  • Updated

The /event/list/ endpoint is used to view, create and update events.  The following parameters are supported on this endpoint:

INPUT PARAMETERS

auto_start
boolean
(optional)

When enabled, the event will be automatically started based on the start time for the event. Any notification methods that have been set in the default notification options when the event is started will also be triggered.

Applies to maintenance events only.

Note: The start time must have seconds equal to '00' in order for the event to be automatically started.

auto_end
boolean
(optional)

When enabled, the event will be automatically ended based on the end time for the event. Any notification methods that have been set in the default notification options when the event is ended will also be triggered.

Applies to maintenance events only.

Note: The end time must have seconds equal to '00' in order for the event to be automatically ended.

auto_mins
integer
(optional)

When automatically starting a maintenance event, optionally send a reminder to subscribed users up to 24 hours (expressed in minutes) prior to the maintenance start time.

Applies to maintenance events only.

coordinator
string
(optional)

The event coordinator. The event coordinator is limited to 1000 characters.

coordinator_md
boolean
(optional)

Enable the markdown editor in the StatusDashboard administration console for this field.

description
string

The description for the event. The event description is limited to 5000 characters.

description_md
boolean
(optional)

Enable the markdown editor in the StatusDashboard administration console for this field.

end
string

The end date/time of the event (in UTC). Date/time must be in the following format: yyyy-mm-ddThh:mm:ss. Incident events that are not closed should not include an end date/time.

event_service
array

Services that are impacted by the event.  Event services can be updated in several different ways:

  • When creating the event (POST)
  • When updating the event (PUT)
Note: A service can also be added by submitting a POST to the /api/v1/event/service/ endpoint.  If you would like to delete services from the event, you must submit a DELETE request to the /api/v1/event/service/ endpoint.
 

service
string

 

The service resource_uri of the service you are adding to the event.

 

event_update
array
(optional)

Updates about the event.  Updates can be added using the /event/list/ endpoint in two ways:

  • When creating the event (POST)
  • When updating the event (PUT)

An event update can also be added by submitting a POST to the /api/v1/event/update/ endpoint.  If you would like to delete updates from the event, you must submit a DELETE request to the /api/v1/event/update/ endpoint.

date
string
(optional)

 

The update date/time (in UTC). Date/time must be in the following format: yyyy-mm-ddThh:mm:ss. If the date is not provided, the current date/time will be used for the update.

 

markdown
boolean
(optional)

 

Enable the markdown editor in the StatusDashboard administration console for this field.

 

status
string
(optional)

 

The resource_uri of the status of this update. If no status is provided, the 'update' status will be assigned.

 

update
string

 

The event update text. Event updates are currently limited to 5000 characters.

 

hidden_admin_uptime
boolean
(optional)

Hide the event from uptime reports run from the StatusDashboard administration portal.

hidden_db
boolean
(optional)

Hide the event from all areas of the dashboard including the main dashboard, content modules, search results, event detail pages RSS feeds and uptime reports.

impact
string
(optional)

The impact analysis for the event. The impact analysis is limited to 1000 characters.

impact_md
boolean
(optional)

Enable the markdown editor in the StatusDashboard administration console for this field.

notifications
string
(optional)

Notifications that will be triggered when the event is created or updated. The following parameters are supported:

email
string
(optional)

 

Email notification settings 

enabled
boolean

 

 Whether or not to trigger email notifications to subscribed users.

email_subject
string
(optional)

 

 The subject line for the email being sent. Once set, this parameter does not need to be set for future email notifications on the same event. This field is limited to 250 characters.

gchat 
string
(optional)

 

Google Chat notification settings 

enabled
boolean

 

Whether or not to trigger Google Chat notifications.

 

details
boolean
(optional)

 

Whether or not to include all event details.

 

message
string
(optional)

 

The Google Chat message to include.

 

slack
string
(optional)

 

Slack notification settings 

enabled
boolean

 

Whether or not to trigger Slack notifications.

 

details
boolean
(optional)

 

Whether or not to include all event details.

 

message
string
(optional)

 

The Slack message to include.

 

sms
string
(optional)

 

SMS notification settings 

enabled
boolean		 Whether or not to trigger sms notifications to subscribed users.
sms_text
string
(optional)		 Custom text for the SMS message, which will replace the default StatusDashboard SMS text. This field is limited to 85 characters.

teams 
string
(optional)

 

Teams notification settings 

enabled
boolean

 

Whether or not to trigger Teams notifications.

 

details
boolean
(optional)

 

Whether or not to include all event details.

 

message
string
(optional)

 

The Teams message to include.

 

twitter
string
(optional)

 

Twitter notification settings 

enabled
boolean		 Whether or not to trigger Twitter notifications.
tweet_text
string
(optional)		 Custom text for the Tweet, which will replace the default StatusDashboard tweet text. This field is limited to 100 characters.

webhook
string
(optional)

Webhook notification settings

 

enabled
boolean		 Whether or not to trigger webhook notifications to subscribed users.

severity
string
(optional)

The event severity. The event severity must be entered as the resource_uri of a valid event severity.

severity_hidden
boolean
(optional)

Whether or not to display the severity on status dashboards and notifications. When set to true, the severity will be hidden.

severity_value

string

(optional)

A custom severity value (the value must already be defined in the event configuration)

start
string

The start date/time of the event (in UTC). Date/time must be in the following format: yyyy-mm-ddThh:mm:ss

status
string

The event status. The event status must be entered as the resource_uri of a valid event status. The following event statuses are supported for each event type: 

  • Incident Events: investigating, identified, monitoring, resolved
  • Maintenance Events: planning, started, inprogress, verifying, completed

tag_event

array

(optional)

Event tags that are added to the event.  Event tags can be added in several different ways:

  • When creating the event (POST)
  • When updating the event (PUT)
Note: An event tag can also be added by submitting a POST to the /api/v1/event/tag/event/ endpoint.  If you would like to delete tags from the event, you must submit a DELETE request to the /api/v1/event/tag/event/ endpoint.

tag
string

 

The tag/event resource_uri of the event tag you are adding to the event.

 

tag_notification

array

(optional)

 

Notification tags that are added to the event.  Notification tags can be added in several different ways:

  • When creating the event (POST)
  • When updating the event (PUT)
Note: A notification tag can also be added by submitting a POST to the /api/v1/event/tag/notification/ endpoint.  If you would like to delete tags from the event, you must submit a DELETE request to the /api/v1/event/tag/notification/ endpoint.

tag
string

 

The tag/notification resource_uri of the notification tag you are adding to the event.

 

template

string

(optional)

An event template from which to create the event.  The event template must be entered as the resource_uri of a valid event template.  Templates are only allowed on POST requests (event creation), not PUTs.

When creating events from templates, only the following fields are required:

  • Incident: start, status
  • Maintenance: start, stop, status

If you want to enable notifications for an event that is being created with a template, you must enable the specific notification method in the API call, for example:

"notifications":{"email":{"enabled":true}}

When parameters are included in the API call that are also provided by the template, the provided parameters will take precedence.

type
string

The event type. The event type must be entered as the resource_uri of a valid event type. There are two types of events that are currently supported:

  • Incident
  • Maintenance

 

Examples

List Events (List method, GET)

curl --header "Authorization:ApiKey testuser:256ee09ded99b29036fac4de96acedb7e8af7bf7" https://www.statusdashboard.com/api/v1/event/list/

{
    "meta": {
        "limit": 10,
        "next": null,
        "offset": 0,
        "previous": null,
        "total_count": 2
    },
    "objects": [
        {
            "auto_start": false,
            "auto_end": false,
            "auto_mins": 0,
            "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,
            "severity_hidden": false,
            "severity_value": "",
            "start": "2015-08-10T16:25:00",
            "status": {
                "resource_uri": "/api/v1/status/2/", 
                "status": "investigating"
            },
            "tag_event": [],
            "tag_notification": [],
            "type": {
                "resource_uri": "/api/v1/type/1/",
                "type": "incident"
            },
            "user": "/api/v1/user/1002/"
        },
        {
            "auto_start": false,
            "auto_end": false,
            "auto_mins": 0,
            "coordinator": "", 
            "coordinator_md": false,
            "description": "We will be performing system maintenance on our corporate website to install system patches.  The patching procedure requires a reboot of the system - the website may be intermittently available during the maintenance period.",
            "description_md": false,
            "end": "2015-05-15T16:00:00",
            "event_service": [
                {
                    "event": "/api/v1/event/list/70/",
                    "resource_uri": "/api/v1/event/service/63/",
                    "service": {
                        "description": "",
                        "group": "North America DataCenter",
                        "hidden": false,
                        "resource_uri": "/api/v1/service/150/",
                        "service_name": "Web Site"
                    }
                }
            ],
            "event_update": [],
            "hidden_admin_uptime": false, 
            "hidden_db": false, 
            "impact": "", 
            "impact_md": false, 
            "resource_uri": "/api/v1/event/list/70/",
            "severity": null,
            "severity_hidden": false,
            "severity_value": "",
            "start": "2015-08-15T14:00:00",
            "status": {
                "resource_uri": "/api/v1/status/1/",
                "status": "planning"
            },
            "type": {
                "resource_uri": "/api/v1/type/2/",
                "type": "maintenance"
            },
            "user": "/api/v1/user/1002/"
        }
    ]
}

Upon success, you'll receive back an HTTP 200 (OK) indicating that the API call succeeded.

Add an Incident Event (List method, POST)

curl --header "Content-Type: application/json" --header "Authorization:ApiKey testuser:256ee09ded99b29036fac4de96acedb7e8af7bf7" -X POST --data '{"start":"2015-09-21T09:00:00","status":"/api/v1/status/2/","description":"API Test event","type":"/api/v1/type/1/", "event_service":[{"service":"/api/v1/service/151/"},{"service":"/api/v1/service/152/"}]}' https://www.statusdashboard.com/api/v1/event/list/

{
    "auto_start": false,
    "auto_end": false,
    "auto_mins": 0,
    "coordinator": "", 
    "coordinator_md": false, 
    "description": "API Test event",
    "description_md": false,
    "end": null,
    "event_service": [
        {
            "event": "/api/v1/event/list/72/",
            "resource_uri": "/api/v1/event/service/66/",
            "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/72/",
            "resource_uri": "/api/v1/event/service/67/",
            "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/72/",
    "severity": null,
    "severity_hidden": false,
    "severity_value": "",
    "start": "2015-09-21T09:00:00",
    "status": {
        "resource_uri": "/api/v1/status/2/",
        "status": "investigating"
    },
    "tag_event": [],
    "tag_notification": [],
    "type": {
        "resource_uri": "/api/v1/type/1/",
        "type": "incident"
    },
    "user": "/api/v1/user/1002/"
}

Upon success, you'll receive back an HTTP 201 (created) along with the details about the resource you just created.

Delete an Event (Detail method, DELETE)

curl --header "Authorization:ApiKey testuser:256ee09ded99b29036fac4de96acedb7e8af7bf7" -X DELETE https://www.statusdashboard.com/api/v1/event/list/72/

Upon success, you'll receive back an HTTP 204 (No Content) indicating that the request was fulfilled but there is no data to display.

Update an Event and trigger email and Teams notifications (Detail method, PUT)

curl --header "Content-Type: application/json" --header "Authorization:ApiKey testuser:256ee09ded99b29036fac4de96acedb7e8af7bf7" -X PUT --data '{"event_update":[{"update":"Test event update."}],"notifications":{"email":{"enabled":true},"teams":{"enabled":true,}}}' https://www.statusdashboard.com/api/v1/event/list/72/

{
    "auto_start": false,
    "auto_end": false,
    "auto_mins": 0,
    "coordinator": "", 
    "coordinator_md": false, 
    "description": "API Test event",
    "description_md": false,
    "end": null,
    "event_service": [
        {
            "event": "/api/v1/event/list/72/",
            "resource_uri": "/api/v1/event/service/66/",
            "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/72/",
            "resource_uri": "/api/v1/event/service/67/",
            "service": {
                "description": "",de
                "group": "North America DataCenter",
                "hidden": false,
                "resource_uri": "/api/v1/service/152/",
                "service_name": "File Server"
            }
        }
    ],
    "event_update": [
        {
            "date": "2015-09-21T09:31:25",
            "event": "/api/v1/event/list/72/",
            "markdown": false,
            "resource_uri": "/api/v1/event/update/15/",
            "status": {
                "resource_uri": "/api/v1/status/8/", 
                "status": "update"
            },
            "update": "Test event update.",
            "user": "/api/v1/user/1002/"
        }
    ],
    "notifications": {
        "email": {
            "enabled": true
        },
        "teams": {
            "enabled": true
        }
    },
    "hidden_admin_uptime": false, 
    "hidden_db": false,
    "impact": "", 
    "impact_md": false,  
    "resource_uri": "/api/v1/event/list/72/",
    "severity": null,
    "severity_hidden": false,
    "severity_value": "",
    "start": "2015-09-21T09:00:00",
    "status": {
        "resource_uri": "/api/v1/status/2/",
        "status": "investigating"
    },

    "type": {
        "resource_uri": "/api/v1/type/1/",
        "type": "incident"
    },
    "user": "/api/v1/user/1002/"
}

Upon success, you'll receive back an HTTP 201 (created) along with the full details of the current event (including the update).

Related articles