Statuspal API Reference

Welcome to the Statuspal API reference.

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

If you need some assistance please email us at [email protected].

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 } }'

← Go back to Statuspal

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

Get the list of incidents of a status page

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

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

200 OK

The list of incidents

type
object
Response Example (200 OK)
{
  "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"
        }
      ]
    }
  ]
}

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
  }
}

Subscriptions

Adds a new subscription email, SMS or discord subscription.

POST /status_pages/{statusPageSubdomain}/subscriptions

The subscription

statusPageSubdomain: string
in path

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

Request Example
{
  "subscription": {
    "type": "email",
    "filter": "services",
    "service_ids": [
      1
    ],
    "incident_id": 123,
    "email": "[email protected]",
    "confirm": true,
    "country_dial_code": 49,
    "phone_number": 12345678900,
    "webhook_url": "https://discordapp.com/api/webhooks/channelId/token"
  }
}

The subscription was created

Response Example (200 OK)
{
  "subscription": {
    "type": "email",
    "filter": "services",
    "service_ids": [
      1
    ],
    "incident_id": 123,
    "email": "[email protected]",
    "confirm": true,
    "country_dial_code": 49,
    "phone_number": 12345678900,
    "webhook_url": "https://discordapp.com/api/webhooks/channelId/token"
  }
}

Schema Definitions

Subscription: object

type: string

The type of Subscription (email, slack, sms, discord).

filter: string

Filter the notifications to subscribe to (all, services, incident).

service_ids: integer[]

An array of service IDs to subscribe to, required if filter is services.

integer
incident_id: integer

An incident ID to subscribe to, required if filter is incident.

email: string

The email to send the notifications to, required if type is email.

confirm: boolean

Set to false to skip sending confirmation email for email subscriptions.

country_dial_code: string

The country code of the phone number to send the notifications to, required if type is sms.

phone_number: string

The phone number to send the notifications to, required if type is sms.

webhook_url: string

The Discord webhook URL, required if type is discord.

Example
{
  "type": "email",
  "filter": "services",
  "service_ids": [
    1
  ],
  "incident_id": 123,
  "email": "[email protected]",
  "confirm": true,
  "country_dial_code": 49,
  "phone_number": 12345678900,
  "webhook_url": "https://discordapp.com/api/webhooks/channelId/token"
}

SubscriptionObj: object

subscription: Subscription
Example
{
  "subscription": {
    "type": "email",
    "filter": "services",
    "service_ids": [
      1
    ],
    "incident_id": 123,
    "email": "[email protected]",
    "confirm": true,
    "country_dial_code": 49,
    "phone_number": 12345678900,
    "webhook_url": "https://discordapp.com/api/webhooks/channelId/token"
  }
}

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 (UTC).

ends_at: string (date-time)

The time at which the incident/maintenance ended/will end (UTC).

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: Maintenance's first update shall have this type.
  • 6 - Retroactive.
  • 7 - Update.
  • 8 - Escalate: Will switch the incident type from minor to major.
  • 9 - De-escalate: Will switch the incident type from major to minor.
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"
        }
      ]
    }
  ]
}