Statuspal API API Reference

Welcome to the Statuspal API reference.

Here you'll learn how to leverage the power of Statuspal API in order to query your status page's status, create and update incidents and custom metrics for your status page and more.

Example call:

curl https://statuspal.io/api/v1/hello \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json'

Authentication Required Endpoints:

Some endpoints require authentication in order to be used, you'll need to pass your API key in the Authorization header, you can find your API key in your User Account page.

Example authenticated call:

curl -X POST \
  https://statuspal.io/api/v1/status_pages/:subdomain/metrics/:metric_id/entries \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: <your-api-key>' \
  -d '{ "entry": { "time": 1561318904, "value": 130 } }'
API Endpoint
https://statuspal.io/api/v1
Contact: [email protected]
Request Content-Types: json
Response Content-Types: json
Schemes: https
Version: 1.0.0

Authentication

api_key

type
apiKey
name
Authorization
in
header

Test

Test endpoints

Says hello

GET /hello
200 OK

A hello message

type
object
Response Example (200 OK)
{
  "message": "hello"
}

Status

Status endpoints

Get the status of a status page

GET /status_pages/{statusPageSubdomain}/status
statusPageSubdomain: string
in path

The subdomain of your status page (subdomain.statuspal.io)

A status page's status

Response Example (200 OK)
{
  "status_page": {
    "name": "Monitoring service",
    "current_incident_type": "string"
  },
  "services": [
    {
      "name": "Monitoring service",
      "id": "integer",
      "parent_id": "integer",
      "current_incident_type": "string",
      "children": [
        {
          "name": "Monitoring service",
          "id": "integer",
          "parent_id": "integer",
          "current_incident_type": "string"
        }
      ]
    }
  ],
  "incidents": [
    {
      "title": "We are having issues with the DB connection",
      "l_title": [
        {
          "lang": "es",
          "text": "Arriba arriba!"
        }
      ],
      "starts_at": "2019-06-24 03:30:00",
      "ends_at": "2019-06-24 04:30:00",
      "type": "major",
      "service_ids": [
        1
      ],
      "incident_activities": [
        {
          "activity_type_id": "integer",
          "description": "We have detected an issue with our CDN",
          "l_description": [
            {
              "lang": "es",
              "text": "Arriba arriba!"
            }
          ],
          "email_notify": "boolean",
          "slack_notify": "boolean",
          "tweet": "boolean"
        }
      ]
    }
  ],
  "maintenances": [
    {
      "title": "We are having issues with the DB connection",
      "l_title": [
        {
          "lang": "es",
          "text": "Arriba arriba!"
        }
      ],
      "starts_at": "2019-06-24 03:30:00",
      "ends_at": "2019-06-24 04:30:00",
      "type": "major",
      "service_ids": [
        1
      ],
      "incident_activities": [
        {
          "activity_type_id": "integer",
          "description": "We have detected an issue with our CDN",
          "l_description": [
            {
              "lang": "es",
              "text": "Arriba arriba!"
            }
          ],
          "email_notify": "boolean",
          "slack_notify": "boolean",
          "tweet": "boolean"
        }
      ]
    }
  ]
}

Get the status of a service

GET /status_pages/{statusPageSubdomain}/services/{serviceId}/status
statusPageSubdomain: string
in path

The subdomain of your status page (subdomain.statuspal.io)

serviceId: integer
in path

The ID of a service

200 OK

A service's status

Response Example (200 OK)
{
  "service": {
    "name": "Monitoring service",
    "id": "integer",
    "parent_id": "integer",
    "current_incident_type": "string",
    "children": [
      {
        "name": "Monitoring service",
        "id": "integer",
        "parent_id": "integer",
        "current_incident_type": "string"
      }
    ]
  },
  "incidents": [
    {
      "title": "We are having issues with the DB connection",
      "inserted_at": "string (date-time)",
      "updated_at": "string (date-time)",
      "starts_at": "string (date-time)",
      "ends_at": "string (date-time)",
      "type": "string",
      "services": [
        {
          "name": "API"
        }
      ],
      "current_status": {
        "description": "We are investigating."
      }
    }
  ],
  "maintenances": [
    {
      "title": "We are having issues with the DB connection",
      "inserted_at": "string (date-time)",
      "updated_at": "string (date-time)",
      "starts_at": "string (date-time)",
      "ends_at": "string (date-time)",
      "type": "string",
      "services": [
        {
          "name": "API"
        }
      ],
      "current_status": {
        "description": "We are investigating."
      }
    }
  ]
}

Incidents

Incidents endpoints

Adds a new incident associated to one or more services

POST /status_pages/{statusPageSubdomain}/incidents

The incident

statusPageSubdomain: string
in path

The subdomain of your status page (subdomain.statuspal.io)

Request Example
{
  "incident": {
    "title": "We are having issues with the DB connection",
    "l_title": [
      {
        "lang": "es",
        "text": "Arriba arriba!"
      }
    ],
    "starts_at": "2019-06-24 03:30:00",
    "ends_at": "2019-06-24 04:30:00",
    "type": "major",
    "service_ids": [
      1
    ],
    "incident_activities": [
      {
        "activity_type_id": "integer",
        "description": "We have detected an issue with our CDN",
        "l_description": [
          {
            "lang": "es",
            "text": "Arriba arriba!"
          }
        ],
        "email_notify": "boolean",
        "slack_notify": "boolean",
        "tweet": "boolean"
      }
    ]
  }
}
200 OK

The incident was created

Response Example (200 OK)
{
  "incident": {
    "title": "We are having issues with the DB connection",
    "l_title": [
      {
        "lang": "es",
        "text": "Arriba arriba!"
      }
    ],
    "starts_at": "2019-06-24 03:30:00",
    "ends_at": "2019-06-24 04:30:00",
    "type": "major",
    "service_ids": [
      1
    ],
    "incident_activities": [
      {
        "activity_type_id": "integer",
        "description": "We have detected an issue with our CDN",
        "l_description": [
          {
            "lang": "es",
            "text": "Arriba arriba!"
          }
        ],
        "email_notify": "boolean",
        "slack_notify": "boolean",
        "tweet": "boolean"
      }
    ]
  }
}

Deletes incident permanently

DELETE /status_pages/{statusPageSubdomain}/incidents/{incidentId}
statusPageSubdomain: string
in path

The subdomain of your status page (subdomain.statuspal.io)

incidentId: integer
in path

The ID of an incident/maintenance

200 OK

Incident deleted successfully

Incident Updates

Incident Updates (called activities within the API) endpoints

Adds a new update to the given incident

POST /status_pages/{statusPageSubdomain}/incidents/{incidentId}/activities

The update

statusPageSubdomain: string
in path

The subdomain of your status page (subdomain.statuspal.io)

incidentId: integer
in path

The ID of an incident/maintenance

Request Example
{
  "incident_activity": {
    "activity_type_id": "integer",
    "description": "We have detected an issue with our CDN",
    "l_description": [
      {
        "lang": "es",
        "text": "Arriba arriba!"
      }
    ],
    "email_notify": "boolean",
    "slack_notify": "boolean",
    "tweet": "boolean"
  }
}

The update was created

Response Example (200 OK)
{
  "incident_activity": {
    "activity_type_id": "integer",
    "description": "We have detected an issue with our CDN",
    "l_description": [
      {
        "lang": "es",
        "text": "Arriba arriba!"
      }
    ],
    "email_notify": "boolean",
    "slack_notify": "boolean",
    "tweet": "boolean"
  }
}

Deletes incident update permanently

DELETE /status_pages/{statusPageSubdomain}/incidents/{incidentId}/activities/{activityId}
statusPageSubdomain: string
in path

The subdomain of your status page (subdomain.statuspal.io)

incidentId: integer
in path

The ID of an incident/maintenance

activityId: integer
in path

(no description)

200 OK

Activity deleted successfully

Metrics

Metrics endpoints

Adds a metric data point to a custom metric

POST /status_pages/{statusPageSubdomain}/metrics/{metricId}/entries

The metric entry

statusPageSubdomain: string
in path

The subdomain of your status page (subdomain.statuspal.io)

metricId: integer
in path

The ID of a custom metric

Request Example
{
  "entry": {
    "time": 1561318904,
    "value": 130
  }
}

The metric data point was created

Response Example (200 OK)
{
  "entry": {
    "time": 1561318904,
    "value": 130
  }
}

Schema Definitions

MetricEntry: object

time: integer

Unix timestamp

value: number (double)
Example
{
  "time": 1561318904,
  "value": 130
}

MetricEntryObj: object

entry: MetricEntry
Example
{
  "entry": {
    "time": 1561318904,
    "value": 130
  }
}

Incident: object

An incident, either major, minor or a scheduled maintenance

title: string

Either use this field, or l_title if you have configured supported languages

l_title: TranslationField

Localized title. Either use this field, or title if you have't configured supported languages.

TranslationField
starts_at: string (date-time)

The time at which the incident/maintenance started/will start (in the time zone configured on your status page settings).

ends_at: string (date-time)

The time at which the incident/maintenance ended/will end (in the time zone configured on your status page settings).

type: IncidentType
service_ids: integer[]

An array of service Ids, at least 1 must be included

integer
incident_activities: IncidentActivity

The incident's updates. On incident creation you must pass exactly one activity object in the array, if the incident is of type minor/major the activity type Issue is recommended, if a scheduled maintenance then use Scheduled.

IncidentActivity
Example
{
  "title": "We are having issues with the DB connection",
  "l_title": [
    {
      "lang": "es",
      "text": "Arriba arriba!"
    }
  ],
  "starts_at": "2019-06-24 03:30:00",
  "ends_at": "2019-06-24 04:30:00",
  "type": "major",
  "service_ids": [
    1
  ],
  "incident_activities": [
    {
      "activity_type_id": "integer",
      "description": "We have detected an issue with our CDN",
      "l_description": [
        {
          "lang": "es",
          "text": "Arriba arriba!"
        }
      ],
      "email_notify": "boolean",
      "slack_notify": "boolean",
      "tweet": "boolean"
    }
  ]
}

IncidentObj: object

incident: Incident
Example
{
  "incident": {
    "title": "We are having issues with the DB connection",
    "l_title": [
      {
        "lang": "es",
        "text": "Arriba arriba!"
      }
    ],
    "starts_at": "2019-06-24 03:30:00",
    "ends_at": "2019-06-24 04:30:00",
    "type": "major",
    "service_ids": [
      1
    ],
    "incident_activities": [
      {
        "activity_type_id": "integer",
        "description": "We have detected an issue with our CDN",
        "l_description": [
          {
            "lang": "es",
            "text": "Arriba arriba!"
          }
        ],
        "email_notify": "boolean",
        "slack_notify": "boolean",
        "tweet": "boolean"
      }
    ]
  }
}

TranslationField: object

lang: string

Language code

text: string

The translated content

Example
{
  "lang": "es",
  "text": "Arriba arriba!"
}

StatusIncident: object

An incident, either major, minor or a scheduled maintenance

title: string
inserted_at: string (date-time)
updated_at: string (date-time)
starts_at: string (date-time)
ends_at: string (date-time)
type: StatusIncidentType
services: object[]
object
name: string
current_status: object
description: string
Example
{
  "title": "We are having issues with the DB connection",
  "inserted_at": "string (date-time)",
  "updated_at": "string (date-time)",
  "starts_at": "string (date-time)",
  "ends_at": "string (date-time)",
  "type": "string",
  "services": [
    {
      "name": "API"
    }
  ],
  "current_status": {
    "description": "We are investigating."
  }
}

ServiceStatus: object

Example
{
  "service": {
    "name": "Monitoring service",
    "id": "integer",
    "parent_id": "integer",
    "current_incident_type": "string",
    "children": [
      {
        "name": "Monitoring service",
        "id": "integer",
        "parent_id": "integer",
        "current_incident_type": "string"
      }
    ]
  },
  "incidents": [
    {
      "title": "We are having issues with the DB connection",
      "inserted_at": "string (date-time)",
      "updated_at": "string (date-time)",
      "starts_at": "string (date-time)",
      "ends_at": "string (date-time)",
      "type": "string",
      "services": [
        {
          "name": "API"
        }
      ],
      "current_status": {
        "description": "We are investigating."
      }
    }
  ],
  "maintenances": [
    {
      "title": "We are having issues with the DB connection",
      "inserted_at": "string (date-time)",
      "updated_at": "string (date-time)",
      "starts_at": "string (date-time)",
      "ends_at": "string (date-time)",
      "type": "string",
      "services": [
        {
          "name": "API"
        }
      ],
      "current_status": {
        "description": "We are investigating."
      }
    }
  ]
}

Service: object

Represents the status of a service

name: string
id: integer
parent_id: integer
current_incident_type: StatusIncidentType
children: ChildService

Nested ServiceStatus children

ChildService
Example
{
  "name": "Monitoring service",
  "id": "integer",
  "parent_id": "integer",
  "current_incident_type": "string",
  "children": [
    {
      "name": "Monitoring service",
      "id": "integer",
      "parent_id": "integer",
      "current_incident_type": "string"
    }
  ]
}

ChildService: object

Represents the status of a service

name: string
id: integer
parent_id: integer
current_incident_type: StatusIncidentType
Example
{
  "name": "Monitoring service",
  "id": "integer",
  "parent_id": "integer",
  "current_incident_type": "string"
}

StatusIncidentType: string

The type of the (current) incident:

  • major - A minor incident is currently taking place.
  • minor - A major incident is currently taking place.
  • scheduled - A scheduled maintenance is currently taking place.
  • null - No incident is taking place.
string major, minor, scheduled, null

IncidentType: string

The type of the (current) incident:

  • major - A minor incident is currently taking place.
  • minor - A major incident is currently taking place.
  • scheduled - A scheduled maintenance is currently taking place.
string major, minor, scheduled

IncidentActivity: object

Communicates an update of an incident, the special type resolved will close an incident.

activity_type_id: integer 1, 2, 3, 4, 5, 6, 7

The type of an incident update/activity:

  • 1 - Investigating.
  • 2 - Issue.
  • 3 - Monitoring.
  • 4 - Resolved (Will close the associated incident by settings its ends_at to the current time).
  • 5 - Scheduled.
  • 6 - Retroactive.
  • 7 - Update.
description: string
l_description: TranslationField

Localized description. Either use this field, or description if you have't configured supported languages.

TranslationField
email_notify: boolean

Should your email subscribers be notified about this update?

slack_notify: boolean

Should your Slack subscribers be notified about this update?

tweet: boolean

Tweet this update with your configured Twitter account?

Example
{
  "activity_type_id": "integer",
  "description": "We have detected an issue with our CDN",
  "l_description": [
    {
      "lang": "es",
      "text": "Arriba arriba!"
    }
  ],
  "email_notify": "boolean",
  "slack_notify": "boolean",
  "tweet": "boolean"
}

IncidentActivityObj: object

incident_activity: IncidentActivity
Example
{
  "incident_activity": {
    "activity_type_id": "integer",
    "description": "We have detected an issue with our CDN",
    "l_description": [
      {
        "lang": "es",
        "text": "Arriba arriba!"
      }
    ],
    "email_notify": "boolean",
    "slack_notify": "boolean",
    "tweet": "boolean"
  }
}

StatusPageStatus: object

Represents the status of a status page

status_page: object
name: string
current_incident_type: StatusIncidentType
services: Service
Service
incidents: Incident
Incident
maintenances: Incident
Incident
Example
{
  "status_page": {
    "name": "Monitoring service",
    "current_incident_type": "string"
  },
  "services": [
    {
      "name": "Monitoring service",
      "id": "integer",
      "parent_id": "integer",
      "current_incident_type": "string",
      "children": [
        {
          "name": "Monitoring service",
          "id": "integer",
          "parent_id": "integer",
          "current_incident_type": "string"
        }
      ]
    }
  ],
  "incidents": [
    {
      "title": "We are having issues with the DB connection",
      "l_title": [
        {
          "lang": "es",
          "text": "Arriba arriba!"
        }
      ],
      "starts_at": "2019-06-24 03:30:00",
      "ends_at": "2019-06-24 04:30:00",
      "type": "major",
      "service_ids": [
        1
      ],
      "incident_activities": [
        {
          "activity_type_id": "integer",
          "description": "We have detected an issue with our CDN",
          "l_description": [
            {
              "lang": "es",
              "text": "Arriba arriba!"
            }
          ],
          "email_notify": "boolean",
          "slack_notify": "boolean",
          "tweet": "boolean"
        }
      ]
    }
  ],
  "maintenances": [
    {
      "title": "We are having issues with the DB connection",
      "l_title": [
        {
          "lang": "es",
          "text": "Arriba arriba!"
        }
      ],
      "starts_at": "2019-06-24 03:30:00",
      "ends_at": "2019-06-24 04:30:00",
      "type": "major",
      "service_ids": [
        1
      ],
      "incident_activities": [
        {
          "activity_type_id": "integer",
          "description": "We have detected an issue with our CDN",
          "l_description": [
            {
              "lang": "es",
              "text": "Arriba arriba!"
            }
          ],
          "email_notify": "boolean",
          "slack_notify": "boolean",
          "tweet": "boolean"
        }
      ]
    }
  ]
}