Incidents

REST API Reference

Development Status: This documentation covers only the REST API endpoints that have been tested and are currently working. The platform is in active development and not all planned endpoints are implemented yet.

API Overview

Base URL: http://localhost:8080/api/v1 (development)
Content Type: application/json
Authentication: Most endpoints currently work without authentication (development mode)

Working Endpoints

The following endpoints have been tested and are functional:

Health Check

GET /health

Check server health status.

Request:

curl http://localhost:8080/health

Response:

{
  "status": "healthy",
  "timestamp": "2025-08-25T10:40:21Z"
}

Incidents

POST /api/v1/incidents

Create a new incident.

Request:

curl -X POST http://localhost:8080/api/v1/incidents \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Database connection timeout",
    "severity": "SEV-2",
    "description": "Users unable to login"
  }'

Response:

{
  "id": "INC-f1960322",
  "title": "Database connection timeout",
  "description": "Users unable to login",
  "severity": "SEV-2",
  "status": "open",
  "created_at": "2025-08-25T10:40:31.182711Z",
  "updated_at": "2025-08-25T10:40:31.182711Z"
}

Supported Severity Levels:

  • SEV-1 - Critical/Emergency
  • SEV-2 - High/Urgent
  • SEV-3 - Medium/Normal
  • SEV-4 - Low/Informational

GET /api/v1/incidents

List all incidents.

Request:

curl http://localhost:8080/api/v1/incidents

Response:

[
  {
    "id": "INC-f1960322",
    "title": "Database connection timeout",
    "description": "Users unable to login",
    "severity": "SEV-2",
    "status": "open",
    "created_at": "2025-08-25T10:40:31.182711Z",
    "updated_at": "2025-08-25T10:40:31.182711Z"
  }
]

GET /api/v1/incidents/{id}

Get specific incident by ID.

Request:

curl http://localhost:8080/api/v1/incidents/INC-f1960322

Response:

{
  "id": "INC-f1960322",
  "title": "Database connection timeout",
  "description": "Users unable to login",
  "severity": "SEV-2",
  "status": "open",
  "created_at": "2025-08-25T10:40:31.182711Z",
  "updated_at": "2025-08-25T10:40:31.182711Z"
}

Incident State Management

POST /api/v1/incidents/{id}/ack

Acknowledge an incident.

Request:

curl -X POST http://localhost:8080/api/v1/incidents/INC-f1960322/ack

Response:

{
  "status": "acknowledged"
}

POST /api/v1/incidents/{id}/mitigate

Mark incident as mitigated.

Request:

curl -X POST http://localhost:8080/api/v1/incidents/INC-f1960322/mitigate

Response:

{
  "status": "mitigated"
}

POST /api/v1/incidents/{id}/resolve

Resolve an incident.

Request:

curl -X POST http://localhost:8080/api/v1/incidents/INC-f1960322/resolve

Response:

{
  "status": "resolved"
}

POST /api/v1/incidents/{id}/close

Close a resolved incident.

Request:

curl -X POST http://localhost:8080/api/v1/incidents/INC-f1960322/close

Response:

{
  "status": "closed"
}

Timeline Service

The Timeline Service provides an event-sourced, append-only ledger for incident events using CloudEvents v1.0 format. All writes are idempotent, reads are policy-enforced with field-level redaction, and timelines can be queried with filters and pagination.

POST /api/v1/timeline/events

Append a CloudEvents v1.0 event to the timeline. Idempotent - duplicate events (same source + im.origin_id) return the existing event ID.

Request:

curl -X POST http://localhost:8080/api/v1/timeline/events \
  -H "Content-Type: application/cloudevents+json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "specversion": "1.0",
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "source": "im://api",
    "type": "im.incident.declare",
    "subject": "incident/INC-1234",
    "time": "2025-12-04T10:30:00Z",
    "data": {
      "title": "Database Connection Issues",
      "severity": "SEV-2",
      "service": "payments"
    },
    "im.actor": "oncall@example.com",
    "im.origin_id": "alert-123"
  }'

Response (201 Created):

{
  "event_id": "550e8400-e29b-41d4-a716-446655440000",
  "created": true,
  "incident_id": "INC-1234"
}

Response (200 OK - Duplicate):

{
  "event_id": "550e8400-e29b-41d4-a716-446655440000",
  "created": false,
  "incident_id": "INC-1234"
}

Required CloudEvents v1.0 Fields:

  • specversion - Must be “1.0”
  • id - Event UUID
  • source - Event source URI (e.g., im://api, im://pagerduty)
  • type - Event type (must start with im.)
  • time - RFC3339 timestamp

Incident Management Extensions:

  • im.actor - Who/what triggered the event
  • im.origin_id - Idempotency key from source system
  • im.correlation_key - Cross-event grouping identifier
  • im.fingerprint - Auto-aggregation grouping
  • im.data_class - Data sensitivity: ["pii"], ["phi"], ["legal_hold"]
  • im.visibility - Access control: public, internal, restricted, or confidential

GET /api/v1/timeline/events/{eventId}

Retrieve a specific timeline event by ID. Subject to policy enforcement and field-level redaction.

Request:

curl http://localhost:8080/api/v1/timeline/events/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer $TOKEN"

Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "incident_id": "INC-1234",
  "event_time": "2025-12-04T10:30:00Z",
  "event_type": "im.incident.declare",
  "actor": "oncall@example.com",
  "title": "Database Connection Issues",
  "content": "",
  "source": "im://api",
  "data": {
    "severity": "SEV-2",
    "service": "payments"
  },
  "created_at": "2025-12-04T10:30:01Z"
}

GET /api/v1/incidents/{id}/timeline

Query timeline events for an incident with filtering and pagination. Results are subject to policy enforcement.

Request:

# Simple query
curl http://localhost:8080/api/v1/incidents/INC-1234/timeline \
  -H "Authorization: Bearer $TOKEN"

# With filters
curl "http://localhost:8080/api/v1/incidents/INC-1234/timeline?type=im.incident.*&from=2025-12-04T00:00:00Z&limit=100" \
  -H "Authorization: Bearer $TOKEN"

Query Parameters:

  • type - Event type pattern (supports wildcards: im.incident.*)
  • from - Start of time range (RFC3339 timestamp)
  • to - End of time range (RFC3339 timestamp)
  • actor - Filter by actor
  • limit - Max results per page (1-1000, default 50)
  • cursor - Pagination cursor from previous response
  • order - Sort order: asc (oldest first) or desc (newest first, default)

Response:

{
  "events": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "incident_id": "INC-1234",
      "event_time": "2025-12-04T10:30:00Z",
      "event_type": "im.incident.declare",
      "actor": "oncall@example.com",
      "title": "Database Connection Issues",
      "content": "",
      "source": "im://api",
      "data": {
        "severity": "SEV-2"
      }
    }
  ],
  "next_cursor": "MjAyNS0xMi0wNFQxMDozMDowMFo6NTUwZTg0MDA="
}

Pagination:

Use the next_cursor value from the response in subsequent requests:

curl "http://localhost:8080/api/v1/incidents/INC-1234/timeline?cursor=MjAyNS0xMi0wNFQxMDozMDowMFo6NTUwZTg0MDA=" \
  -H "Authorization: Bearer $TOKEN"

POST /api/v1/timeline/query

Advanced timeline query supporting cross-incident searches by correlation key, fingerprint, or other criteria.

Request:

curl -X POST http://localhost:8080/api/v1/timeline/query \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "correlation_key": "database-pool-exhaustion",
    "from_time": "2025-12-04T00:00:00Z",
    "to_time": "2025-12-04T23:59:59Z",
    "limit": 100
  }'

Response:

Same format as GET /incidents/{id}/timeline

GET /api/v1/incidents/{id}/timeline/export

Export the complete timeline for an incident in JSON or Markdown format. Export reflects the caller’s access level (redacted view).

Request (JSON):

curl "http://localhost:8080/api/v1/incidents/INC-1234/timeline/export?format=json" \
  -H "Authorization: Bearer $TOKEN" \
  -o timeline.json

Request (Markdown):

curl "http://localhost:8080/api/v1/incidents/INC-1234/timeline/export?format=markdown" \
  -H "Authorization: Bearer $TOKEN" \
  -o timeline.md

JSON Export Response:

CloudEvents array in JSON format.

Markdown Export Example:

# Timeline: INC-1234

**Incident**: Database Connection Issues
**Generated**: 2025-12-04T10:45:00Z

---

## 2025-12-04T10:30:00Z - im.incident.declare

**Actor**: oncall@example.com
**Source**: im://api

Database Connection Issues

**Data**:

- severity: SEV-2
- service: payments

---

## 2025-12-04T10:32:15Z - im.incident.ack

**Actor**: oncall@example.com
**Source**: im://api

Incident acknowledged

Timeline Event Types:

Core incident lifecycle events:

  • im.incident.declare - Incident creation
  • im.incident.ack - Incident acknowledgment
  • im.incident.mitigate - Incident mitigation
  • im.incident.resolve - Incident resolution
  • im.incident.close - Incident closure
  • im.incident.note - Manual note added to timeline

External alert events:

  • im.alert.trigger - Alert triggered from monitoring system
  • im.alert.resolve - Alert auto-resolved

ITSM integration events:

  • im.servicenow.sync - ServiceNow ticket created/updated
  • im.jira.sync - Jira issue created/updated
  • im.pagerduty.escalate - PagerDuty escalation triggered

Error Responses:

  • 400 - Invalid CloudEvent format
  • 403 - Permission denied (missing required role: timeline.writer, timeline.reader, or timeline.exporter)
  • 404 - Event or incident not found
  • 409 - State transition violation
  • 503 - Policy Decision Point unavailable (fail-closed behavior)

Non-Functional Endpoints

The following endpoints are defined in the server code but return 404 (not yet implemented):

  • /api/v1/realtime/stats - Real-time statistics
  • /api/v1/correlation/groups - Correlation groups
  • /api/v1/correlation/stats - Correlation statistics
  • /api/v1/sla/status/{id} - SLA status
  • /api/v1/sla/metrics - SLA metrics
  • /api/v1/metrics/incidents - Incident metrics
  • /api/v1/metrics/teams - Team metrics
  • /api/v1/metrics/services/{service}/reliability - Service reliability
  • /api/v1/connectors - Connector management

Example Usage

Full Incident Lifecycle 

# 1. Create incident
INCIDENT=$(curl -s -X POST http://localhost:8080/api/v1/incidents \
  -H "Content-Type: application/json" \
  -d '{"title":"Test incident","severity":"SEV-3"}' \
  | jq -r '.id')

echo "Created incident: $INCIDENT"

# 2. Acknowledge incident
curl -X POST http://localhost:8080/api/v1/incidents/$INCIDENT/ack

# 3. Check timeline
curl -s http://localhost:8080/api/v1/incidents/$INCIDENT/timeline | jq

# 4. Resolve incident
curl -X POST http://localhost:8080/api/v1/incidents/$INCIDENT/resolve

# 5. Close incident
curl -X POST http://localhost:8080/api/v1/incidents/$INCIDENT/close

List and Filter 

# Get all incidents
curl -s http://localhost:8080/api/v1/incidents | jq

# Get specific incident
curl -s http://localhost:8080/api/v1/incidents/INC-12345 | jq

# Check if incident exists (returns incident data or 404)
if curl -s -f http://localhost:8080/api/v1/incidents/INC-12345 > /dev/null; then
  echo "Incident exists"
else
  echo "Incident not found"
fi

Validation & Simulation

GET /api/v1/validate

Validate the deployment and check system health.

Request:

curl http://localhost:8080/api/v1/validate \
  -H "Authorization: Bearer $TOKEN"

# With comprehensive self-test
curl "http://localhost:8080/api/v1/validate?self_test=true" \
  -H "Authorization: Bearer $TOKEN"

Response:

{
  "timestamp": "2025-12-11T10:30:00Z",
  "version": "1.0.0",
  "capabilities": {
    "database": true,
    "timeline": true,
    "websocket": true,
    "sse": true,
    "graphql": true
  },
  "results": [
    {
      "component": "Database",
      "check": "Connection",
      "status": "pass",
      "message": "Database connected and schema verified",
      "duration": "1.234ms"
    }
  ],
  "summary": {
    "total": 10,
    "passed": 9,
    "failed": 0,
    "warned": 1
  }
}

POST /api/v1/simulate

Simulate event processing without modifying the database.

Request:

curl -X POST http://localhost:8080/api/v1/simulate \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "events": [
      {
        "specversion": "1.0",
        "id": "test-event-1",
        "source": "simulation",
        "type": "incident.trigger",
        "data": {"title": "Test Incident"}
      }
    ],
    "dry_run": true
  }'

Response:

{
  "timestamp": "2025-12-11T10:30:00Z",
  "dry_run": true,
  "events_read": 1,
  "events_created": [
    {
      "id": "INC-0001",
      "type": "incident.declared",
      "source": "simulation",
      "subject": "INC-0001",
      "time": "2025-12-11T10:30:00Z",
      "would_create": "New incident: INC-0001 (Test Incident)"
    }
  ],
  "errors": []
}

Schema & Documentation

GET /api/v1/schema

Get schema definitions for data models.

Request:

# Get incident schema in OpenAPI format
curl "http://localhost:8080/api/v1/schema?type=incident&format=openapi" \
  -H "Authorization: Bearer $TOKEN"

# Get event schema in JSON Schema format
curl "http://localhost:8080/api/v1/schema?type=event&format=jsonschema" \
  -H "Authorization: Bearer $TOKEN"

Query Parameters:

  • type - Schema type: incident, event, or config (default: incident)
  • format - Output format: openapi or jsonschema (default: openapi)

GET /api/v1/openapi.json

Get the full OpenAPI 3.0 specification.

Request:

curl http://localhost:8080/api/v1/openapi.json \
  -H "Authorization: Bearer $TOKEN"

GET /api/v1/docs (Development Mode Only)

Access the Swagger UI for interactive API exploration.

Note: This endpoint is only available when the server is running in development mode (dev: true).

GraphQL

GET/POST /api/v1/graphql

Execute GraphQL queries and mutations.

Request (GET):

curl "http://localhost:8080/api/v1/graphql?query={myIncidents{id,title,severity}}" \
  -H "Authorization: Bearer $TOKEN"

Request (POST):

curl -X POST http://localhost:8080/api/v1/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "query": "query { myIncidents { id title severity status } }"
  }'

Response:

{
  "data": {
    "myIncidents": [
      {
        "id": "INC-12345",
        "title": "Database Connection Issues",
        "severity": "SEV_2",
        "status": "ACKNOWLEDGED"
      }
    ]
  }
}

See the GraphQL documentation for the full schema and available operations.

Error Responses

The API returns standard HTTP status codes:

  • 200 - Success
  • 201 - Created
  • 404 - Not Found
  • 500 - Internal Server Error

Example error response:

{
  "error": "incident not found",
  "status": 404
}

Development Notes

  • Server must be running on localhost:8080 for API access
  • SQLite database is used for storage (incidents.db file)
  • No authentication required in development mode
  • All timestamps are in RFC3339 format (UTC)
  • Incident IDs follow the pattern INC-{8-char-hex}

Production Development: Authentication, rate limiting, and additional endpoints will be added as the platform progresses toward production readiness.

Edit this page on GitHub
Prev
Event Publishing Configuration
Next
Installation