Incident Tracking

Incident Tracking provides the core functionality for creating, retrieving, and managing incidents across your organization. It enables teams to maintain operational visibility, respond quickly to disruptions, and log resolution activity within a structured incident lifecycle.

Through this system, you can:
  • Verify system status — Use a dedicated endpoint to check whether incidents are currently active or resolved.
  • Retrieve incident history — Fetch incidents by team or ID to audit past events or understand ongoing issues.
  • Create new incidents — Manually trigger incidents for internal reporting or unmonitored events.
  • Update incident details — Modify descriptions, status, and resolution notes to reflect progress and final outcomes.
  • Track incident actions — Review automated or manual actions associated with each incident to understand how it was handled.

This comprehensive structure supports centralized incident tracking, whether events are triggered automatically through rulesets or manually by your team.
ENDPOINTS
Expand all
  • Health check
    GET/health-check
  • Incident management
Check Service Health Status
Check the real-time operational status of the incident management service. This endpoint provides a lightweight health check to verify that the system is responsive and functioning as expected.

It can be used in automated monitoring tools, uptime dashboards, or CI/CD pipelines to ensure that incident-related functionality (such as rule execution and webhook processing) is available.

Use cases:
  • System monitoring — Include this endpoint in health checks to validate the availability of the incident engine.
  • Pre-deployment checks — Ensure the service is live before creating or submitting incidents from automation tools.
  • Status API integrations — Use as a base-level readiness indicator for incident-related integrations.
JavaScript
Response codes
const axios = require('axios');

const url = "https://incident-query.api.pinghome.io/v1/health-check";

axios.get(url)
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});
ResponseThis section is used to view the possible HTTP response codes returned by the API. These codes indicate the status of a request, such as 201 (Created), 401 (Unauthorized), 409 (Conflict), or 422 (Unprocessable Entity).
Retrieve Incident Data
Retrieve a list of incidents associated with a specific team by providing the team_id in the path. The response includes incidents created manually or triggered through automated rulesets, allowing teams to track their current and historical incident activity.

Each incident record contains essential metadata such as id, status, urgency, created_at, and description, providing full visibility into the lifecycle and context of reported issues.

Use cases:
  • Team-level incident tracking — View all incidents assigned to or created by a specific team for monitoring and reporting.
  • Post-incident reviews — Access resolved and ongoing incidents for audit or retrospective analysis.
  • Dashboard integration — Populate custom dashboards or analytics tools with incident data filtered by team.

Need to modify an incident after retrieval? Use the Update Incident endpoint to change its name, urgency, assignees, or metadata.

Authorization: Bearer YOUR_TOKEN


Expected Behavior:


  • On success, the system will return a list of incidents associated with the specified team.
  • If the request is unauthorized, the system will return an error message.
  • If the incident is not found, a 404 error will be returned.
Path Parameters
  • id string
    The ID of the team for which incidents are being retrieved. Example: 'c03b02ec-244f-4d2c-8f68-3910071ed5c8'
JavaScript
Response codes
const axios = require('axios');

const url = 'https://incident-query.api.pinghome.io/v1/team/c03b02ec-244f-4d2c-8f68-3910071ed5c8/incidents';

axios.get(url, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});
ResponseThis section is used to view the possible HTTP response codes returned by the API. These codes indicate the status of a request, such as 201 (Created), 401 (Unauthorized), 409 (Conflict), or 422 (Unprocessable Entity).
Retrieve Incident Actions
Retrieve a list of actions associated with a specific incident by providing the incident_id in the path. These actions reflect both manual and automated responses triggered during the incident’s lifecycle — such as notifications, escalations, or status page updates.

Each action entry typically includes the type of action, the target (e.g., service or component), and timestamps indicating when the action was executed. This gives teams clear visibility into how incidents were handled in real time.

Use cases:
  • Response tracking — Understand which actions were performed during an incident and when.
  • Postmortem analysis — Review the sequence of actions to evaluate response effectiveness and timelines.
  • Audit readiness — Provide a transparent log of incident-related automation and interventions.

To view the incident this data belongs to, use the Get Incidents endpoint and to update its details, use the Update Incident endpoint.

Authorization: Bearer YOUR_TOKEN


Expected Behavior:


  • On success, the system will return the actions data associated with the specified incident.
  • If the request is unauthorized, the system will return an error message.
  • If the incident is not found, a 404 error will be returned.
Path Parameters
  • id string
    The ID of the incident for which actions are being retrieved. Example: 'c03b02ec-244f-4d2c-8f68-3910071ed5c8'
JavaScript
Response codes
const axios = require('axios');

const url = 'https://incident-query.api.pinghome.io/v1/incident/c03b02ec-244f-4d2c-8f68-3910071ed5c8/actions';

axios.get(url, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});
ResponseThis section is used to view the possible HTTP response codes returned by the API. These codes indicate the status of a request, such as 201 (Created), 401 (Unauthorized), 409 (Conflict), or 422 (Unprocessable Entity).
Create New Incident
Create a new incident under a specific team by providing the team_id in the path and submitting incident details in the request body. Required fields include the name of the incident, a brief description, and its urgency level (e.g., low, medium, high).

This endpoint is used for manually creating incidents that are not triggered by automated rulesets — such as those reported by users, detected through manual testing, or raised in response to unmonitored issues.

Use cases:
  • Manual incident reporting — Log issues discovered by team members or reported externally that require structured follow-up.
  • Internal escalation — Create incidents as part of internal workflows when external events do not automatically trigger them.
  • Incident simulation or testing — Manually trigger test scenarios to verify response automation, notifications, and rule behavior.

To track actions taken on this incident, use the Retrieve Incident Actions endpoint. Need to make changes later? Use the Update Incident endpoint.

Authorization: Bearer YOUR_TOKEN


Expected Behavior:


  • On success, the system will create a new incident and return the incident ID.
  • If the request is invalid, the system will return an error message with details of the invalid fields.
Path Parameters
  • id string
    The ID of the team for which the incident is being created. Example: '445a5c1f-c0eb-403a-96d7-3976e5dc74ed'
Request Body Parameters
  • name string
    The name of the incident.
  • description string
  • urgency string
  • assignees (optional) array of objects
  • actions (optional) array of objects
JavaScript
Response codes
const axios = require('axios');

const url = 'https://incident-cmd.api.pinghome.io/v1/team/445a5c1f-c0eb-403a-96d7-3976e5dc74ed/incident';
const data = {
  name: "Incident name",
  description: "Incident description",
  urgency: "medium",
  assignees: [
    {
      type: "team",
      id: "445a5c1f-c0eb-403a-96d7-3976e5dc74ed"
    }
  ],
  actions: [
    {
      type: "trigger-alerts",
      settings: [
        {
          status_page_id: "445a5c1f-c0eb-403a-96d7-3976e5dc74ed",
          component_id: "445a5c1f-c0eb-403a-96d7-3976e5dc74ed"
        }
      ]
    }
  ]
};

axios.post(url, data, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});
ResponseThis section is used to view the possible HTTP response codes returned by the API. These codes indicate the status of a request, such as 201 (Created), 401 (Unauthorized), 409 (Conflict), or 422 (Unprocessable Entity).
Update Incident
Update an existing incident by providing its incident_id in the URL path and submitting the new details in the request body. This endpoint is ideal for maintaining accurate, up-to-date information throughout the incident lifecycle.

Unlike creating an incident, updating allows you to reflect real-time developments, and adjust urgency or ownership as needed.

Typical Use Cases:
  • Escalation Handling — Elevate the urgency from medium to high if user impact increases or SLA deadlines approach.
  • Progress Notes — Append resolution steps, root cause analysis, or investigation findings directly in the description field.
  • Responsibility Reassignment — Reassign the incident to different team members using the assignees array.
  • Incident Enrichment — Add affected service components, status page references, or other contextual metadata that become available after the incident has been initially created.

To retrieve current incident data before updating, use the Get Incidents endpoint.

Authorization: Bearer YOUR_TOKEN


Expected Behavior:


  • On success, the system will update the incident and return a success message.
  • If the request is invalid, the system will return an error message with details of the invalid fields.
Path Parameters
  • id string
    The unique ID of the incident to be updated. Example: '445a5c1f-c0eb-403a-96d7-3976e5dc74ed'
Request Body Parameters
  • name string
    The updated name of the incident.
  • description string
  • urgency string
  • assignees (optional) array of objects
  • actions (optional) array of objects
JavaScript
Response codes
const axios = require('axios');

const url = 'https://incident-cmd.api.pinghome.io/v1/incident/445a5c1f-c0eb-403a-96d7-3976e5dc74ed';
const data = {
  name: "Incident name",
  description: "Incident description",
  urgency: "medium",
  assignees: [
    {
      type: "team",
      id: "445a5c1f-c0eb-403a-96d7-3976e5dc74ed"
    }
  ],
  actions: [
    {
      id: "",
      type: "trigger-alerts",
      settings: [
        {
          id: "",
          status_page_id: "445a5c1f-c0eb-403a-96d7-3976e5dc74ed",
          component_id: "445a5c1f-c0eb-403a-96d7-3976e5dc74ed"
        }
      ]
    }
  ]
};

axios.put(url, data, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});
ResponseThis section is used to view the possible HTTP response codes returned by the API. These codes indicate the status of a request, such as 201 (Created), 401 (Unauthorized), 409 (Conflict), or 422 (Unprocessable Entity).