Fortinet Document Library

Version:


Table of Contents

User Guide

21.4.0
Copy Link

Custom incidents using API

FortiMonitor supports the creation of custom incidents using API, which provides a mechanism for your own applications to push event data to our system and leverage FortiMonitor’s alerting and dashboard functionality.

To use the API to create and close custom incidents, the Custom Incidents feature must be enabled on your account. Please contact our support team to have it enabled.

Access FortiMonitor's API library to see all of the supported API endpoints in detail.

Add a custom incident filter 

Before you can start sending custom incidents using the API, you need to enable support on the server whose agent will be sending the incident data. To add a custom incident filter, see this topic.

Create a custom incident

This API request allows you to create a custom incident on any of your servers in FortiMonitor. The location response header contains the full URL of the new resource.

Endpoint

POST /server/{server_id}/custom_incident

The {server_id} is the Server ID of the instance where this custom incident will be created.

Authentication 

For each request, set the Authorization header to a string made up of ApiKey {token} where {token} is the API key provided to you.

Users sending API requests to FortiMonitor must have an API key and the proper user permissions

To view and manage your API keys, see API keys.

Payload 

{
"description": null,
"metadata": null,
"plugin_textkey": null,
"resource_textkey": null,
"start_time": null
}

The attributes are described in the following table:

Attribute

Data type

Required

Description

description

String


Human-readable description of the incident, which is shown in the control panel and alerts.

metadata

Dictionary


(optional) Optional dictionary of key/value fields that will be added to the incident description.

plugin_textkey

String


Textkey which specifies the application category the incident relates to.

resource_textkey

String


Textkey which specifies the metric the incident relates to.

start_time

Date


(optional) Start time in UTC; format: YYYY-MM-DD HH:MM:SS. If not provided, defaults to current time.

Resolve an incident

This API request allows you to force resolution of a custom incident. 

Endpoint

PUT /outage/{outage_id}/force_resolve

The {outage_id} is the Incident ID of the custom incident that you want to resolve using this endpoint.

Authentication 

For each request, set the Authorization header to a string made up of ApiKey {token} where {token} is the API key provided to you.

Users sending API requests to FortiMonitor must have an API key and the proper user permissions

To view and manage your API keys, see API keys.

Payload 

{
"reason": null
}

The attributes are described in the following table:

Attribute

Data type

Required

Description

reason

String


(optional) The reason for ending the incident. This will be appended to the incident log. 

HTTP status code summary

The HTTP status codes is part of the response message that provides information on the status of your API request. The following table describes the HTTP status error codes in detail: 

HTTP status code

Reason 

200 - OK

The API request is successful.

400 - Bad Request

The request failed, often due to a missing or misconfigured parameter. Check the response body for details on validation errors.

401 - Unauthorized Access

The API key provided is not valid.

404 - Not Found

The requested resource does not exist.

405 - Method Not Allowed  

The server rejected the method for the requested resource.

500 -  Internal Server Error 

The API request failed due to an internal server error.

Check the ErrorCode and ErrorMessage response headers for more information.

Custom incidents using API

FortiMonitor supports the creation of custom incidents using API, which provides a mechanism for your own applications to push event data to our system and leverage FortiMonitor’s alerting and dashboard functionality.

To use the API to create and close custom incidents, the Custom Incidents feature must be enabled on your account. Please contact our support team to have it enabled.

Access FortiMonitor's API library to see all of the supported API endpoints in detail.

Add a custom incident filter 

Before you can start sending custom incidents using the API, you need to enable support on the server whose agent will be sending the incident data. To add a custom incident filter, see this topic.

Create a custom incident

This API request allows you to create a custom incident on any of your servers in FortiMonitor. The location response header contains the full URL of the new resource.

Endpoint

POST /server/{server_id}/custom_incident

The {server_id} is the Server ID of the instance where this custom incident will be created.

Authentication 

For each request, set the Authorization header to a string made up of ApiKey {token} where {token} is the API key provided to you.

Users sending API requests to FortiMonitor must have an API key and the proper user permissions

To view and manage your API keys, see API keys.

Payload 

{
"description": null,
"metadata": null,
"plugin_textkey": null,
"resource_textkey": null,
"start_time": null
}

The attributes are described in the following table:

Attribute

Data type

Required

Description

description

String


Human-readable description of the incident, which is shown in the control panel and alerts.

metadata

Dictionary


(optional) Optional dictionary of key/value fields that will be added to the incident description.

plugin_textkey

String


Textkey which specifies the application category the incident relates to.

resource_textkey

String


Textkey which specifies the metric the incident relates to.

start_time

Date


(optional) Start time in UTC; format: YYYY-MM-DD HH:MM:SS. If not provided, defaults to current time.

Resolve an incident

This API request allows you to force resolution of a custom incident. 

Endpoint

PUT /outage/{outage_id}/force_resolve

The {outage_id} is the Incident ID of the custom incident that you want to resolve using this endpoint.

Authentication 

For each request, set the Authorization header to a string made up of ApiKey {token} where {token} is the API key provided to you.

Users sending API requests to FortiMonitor must have an API key and the proper user permissions

To view and manage your API keys, see API keys.

Payload 

{
"reason": null
}

The attributes are described in the following table:

Attribute

Data type

Required

Description

reason

String


(optional) The reason for ending the incident. This will be appended to the incident log. 

HTTP status code summary

The HTTP status codes is part of the response message that provides information on the status of your API request. The following table describes the HTTP status error codes in detail: 

HTTP status code

Reason 

200 - OK

The API request is successful.

400 - Bad Request

The request failed, often due to a missing or misconfigured parameter. Check the response body for details on validation errors.

401 - Unauthorized Access

The API key provided is not valid.

404 - Not Found

The requested resource does not exist.

405 - Method Not Allowed  

The server rejected the method for the requested resource.

500 -  Internal Server Error 

The API request failed due to an internal server error.

Check the ErrorCode and ErrorMessage response headers for more information.