{ "openapi": "3.1.0", "info": { "title": "Runframe V1 API", "version": "1.0.0", "description": "The Runframe direct customer API for incident management, on-call scheduling, and postmortems." }, "servers": [ { "url": "https://runframe.io", "description": "Production" } ], "security": [ { "bearerAuth": [] } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "API key (rf_...) or session JWT" } }, "schemas": { "SuccessEnvelope": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ] }, "data": {}, "meta": { "type": "object", "properties": { "request_id": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } } } } }, "ErrorEnvelope": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "user_message": { "type": "string" }, "details": { "type": "object" } }, "required": [ "code", "message" ] }, "meta": { "type": "object", "properties": { "request_id": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } } } } }, "PaginationMeta": { "type": "object", "properties": { "total": { "type": "integer" }, "has_more": { "type": "boolean" }, "next_offset": { "type": "integer", "nullable": true } } }, "IncidentNumber": { "type": "string", "description": "Human-readable incident identifier like INC-2026-044", "example": "INC-2026-044" }, "IncidentId": { "allOf": [ { "$ref": "#/components/schemas/IncidentNumber" } ], "description": "Human-readable incident identifier scoped to the organization" }, "ServiceKey": { "type": "string", "description": "Public service key like svc_K7M4Q9TZ2H", "example": "svc_K7M4Q9TZ2H" }, "Severity": { "type": "string", "enum": [ "SEV0", "SEV1", "SEV2", "SEV3", "SEV4" ], "description": "Severity level" }, "PostmortemImpact": { "type": "object", "properties": { "duration": { "type": "string", "nullable": true }, "users_affected": { "type": "string", "nullable": true }, "services_affected": { "type": "array", "items": { "type": "string" }, "nullable": true }, "revenue_impact": { "type": "string", "nullable": true } } }, "PostmortemTimelineEvent": { "type": "object", "properties": { "timestamp": { "type": "string" }, "description": { "type": "string" } } }, "PostmortemActionItem": { "type": "object", "properties": { "text": { "type": "string" }, "owner_email": { "type": "string", "format": "email", "nullable": true }, "due_date": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "pending", "in_progress", "completed" ] } } }, "IncidentV1": { "type": "object", "properties": { "incident_number": { "$ref": "#/components/schemas/IncidentNumber" }, "title": { "type": "string" }, "description": { "type": "string", "nullable": true }, "status": { "type": "string", "description": "Canonical organization-defined status name used for filters and status transitions", "example": "investigating" }, "severity": { "$ref": "#/components/schemas/Severity" }, "assigned_to": { "type": "object", "nullable": true, "properties": { "name": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true } } }, "team": { "type": "object", "nullable": true, "properties": { "name": { "type": "string", "nullable": true } } }, "created_at": { "type": "string", "format": "date-time" }, "acknowledged_at": { "type": "string", "format": "date-time", "nullable": true }, "resolved_at": { "type": "string", "format": "date-time", "nullable": true } } }, "ServiceV1": { "type": "object", "properties": { "name": { "type": "string" }, "service_key": { "$ref": "#/components/schemas/ServiceKey" }, "description": { "type": "string", "nullable": true }, "is_active": { "type": "boolean" }, "default_severity": { "anyOf": [ { "$ref": "#/components/schemas/Severity" }, { "type": "null" } ] } } }, "UserV1": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true }, "is_active": { "type": "boolean" } } }, "TeamV1": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "member_count": { "type": "integer" }, "is_active": { "type": "boolean" } } }, "PostmortemV1": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "postmortem_number": { "type": "string" }, "incident_number": { "$ref": "#/components/schemas/IncidentNumber" }, "level": { "type": "string" }, "status": { "type": "string" }, "summary": { "type": "string", "nullable": true }, "root_cause": { "type": "string", "nullable": true }, "resolution": { "type": "string", "nullable": true }, "impact": { "anyOf": [ { "$ref": "#/components/schemas/PostmortemImpact" }, { "type": "string", "description": "Legacy HTML content. Prefer impact_html when present." }, { "type": "null" } ] }, "impact_html": { "type": "string", "nullable": true }, "timeline": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/PostmortemTimelineEvent" } }, { "type": "string", "description": "Legacy HTML content. Prefer timeline_html when present." }, { "type": "null" } ] }, "timeline_html": { "type": "string", "nullable": true }, "action_items": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/PostmortemActionItem" } }, { "type": "string", "description": "Legacy HTML content. Prefer action_items_html when present." }, { "type": "null" } ] }, "action_items_html": { "type": "string", "nullable": true }, "contributing_factors": { "type": "string", "nullable": true }, "detection_path": { "type": "string", "nullable": true }, "monitoring_gaps": { "type": "string", "nullable": true }, "response_timeline": { "anyOf": [ { "type": "object", "properties": { "time_to_acknowledge": { "type": "string", "nullable": true }, "time_to_identify": { "type": "string", "nullable": true }, "time_to_resolve": { "type": "string", "nullable": true } } }, { "type": "string", "description": "Legacy HTML content. Prefer response_timeline_html when present." }, { "type": "null" } ] }, "response_timeline_html": { "type": "string", "nullable": true }, "five_whys": { "type": "string", "nullable": true }, "executive_summary": { "type": "string", "nullable": true }, "prevented_recurrence": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } } }, "OnCallEngineerV1": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string", "nullable": true }, "slack_user_id": { "type": "string", "nullable": true }, "role": { "type": "string" }, "schedule_name": { "type": "string", "nullable": true }, "shift_starts_at": { "type": "string", "format": "date-time", "nullable": true }, "shift_ends_at": { "type": "string", "format": "date-time", "nullable": true } } }, "OnCallPrimaryV1": { "$ref": "#/components/schemas/OnCallEngineerV1" }, "OnCallServiceV1": { "type": "object", "properties": { "service_key": { "anyOf": [ { "$ref": "#/components/schemas/ServiceKey" }, { "type": "null" } ] }, "service_name": { "type": "string" }, "service_description": { "type": "string", "nullable": true }, "team_name": { "type": "string" }, "team_description": { "type": "string", "nullable": true }, "on_call_engineers": { "type": "array", "items": { "$ref": "#/components/schemas/OnCallEngineerV1" } }, "has_coverage": { "type": "boolean" }, "primary_on_call": { "anyOf": [ { "$ref": "#/components/schemas/OnCallPrimaryV1" }, { "type": "null" } ] }, "schedule_names": { "type": "array", "items": { "type": "string" } } } }, "OnCallSummaryV1": { "type": "object", "properties": { "total_services": { "type": "integer" }, "services_with_coverage": { "type": "integer" }, "services_without_coverage": { "type": "integer" }, "coverage_percentage": { "type": "integer" } } }, "OnCallV1": { "type": "object", "properties": { "timestamp": { "type": "string", "format": "date-time" }, "summary": { "$ref": "#/components/schemas/OnCallSummaryV1" }, "services": { "type": "array", "items": { "$ref": "#/components/schemas/OnCallServiceV1" } } } }, "StatusPageComponentStatus": { "type": "string", "enum": [ "operational", "degraded_performance", "partial_outage", "major_outage", "under_maintenance", "unknown" ] }, "PublicStatusComponent": { "type": "object", "properties": { "component_id": { "type": "string", "example": "cmp_Q7K2MNPQ8R" }, "name": { "type": "string" }, "status": { "$ref": "#/components/schemas/StatusPageComponentStatus" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "component_id", "name", "status", "updated_at" ] }, "PublicStatusSummary": { "type": "object", "properties": { "page": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": "string", "format": "uri" } }, "required": [ "name", "url" ] }, "status": { "$ref": "#/components/schemas/StatusPageComponentStatus" }, "updated_at": { "type": "string", "format": "date-time" }, "active_incident_count": { "type": "integer" }, "active_maintenance_count": { "type": "integer" } }, "required": [ "page", "status", "updated_at", "active_incident_count", "active_maintenance_count" ] }, "PublicStatusComponents": { "type": "object", "properties": { "sections": { "type": "array", "items": { "type": "object", "properties": { "section_id": { "type": "string", "example": "sec_Q7K2MNPQ8R" }, "name": { "type": "string" }, "components": { "type": "array", "items": { "$ref": "#/components/schemas/PublicStatusComponent" } }, "groups": { "type": "array", "items": { "type": "object", "properties": { "group_id": { "type": "string", "example": "grp_Q7K2MNPQ8R" }, "name": { "type": "string" }, "components": { "type": "array", "items": { "$ref": "#/components/schemas/PublicStatusComponent" } } }, "required": [ "group_id", "name", "components" ] } } }, "required": [ "section_id", "name", "components", "groups" ] } } }, "required": [ "sections" ] }, "PublicStatusIncident": { "type": "object", "properties": { "incident_id": { "type": "string", "example": "inc_Q7K2MNPQ8R" }, "title": { "type": "string" }, "status": { "type": "string", "enum": [ "investigating", "identified", "monitoring", "resolved" ] }, "impact": { "type": "string", "enum": [ "none", "minor", "major", "critical" ] }, "started_at": { "type": "string", "format": "date-time" }, "resolved_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "updates": { "type": "array", "items": { "type": "object", "properties": { "status": { "type": "string" }, "body": { "type": "string" }, "published_at": { "type": "string", "format": "date-time" } }, "required": [ "status", "body", "published_at" ] } }, "affected_components": { "type": "array", "items": { "type": "object", "properties": { "component_id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "component_id", "name" ] } } }, "required": [ "incident_id", "title", "status", "impact", "started_at", "resolved_at", "updated_at", "updates", "affected_components" ] }, "PublicStatusIncidents": { "type": "object", "properties": { "incidents": { "type": "array", "items": { "$ref": "#/components/schemas/PublicStatusIncident" } }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "incidents", "next_cursor" ] }, "PublicStatusMaintenanceWindow": { "type": "object", "properties": { "maintenance_id": { "type": "string", "example": "mnt_Q7K2MNPQ8R" }, "title": { "type": "string" }, "status": { "type": "string", "enum": [ "scheduled", "in_progress", "completed", "cancelled" ] }, "scheduled_start": { "type": "string", "format": "date-time" }, "scheduled_end": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "affected_components": { "type": "array", "items": { "type": "object", "properties": { "component_id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "component_id", "name" ] } } }, "required": [ "maintenance_id", "title", "status", "scheduled_start", "scheduled_end", "updated_at", "affected_components" ] }, "PublicStatusMaintenance": { "type": "object", "properties": { "maintenance": { "type": "array", "items": { "$ref": "#/components/schemas/PublicStatusMaintenanceWindow" } }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "maintenance", "next_cursor" ] } }, "parameters": { "limitParam": { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "description": "Results per page (max 100)" }, "offsetParam": { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 }, "description": "Pagination offset" }, "incidentIdParam": { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Human-readable incident identifier scoped to the organization (e.g. INC-2026-044)" } } }, "paths": { "/api/v1/auth/verify": { "get": { "operationId": "verifyAuth", "summary": "Verify API key and return scopes", "tags": [ "Authentication" ], "responses": { "200": { "description": "Key is valid", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "valid": { "type": "boolean" }, "scopes": { "type": "array", "items": { "type": "string" } }, "organization_name": { "type": "string" } } } } } ] } } } }, "401": { "description": "Invalid or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/incidents": { "get": { "operationId": "listIncidents", "summary": "List incidents", "description": "Returns incidents that are still in progress by default. To include resolved or closed incidents, pass explicit status filters.", "tags": [ "Incidents" ], "parameters": [ { "$ref": "#/components/parameters/limitParam" }, { "$ref": "#/components/parameters/offsetParam" }, { "name": "status", "in": "query", "schema": { "type": "array", "items": { "type": "string" } }, "description": "Filter by canonical status name" }, { "name": "severity", "in": "query", "schema": { "type": "array", "items": { "type": "string" } }, "description": "Filter by severity (SEV0-SEV4)" }, { "name": "team_name", "in": "query", "schema": { "type": "string" }, "description": "Filter by team name (case-insensitive)" }, { "name": "assigned_to", "in": "query", "schema": { "type": "string", "format": "email" }, "description": "Filter by current assignee email" }, { "name": "resolved_by", "in": "query", "schema": { "type": "string", "format": "email" }, "description": "Filter by resolver email" }, { "name": "created_after", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Only incidents created at or after this timestamp" }, { "name": "created_before", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Only incidents created at or before this timestamp" }, { "name": "resolved_after", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Only incidents resolved at or after this timestamp" }, { "name": "resolved_before", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Only incidents resolved at or before this timestamp" } ], "responses": { "200": { "description": "Paginated incident list", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/PaginationMeta" }, { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/IncidentV1" } } } } ] } } } ] } } } }, "401": { "description": "Missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "operationId": "createIncident", "summary": "Create an incident", "tags": [ "Incidents" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "schema": { "type": "string" }, "description": "Optional idempotency key for replay-safe creates. Same key + same payload replays the original response. Same key + different payload returns 409. A duplicate request sent while the original request is still in progress also returns 409." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "title", "service_ids" ], "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "maxLength": 10000 }, "severity": { "$ref": "#/components/schemas/Severity" }, "service_ids": { "type": "array", "items": { "$ref": "#/components/schemas/ServiceKey" }, "minItems": 1, "maxItems": 50, "description": "Public service keys (e.g. svc_K7M4Q9TZ2H). Use GET /api/v1/services to discover available keys." } } } } } }, "responses": { "201": { "description": "Incident created. Returns the incident snapshot at creation time. Post-create automation such as assignment and notifications may complete asynchronously, so assigned_to and team may not yet reflect final post-create state.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/IncidentV1" } } } ] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency conflict: payload mismatch or duplicate request still in progress", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Server-side configuration error, including incomplete SLA configuration for the requested severity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "SLA settings are invalid for severity SEV2. Update these settings in Settings -> Severities & SLA.", "user_message": "An internal error occurred. Please try again." }, "meta": { "request_id": "req_abc123", "timestamp": "2026-04-19T10:30:00.000Z" } } } } } } } }, "/api/v1/incidents/{id}": { "parameters": [ { "$ref": "#/components/parameters/incidentIdParam" } ], "get": { "operationId": "getIncident", "summary": "Get incident details with timeline", "tags": [ "Incidents" ], "responses": { "200": { "description": "Full incident details", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/IncidentV1" }, { "type": "object", "properties": { "timeline": { "type": "array", "items": { "type": "object", "properties": { "event_type": { "type": "string" }, "title": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "user": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } } } }, "timeline_meta": { "type": "object", "properties": { "limit": { "type": "integer" }, "has_more": { "type": "boolean" } } } } } ] } } } ] } } } }, "401": { "description": "Missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Incident not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "patch": { "operationId": "updateIncident", "summary": "Update incident fields (not status transitions)", "tags": [ "Incidents" ], "description": "Field updates only. For status changes use POST /api/v1/incidents/{id}/status.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "minProperties": 1, "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "maxLength": 10000 }, "severity": { "$ref": "#/components/schemas/Severity" }, "assigned_to": { "type": "string", "format": "email", "description": "Email address of engineer to assign" } } } } } }, "responses": { "200": { "description": "Updated incident", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/IncidentV1" } } } ] } } } }, "400": { "description": "Validation error (e.g. invalid severity)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Incident not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/incidents/{id}/acknowledge": { "parameters": [ { "$ref": "#/components/parameters/incidentIdParam" } ], "post": { "operationId": "acknowledgeIncident", "summary": "Acknowledge an incident", "tags": [ "Incidents" ], "description": "A deliberate action endpoint separate from status transitions. Auto-assigns, stamps acknowledgement time, and resolves the acknowledge SLA.", "responses": { "200": { "description": "Incident acknowledged", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "incident_number": { "$ref": "#/components/schemas/IncidentNumber" }, "acknowledged": { "type": "boolean" }, "acknowledged_at": { "type": "string", "format": "date-time", "nullable": true } } } } } ] } } } }, "401": { "description": "Missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Incident not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/incidents/{id}/status": { "parameters": [ { "$ref": "#/components/parameters/incidentIdParam" } ], "post": { "operationId": "changeIncidentStatus", "summary": "Transition incident status", "tags": [ "Incidents" ], "description": "Canonical status transition endpoint. Resolve, close, investigate, and monitor all flow through here. For acknowledging, use POST /api/v1/incidents/{id}/acknowledge instead.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "description": "Target canonical status name returned by the incident `status` field" }, "comment": { "type": "string", "maxLength": 500, "description": "Reason for the status change" } } } } } }, "responses": { "200": { "description": "Status updated", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/IncidentV1" } } } ] } } } }, "400": { "description": "Invalid status or transition not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Incident not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/incidents/{id}/page": { "parameters": [ { "$ref": "#/components/parameters/incidentIdParam" } ], "post": { "operationId": "pageSomeone", "summary": "Page a specific person about an incident", "tags": [ "Incidents" ], "description": "Sends a real notification. Urgency is derived from incident severity automatically.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email", "channels" ], "properties": { "email": { "type": "string", "format": "email", "description": "Customer-facing identifier for the person to page" }, "channels": { "type": "array", "minItems": 1, "items": { "type": "string", "enum": [ "slack", "email" ] }, "description": "One or more delivery channels" }, "message": { "type": "string", "maxLength": 500 } }, "example": { "email": "niketa@runframe.io", "channels": [ "slack", "email" ], "message": "Please investigate this incident" } } } } }, "responses": { "200": { "description": "At least one requested channel sent successfully. Response includes per-channel delivery results.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "incident_number": { "$ref": "#/components/schemas/IncidentNumber" }, "sent": { "type": "boolean" }, "channels": { "type": "array", "items": { "type": "string", "enum": [ "slack", "email" ] } }, "deliveries": { "type": "array", "items": { "type": "object", "properties": { "channel": { "type": "string", "enum": [ "slack", "email" ] }, "sent": { "type": "boolean" }, "error_code": { "type": "string", "nullable": true }, "message": { "type": "string", "nullable": true } }, "required": [ "channel", "sent" ] } } } } } } ] } } } }, "401": { "description": "Missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Delivery failed for all requested channels because the user does not have the required contact details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Delivery failed for all requested channels because the notification provider could not deliver the message", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/incidents/{id}/events": { "parameters": [ { "$ref": "#/components/parameters/incidentIdParam" } ], "post": { "operationId": "addIncidentEvent", "summary": "Add a timeline event to an incident", "tags": [ "Incidents" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "comment" ], "properties": { "comment": { "type": "string", "minLength": 1 } } } } } }, "responses": { "200": { "description": "Timeline entry added", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "incident_number": { "$ref": "#/components/schemas/IncidentNumber" }, "comment": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } } } } ] } } } }, "401": { "description": "Missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Incident not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/incidents/{id}/escalate": { "parameters": [ { "$ref": "#/components/parameters/incidentIdParam" } ], "post": { "operationId": "escalateIncident", "summary": "Escalate an incident to the next policy level", "tags": [ "Incidents" ], "responses": { "200": { "description": "Incident escalated", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "incident_number": { "$ref": "#/components/schemas/IncidentNumber" }, "escalated": { "type": "boolean" }, "notified_emails": { "type": "array", "items": { "type": "string", "format": "email" } }, "current_level": { "type": "integer", "nullable": true }, "next_level": { "type": "integer", "nullable": true } } } } } ] } } } }, "401": { "description": "Missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Incident not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/on-call/current": { "get": { "operationId": "getCurrentOnCall", "summary": "Get current on-call responder", "tags": [ "On-Call" ], "parameters": [ { "name": "team_name", "in": "query", "schema": { "type": "string" }, "description": "Optional team name filter (case-insensitive)" } ], "responses": { "200": { "description": "Current on-call data", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/OnCallV1" } } } ] } } } }, "401": { "description": "Missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Incident has already been acknowledged", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/postmortems": { "get": { "operationId": "getPostmortem", "summary": "Get the postmortem for an incident", "tags": [ "Postmortems" ], "parameters": [ { "name": "incident_number", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/IncidentNumber" }, "description": "Canonical customer-facing incident identifier." } ], "responses": { "200": { "description": "Postmortem details", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PostmortemV1" } } } ] } } } }, "401": { "description": "Missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Incident or postmortem not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "operationId": "createPostmortem", "summary": "Create a postmortem for an incident", "tags": [ "Postmortems" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "incident_number" ], "properties": { "incident_number": { "$ref": "#/components/schemas/IncidentNumber" }, "summary": { "type": "string" }, "root_cause": { "type": "string" }, "resolution": { "type": "string" }, "impact": { "$ref": "#/components/schemas/PostmortemImpact" }, "timeline": { "type": "array", "items": { "$ref": "#/components/schemas/PostmortemTimelineEvent" } }, "action_items": { "type": "array", "items": { "$ref": "#/components/schemas/PostmortemActionItem" } }, "contributing_factors": { "type": "string" }, "detection_path": { "type": "string" }, "monitoring_gaps": { "type": "string" }, "response_timeline": { "type": "object", "properties": { "time_to_acknowledge": { "type": "string", "nullable": true }, "time_to_identify": { "type": "string", "nullable": true }, "time_to_resolve": { "type": "string", "nullable": true } }, "example": { "time_to_acknowledge": "66s", "time_to_identify": "2m", "time_to_resolve": "90s" } }, "five_whys": { "type": "string" }, "executive_summary": { "type": "string" }, "prevented_recurrence": { "type": "string" } }, "example": { "incident_number": "INC-2026-052", "summary": "Brief summary", "root_cause": "Root cause details", "resolution": "Resolution details", "impact": { "duration": "90s", "users_affected": "0 external customers", "services_affected": [ "Incident Command Console" ], "revenue_impact": "none" }, "timeline": [ { "timestamp": "2026-04-19T16:58:26Z", "description": "Incident created" } ], "action_items": [ { "text": "Add source validation", "owner_email": "owner@example.com", "due_date": "2026-04-30", "status": "pending" } ], "contributing_factors": "Missing source validation", "detection_path": "Local Postman collection", "monitoring_gaps": "No false-positive source alerting", "response_timeline": { "time_to_acknowledge": "66s", "time_to_identify": "2m", "time_to_resolve": "90s" }, "five_whys": "Why chain", "executive_summary": "Executive summary", "prevented_recurrence": "Add validation and isolation" } } } } }, "responses": { "201": { "description": "Postmortem created", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "postmortem_number": { "type": "string" }, "incident_number": { "$ref": "#/components/schemas/IncidentNumber" }, "level": { "type": "string" }, "status": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } } } } ] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Incident not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/escalation-policies": { "get": { "operationId": "getEscalationPolicy", "summary": "Get escalation policy for a severity level", "tags": [ "Escalation Policies" ], "parameters": [ { "name": "severity", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/Severity" }, "description": "Severity level to look up policy for" } ], "responses": { "200": { "description": "Escalation policy", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object" } } } ] } } } }, "400": { "description": "Invalid severity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/services": { "get": { "operationId": "listServices", "summary": "List services", "tags": [ "Services" ], "description": "How clients discover service keys for use in incident creation.", "parameters": [ { "$ref": "#/components/parameters/limitParam" }, { "$ref": "#/components/parameters/offsetParam" }, { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Filter by name" } ], "responses": { "200": { "description": "Paginated service list", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/PaginationMeta" }, { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ServiceV1" } } } } ] } } } ] } } } }, "401": { "description": "Missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/services/{id}": { "get": { "operationId": "getService", "summary": "Get service details", "tags": [ "Services" ], "description": "Lookup by public service key.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ServiceKey" }, "description": "Public service key like svc_K7M4Q9TZ2H" } ], "responses": { "200": { "description": "Service details", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ServiceV1" } } } ] } } } }, "400": { "description": "Invalid service key format", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Service not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/teams": { "get": { "operationId": "listTeams", "summary": "List teams", "tags": [ "Teams" ], "parameters": [ { "$ref": "#/components/parameters/limitParam" }, { "$ref": "#/components/parameters/offsetParam" }, { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Filter by team name" } ], "responses": { "200": { "description": "Paginated team list", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/PaginationMeta" }, { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/TeamV1" } } } } ] } } } ] } } } }, "401": { "description": "Missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/users": { "get": { "operationId": "listUsers", "summary": "List users", "tags": [ "Users" ], "description": "Search people by name or email to resolve assignee and resolver IDs.", "parameters": [ { "$ref": "#/components/parameters/limitParam" }, { "$ref": "#/components/parameters/offsetParam" }, { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Search by name or email" }, { "name": "is_active", "in": "query", "schema": { "type": "boolean" }, "description": "Optional active-state filter" } ], "responses": { "200": { "description": "Paginated user list", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/PaginationMeta" }, { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/UserV1" } } } } ] } } } ] } } } }, "401": { "description": "Missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/status": { "get": { "operationId": "getPublicStatusSummary", "summary": "Get public status summary", "tags": [ "Status Page" ], "security": [], "parameters": [], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining requests in the current window" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Reset timestamp" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PublicStatusSummary" } } } ] } } } }, "304": { "description": "Not modified" }, "404": { "description": "Status page not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "405": { "description": "Method not allowed" }, "429": { "description": "Rate limited", "headers": { "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining requests in the current window" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Reset timestamp" }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Status page data or public keys not ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/status/components": { "get": { "operationId": "getPublicStatusComponents", "summary": "Get public status components", "tags": [ "Status Page" ], "security": [], "parameters": [], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining requests in the current window" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Reset timestamp" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PublicStatusComponents" } } } ] } } } }, "304": { "description": "Not modified" }, "404": { "description": "Status page not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "405": { "description": "Method not allowed" }, "429": { "description": "Rate limited", "headers": { "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining requests in the current window" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Reset timestamp" }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Status page data or public keys not ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/status/incidents": { "get": { "operationId": "getPublicStatusIncidents", "summary": "Get public status incident history", "tags": [ "Status Page" ], "security": [], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "open", "resolved", "all" ], "default": "all" } }, { "name": "updates_limit", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 20, "default": 5 } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining requests in the current window" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Reset timestamp" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PublicStatusIncidents" } } } ] } } } }, "304": { "description": "Not modified" }, "400": { "description": "Invalid query parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Status page not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "405": { "description": "Method not allowed" }, "429": { "description": "Rate limited", "headers": { "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining requests in the current window" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Reset timestamp" }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Status page data or public keys not ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/status/incidents/unresolved": { "get": { "operationId": "getPublicStatusUnresolvedIncidents", "summary": "Get unresolved public status incidents", "tags": [ "Status Page" ], "security": [], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "updates_limit", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 20, "default": 5 } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining requests in the current window" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Reset timestamp" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PublicStatusIncidents" } } } ] } } } }, "304": { "description": "Not modified" }, "400": { "description": "Invalid query parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Status page not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "405": { "description": "Method not allowed" }, "429": { "description": "Rate limited", "headers": { "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining requests in the current window" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Reset timestamp" }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Status page data or public keys not ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/status/maintenance": { "get": { "operationId": "getPublicStatusMaintenance", "summary": "Get public status maintenance windows", "tags": [ "Status Page" ], "security": [], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "scheduled", "in_progress", "completed", "cancelled", "all" ], "default": "all" } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining requests in the current window" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Reset timestamp" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PublicStatusMaintenance" } } } ] } } } }, "304": { "description": "Not modified" }, "400": { "description": "Invalid query parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Status page not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "405": { "description": "Method not allowed" }, "429": { "description": "Rate limited", "headers": { "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining requests in the current window" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Reset timestamp" }, "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Status page data or public keys not ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } } }