{ "openapi": "3.1.0", "info": { "title": "Statusentry API", "version": "1.0.0", "summary": "Create and update incidents and scheduled maintenance on a Statusentry status page.", "description": "REST API for the Statusentry hosted status page: open incidents, post incident updates (entries) with component status, and schedule maintenance. Subscribers are notified by email, Slack and webhook unless `sendNotification` is false.\n\n**Authentication.** Create an API key pair (access key + secret key) under API keys in the Statusentry admin panel. For each request, sign a short-lived JWT with the secret key (HS256, `iss` = access key, `aud` = `www.statusentry.com`, `iat`, `exp`) and send `Authorization: StatusEntry :`. The key pair identifies the status page, so paths have no page ID. See https://statusentry.com/auth.md.\n\nAPI access is included on paid plans from Start Up ($9.99/month). Components, subscribers and metrics are managed in the dashboard, not through the API.", "termsOfService": "https://statusentry.com/terms", "contact": { "name": "Statusentry support", "email": "support@statusentry.com", "url": "https://statusentry.com/contact" } }, "externalDocs": { "description": "Statusentry API documentation", "url": "https://docs.statusentry.com/incident-api" }, "servers": [ { "url": "https://api.statusentry.com/v1" } ], "security": [ { "statusentryKeyPair": [] } ], "tags": [ { "name": "Incidents", "description": "Incidents shown on the status page.", "externalDocs": { "url": "https://docs.statusentry.com/incident-api" } }, { "name": "Incident entries", "description": "Updates posted on an incident.", "externalDocs": { "url": "https://docs.statusentry.com/incident-entry" } }, { "name": "Maintenances", "description": "Scheduled maintenance windows.", "externalDocs": { "url": "https://docs.statusentry.com/maintenance-api" } } ], "paths": { "/incidents": { "get": { "tags": [ "Incidents" ], "operationId": "listIncidents", "summary": "List incidents", "responses": { "200": { "description": "Incidents of the status page.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IncidentList" } } } } } }, "post": { "tags": [ "Incidents" ], "operationId": "createIncident", "summary": "Create an incident", "description": "Creates the incident together with its first update (`entry`).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IncidentCreate" } } } }, "responses": { "200": { "description": "The created incident.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Incident" } } } } } } }, "/incidents/{incidentId}": { "parameters": [ { "name": "incidentId", "in": "path", "required": true, "description": "Incident ID.", "schema": { "type": "string" } } ], "get": { "tags": [ "Incidents" ], "operationId": "getIncident", "summary": "Get an incident", "responses": { "200": { "description": "The incident.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Incident" } } } } } }, "delete": { "tags": [ "Incidents" ], "operationId": "deleteIncident", "summary": "Delete an incident", "responses": { "200": { "description": "Deleted." } } } }, "/incidents/{incidentId}/entries": { "parameters": [ { "name": "incidentId", "in": "path", "required": true, "description": "Incident ID.", "schema": { "type": "string" } } ], "get": { "tags": [ "Incident entries" ], "operationId": "listIncidentEntries", "summary": "List the updates of an incident", "responses": { "200": { "description": "Entries of the incident.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IncidentEntryList" } } } } } }, "post": { "tags": [ "Incident entries" ], "operationId": "createIncidentEntry", "summary": "Post an incident update", "description": "Adds an update with its own status. An entry with `incidentStatus: resolved` resolves the incident.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IncidentEntryInput" } } } }, "responses": { "200": { "description": "The created entry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IncidentEntry" } } } } } } }, "/incidents/{incidentId}/entries/{entryId}": { "parameters": [ { "name": "incidentId", "in": "path", "required": true, "description": "Incident ID.", "schema": { "type": "string" } }, { "name": "entryId", "in": "path", "required": true, "description": "Incident entry (update) ID.", "schema": { "type": "string" } } ], "get": { "tags": [ "Incident entries" ], "operationId": "getIncidentEntry", "summary": "Get an incident update", "responses": { "200": { "description": "The entry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IncidentEntry" } } } } } }, "put": { "tags": [ "Incident entries" ], "operationId": "updateIncidentEntry", "summary": "Update an incident update", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IncidentEntryInput" } } } }, "responses": { "200": { "description": "Updated.", "content": { "application/json": { "schema": { "type": "object" } } } } } }, "delete": { "tags": [ "Incident entries" ], "operationId": "deleteIncidentEntry", "summary": "Delete an incident update", "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/maintenances": { "get": { "tags": [ "Maintenances" ], "operationId": "listMaintenances", "summary": "List scheduled maintenances", "responses": { "200": { "description": "Maintenances of the status page.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MaintenanceList" } } } } } }, "post": { "tags": [ "Maintenances" ], "operationId": "createMaintenance", "summary": "Schedule a maintenance", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MaintenanceInput" } } } }, "responses": { "200": { "description": "The created maintenance.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Maintenance" } } } } } } }, "/maintenances/{maintenanceId}": { "parameters": [ { "name": "maintenanceId", "in": "path", "required": true, "description": "Maintenance ID.", "schema": { "type": "string" } } ], "get": { "tags": [ "Maintenances" ], "operationId": "getMaintenance", "summary": "Get a maintenance", "responses": { "200": { "description": "The maintenance.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Maintenance" } } } } } }, "put": { "tags": [ "Maintenances" ], "operationId": "updateMaintenance", "summary": "Update a maintenance", "description": "Replaces all fields of the maintenance.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MaintenanceInput" } } } }, "responses": { "200": { "description": "The updated maintenance.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Maintenance" } } } } } }, "delete": { "tags": [ "Maintenances" ], "operationId": "deleteMaintenance", "summary": "Delete a maintenance", "responses": { "200": { "description": "The deleted maintenance.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Maintenance" } } } } } } } }, "components": { "securitySchemes": { "statusentryKeyPair": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "`StatusEntry :`: the JWT is signed with the secret key (HS256) with `iss` = access key and `aud` = `www.statusentry.com`. See https://docs.statusentry.com/how-to-use-statusentry-api-key-pairs-to-authenticate-your-request" } }, "schemas": { "IncidentStatus": { "type": "string", "enum": [ "investigating", "identified", "monitoring", "resolved" ] }, "IncidentImpact": { "type": "string", "enum": [ "none", "minor", "major", "critical" ], "default": "none" }, "ComponentStatus": { "type": "string", "enum": [ "operational", "degraded_performance", "partial_outage", "major_outage", "under_maintenance" ] }, "AffectedComponent": { "type": "object", "properties": { "componentId": { "type": "string", "description": "Component (service) ID." }, "componentStatus": { "$ref": "#/components/schemas/ComponentStatus" } } }, "IncidentEntryInput": { "type": "object", "properties": { "message": { "type": "string", "description": "Update message shown on the status page." }, "date": { "type": "integer", "description": "Time of the update, epoch milliseconds." }, "incidentStatus": { "$ref": "#/components/schemas/IncidentStatus" }, "affectedComponents": { "type": "array", "items": { "$ref": "#/components/schemas/AffectedComponent" } }, "sendNotification": { "type": "boolean", "default": true, "description": "Notify subscribers about this update." } } }, "IncidentCreate": { "type": "object", "properties": { "name": { "type": "string", "description": "Incident title." }, "incidentStatus": { "$ref": "#/components/schemas/IncidentStatus" }, "incidentImpact": { "$ref": "#/components/schemas/IncidentImpact" }, "entry": { "$ref": "#/components/schemas/IncidentEntryInput", "description": "The first update of the incident." } } }, "Incident": { "type": "object", "properties": { "customerId": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "incidentStatus": { "$ref": "#/components/schemas/IncidentStatus" }, "incidentImpact": { "$ref": "#/components/schemas/IncidentImpact" }, "creationTime": { "type": [ "string", "integer" ], "description": "Epoch time in milliseconds (returned as a string in the documented examples)." }, "resolutionTime": { "type": [ "string", "integer" ], "description": "Set on resolved incidents. Epoch time in milliseconds (returned as a string in the documented examples)." } } }, "IncidentList": { "type": "object", "properties": { "customerId": { "type": "string" }, "incidents": { "type": "array", "items": { "$ref": "#/components/schemas/Incident" } } } }, "IncidentEntry": { "type": "object", "properties": { "customerId": { "type": "string" }, "id": { "type": "string" }, "incidentId": { "type": "string" }, "message": { "type": "string" }, "date": { "type": [ "string", "integer" ], "description": "Epoch time in milliseconds (returned as a string in the documented examples)." }, "incidentStatus": { "$ref": "#/components/schemas/IncidentStatus" }, "affectedComponents": { "type": "array", "items": { "$ref": "#/components/schemas/AffectedComponent" } }, "sendNotification": { "type": "boolean" } } }, "IncidentEntryList": { "type": "object", "properties": { "customerId": { "type": "string" }, "incidentId": { "type": "string" }, "entries": { "type": "array", "items": { "$ref": "#/components/schemas/IncidentEntry" } } } }, "MaintenanceInput": { "type": "object", "properties": { "name": { "type": "string", "description": "Maintenance title." }, "message": { "type": "string", "description": "Maintenance message." }, "plannedStartTime": { "type": "integer", "description": "Planned start, epoch milliseconds." }, "plannedEndTime": { "type": "integer", "description": "Planned end, epoch milliseconds." }, "affectedComponents": { "type": "array", "items": { "type": "string" }, "description": "IDs of the affected components." }, "sendNotification": { "type": "boolean", "description": "Notify subscribers." }, "internal": { "type": "boolean", "description": "Internal-only maintenance (not shown publicly)." } } }, "Maintenance": { "type": "object", "properties": { "customerId": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "message": { "type": "string" }, "plannedStartTime": { "type": "string", "description": "Planned start (ISO 8601 in the documented examples)." }, "plannedEndTime": { "type": "string", "description": "Planned end (ISO 8601 in the documented examples)." }, "affectedComponents": { "type": "array", "items": { "type": "object", "properties": { "componentId": { "type": "string" } } } }, "sendNotification": { "type": "boolean" }, "internal": { "type": "boolean" } } }, "MaintenanceList": { "type": "object", "properties": { "customerId": { "type": "string" }, "maintenances": { "type": "array", "items": { "$ref": "#/components/schemas/Maintenance" } } } } } } }