TABLE OF CONTENTS
- Overview
- What API commands are used by Freshstatus?
- Rate Limit
- Policies
- Deprecation Policy
- Breaking Change Policy
- Authentication
- Where can I find my API key?
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:
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?
Login to your account
Go to Settings > Account
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.
List all Services
GET: services/ |
Response:
{ |
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:
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.
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:
Incident Status
Incident Status refers to the current status the Incident has been updated with.
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:
Incidents
Incidents are logs that contain information about every downtime like descriptions, start and end times, sources, updates, etc.
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:
{ |
Delete an incident
| DELETE: incidents/<incident_id>/ |
Response:
Incident Updates
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:
Scheduled Maintenance
These are logs that contain information about scheduled maintenances.
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:
{ |
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:
Scheduled Maintenance Updates
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: