Incidents API

Incidents API allows organizations to programmatically handle incidents. After creating an API key, developers can directly trigger and respond to incidents from their programs and scripts through the API. It provides a channel for interaction between your organization's internal systems and TaskCall. It serves the same purpose for your internal systems as do built-in integrations with external monitoring tools.

This documentation contains the complete schema for the API. It lists the parameters needed for each call and provides examples alongside for further clarity.

Basic Pointers
https://incidents-api.taskcallapp.com
https://incidents-api.us.taskcallapp.com

Parameter Value
Authorization token { api key }
Content-type application/json

In TaskCall's REST APIs incidents are referred to as instances. Hence, the ID associated to an incident is referred to as an instance_id .

Two of these IDs are generated for each incident. One is respective to your organization and the other is a global ID. The ID displayed on the web and mobile apps is the organization specific ID. However, for the API clients are required to use the global ID. The global "instance_id" of the incident will be returned in the response of a trigger request. This should be saved on your side if you wish to act on the incident programmatically through the API as well because all requests for taking actions on an incident require the global "instance_id" of the incident.


curl -H "Authorization: token exampleapikey" -H "Content-Type: application/json" -X POST -d "{"instance_id":1}" https://incidents-api.taskcallapp.com/acknowledge/
List Components

Get list of components like escalation policies, services, users, etc, and their respective IDs. Component IDs will be needed to create and respond to incidents.

/list/{component-type}
GET
users, escalation-policies, services, business-services, workflows, incidents
JSON response
Create Incident

Trigger a new incident. The trigger will be treated the same as other incidents and may be subjected to conditional routing if any of the conditions apply.

/create
POST

  • title: (string) The title or subject of the incident. It explains what the incidents is for in brief.

In addition, at least one of the three optional fields - service_ref_id, policy_ref_id, users - should be included in the request for assignment. Otherwise, the request will be rejected.


  • service_ref_id: (string) The ID of the service the incident is being triggered on.
  • policy_ref_id: (list) The list of IDs of escalation policies the incident should be assigned to. Include this if you would like the incident to be assigned to specific escalation policies.
  • users: (list) The list of preferred username of users the incident should be assigned to. Include this if you would like the incident to be assigned to a specific group of user(s).
  • description: (string) Detailed description of what caused the incident. Terminal logs, code snippets and all other relevant data that will help with the incident investigation should be included here.
  • urgency_level: (integer) TaskCall splits the urgency of an incident into 5 categories. Each category is identified on the API as a number between 1 and 5 with the severity increasing with larger numbers. The urgency levels are mapped as follows: 1: Minor, 2: Low, 3: Medium, 4: High, 5: Critical .
  • notes: (string) Any notes or pointers that can be help the responders resolve the incident.
  • tags: (list) The list of tags that should be assiciated with the incident. Tags can help classify and group incidents better.
  • dedup_key: (string) If a dedup_key is included then TaskCall will check if any other incident with the same dedup_key is currently open or not. If there is one, then this alert will be suppressed and no new incident will be triggered. 
 {
 "title": "CS EU Trade Reconciliation Failed",
 "service_ref_id": "dySeOLtKTr-cIdTFZRHgKg",
 "users": ["mofab"],
 "policy_ref_id": ["KmRsye1vSAaqPZY-fxi22g"],
 "description": "Needs to be fixed before EOD",
 "notes": "Check other trade rec fails from before",
 "tags": ["ops", "reports"],
 "dedup_key": "trade-rec"
 }

  • instance_id: (integer) This is the global "instance_id". Please refer to the Basic Pointers section above to learn more about this ID.
  • timestamp: (string) The UTC timestamp this incident has been created on.
Incident Details

Get the details of an incident.

/details
POST

  • instance_id: (integer) Global instance_id of the incident.
JSON response 
 {
 "impacted_business_services": null,
 "conference_bridges": null,
 "instance_timestamp": "2021-05-05T17:20:14.343825",
 "last_alert_timestamp": "2021-05-05T17:20:14.343825",
 "subscribers": null,
 "resolved_on": "2021-05-05T17:23:46.015431",
 "status_update": null,
 "organization_instance_id": 320,
 "status": "RESOLVED",
 "events": [{
 "event_type": "TRIGGER",
 "event_timestamp": "2021-05-05T17:20:14.343825",
 "event_method": "INTEGRATIONS_API",
 "event_by": null,
 "event_date": "2021-05-05",
 "event_log": "{"next_alert_timestamp": "2021-05-05T17:35:14.343825"}",
 "instance_id": 463
 }],
 "notes": [],
 "task": {
 "integration_key": "2cd4c001-b125-41ef-ab2b-f2995ea4d166",
 "services": ["Ops System Monitor", "s879IRLUSwW9XjbBmW3PnQ"],
 "assignees": [],
 "task_ref_id": "gCX2Sg9HSDCxgYXOR0RCqA",
 "related_task_id": "gCX2Sg9HSDCxgYXOR0RCqA",
 "task_timezone": "UTC",
 "labels": null,
 "text_msg": "TEST ALERT: Testing Notification Channel TaskCall Integration Event Generated: Severity: Medium Metric: cpu.used.percent = 91.8600 % Segment: container.name = 'container1_0' and host.mac = '08:00:27:70:1a:03' Scope: host.hostName = Host-0 (08:00:27:70:1a:03) Time: 05/05/2021 05:20 PM UTC State: Triggered Notification URL: https://eu1.app.sysdig.com/#/events/notifications/l:2419200/1088/details ------ Triggered by Alert: Name: TEST ALERT: Testing Notification Channel TaskCall Integration Description: Alert description Team: Monitor Operations Scope: host.hostName = Host-0 (08:00:27:70:1a:03) Segment by: host.mac, container.name When: avg(cpu.used.percent) > 85 For at least: 10 m Alert URL: https://eu1.app.sysdig.com/#/alerts/3129 ",
 "with_completion_notice": false,
 "integration_name": "Sysdig Monitor Integration",
 "task_title": "TEST ALERT: Testing Notification Channel TaskCall Integration",
 "urgency_level": 3,
 "created_by": null,
 "task_id": "gCX2Sg9HSDCxgYXOR0RCqA",
 "repeat": null,
 "task_time": "17:20:00",
 "start_date": "2021-05-05"
 },
 "assignee_level": 1,
 "assignees": [],
 "state_timestamp": "2021-05-11T18:55:47.322406",
 "instance_id": 463,
 "next_alert_timestamp": "2021-05-05T17:30:53.314303"
 }
Incident Alerts

Get all the alerts that are associated with an incident.

/alerts
POST

  • instance_id: (integer) Global instance_id of the incident.
JSON response 
 [{
 "text_msg": "",
 "organization_instance_id": 316,
 "timestamp": "2021-04-14T18:31:36.106251",
 "integration_name": null,
 "urgency_level": 4,
 "instance_id": 422,
 "task_title": "Merger Test Pair",
 "task_ref_id": "PYBfBR-QRc-3_4Rt5ZGYMA",
 "status": "GROUPED",
 "services": null,
 "resolved_on": "2021-04-14T18:32:41.791455"
 },
 {
 "text_msg": "",
 "organization_instance_id": 316,
 "timestamp": "2021-04-14T17:42:21.434198",
 "integration_name": null,
 "urgency_level": 2,
 "instance_id": 422,
 "task_title": "Merger Error Debugging Incident",
 "task_ref_id": "Vmr03E8JSKqQHZ9nt3mGaQ",
 "status": "TRIGGERED",
 "services": null,
 "resolved_on": "2021-04-14T18:32:41.791455"
 }]
Acknowledge

Acknowledge an open incident.

/acknowledge
POST

  • instance_id: (integer) Global instance_id of the incident.

  • next_alert_timestamp: (string) The UTC timestamp alerts on for this incident will be re-triggered next.
Resolve

Resolve an incident.

/resolve
POST

  • instance_id: (integer) Global instance_id of the incident.
(string) Success
Escalate

Escalate an incident to the next on-call support level.

/escalate
POST

  • instance_id: (integer) Global instance_id of the incident.
(string) Success
Reassign

Reassign an incident to another escalation policy or user (or multiple).

/reassign
POST

  • instance_id: (integer) Global instance_id of the incident.
  • reassign_to: (list) Policy IDs of the escalation policies or users the incident should be reassigned to. The policy ID of the users can be obtained using the list components request. 
 {
 "instance_id": 8912,
 "reassign_to": ["KmRsye1vSAaqPZY-fxi22g", "ufgoOLtKTr-cIbvcDgJgKg"]
 }
(string) Success
Snooze

Snooze an incident for a given number of minutes.

/snooze
POST

  • instance_id: (integer) Global instance_id of the incident.
  • snooze_for: (integer) Number of minutes to snooze the incident for. 
 {
 "instance_id": 8912,
 "snooze_for": 30 
 }
(string) Success
Un-acknowledge

Un-acknowledge an incident that is currently acknowledged.

/unacknowledge
POST

  • instance_id: (integer) Global instance_id of the incident.
(string) Success
Amend Urgency

Amend the urgency of an incident.

/amend-urgency
POST

  • instance_id: (integer) Global instance_id of the incident.
  • urgency_level: (integer) The urgency level the incident should be set to. Refer to the urgency level map described above. 
 {
 "instance_id": 8912,
 "amend-urgency": 3 
 }
(string) Success
Add Responders

Add new responders to an incident and mobilize the response effort.

/add-responders
POST

  • instance_id: (integer) Global instance_id of the incident.
  • assignees: (list) Policy IDs of the escalation policies or users who should be added on as responders. The policy ID of the users can be obtained using the list components request. 
 {
 "instance_id": 8912,
 "assignees": ["KmRsye1vSAaqPZY-fxi22g", "ufgoOLtKTr-cIbvcDgJgKg"]
 }
(string) Success
Notate

Add notes to an active incident.

/notate
POST

  • instance_id: (integer) Global instance_id of the incident.
  • notes: (string) Note to add.
(string) Success
Merge

Merge an incident with another. The incident will be closed and the alert that triggered the incident will show under the incident that it is being merged with under the status "GROUPED".

/merge
POST

  • instance_id: (integer) Global instance_id of the incident that is being merged.
  • related_instance_id: (integer) Global instance_id of the incident that the primary incident is being merge with. This is the incident that will sustain. 
 {
 "instance_id": 8912,
 "related_instance_id": 7884 
 }
(string) Success
Un-merge

Un-merge an alert from an incident and create a new incident with that alert. After the alert is un-merged it will only be associated with the new incident.

/unmerge
POST

  • instance_id: (integer) Global instance_id of the incident that the alert belongs to.
  • task_ref_id: (string) ID of the alert (in TaskCall's APIs alerts are referred to as tasks). This can be obtained from the incident details request. 
 {
 "instance_id": 8912,
 "task_ref_id": "jNSYZE1vSAaqrvS-fPi5H1" 
 }

  • instance_id: (integer) Global "instance_id" of the new incident that was created from the un-merged alert.
  • timestamp: (string) UTC timestamp this incident has been created on.
Add Subscribers

Add subscribers to an incident. This allows the subscribed users to get notified about updates on the incident as they are published.

/add-subscribers
POST

  • instance_id: (integer) Global instance_id of the incident.
  • subscribers: (list) Preferred usernames of the users who should be added as subscribers. 
 {
 "instance_id": 8912,
 "subscribers": ["adsmi", "mofab"] 
 }
(string) Success
Remove Subscribers

Remove subscribers from an incident.

/remove-subscribers
POST

  • instance_id: (integer) Global instance_id of the incident.
  • subscribers: (list) Preferred usernames of the users who should be removed as subscribers. 
 {
 "instance_id": 8912,
 "subscribers": ["mofab"] 
 }
(string) Success
Update Status

Publish a status update for an incident.

/update-status
POST

  • instance_id: (integer) Global instance_id of the incident.
  • status_update: (string) New update. 
 {
 "instance_id": 8912,
 "status_update": "The root cause of the issue has been identified. The system will be back up in 15 minutes." 
 }
(string) Success
Add Business Impact

Mark a business service as having been impacted by a given incident.

/add-impact
POST

  • instance_id: (integer) Global instance_id of the incident.
  • business_service_ref_id: (string) ID of the business service that has been impacted. 
 {
 "instance_id": 8912,
 "business_service_ref_id": "6jbYk31vSAaqLMi-fPp89R" 
 }
(string) Success
Remove Business Impact

Remove an impacted business service from the list of business impacts associated with an incident.

/remove-impact
POST

  • instance_id: (integer) Global instance_id of the incident.
  • business_service_ref_id: (string) ID of the business service to remove from the list of business impacts. 
 {
 "instance_id": 8912,
 "business_service_ref_id": "6jbYk31vSAaqLMi-fPp89R" 
 }
(string) Success
Run Workflow

Run a workflow to mobilize your response effort.

/run-workflow
POST

  • instance_id: (integer) Global instance_id of the incident.
  • workflow_ref_id: (string) ID of the workflow that should be run. 
 {
 "instance_id": 8912,
 "workflow_ref_id": "Z9mn4KLvoDhqLMi-uhc7-g" 
 }
(string) Success
Edit Incident Title

Edit the title of an incident.

/edit-title
POST

  • instance_id: (integer) Global instance_id of the incident.
  • task_title: (string) New title of the incident. 
 {
 "instance_id": 8912,
 "task_title": "Server 10 is on fire!" 
 }
(string) Success
Update Tags

Update the tags associated to an incident. This function is essentially used to add and remove tags from the incident. The list of tags that the incident gets updated with becomes the tags assocaited to it. If an empty list is sent then all prior tags will be removed and the incident will not have any tags assocaited to it. If the incident had 3 tags initially and you want to remove one of the tags, then you can make a call to this function with the other 2 tags in a list.

/update-tags
POST

  • instance_id: (integer) Global instance_id of the incident.
  • tags: (list) List of tags. Each tag should be a string. 
 {
 "instance_id": 8912,
 "tags": ["database", "apac"] 
 }
(string) Success
On this page