TABLE OF CONTENTS

Overview

Freshstatus allows companies to build and publish private or public status pages for internal stakeholders or end-users. With Freshstatus companies can proactively communicate incidents or service disruptions via Email, Twitter, and more. Our goal is simple: make it effortless for companies to communicate downtimes to their customers and reduce support costs.

Freshstatus’s APIs belong to the Representational State Transfer (REST) category. They allow you to perform 'RESTful' operations such as reading, modifying, adding, or deleting data from your status page.

What API commands are used by Freshstatus?

Freshstatus APIs are plain JSON over HTTP and use the following HTTP verbs:

COMMAND

PURPOSE

POST

Create an object

GET

Fetch one or more objects

PATCH

Update an object

DELETE

Remove an object

Note: All API requests should hit the secured endpoint, that is, only HTTPS


Rate Limit

The number of API calls per hour is 1000

Policies

Freshstatus APIs are classified into either production or beta APIs. A production API is one that has been made generally available for public use and is stable. A beta API is one that is still in development or is for internal or limited use and whose stability cannot be guaranteed. Beta APIs may be removed or modified at any time without advance notice. The following policies apply to production APIs only.

Deprecation Policy

The current version of production-level APIs is v1. When a new version of APIs is made generally available (not beta), the older version will be deprecated and will cease to function after six months. Once an API is removed, any request to it will result in a 404 error.


Breaking Change Policy

Changes that do not break an API, such as adding a new attribute can be made at any time. Changes that break a production level API such as removing attributes or making major changes to the API’s behavior will only be done with advance notice of 60 days. However, there may be rare occasions where we are forced to make breaking changes without advance notice due to legal, performance, or security reasons.

Authentication

Authentication is done over Basic Authentication using your organization API key as Username and Freshstatus subdomain as Password to authenticate the request.

curl -v -u <apikey>:<freshstatus_subdomain> -H "Content-Type: application/json" -X GET 'https://public-api.freshstatus.io/api/v1/'


For example, if your API key is abcdefghij1234567890 and Freshstatus URL is xyz.freshstatus.io, the curl command to use is:

curl -v -u abcdefghij1234567890:xyz -H "Content-Type: application/json" -X GET 'https://public-api.freshstatus.io/api/v1/services/'


Note:

If you are sure that your credentials are correct, but are still unable to access the APIs, make sure that the "APIkey:X" is Base64-encoded before passing it as an "Authorization" header.


Where can I find my API key?

  1. Login to your account

  2. Go to Settings > Account

  3. Copy API Key




Service Components

These are the building blocks of your status page. Add the services whose status you want to display to the end-users.



Attribute

Data Type

Type

Description

id

Integer

Mandatory

Service id

name

String

Mandatory

Service name

description

String

Optional

Service description

order

Integer

Mandatory

Service order

status

String

ReadOnly

Operational, Performance Degraded, Partial Outage, Major Outage, Under Maintenance

display_options

Object

Optional

{

  "service_start_date""2021-04-01", //Datetime (YYYY-MM-DD)

  "uptime_history_enabled""true" //Boolean

}

group

Object

ReadOnly

(Default null)


Parent group data if applicable otherwise null if no group

{

  "id": 2,

  "name""Group1",

  "order"1,

  "parent"1,

}



List all Services

GET: services/


Response:


{
   "count"1,
   "next"null,
   "previous"null,
   "results": [
       {
           "id"1,
           "name""Service name",
           "description""Service description",
           "order"0,
           "display_options": {
          "service_start_date""2021-04-01",
               "uptime_history_enabled""false"
           },
           "group": {
               "id"1,
               "name""Group 1",
               "order"1,
               "parent"null
           }
       }
   ]
}


Get a specific Service


GET: services/<service_id>/


Response:

{
   "id"1,
   "name""Service name",
   "description""Service description",
   "order"0,
   "status""Operational",
   "display_options": {
    "service_start_date""2021-04-01",
       "uptime_history_enabled""false"
   },
   "group": {
       "id"1,
       "name""Group 1",
       "order"1,
       "parent"null
   }
}

Create a Service

POST: services/



Request:

{
   "name""Service name",
   "description""Service description",
   "order"0,
   "group"1,
   "display_options": {
    "service_start_date""2021-04-01",
       "uptime_history_enabled""true"
   }
}


Response:

{

   "id"1,

   "name""Service name",

   "description""Service description",

   "order"0,

   "status""Operational",

   "display_options": {

       "service_start_date""2021-04-01",

       "uptime_history_enabled""true"

   },

   "group": {

       "id"1,

       "name""G1",

       "order"1,

       "parent"null

   }

}



Update a Service

PATCH: services/<service_id>/



Request:

{
   "name""Service name",
   "description""Service description",
   "order"0,
   "group"1,
   "display_options": {
    "service_start_date""2021-04-01",
       "uptime_history_enabled""false"
   }
}



Response:

{

   "id"1,

   "name""New service name",

   "description""New service description",

   "order"0,

   "status""Operational",

   "display_options": {

       "service_start_date""2021-04-01",

       "uptime_history_enabled""true"

   },

   "group": {

       "id"1,

       "name""G1",

       "order"1,

       "parent"null

   }

}

 

Delete a Service

DELETE: services/<service_id>/



Response:

HTTP Status: 204 No Content


Filter a Service

DELETE: services/<service_id>/




Service Groups

Create groups or sub-groups of services to be able to display consolidated service status on the status page. 


Attribute

Data Type

Type

Description

id

Integer

Mandatory

Group id

name

String

Mandatory

Group name

description

String

Optional

Group description

order

Integer

Optional

Group order

parent

Integer

Optional (Default null)

Parent group id


If the parent is null, it's a root-level Group. Sub-groups have a parent value.

status

String

ReadOnly

Operational, Performance Degraded, Partial Outage, Major Outage, Under Maintenance

display_options

Object

Optional

{

  "expand_on_load""true", //Boolean

  "uptime_history_enabled""true" //Boolean

}


List all Service Groups

GET: groups/


Response:

{
   "count"1,
   "next"null,
   "previous"null,
   "results": [
       {
           "id"1,
           "name""Group 1",
           "description""",
           "order"1,
           "parent"null,
           "display_options": {
               "expand_on_load""true",
               "uptime_history_enabled""false"
           }
       }
   ]
}



Get a specific Service Group


GET: groups/<group_id>/



Response:

{
   "id"1,
   "name""Group 1",
   "description""",
   "order"1,
   "parent"null,
   "display_options": {
       "expand_on_load""true",
       "uptime_history_enabled""false"
   }
}



Create a Service Group


POST: groups/




Request:

{
   "name""Group name",
   "description""Group description",
   "order"0,
   "parent"null,
   "display_options": {
       "expand_on_load""true",
       "uptime_history_enabled""false"
   }
}


Response:

{

   "id"1,

   "name""Group name",

   "description""Group description",

   "order"0,

   "parent"null,

   "display_options": {

       "expand_on_load""true",

       "uptime_history_enabled""false"

   }

}


 

Update a Service Group

PATCH: groups/<group_id>/



Request:

{
   "name""Group name",
   "description""Group description",
   "order"0,
   "parent"null,
   "display_options": {
       "expand_on_load""true",
       "uptime_history_enabled""false"
   }
}


Response:

{

   "id"1,

   "name""Group name",

   "description""Group description",

   "order"0,

   "parent"null,

   "display_options": {

       "expand_on_load""true",

       "uptime_history_enabled""false"

   }

}


 

Delete a Service Group


DELETE: groups/<group_id>/


Response:


HTTP Status: 204 No Content



Incident Status

Incident Status refers to the current status the Incident has been updated with.


Attribute

Data Type

Type

Description

id

Integer

Mandatory

Incident update id

value

String

Mandatory

Incident update value


List all Incident status

GET: incident-status/



Response:

{
   "count"1,
   "next"null,
   "previous"null,
   "results": [
       {
           "id"1,
           "value""Investigating"
       }
   ]
}




Get a specific Incident status

GET: incident-status/<incident_status_id>/


Response:

{
   "id"1,
   "value""Investigating"
}



Create an Incident status

POST: incident-status/



Request:

{
   "value""Investigating"
}



Response:

{

   "id"1,

   "value""Investigating",

   "order"1

}


 

Update an Incident status


PATCH: incident-status/<incident_status_id>/


Request:

{

  "value""Monitoring",

  "order"2

}



 Response:

{

   "id"1,

   "value""Monitoring",

   "order"2

}


Delete an Incident status


DELETE: incident-status/<incident_status_id>/


Response:


HTTP Status: 204 No Content




Incidents

Incidents are logs that contain information about every downtime like descriptions, start and end times, sources, updates, etc.


Attribute

Data Type

Type

Description

id

Integer

Mandatory

Incident id

title

String

Mandatory

Incident title

description

String

Optional

Incident description

start_time

Datetime (UTC)

Mandatory

Start time of the incident in UTC Datetime format.

Format: YYYY-MM-DDThh:mm:ssZ

Example: 2021-01-30T05:40:00Z


This is the actual start time and may be different from scheduled_start_time when the incident is started manually.

end_time

Datetime (UTC)

Mandatory

End time of the incident in UTC Datetime format. 

Format: YYYY-MM-DDThh:mm:ssZ

Example: 2021-01-30T05:40:00Z


This is the actual start time and may be different from scheduled_start_time when the incident is started manually.

is_private

Boolean

Optional (Default False)

Mark the incident as Private

affected_components

Array

Optional

Example: 

[

  {"component":"1""new_status":"MO"},

  {"component":"2""new_status":"MO"}

]

OP: Operational

PD: Performance Degraded

PO: Partial Outage

MO: Major Outage

UM: Under Maintenance

source

Integer

Optional


notification_options

Object

Optional

{

  "send_tweet":"false",

  "send_email":"false"

}

incident_updates

Object

Optional

Returns associated Incident Updates array


List all Incidents

GET: incidents/



Response:

{

   "count"1,

   "next"null,

   "previous"null,

   "results": [

       {

           "id"1,

           "title""Incident title",

           "description""Incident description",

           "start_time""2021-01-30T05:40:00Z",

           "end_time""2021-01-31T05:40:00Z",

           "source"null,

           "is_private"false,

           "affected_components": [

       {"component""1""new_status""MO"},

       {"component""2""new_status""MO"}

           ],

           "notification_options": {

               "send_notification""false",

               "send_tweet""false"

           },

           "incident_updates": []

       }

   ]

}



Get a specific Incident

GET: incidents/<incident_id>/



Response:

{
   "id"1,
   "title""Incident title",
   "description""Incident description",
   "start_time""2021-01-30T05:40:00Z",
   "end_time""2021-01-30T05:40:00Z",
   "is_private"false,
   "affected_components": [
       {"component""1""new_status""MO"},
       {"component""2""new_status""MO"}
   ],
   "notification_options": {
       "send_email""true",
       "send_tweet""false"
   },
   "incident_updates": []
}



Create an Incident

POST: incidents/



Request:

{

   "title""Incident title",

   "description""Incident description",

   "start_time""2021-01-30T05:40:00Z",

   "end_time""2021-01-31T05:40:00Z",

   "is_private"false,

   "affected_components": [

       {"component""1""new_status""MO"},

       {"component""2""new_status""MO"}

   ],

   "source"null,

   "notification_options": {

       "send_notification""false",

       "send_tweet""false"

   }

}

 

Response:

{

   "id"1,

   "title""Incident title",

   "description""Incident description",

   "start_time""2021-01-30T05:40:00Z",

   "end_time""2021-01-31T05:40:00Z",

   "is_private"false,

   "affected_components": [

       {"component""1""new_status""MO"},

       {"component""2""new_status""MO"}

   ],

   "source"null,

   "notification_options": {

       "send_notification""false",

       "send_tweet""false"

   },

   "incident_updates": []

}



Update an Incident

PATCH: incidents/<incident_id>/


Request:

{

   "title""Incident title",

   "description""Incident description",

   "start_time""2021-01-30T05:40:00Z",

   "end_time""2021-01-31T05:40:00Z",

   "is_private"false,

   "affected_components": [

       {"component""1""new_status""MO"},

       {"component""2""new_status""MO"}

   ],

   "source"null,

   "notification_options": {

       "send_notification""false",

       "send_tweet""false"

   }

}

 

Response:

{

   "id"1,

   "title""Incident title",

   "description""Incident description",

   "start_time""2021-01-30T05:40:00Z",

   "end_time""2021-01-31T05:40:00Z",

   "is_private"false,

   "affected_components": [

       {"component""1""new_status""MO"},

       {"component""2""new_status""MO"}

   ],

   "source"null,

   "notification_options": {

       "send_notification""false",

       "send_tweet""false"

   },

   "incident_updates": []

}


 

Resolve an incident

POST: incidents/<incident_id>/resolve/


Post “message” as an incident update. This field is optional.


Request:

{
   "message""The incident has been resolved"
}


Delete an incident

DELETE: incidents/<incident_id>/




Response:


HTTP Status: 204 No Content



Incident Updates


Attribute

Data Type

Type

Description

id

Integer

Mandatory

Incident Update id

message

String

Optional

Incident Update message

time

Datetime (UTC)

Mandatory

Time of incident update in UTC Datetime format.

Format: YYYY-MM-DDThh:mm:ssZ

Example: 2021-01-30T05:40:00Z

is_private

Boolean

Optional (Default False)

Mark the incident update as Private

notification_options

Object

Optional

{

  "send_tweet":"false",

  "send_email":"false"

}

incident_id

Integer

Mandatory

Incident id

incident_status

String

Optional

Current Incident status


List Incident updates by Incident ID

GET: incident-updates/?incident=<incident_id>



Response:

{

   "count"1,

   "next"null,

   "previous"null,

   "results": [

       {

           "id"1,

    "message""Incident Update message",

    "time""2020-10-09T06:45:53.727004Z",

    "is_private"false,

    "incident"1,

    "incident_status""Investigating",

    "notification_options": {

               "send_notification""false",

               "send_tweet""false"

     }

       }

   ]

}


 

Get a specific Incident

GET: incident-updates/<incident-update_id>/



Response:

{

   "id"1,

   "message""Incident Update message",

   "time""2020-10-09T06:45:53.727004Z",

   "is_private"false,

   "incident"1,

   "incident_status""Investigating",

   "notification_options": {

       "send_notification""false",

       "send_tweet""false"

   }

}


 

Create an Incident update

POST: incident-updates/


Request:

{

    "message""Incident Update message",

    "time""2020-10-09T06:45:53.727004Z",

    "is_private"false,

    "incident"1,

    "incident_status""Investigating",

    "notification_options": {

       "send_notification""false",

       "send_tweet""false"

    }

}


 

Response:

{

   "id"1,

   "message""Incident Update message",

   "time""2020-10-09T06:45:53.727004Z",

   "is_private"false,

   "incident"1,

   "incident_status""Investigating",

   "notification_options": {

       "send_notification""false",

       "send_tweet""false"

   }

}


 

Update an Incident update

PATCH: incident-updates/<incident_update_id>/


Request:

{

    "message""Incident Update message",

    "time""2020-10-09T06:45:53.727004Z",

    "is_private"false,

    "notification_options": {

       "send_notification""false",

       "send_tweet""false"

    }

}


 

Response:

{

   "id"1,

   "message""Incident Update message",

   "time""2020-10-09T06:45:53.727004Z",

   "is_private"false,

   "incident"1,

   "incident_status""Investigating",

   "notification_options": {

       "send_notification""false",

       "send_tweet""false"

   }

}




Delete an Incident update

DELETE: incident-updates/<incident_update_id>/


Response:


HTTP Status: 204 No Content


 

Scheduled Maintenance

These are logs that contain information about scheduled maintenances.


Attribute

Data Type

Type

Description

id

Integer

Mandatory

Maintenance id

title

String

Mandatory

Maintenance title

description

String

Optional

Maintenance description

start_time

Datetime (UTC)

Mandatory

Start time of maintenance in UTC Datetime format. 

Format: YYYY-MM-DDThh:mm:ssZ

Example: 2021-01-30T05:40:00Z


This is the actual start time and may be different from scheduled_start_time when the maintenance is started manually.

end_time

Datetime (UTC)

Mandatory

End time of maintenance in UTC Datetime format. 

Format: YYYY-MM-DDThh:mm:ssZ

Example: 2021-01-30T05:40:00Z


This is the actual start time and may be different from scheduled_start_time when the maintenance is started manually.

is_private

Boolean

Optional (Default False)

Mark the maintenance as Private

affected_components

Array

Optional

Example: 

[

  {"component":"1"},

  {"component":"2"}

]

source

Integer

Optional


is_auto_start

Boolean

Optional

Auto start maintenance on start_time

is_auto_start

Boolean

Optional

Auto end maintenance on end_time

notification_options

Object

Optional

{

  "email_before_one_hour":"true",

  "email_before_day_hour":"true",

  "email_on_start":"true",

  "email_on_complete":"true",

  "send_tweet":"false",

  "send_email":"true"

}

maintenance_updates

Object

Optional

Returns associated Maintenance Updates array


List all Scheduled Maintenance

GET: maintenance/



Response:

{

   "count"1,

   "next"null,

   "previous"null,

   "results": [

       {

           "id"1,

           "title""Maintenance title",

           "description""Maintenance description",

           "start_time""2021-01-30T05:40:00Z",

           "end_time""2021-01-31T05:40:00Z",

           "is_auto_start"true,

           "is_auto_end"true,

           "source"null,

           "is_private"false,

           "affected_components": [

       {"component""1""new_status""UM"},

       {"component""2""new_status""UM"}

           ],

           "notification_options": {

               "send_notification""false",

               "send_tweet""false",

               "email_on_start""false",

               "email_on_complete""false",

               "email_before_day_hour""false",

               "email_before_one_hour""false"

           },

           "maintenance_updates": []

       }

   ]

}



Get a specific Scheduled Maintenance

GET: maintenance/<maintenance_id>/



Response:

{

   "id"1,

   "title""Maintenance title",

   "description""Maintenance description",

   "start_time""2021-01-30T05:40:00Z",

   "end_time""2021-01-31T05:40:00Z",

   "is_auto_start"true,

   "is_auto_end"true,

   "source"null,

   "is_private"false,

   "affected_components": [

       {"component""1""new_status""UM"},

       {"component""2""new_status""UM"}

   ],

   "notification_options": {

       "send_notification""false",

       "send_tweet""false",

       "email_on_start""false",

       "email_on_complete""false",

       "email_before_day_hour""false",

       "email_before_one_hour""false"

   },

   "maintenance_updates": []

}


 


Create a Scheduled Maintenance

POST: maintenance/




Request:

{

   "title""Maintenance title",

   "description""Maintenance description",

   "start_time""2021-01-30T05:40:00Z",

   "end_time""2021-01-31T05:40:00Z",

   "is_auto_start"true,

   "is_auto_end"true,

   "source"null,

   "is_private"false,

   "affected_components": [

       {"component""1""new_status""UM"},

       {"component""2""new_status""UM"}

   ],

   "notification_options": {

       "send_notification""true",

       "send_tweet""true",

       "email_on_start""true",

       "email_on_complete""true",

       "email_before_day_hour""true",

       "email_before_one_hour""true"

   }

}


Response:

{

   "id"1,

   "title""Maintenance title",

   "description""Maintenance description",

   "start_time""2021-01-30T05:40:00Z",

   "end_time""2021-01-31T05:40:00Z",

   "is_auto_start"true,

   "is_auto_end"true,

   "source"null,

   "is_private"false,

   "affected_components": [

       {"component""1""new_status""UM"},

       {"component""2""new_status""UM"}

   ],

   "notification_options": {

       "send_notification""false",

       "send_tweet""false",

       "email_on_start""false",

       "email_on_complete""false",

       "email_before_day_hour""false",

       "email_before_one_hour""false"

   },

   "maintenance_updates": []

}


 



Update a Scheduled Maintenance

PATCH: maintenance/<maintenance_id>/

Request:

{

   "title""Maintenance title",

   "description""Maintenance description",

   "start_time""2021-01-30T05:40:00Z",

   "end_time""2021-01-31T05:40:00Z",

   "is_auto_start"true,

   "is_auto_end"true,

   "source"null,

   "is_private"false,

   "affected_components": [

       {"component""1""new_status""UM"},

       {"component""2""new_status""UM"}

   ],

   "notification_options": {

       "send_notification""true",

       "send_tweet""true",

       "email_on_start""true",

       "email_on_complete""true",

       "email_before_day_hour""true",

       "email_before_one_hour""true"

   }

}



Response:

{

   "id"1,

   "title""Maintenance title",

   "description""Maintenance description",

   "start_time""2021-01-30T05:40:00Z",

   "end_time""2021-01-31T05:40:00Z",

   "is_auto_start"true,

   "is_auto_end"true,

   "source"null,

   "is_private"false,

   "affected_components": [

       {"component""1""new_status""UM"},

       {"component""2""new_status""UM"}

   ],

   "notification_options": {

       "send_notification""false",

       "send_tweet""false",

       "email_on_start""false",

       "email_on_complete""false",

       "email_before_day_hour""false",

       "email_before_one_hour""false"

   },

   "maintenance_updates": []

}


 

 

Start a Scheduled Maintenance

POST: maintenance/<maintenance_id>/start/


Post “message” as maintenance update. This field is optional.


 Request:

{
   "message""The incident has been started"
}

 

Response:

HTTP Status: 200 OK

 

Complete a Scheduled Maintenance


POST: maintenance/<maintenance_id>/complete/

Post “message” as maintenance update. This field is optional.

Request:

{
   "message""The incident has been completed"
}


 

Delete a Scheduled Maintenance

DELETE: maintenance/<maintenance_id>/


Response:

HTTP Status: 204 No Content


 

Scheduled Maintenance Updates


Attribute

Data Type

Type

Description

id

Integer

Mandatory

maintenance Update id

message

String

Optional

maintenance Update message

time

Datetime (UTC)

Mandatory

Time of maintenance update in UTC Datetime format.

Format: YYYY-MM-DDThh:mm:ssZ

Example: 2021-01-30T05:40:00Z

is_private

Boolean

Optional (Default False)

Mark the maintenance update as Private

notification_options

Object

Optional

{

  "send_tweet":"false",

  "send_email":"false"

}

maintenance_id

Integer

Mandatory

maintenance id

maintenance_status

String

Optional

Current maintenance status


List Maintenance updates by Maintenance id

GET: maintenance-updates/?maintenance=<maintenance_id>


Response:

{

   "count"1,

   "next"null,

   "previous"null,

   "results": [

       {

           "id"1,

    "message""Maintenance Update message",

    "time""2020-10-09T06:45:53.727004Z",

    "is_private"false,

    "maintenance"1,

    "maintenance_status""Investigating",

    "notification_options": {

               "send_notification""false",

               "send_tweet""false"

     }

       }

   ]

}



Get a specific Maintenance update


GET:maintenance-updates/<maintenance-update_id>/


Response:

{

   "id"1,

   "message""Maintenance Update message",

   "time""2020-10-09T06:45:53.727004Z",

   "is_private"false,

   "maintenance"1,

   "maintenance_status""Investigating",

   "notification_options": {

       "send_notification""false",

       "send_tweet""false"

   }

}



Create a Maintenance update


POST: maintenance-updates/


Request

{

    "message""Maintenance Update message",

    "time""2020-10-09T06:45:53.727004Z",

    "is_private"false,

    "maintenance"1,

    "maintenance_status""Investigating",

    "notification_options": {

       "send_notification""false",

       "send_tweet""false"

    }

}



Response:

{

   "id"1,

   "message""Maintenance Update message",

   "time""2020-10-09T06:45:53.727004Z",

   "is_private"false,

   "maintenance"1,

   "notification_options": {

       "send_notification""false",

       "send_tweet""false"

   }

}


 

Update a Maintenance update


PATCH: maintenance-updates/<maintenance_update_id>/


Request:

{

    "message""Maintenance Update message",

    "time""2020-10-09T06:45:53.727004Z",

    "is_private"false,

    "notification_options": {

       "send_notification""false",

       "send_tweet""false"

    }

}

Response:

{

   "id"1,

   "message""Maintenance Update message",

   "time""2020-10-09T06:45:53.727004Z",

   "is_private"false,

   "maintenance"1,

   "notification_options": {

       "send_notification""false",

       "send_tweet""false"

   }

}

Delete a maintenance update


DELETE: maintenance-updates/<maintenance_update_id>/


Response:

HTTP Status: 204 No Content