Skip to main content

Incidents API

Query incident history, acknowledge incidents, add notes, and manage resolution programmatically. Track downtime and MTTR metrics.

List Incidents

GET /v1/incidents

# Query parameters:
?status=open           # Filter by status (open, acknowledged, resolved)
?severity=critical     # Filter by severity
?monitor_id=mon_abc    # Filter by monitor
?from=2026-02-01       # Start date
?to=2026-02-13         # End date
?page=1&limit=20       # Pagination

Response

{
  "data": [
    {
      "id": "inc_xyz789",
      "monitorId": "mon_abc123",
      "monitorName": "Production API",
      "status": "resolved",
      "severity": "critical",
      "startedAt": "2026-02-13T10:30:00Z",
      "acknowledgedAt": "2026-02-13T10:32:15Z",
      "resolvedAt": "2026-02-13T10:38:42Z",
      "downtime": 522,
      "failureCount": 3,
      "lastError": "Connection timeout after 10s"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 156
  }
}

Get Incident

GET /v1/incidents/:id

# Example:
GET /v1/incidents/inc_xyz789

Response

{
  "id": "inc_xyz789",
  "monitorId": "mon_abc123",
  "monitorName": "Production API",
  "status": "resolved",
  "severity": "critical",
  "startedAt": "2026-02-13T10:30:00Z",
  "acknowledgedAt": "2026-02-13T10:32:15Z",
  "acknowledgedBy": {
    "id": "usr_abc",
    "name": "John Doe"
  },
  "resolvedAt": "2026-02-13T10:38:42Z",
  "resolvedBy": {
    "id": "usr_abc",
    "name": "John Doe"
  },
  "downtime": 522,
  "downtimeFormatted": "8 minutes 42 seconds",
  "failureCount": 3,
  "lastError": "Connection timeout after 10s",
  "notes": [
    {
      "id": "note_123",
      "text": "Restarted service, investigating root cause",
      "createdBy": "John Doe",
      "createdAt": "2026-02-13T10:35:00Z"
    }
  ]
}

Create Incident

Manually create an incident (independent of monitor failures):

POST /v1/incidents
Content-Type: application/json

{
  "title": "Database Performance Issue",
  "description": "Slow queries detected on production database",
  "severity": "high",
  "monitorId": "mon_db_001"  # Optional
}

# Response: 201 Created
{
  "id": "inc_manual_001",
  "title": "Database Performance Issue",
  "status": "open",
  "severity": "high",
  "createdAt": "2026-02-13T12:00:00Z"
}

Acknowledge Incident

POST /v1/incidents/:id/acknowledge

# Response: 200 OK
{
  "id": "inc_xyz789",
  "status": "acknowledged",
  "acknowledgedAt": "2026-02-13T10:32:15Z",
  "acknowledgedBy": {
    "id": "usr_abc",
    "name": "John Doe"
  }
}

Resolve Incident

POST /v1/incidents/:id/resolve
Content-Type: application/json

{
  "resolutionNote": "Service restarted, issue resolved"
}

# Response: 200 OK
{
  "id": "inc_xyz789",
  "status": "resolved",
  "resolvedAt": "2026-02-13T10:38:42Z",
  "resolvedBy": {
    "id": "usr_abc",
    "name": "John Doe"
  },
  "downtime": 522,
  "resolutionNote": "Service restarted, issue resolved"
}

Reopen Incident

POST /v1/incidents/:id/reopen
Content-Type: application/json

{
  "reason": "Issue persists, reopening investigation"
}

# Response: 200 OK
{
  "id": "inc_xyz789",
  "status": "open",
  "reopenedAt": "2026-02-13T11:00:00Z"
}

Add Note

POST /v1/incidents/:id/notes
Content-Type: application/json

{
  "text": "Identified root cause: database connection pool exhausted"
}

# Response: 201 Created
{
  "id": "note_456",
  "incidentId": "inc_xyz789",
  "text": "Identified root cause: database connection pool exhausted",
  "createdBy": {
    "id": "usr_abc",
    "name": "John Doe"
  },
  "createdAt": "2026-02-13T10:35:00Z"
}

Get Timeline

Retrieve full incident timeline (immutable event log):

GET /v1/incidents/:id/timeline

# Response:
{
  "events": [
    {
      "type": "created",
      "timestamp": "2026-02-13T10:30:00Z",
      "actor": "System",
      "details": "Incident created after 3 consecutive failures"
    },
    {
      "type": "acknowledged",
      "timestamp": "2026-02-13T10:32:15Z",
      "actor": "John Doe",
      "details": "Incident acknowledged"
    },
    {
      "type": "note_added",
      "timestamp": "2026-02-13T10:35:00Z",
      "actor": "John Doe",
      "details": "Identified root cause: database connection pool exhausted"
    },
    {
      "type": "resolved",
      "timestamp": "2026-02-13T10:38:42Z",
      "actor": "John Doe",
      "details": "Service restarted, issue resolved"
    }
  ]
}

Get Statistics

Query incident metrics and analytics:

GET /v1/incidents/stats

# Query parameters:
?from=2026-02-01
?to=2026-02-13
?group_by=day  # day, week, month

# Response:
{
  "totalIncidents": 156,
  "openIncidents": 3,
  "mttr": 342,  # Mean Time To Recovery (seconds)
  "avgDowntime": 450,
  "bySeverity": {
    "critical": 12,
    "high": 45,
    "medium": 78,
    "low": 21
  },
  "byDay": [
    {
      "date": "2026-02-13",
      "incidents": 8,
      "avgDowntime": 420
    }
  ]
}

Incident Severity Levels

SeverityDescriptionResponse Time
criticalProduction outage, all users affectedImmediate (2-3 min)
highDegraded performance, partial outageWithin 15 min
mediumNon-critical issue, minor impactWithin 1 hour
lowMinor issue, no user impactBest effort

Incident Status Flow

open → acknowledged → resolved
  ↓              ↓
  └──── reopen ──┘

# Allowed transitions:
- open → acknowledged
- open → resolved (can skip ack)
- acknowledged → resolved
- resolved → reopened → acknowledged → resolved

Error Responses

409 Conflict

{
  "error": "Conflict",
  "message": "Incident already acknowledged",
  "status": 409
}

Code Examples

Python

from blacktide import Client

client = Client(api_token="YOUR_TOKEN")

# Get open incidents
incidents = client.incidents.list(status="open")

# Acknowledge incident
client.incidents.acknowledge(incident.id)

# Add note
client.incidents.add_note(incident.id, {
    "text": "Investigating database performance"
})

# Resolve
client.incidents.resolve(incident.id, {
    "resolutionNote": "Fixed by restarting service"
})

JavaScript/TypeScript

import { BlackTide } from '@blacktide/sdk';

const client = new BlackTide('YOUR_TOKEN');

// Get critical incidents
const incidents = await client.incidents.list({
  severity: 'critical',
  status: 'open'
});

// Acknowledge and add note
await client.incidents.acknowledge(incident.id);
await client.incidents.addNote(incident.id, {
  text: 'Team notified, investigating'
});

// Get MTTR stats
const stats = await client.incidents.getStats({
  from: '2026-02-01',
  to: '2026-02-13'
});
console.log(`MTTR: ${stats.mttr}s`);

Next Steps