Update an incident

API v3 is in preview

Endpoints and response shapes can change before general availability. API v2 is unchanged.

PATCH https://app.honeybadger.io/v3/status_pages/{status_page_id}/incidents/{incident_id}

Required scope incidents:write

Updates an incident’s details. Its status, severity and closed_at come from its updates, so change those by posting or editing an update. build_type can’t be changed.

Example request

curl -X PATCH "https://app.honeybadger.io/v3/status_pages/$STATUS_PAGE_ID/incidents/$INCIDENT_ID" \
  -H "Authorization: Bearer $HONEYBADGER_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "title": "Elevated error rates on checkout"
}'

Parameters

2

Path parameters

Field	Type	Description
status_page_id required	string	Status page ID.
incident_id required	string	Incident ID.

Request body

Field	Type	Description
title	string
retro_should_notify	boolean
retro_notify_message	string | null

Responses

1

200 Success

Example payload

{
  "data": {
    "id": "In3pKr",
    "status_page_id": "Sp7bMq",
    "title": "Database connectivity issues",
    "retro_should_notify": true,
    "retro_notify_message": null,
    "build_type": "current",
    "current_status": "maintenance_scheduled",
    "current_severity": "problem_detected",
    "start_at": "2026-01-01T00:00:00Z",
    "closed_at": "2026-01-01T00:00:00Z",
    "created_at": "2026-01-01T00:00:00Z",
    "updated_at": "2026-01-01T00:00:00Z",
    "updates": [
      {
        "id": "Iu6tMn",
        "incident_id": "In3pKr",
        "message": "We have identified the cause and are rolling back.",
        "status": "maintenance_scheduled",
        "severity": "problem_detected",
        "start_at": "2026-01-01T00:00:00Z",
        "should_notify": true,
        "notified_at": "2026-01-01T00:00:00Z",
        "created_at": "2026-01-01T00:00:00Z",
        "updated_at": "2026-01-01T00:00:00Z"
      }
    ],
    "links": {
      "web": "https://app.honeybadger.io/projects/Xk9mZp"
    }
  },
  "meta": {
    "request_id": "6f1c2b0e-8d4a-4f6e-9b2a-3c5d7e9f1a2b"
  }
}

Response schema28

Field	Type	Description
data required	object	An incident on a status page. An incident is a container for a thread of updates: the prose lives on each update, and current_status, current_severity and closed_at are derived from them and are never writable.
data.id required	string
data.status_page_id required	string	ID of the status page.
data.title required	string	Incident title.
data.retro_should_notify required	boolean	For a retroactive incident, whether to announce it once on the status page's connected accounts.
data.retro_notify_message required	string | null	The announcement sent when retro_should_notify is true.
data.build_type required	string	How the incident was opened. current is happening now, retroactive records something already over, scheduled_maintenance is planned. Only a scheduled_maintenance incident may have updates starting in the future. Allowed values: current, retroactive, scheduled_maintenance.
data.current_status	string | null	Status of the update in effect now. Derived from the updates. An incident's status. Allowed values: maintenance_scheduled, in_maintenance, maintenance_complete, investigating, identified, resolving, monitoring, resolved.
data.current_severity	string | null	Severity of the update in effect now. Derived from the updates. An incident's severity. Allowed values: problem_detected, degraded_performance, partial_outage, outage, operational.
data.start_at	date-time | null	When the incident starts. Derived from the updates.
data.closed_at	date-time | null	When the incident closed, or null while it is open. Derived from the updates: it is set once an update reaches resolved or maintenance_complete.
data.created_at	date-time	When the incident was created.
data.updated_at	date-time	When the incident was last updated.
data.updates required	array<object>	The incident's thread, newest first. Always at least one update.
data.updates[].id required	string
data.updates[].incident_id required	string	ID of the incident.
data.updates[].message	string | null	The update's prose.
data.updates[].status required	string	An incident's status. Allowed values: maintenance_scheduled, in_maintenance, maintenance_complete, investigating, identified, resolving, monitoring, resolved.
data.updates[].severity required	string	An incident's severity. Allowed values: problem_detected, degraded_performance, partial_outage, outage, operational.
data.updates[].start_at	date-time	When the update takes effect. A future time schedules it.
data.updates[].should_notify	boolean | null	Whether the update is announced on the status page's connected accounts.
data.updates[].notified_at	date-time | null	When the announcement was sent.
data.updates[].created_at	date-time	When the update was posted.
data.updates[].updated_at	date-time	When the update was last changed.
data.links required	object	Links into the Honeybadger web UI.
data.links.web required	uri	The resource's page in the Honeybadger web UI, as an absolute URL. Resources without a page, such as outages and deploys, don't have links. For a project provisioned through Heroku, error, notice and comment links go through Heroku's single sign-on.
meta	object
meta.request_id	string	Unique identifier for the request, for correlating with support.

Errors

4

401 Unauthorized

The credential is missing, invalid, expired or revoked (unauthorized), or was sent in a way v3 doesn’t accept (see the examples).

Example payload: unauthorized (Missing, malformed, expired or revoked credential)

{
  "error": {
    "code": "unauthorized",
    "message": "Access denied"
  },
  "meta": {
    "request_id": "abc123"
  }
}

Example payload: unsupported_auth_scheme (Sent as HTTP basic, which v3 does not accept)

{
  "error": {
    "code": "unsupported_auth_scheme",
    "message": "Send the credential as `Authorization: Bearer <token>`; v3 does not accept HTTP basic"
  },
  "meta": {
    "request_id": "abc123"
  }
}

Example payload: credential_in_query (Sent as the `auth_token` query parameter)

{
  "error": {
    "code": "credential_in_query",
    "message": "Credentials must be sent in the Authorization header"
  },
  "meta": {
    "request_id": "abc123"
  }
}

Response schema6

Field	Type	Description
error required	object
error.code required	string	Machine-readable code. Branch on this, not the message. Allowed values: unauthorized, unsupported_auth_scheme, credential_in_query, access_denied, insufficient_scope, requires_user_token, project_restricted, account_inactive, account_parked, feature_unavailable, not_found, validation_error, delete_failed, limit_reached, rate_limit_exceeded, concurrent_request, streams_provisioning, ingestion_key_not_accepted, maintenance_mode, invalid_parameter, forbidden_attributes, service_unavailable, ambiguous_account, fault_merged.
error.message required	string	Human-readable explanation.
error.details	array<object> | object	A list of {field, message} on validation_error and invalid_parameter, and on feature_unavailable or limit_reached when one field caused the refusal; {required_scope, token_scopes} on insufficient_scope; {merged_into, location} on fault_merged. Absent when there's nothing to add.
meta	object
meta.request_id	string	Unique identifier for the request, for correlating with support.

403 Forbidden

The credential isn’t allowed to do this. error.code says why. An account or project the credential doesn’t cover is 404 not_found, not 403.

Example payload: access_denied (The credential isn't allowed to do this to this record)

{
  "error": {
    "code": "access_denied",
    "message": "Access denied"
  },
  "meta": {
    "request_id": "abc123"
  }
}

Example payload: insufficient_scope (The credential lacks the permission this endpoint requires)

{
  "error": {
    "code": "insufficient_scope",
    "message": "Insufficient scope",
    "details": {
      "required_scope": "faults:write",
      "token_scopes": [
        "faults:read",
        "insights:read"
      ]
    }
  },
  "meta": {
    "request_id": "abc123"
  }
}

Example payload: requires_user_token (The endpoint records who acted, and an account token has nobody)

{
  "error": {
    "code": "requires_user_token",
    "message": "This endpoint records the person who acted, so it requires a user credential rather than an account token"
  },
  "meta": {
    "request_id": "abc123"
  }
}

Example payload: project_restricted (A project-restricted credential cannot create a project)

{
  "error": {
    "code": "project_restricted",
    "message": "Project-restricted tokens cannot create projects"
  },
  "meta": {
    "request_id": "abc123"
  }
}

Response schema6

Field	Type	Description
error required	object
error.code required	string	Machine-readable code. Branch on this, not the message. Allowed values: unauthorized, unsupported_auth_scheme, credential_in_query, access_denied, insufficient_scope, requires_user_token, project_restricted, account_inactive, account_parked, feature_unavailable, not_found, validation_error, delete_failed, limit_reached, rate_limit_exceeded, concurrent_request, streams_provisioning, ingestion_key_not_accepted, maintenance_mode, invalid_parameter, forbidden_attributes, service_unavailable, ambiguous_account, fault_merged.
error.message required	string	Human-readable explanation.
error.details	array<object> | object	A list of {field, message} on validation_error and invalid_parameter, and on feature_unavailable or limit_reached when one field caused the refusal; {required_scope, token_scopes} on insufficient_scope; {merged_into, location} on fault_merged. Absent when there's nothing to add.
meta	object
meta.request_id	string	Unique identifier for the request, for correlating with support.

404 Not Found

Resource not found

Example payload

{
  "error": {
    "code": "not_found",
    "message": "Resource not found"
  },
  "meta": {
    "request_id": "abc123"
  }
}

Response schema6

Field	Type	Description
error required	object
error.code required	string	Machine-readable code. Branch on this, not the message. Allowed values: unauthorized, unsupported_auth_scheme, credential_in_query, access_denied, insufficient_scope, requires_user_token, project_restricted, account_inactive, account_parked, feature_unavailable, not_found, validation_error, delete_failed, limit_reached, rate_limit_exceeded, concurrent_request, streams_provisioning, ingestion_key_not_accepted, maintenance_mode, invalid_parameter, forbidden_attributes, service_unavailable, ambiguous_account, fault_merged.
error.message required	string	Human-readable explanation.
error.details	array<object> | object	A list of {field, message} on validation_error and invalid_parameter, and on feature_unavailable or limit_reached when one field caused the refusal; {required_scope, token_scopes} on insufficient_scope; {merged_into, location} on fault_merged. Absent when there's nothing to add.
meta	object
meta.request_id	string	Unique identifier for the request, for correlating with support.

422 Unprocessable Content

Validation error

Example payload

{
  "error": {
    "code": "validation_error",
    "message": "Name can't be blank",
    "details": [
      {
        "field": "name",
        "message": "can't be blank"
      }
    ]
  },
  "meta": {
    "request_id": "abc123"
  }
}

Response schema6

Field	Type	Description
error required	object
error.code required	string	Machine-readable code. Branch on this, not the message. Allowed values: unauthorized, unsupported_auth_scheme, credential_in_query, access_denied, insufficient_scope, requires_user_token, project_restricted, account_inactive, account_parked, feature_unavailable, not_found, validation_error, delete_failed, limit_reached, rate_limit_exceeded, concurrent_request, streams_provisioning, ingestion_key_not_accepted, maintenance_mode, invalid_parameter, forbidden_attributes, service_unavailable, ambiguous_account, fault_merged.
error.message required	string	Human-readable explanation.
error.details	array<object> | object	A list of {field, message} on validation_error and invalid_parameter, and on feature_unavailable or limit_reached when one field caused the refusal; {required_scope, token_scopes} on insufficient_scope; {merged_into, location} on fault_merged. Absent when there's nothing to add.
meta	object
meta.request_id	string	Unique identifier for the request, for correlating with support.