Skip to main content

​
Overview

Update the status of an incident through its lifecycle. This endpoint enforces strict state transition rules to maintain incident workflow integrity. It’s the primary way to acknowledge, resolve, and close incidents.

​
Authentication

Requires API Key authentication:
  • API Key: X-API-Key: YOUR_API_KEY

​
Path Parameters

​
id
string
required
Incident ID (UUID). The unique identifier of the incident to update.

​
Request Body

​
status
string
required
New incident status. Valid values: open, acknowledged, resolved, closed.
​
note
string
Optional note or comment explaining the status change. Maximum 500 characters.
​
assignee_id
string
User ID (UUID) of the person assigned to this incident. If not provided, defaults to the authenticated user making the request.

​
State Transition Rules

The incident status follows a strict forward-only state machine:
Current StatusValid TransitionsNotes
openacknowledged, resolvedCan acknowledge or directly resolve
acknowledgedresolved, closedCan resolve or close directly
resolvedclosedCan only close after resolution
closed(none)Terminal state - no further transitions
Backward transitions are not allowed. The state machine enforces forward-only progression. Once an incident moves to a later state, it cannot return to a previous state. Same-state transitions (e.g., open to open) are also rejected.
Invalid transitions will result in a 400 Bad Request error with the valid transitions listed.

​
Response Format

​
success
boolean
Whether the request was successful
​
data
object

​
Example Requests

curl -X PUT 'https://api.uptimeio.com/api/incidents/550e8400-e29b-41d4-a716-446655440000/status' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "status": "acknowledged",
    "note": "Investigating the root cause"
  }'

​
Example Response

{
  "success": true,
  "data": {
    "incident": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "check_id": "660e8400-e29b-41d4-a716-446655440000",
      "monitor_name": "API Health Check",
      "status": "resolved",
      "severity": "critical",
      "type": "timeout",
      "title": "API Health Check - Timeout",
      "error_message": "Request timeout after 5000ms",
      "started_at": "2023-12-19T16:00:00.000Z",
      "resolved_at": "2023-12-19T17:00:00.000Z",
      "acknowledged_at": "2023-12-19T16:01:00.000Z",
      "recovery_time_seconds": 3600,
      "affected_regions": ["us-east-1", "eu-west-1"],
      "failure_count": 3,
      "notification_sent": true,
      "created_at": "2023-12-19T16:00:00.000Z",
      "updated_at": "2023-12-19T17:00:00.000Z"
    },
    "recovery_time_seconds": 3600
  }
}

​
Status Codes

StatusDescription
200 OKStatus successfully updated
400 Bad RequestInvalid state transition or validation error
401 UnauthorizedAuthentication failed or invalid credentials
404 Not FoundIncident not found or not accessible in current project
500 Internal Server ErrorServer error during status update

​
Error Codes

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Cannot transition from closed to open. Incident is in final state and cannot be modified.",
    "details": {
      "fromStatus": "closed",
      "toStatus": "open",
      "validTransitions": []
    }
  }
}

​
Status Transition Examples

​
Example 1: Open → Acknowledged → Resolved → Closed

# Step 1: Acknowledge the incident
PUT /api/incidents/{id}/status
{"status": "acknowledged", "note": "Investigating"}

# Step 2: Resolve the issue
PUT /api/incidents/{id}/status
{"status": "resolved", "note": "Issue fixed"}

# Step 3: Close for post-mortem completion
PUT /api/incidents/{id}/status
{"status": "closed", "note": "Post-mortem documented"}

​
Example 2: Open → Resolved (skip acknowledge)

# Directly resolve without acknowledging
PUT /api/incidents/{id}/status
{"status": "resolved", "note": "Auto-resolved by monitoring system"}

​
Example 3: Acknowledged → Closed (skip resolved)

# Close directly from acknowledged state (e.g., false positive)
PUT /api/incidents/{id}/status
{"status": "closed", "note": "False positive - no action needed"}

​
Example 4: Invalid Transition (Error)

# This will fail - cannot go from open directly to closed
PUT /api/incidents/{id}/status
{"status": "closed"}

# Response: 400 Bad Request
# "Cannot transition incident from 'open' to 'closed'. Valid transitions: acknowledged, resolved"

​
Example 5: Terminal State (Error)

# This will fail - closed is a terminal state
PUT /api/incidents/{id}/status
{"status": "open"}

# Response: 400 Bad Request
# "Cannot transition incident from 'closed' to 'open'. Incident is in final state and cannot be modified."

​
Incident Lifecycle

State Transitions (forward-only):
  open         → acknowledged, resolved
  acknowledged → resolved, closed
  resolved     → closed
  closed       → (terminal - no transitions)

​
Notes

  • The assignee_id defaults to the authenticated user if not provided
  • All status changes are logged to the incident audit trail with full attribution
  • Recovery time is automatically calculated from started_at to resolution
  • The state machine enforces forward-only progression to maintain workflow integrity
  • Once closed, an incident cannot be modified (terminal state)
  • Same-state transitions are rejected (e.g., open to open returns an error)
  • Status change notes are optional but recommended for team communication