Notices

New notices should be created for each incident, maintenance or general notice you want listed on your status page, with additional comments added or state changes made using PUT requests.

Note: Creating new notices, and updating existing notices will trigger their publication not only to the Status Page but also to any configured integrations such as X (Twitter), Email, SMS, MS Teams, Slack and Google Chat.

Endpoints

https://api.sorryapp.com/v1/pages/:page_id/notices/

https://api.sorryapp.com/v1/pages/:page_id/notices/:notice_id

Objects

These are the attributes which represent the object, most of which can be posted too and received in response to the available methods.

Properties

Name
id
Description
The unique identifier for the notices.
Name
type
Description
Either 'planned' or 'unplanned', planned notices include expected start times and durations, often used for maintenance.
Name
subject
Description
The subject for a notice i.e. API Performance Issues
Name
synopsis
Description
A short description of the notice, taken from the first comment/update.
Name
state
Description
The current state of the notice. Available states depend on the notice type. For planned: 'scheduled', 'underway', 'complete' and for unplanned: 'investigating', 'identified', 'recovering', 'resolved' and 'false_alarm'
Name
timeline_state
Description
This gives you an idea of whether a notice is 'future', 'present', 'past_recent' or 'past_distant'. Past notices are those which are closed or resolved, _recent and _distant depend on whether it was closed in the past 7 days, or previously. (Read-only)
Name
begins_at
Description
The date/time a planned notice is expected to go underway.
Name
ends_at
Description
The date/time a planned notice is expected to be complete.
Name
began_at
Description
The date/time the notice was opened (if unplanned), or went underway (if planned).
Name
ended_at
Description
The date/time the notice was closed (if unplanned), or was complete (if planned).
Name
should_automate_schedule
Description
A boolean to determine if planned notices should automatically switch to 'underway' and 'complete' at the scheduled times.
Name
created_at
Description
The date/time the record was created.
Name
updated_at
Description
The date/time the record was last updated.
Name
link
Description
A permanent link to the notice on the public status page.
Name
include
Description
components, updates

GET/v1/pages/:page_id/notices

List notices

This endpoint displays a list of all subscribers in a single status page.

Request

GET

/v1/pages/12ab34cd/notices

curl -X GET https://api.sorryapp.com/v1/pages/12ab34cd/notices \
-H "Authorization: Bearer {token}"

Response

{
"response": [
    {
        "id": 432500,
        "type": "unplanned",
        "state": "investigating",
        "timeline_state": "present",
        "subject": "Investigating issues with Customer Portal",
        "synopsis": "We know some customers are experiencing an unexpected issue with the Customer Portal. We are actively investigating the cause. We will provide updates as soon as we know more. Thank you for your patience.\n",
        "link": "https://status.acme.com/notices/shkx7ggxfur0uewo-investigating-issues-with-customer-portal",
        "began_at": "2025-01-27T13:30:27.650Z",
        "ended_at": null,
        "created_at": "2025-01-27T13:30:27.667Z",
        "updated_at": "2025-01-27T13:30:39.874Z",
        "tag_list": []
    },
    {
        "id": 432499,
        "type": "planned",
        "state": "complete",
        "timeline_state": "past_recent",
        "subject": "DNS Maintenance",
        "synopsis": "We will be performing maintenance on [month] [day] starting at [time] for [minutes/hours]. During this time, the [service] will be unavailable or degraded. We will provide updates in this notice as the maintenance progresses. \n",
        "link": "https://status.acme.com/notices/pmtjhjemrjolot2e-dns-maintenance",
        "began_at": "2025-01-27T13:34:54.398Z",
        "ended_at": "2025-01-30T15:28:00.180Z",
        "created_at": "2025-01-27T13:28:49.104Z",
        "updated_at": "2025-01-30T15:28:00.199Z",
        "tag_list": [],
        "begins_at": "2025-01-29T13:28:00.000Z",
        "ends_at": "2025-01-30T15:28:00.000Z",
        "should_automate_schedule": true
    }
],
"count": 2
}

Including components

To include a list of affected components in a notice, append ?include=components onto the end of the endpoint. This will return an array list of components.

Request

GET

/v1/pages/12ab34cd/notices?include=components

curl -X GET https://api.sorryapp.com/v1/pages/12ab34cd/notices?include=components \
-H "Authorization: Bearer {token}"

POST/v1/pages/:page_id/notices

Create a notice

This endpoint allows you to create a new notice. The example includes passing through a list of components.

Optional attributes

Name
initial_comment
Description
Pass this to create a single update to introduce the notice.
Name
should_publish
Description
Boolean, Send these changes out through Email, Slack Twitter etc.
Name
component_ids
Description
An array of numeric IDs for the components which are affected by this incident. The component will then be 'degraded' the whole time the notice is ongoing. i.e. [1, 2, 3]
Name
begins_at_date
Description
planned only The date that the planned notice should start. In the format 'YYYY-MM-DD'. i.e. '2019-01-29'
Name
begins_at_time
Description
planned only The time that the planned notice should start. In the 24 hour format 'HH:MM:SS'. i.e. '16:30:00'
Name
duration_in_minutes
Description
planned only The number of minutes that the maintenance is expected to last.

Request

POST

/v1/pages/12ab34cd/notices

curl -X POST https://api.sorryapp.com/v1/pages/12ab34cd/notices \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {token}' \
-d "{"type":"unplanned",
  "subject":"API Performance Issues",
  "initial_comment":"Some people are experiencing problems with our service right now. We\'re so sorry about that. Please standby for further updates, and we\'ll be in touch as soon as we know more.",
  "should_publish":"1",
  "component_ids":[85878,85879]
 }"

Response

{
"response": {
    "id": 433244,
    "type": "unplanned",
    "state": "investigating",
    "timeline_state": "present",
    "subject": "API Performance Issues",
    "synopsis": "Some people are experiencing problems with our service right now. We're so sorry about that. Please standby for further updates, and we'll be in touch as soon as we know more.\n",
    "link": "https://status.acme.com/notices/nrcuzirp2fpmyokw-api-performance-issues",
    "began_at": "2025-02-03T14:04:17.145Z",
    "ended_at": null,
    "created_at": "2025-02-03T14:04:17.163Z",
    "updated_at": "2025-02-03T14:04:17.229Z",
    "tag_list": []
}
}

GET/v1/pages/:page_id/notices/:notice_id

Retrieve a notice

This endpoint allows you to retrieve a single notice.

Request

GET

/v1/pages/12ab34cd/notices/433244

   curl -X GET https://api.sorryapp.com/v1/pages/12ab34cd/notices/433244 \
-H "Authorization: Bearer {token}"

Response

{
"response": {
    "id": 433244,
    "type": "unplanned",
    "state": "investigating",
    "timeline_state": "present",
    "subject": "API Performance Issues",
    "synopsis": "Some people are experiencing problems with our service right now. We're so sorry about that. Please standby for further updates, and we'll be in touch as soon as we know more.\n",
    "link": "https://status.acme.com/notices/nrcuzirp2fpmyokw-api-performance-issues",
    "began_at": "2025-02-03T14:04:17.145Z",
    "ended_at": null,
    "created_at": "2025-02-03T14:04:17.163Z",
    "updated_at": "2025-02-03T14:04:17.229Z",
    "tag_list": []
}
}

PATCH/v1/pages/:page_id/notices/:notice_id

Update a notice

This endpoint allows you to update a notice's details.

Optional attributes

Name
additional_comment
Description
Pass this to create a single update to introduce the notice.
Name
state
Description
Allows you to change the state of the notice.
Name
should_publish
Description
Boolean, Send these changes out through Email, Slack Twitter etc.
Name
component_ids
Description
An array of numeric IDs for the components which are affected by this incident. The component will then be 'degraded' the whole time the notice is ongoing. i.e. [1, 2, 3]
Name
begins_at_date
Description
planned only The date that the planned notice should start. In the format 'YYYY-MM-DD'. i.e. '2019-01-29'
Name
begins_at_time
Description
planned only The time that the planned notice should start. In the 24 hour format 'HH:MM:SS'. i.e. '16:30:00'
Name
duration_in_minutes
Description
planned only The number of minutes that the maintenance is expected to last.

Request

PATCH

/v1/pages/12ab34cd/notices/433244

curl -X PATCH https://api.sorryapp.com/v1/pages/12ab34cd/notices/433244 \
-d subject="API v1 Performance Issues" \
-H "Authorization: Bearer {token}"

Response

{
"response": {
    "id": 433244,
    "type": "unplanned",
    "state": "investigating",
    "timeline_state": "present",
    "subject": "API v1 Performance Issues",
    "synopsis": "Some people are experiencing problems with our service right now. We're so sorry about that. Please standby for further updates, and we'll be in touch as soon as we know more.\n",
    "link": "https://status.acme.com/notices/r9cjlguanrtr5duc-api-v1-performance-issues",
    "began_at": "2025-02-03T14:04:17.145Z",
    "ended_at": null,
    "created_at": "2025-02-03T14:04:17.163Z",
    "updated_at": "2025-02-03T14:18:34.146Z",
    "tag_list": []
}
}

DELETE/v1/pages/:page_id/notices/:notice_id

Delete a notice

This endpoint allows you to delete a notice.

Request

DELETE

/v1/pages/12ab34cd/notices/433244

curl -X DELETE https://api.sorryapp.com/v1/pages/12ab34cd/notices/433244 \
-H "Authorization: Bearer {token}"