Documentation Powered by ReDoc

Defcon API (0.1.0)

Download OpenAPI specification:Download

Defcon control plane API documentation

Checks

List checks

By default, this endpoint lists all enabled checks defined in the system. If all is provided with a 1 value, list all checks (enabled or not).

query Parameters
all
boolean
Default: false
Enum: false true

Should we display all checks or enabled checks only

group
string <uuid>

UUID of the group of which to return the checks

kind
string

Slug for the handler types to return

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a new check

Request Body schema: application/json

The definition of a check

One of
name
required
string

Human-friendly name

enabled
boolean
Default: true

Whether the check should run or not

sites
Array of strings
Default: ["@controller"]

List of site identifier where the check should run. If omitted, defaults to @controller.

interval
required
string

Period of time between two run of the check

site_threshold
integer
Default: 1

Number of site outages required to confirm an outage

passing_threshold
required
integer

Number of consecutive fails required to consider a site failed

failing_threshold
required
integer

Number of consecutive passes required to consider a site recovered

silent
boolean
Default: false

Should an outage for this check trigger an alert

group
string <uuid>
Default: null

Group to which the check is assigned

alerter
string <uuid>
Default: null

Unique identifier for the alerter linked to the check

required
object

Responses

Request samples

Content type
application/json
Example
Ping
Ping
TCP
UDP
HTTP
DNS
TLS expiration
Domain expiration
App Store
Play Store
Python
{
  • "name": "string",
  • "enabled": true,
  • "sites": [
    ],
  • "interval": "string",
  • "site_threshold": 1,
  • "passing_threshold": 0,
  • "failing_threshold": 0,
  • "silent": false,
  • "group": null,
  • "alerter": null,
  • "spec": {
    }
}

Retrieve a check

path Parameters
uuid
required
string <uuid>

Unique identifier

Responses

Response samples

Content type
application/json
Example
Ping
Ping
TCP
UDP
HTTP
DNS
TLS expiration
Domain expiration
Play Store
Python
{
  • "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
  • "name": "string",
  • "enabled": true,
  • "sites": [
    ],
  • "interval": "string",
  • "site_threshold": 1,
  • "passing_threshold": 0,
  • "failing_threshold": 0,
  • "silent": false,
  • "group": {
    },
  • "alerter": {
    },
  • "spec": {
    }
}

Update a check

Update a check by providing a full valid definition. Note that the handler type (spec.kind) cannot be updated in-place.

path Parameters
uuid
required
string <uuid>

Unique identifier

Request Body schema: application/json

The definition of a check

One of
name
required
string

Human-friendly name

enabled
boolean
Default: true

Whether the check should run or not

sites
Array of strings
Default: ["@controller"]

List of site identifier where the check should run. If omitted, defaults to @controller.

interval
required
string

Period of time between two run of the check

site_threshold
integer
Default: 1

Number of site outages required to confirm an outage

passing_threshold
required
integer

Number of consecutive fails required to consider a site failed

failing_threshold
required
integer

Number of consecutive passes required to consider a site recovered

silent
boolean
Default: false

Should an outage for this check trigger an alert

group
string <uuid>
Default: null

Group to which the check is assigned

alerter
string <uuid>
Default: null

Unique identifier for the alerter linked to the check

required
object

Responses

Request samples

Content type
application/json
Example
Ping
Ping
TCP
UDP
HTTP
DNS
TLS expiration
Domain expiration
App Store
Play Store
Python
{
  • "name": "string",
  • "enabled": true,
  • "sites": [
    ],
  • "interval": "string",
  • "site_threshold": 1,
  • "passing_threshold": 0,
  • "failing_threshold": 0,
  • "silent": false,
  • "group": null,
  • "alerter": null,
  • "spec": {
    }
}

Update check attributes

Update some of the attributes of a check through a partial definition. Note that the handler type (spec.kind) cannot be updated in-place and that you have to specify the full handler definition (spec) if you wish to update it.

path Parameters
uuid
required
string <uuid>

Unique identifier

Request Body schema: application/json

The partial definition of a check

name
string

Human-friendly name

enabled
boolean
Default: true

Whether the check should run or not

sites
Array of strings
Default: ["@controller"]

List of site identifier where the check should run. If omitted, defaults to @controller.

interval
string

Period of time between two run of the check

site_threshold
integer
Default: 1

Number of site outages required to confirm an outage

passing_threshold
integer

Number of consecutive fails required to consider a site failed

failing_threshold
integer

Number of consecutive passes required to consider a site recovered

silent
boolean
Default: false

Should an outage for this check trigger an alert

group
string <uuid>
Default: null

Group to which the check is assigned

alerter
string <uuid>
Default: null

Unique identifier for the alerter linked to the check

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "enabled": true,
  • "sites": [
    ],
  • "interval": "string",
  • "site_threshold": 1,
  • "passing_threshold": 0,
  • "failing_threshold": 0,
  • "silent": false,
  • "group": null,
  • "alerter": null
}

Disable or delete a check

Defcon does not allow to completely delete a check, only to disable it (prevent it from running).

path Parameters
uuid
required
string <uuid>

Unique identifier

query Parameters
delete
boolean
Default: false
Enum: false true

Delete the check instead of disabling it

Responses

Get a check outages

path Parameters
uuid
string <uuid>

Unique identifier

query Parameters
from
string <date>

Display outages from this date

to
string <date>

Display outages until this date

limit
int

Number of items per page of results

page
int

Page number to return

Responses

Response samples

Content type
application/json
{
  • "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
  • "started_on": "2019-08-24T14:15:22Z",
  • "ended_on": "2019-08-24T14:15:22Z",
  • "comment": "string",
  • "check": {
    }
}

Get a check outage events

path Parameters
uuid
string <uuid>

Unique identifier

query Parameters
from
string <date-time>

Display events from this date

to
string <date-time>

Display events until this date

limit
int

Number of items per page of results

page
int

Page number to return

Responses

Response samples

Content type
application/json
{
  • "site": "string",
  • "status": 0,
  • "message": "string",
  • "created_at": "2019-08-24T14:15:22Z"
}

Groups

List Groups

List all defined groups

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a new group

Request Body schema: application/json

The definition of a group

name
required
string <uuid>

Unique identifier

Responses

Request samples

Content type
application/json
{
  • "name": "9ffa9185-7453-4fb2-aa6a-3105a6ae83a8"
}

Update a group

Update a group by providing a full valid definition.

path Parameters
uuid
required
string <uuid>

Unique identifier

Request Body schema: application/json

The definition of a group

name
required
string <uuid>

Unique identifier

Responses

Request samples

Content type
application/json
{
  • "name": "9ffa9185-7453-4fb2-aa6a-3105a6ae83a8"
}

Delete a group

Delete an existing group. All checks assigned to this group will be unassigned.

path Parameters
uuid
required
string <uuid>

Unique identifier

Responses

Alerters

List all alerters

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create an alerter

Request Body schema: application/json

The definition of an alerter

kind
required
string
Enum: "webhook" "slack" "pagerduty"

Type of alerter

webhook
required
string <url>

URL to the incoming webhook

username
string

Username to use in the HTTP Basic auth to the webhook

password
string

Password to use in the HTTP Basic auth to the webhook

Responses

Request samples

Content type
application/json
{
  • "kind": "webhook",
  • "webhook": "string",
  • "username": "string",
  • "password": "string"
}

Get an alerter

path Parameters
uuid
string <uuid>

Unique identifier

Responses

Response samples

Content type
application/json
{
  • "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
  • "kind": "webhook",
  • "webhook": "string",
  • "username": "string",
  • "password": "string"
}

Update an alerter

path Parameters
uuid
required
string <uuid>

Unique identifier

Request Body schema: application/json

The definition of an alerter

kind
required
string
Enum: "webhook" "slack" "pagerduty"

Type of alerter

webhook
required
string <url>

URL to the incoming webhook

username
string

Username to use in the HTTP Basic auth to the webhook

password
string

Password to use in the HTTP Basic auth to the webhook

Responses

Request samples

Content type
application/json
{
  • "kind": "webhook",
  • "webhook": "string",
  • "username": "string",
  • "password": "string"
}

Delete an alerter

Delete an existing alerter, will be unassigned to all checks this alerter is assigned to.

path Parameters
uuid
required
string <uuid>

Unique identifier

Responses

Update alerter attributes

path Parameters
uuid
required
string <uuid>

Unique identifier

Request Body schema: application/json

The definition of an alerter

kind
string
Enum: "webhook" "slack" "pagerduty"

Type of alerter

webhook
string <url>

URL to the incoming webhook

username
string

Username to use in the HTTP Basic auth to the webhook

password
string

Password to use in the HTTP Basic auth to the webhook

Responses

Request samples

Content type
application/json
{
  • "kind": "webhook",
  • "webhook": "string",
  • "username": "string",
  • "password": "string"
}

Outages

List current outages

query Parameters
check
string <uuid>

UUID for a check to list outages for

from
string <date>

Display resolved outages from this date

to
string <date>

Display resolved outages until this date

limit
int

Number of items per page of results

page
int

Page number to return

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Add a comment

path Parameters
uuid
required
string <uuid>

Unique identifier

Request Body schema: application/json

The comment to be added to the outage

comment
string

The comment to be added

Responses

Request samples

Content type
application/json
{
  • "comment": "string"
}

Site outages

Get a site outage events

path Parameters
uuid
string <uuid>

Unique identifier

query Parameters
limit
int

Number of items per page of results

page
int

Page number to return

Responses

Response samples

Content type
application/json
{
  • "site": "string",
  • "status": 0,
  • "message": "string",
  • "created_at": "2019-08-24T14:15:22Z"
}

List current site outages

query Parameters
from
string <date>

Display resolved outages from this date

to
string <date>

Display resolved outages until this date

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get a site outage

path Parameters
uuid
string <uuid>

Unique identifier

Responses

Response samples

Content type
application/json
{
  • "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
  • "site": "string",
  • "passing_strikes": 0,
  • "failing_strikes": 0,
  • "started_on": "2019-08-24T14:15:22Z",
  • "ended_on": "2019-08-24T14:15:22Z",
  • "check": {
    }
}

Statistics

Get the global status for the system

Responses

Response samples

Content type
application/json
{
  • "ok": true,
  • "checks": 0,
  • "outages": {
    }
}

Get outage history by day

query Parameters
from
string <date>

Display resolved outages from this date

to
string <date>

Display resolved outages until this date

Responses

Response samples

Content type
application/json
{
  • "property1": [
    ],
  • "property2": [
    ]
}