Skip to content
GuvDocs

Incidents

View as Markdown

Incidents opened by monitoring and the AI ops team.

Operation Method and path
List incidents GET /v1/incidents
Open an incident POST /v1/incidents
Get an incident GET /v1/incidents/{incident_id}
Update an incident PATCH /v1/incidents/{incident_id}
Incident timeline GET /v1/incidents/{incident_id}/events
Add to the timeline POST /v1/incidents/{incident_id}/events

List incidents

Section titled “List incidents”
GET /v1/incidents

Platform admins see everything; customers see customer-visible incidents for their projects.

  • Operation: listIncidents
  • Scopes: incidents:read
  • Paginated: ?limit= and ?cursor=

Parameters

Name In Type Description
status query IncidentStatus
project query string
severity query IncidentSeverity

Responses

Status Meaning Body
200 OK A page of Incident objects. IncidentList

Errors: 400, 401, 403, 429, 500, as problem+json with a stable code.

Example

Terminal window
curl https://api.guv.dev/v1/incidents \
  -H "Authorization: Bearer $GUV_TOKEN"

Example response

{
  "data": [
    {
      "id": "inc_01jbx2m9k7q4r8t5v6w3y0z1pr",
      "scope": "platform",
      "title": "api will run out of memory in about 6 hours",
      "summary": "string",
      "severity": "sev1",
      "status": "open",
      "source": "alert",
      "cell": "lon1-a",
      "workspace_id": "string",
      "project_id": "string",
      "affected": [
        {
          "type": "service",
          "id": "svc_01jbx2m9k7q4r8t5v6w3y0z1sv",
          "name": "web",
          "url": "/v1/projects/primecarers/services/web"
        }
      ],
      "opened_by": {
        "type": "agent",
        "id": "tok_01jbx2m9k7q4r8t5v6w3y0z1tk",
        "display": "Stewart Webb via agent claude-code-on-stewart-laptop",
        "via_agent": {
          "id": "tok_01jbx2m9k7q4r8t5v6w3y0z1tk",
          "name": "claude-code-on-stewart-laptop"
        },
        "on_behalf_of": {
          "id": "usr_01jbx2m9k7q4r8t5v6w3y0z1us",
          "display": "Stewart Webb"
        }
      },
      "assigned_agent": "sentinel",
      "customer_visible": false,
      "opened_at": "2026-10-22T13:05:00Z",
      "mitigated_at": "2026-10-22T13:05:00Z",
      "resolved_at": "2026-10-22T13:05:00Z",
      "postmortem_url": "https://guv.dev/"
    }
  ],
  "next_cursor": "string",
  "has_more": false
}

Open an incident

Section titled “Open an incident”
POST /v1/incidents
  • Operation: openIncident
  • Scopes: incidents:write
  • Idempotency-Key: required

Request body (application/json, required): IncidentCreate

Field Type Description
scope platform, project Default platform.
title * string
summary string
severity * IncidentSeverity
source * alert, probe, detector, customer_report, agent, human
cell string
project_id string
affected array of ResourceRef
customer_visible boolean Default false.
dedupe_key string Incidents with the same open dedupe key are merged.

Responses

Status Meaning Body
201 Created Created. Incident

Errors: 400, 401, 403, 409, 422, 429, 500, as problem+json with a stable code.

Example

Terminal window
curl -X POST https://api.guv.dev/v1/incidents \
  -H "Authorization: Bearer $GUV_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "scope": "platform",
  "title": "string",
  "summary": "string",
  "severity": "sev1",
  "source": "alert",
  "cell": "string",
  "project_id": "string",
  "affected": [
    {
      "type": "service",
      "id": "svc_01jbx2m9k7q4r8t5v6w3y0z1sv",
      "name": "web",
      "url": "/v1/projects/primecarers/services/web"
    }
  ],
  "customer_visible": false,
  "dedupe_key": "string"
}'

Example response

{
  "id": "inc_01jbx2m9k7q4r8t5v6w3y0z1pr",
  "scope": "platform",
  "title": "api will run out of memory in about 6 hours",
  "summary": "string",
  "severity": "sev1",
  "status": "open",
  "source": "alert",
  "cell": "lon1-a",
  "workspace_id": "string",
  "project_id": "string",
  "affected": [
    {
      "type": "service",
      "id": "svc_01jbx2m9k7q4r8t5v6w3y0z1sv",
      "name": "web",
      "url": "/v1/projects/primecarers/services/web"
    }
  ],
  "opened_by": {
    "type": "agent",
    "id": "tok_01jbx2m9k7q4r8t5v6w3y0z1tk",
    "display": "Stewart Webb via agent claude-code-on-stewart-laptop",
    "via_agent": {
      "id": "tok_01jbx2m9k7q4r8t5v6w3y0z1tk",
      "name": "claude-code-on-stewart-laptop"
    },
    "on_behalf_of": {
      "id": "usr_01jbx2m9k7q4r8t5v6w3y0z1us",
      "display": "Stewart Webb"
    }
  },
  "assigned_agent": "sentinel",
  "customer_visible": false,
  "opened_at": "2026-10-22T13:05:00Z",
  "mitigated_at": "2026-10-22T13:05:00Z",
  "resolved_at": "2026-10-22T13:05:00Z",
  "postmortem_url": "https://guv.dev/"
}

Get an incident

Section titled “Get an incident”
GET /v1/incidents/{incident_id}
  • Operation: getIncident
  • Scopes: incidents:read

Parameters

Name In Type Description
incident_id * path string

Responses

Status Meaning Body
200 OK OK. Incident

Errors: 400, 401, 403, 404, 429, 500, as problem+json with a stable code.

Example

Terminal window
curl https://api.guv.dev/v1/incidents/inc_01jbx2m9k7q4r8t5v6w3y0z1pr \
  -H "Authorization: Bearer $GUV_TOKEN"

Example response

{
  "id": "inc_01jbx2m9k7q4r8t5v6w3y0z1pr",
  "scope": "platform",
  "title": "api will run out of memory in about 6 hours",
  "summary": "string",
  "severity": "sev1",
  "status": "open",
  "source": "alert",
  "cell": "lon1-a",
  "workspace_id": "string",
  "project_id": "string",
  "affected": [
    {
      "type": "service",
      "id": "svc_01jbx2m9k7q4r8t5v6w3y0z1sv",
      "name": "web",
      "url": "/v1/projects/primecarers/services/web"
    }
  ],
  "opened_by": {
    "type": "agent",
    "id": "tok_01jbx2m9k7q4r8t5v6w3y0z1tk",
    "display": "Stewart Webb via agent claude-code-on-stewart-laptop",
    "via_agent": {
      "id": "tok_01jbx2m9k7q4r8t5v6w3y0z1tk",
      "name": "claude-code-on-stewart-laptop"
    },
    "on_behalf_of": {
      "id": "usr_01jbx2m9k7q4r8t5v6w3y0z1us",
      "display": "Stewart Webb"
    }
  },
  "assigned_agent": "sentinel",
  "customer_visible": false,
  "opened_at": "2026-10-22T13:05:00Z",
  "mitigated_at": "2026-10-22T13:05:00Z",
  "resolved_at": "2026-10-22T13:05:00Z",
  "postmortem_url": "https://guv.dev/"
}

Update an incident

Section titled “Update an incident”
PATCH /v1/incidents/{incident_id}
  • Operation: updateIncident
  • Scopes: incidents:write
  • Idempotency-Key: required
  • Concurrency: send the ETag you read as If-Match

Parameters

Name In Type Description
incident_id * path string

Request body (application/json, required): IncidentUpdate

Field Type Description
title string
summary string
severity IncidentSeverity
status IncidentStatus
assigned_agent string or null
customer_visible boolean
postmortem_url string or null

Responses

Status Meaning Body
200 OK OK. Incident

Errors: 400, 401, 403, 404, 409, 412, 422, 429, 500, as problem+json with a stable code.

Example

Terminal window
curl -X PATCH https://api.guv.dev/v1/incidents/inc_01jbx2m9k7q4r8t5v6w3y0z1pr \
  -H "Authorization: Bearer $GUV_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "title": "string",
  "summary": "string",
  "severity": "sev1",
  "status": "open",
  "assigned_agent": "string",
  "customer_visible": false,
  "postmortem_url": "string"
}'

Example response

{
  "id": "inc_01jbx2m9k7q4r8t5v6w3y0z1pr",
  "scope": "platform",
  "title": "api will run out of memory in about 6 hours",
  "summary": "string",
  "severity": "sev1",
  "status": "open",
  "source": "alert",
  "cell": "lon1-a",
  "workspace_id": "string",
  "project_id": "string",
  "affected": [
    {
      "type": "service",
      "id": "svc_01jbx2m9k7q4r8t5v6w3y0z1sv",
      "name": "web",
      "url": "/v1/projects/primecarers/services/web"
    }
  ],
  "opened_by": {
    "type": "agent",
    "id": "tok_01jbx2m9k7q4r8t5v6w3y0z1tk",
    "display": "Stewart Webb via agent claude-code-on-stewart-laptop",
    "via_agent": {
      "id": "tok_01jbx2m9k7q4r8t5v6w3y0z1tk",
      "name": "claude-code-on-stewart-laptop"
    },
    "on_behalf_of": {
      "id": "usr_01jbx2m9k7q4r8t5v6w3y0z1us",
      "display": "Stewart Webb"
    }
  },
  "assigned_agent": "sentinel",
  "customer_visible": false,
  "opened_at": "2026-10-22T13:05:00Z",
  "mitigated_at": "2026-10-22T13:05:00Z",
  "resolved_at": "2026-10-22T13:05:00Z",
  "postmortem_url": "https://guv.dev/"
}

Incident timeline

Section titled “Incident timeline”
GET /v1/incidents/{incident_id}/events
  • Operation: listIncidentEvents
  • Scopes: incidents:read
  • Paginated: ?limit= and ?cursor=

Parameters

Name In Type Description
incident_id * path string

Responses

Status Meaning Body
200 OK A page of IncidentEvent objects. IncidentEventList

Errors: 400, 401, 403, 404, 429, 500, as problem+json with a stable code.

Example

Terminal window
curl https://api.guv.dev/v1/incidents/inc_01jbx2m9k7q4r8t5v6w3y0z1pr/events \
  -H "Authorization: Bearer $GUV_TOKEN"

Example response

{
  "data": [
    {
      "id": "string",
      "incident_id": "string",
      "at": "2026-10-22T13:05:00Z",
      "actor": {
        "type": "agent",
        "id": "tok_01jbx2m9k7q4r8t5v6w3y0z1tk",
        "display": "Stewart Webb via agent claude-code-on-stewart-laptop",
        "via_agent": {
          "id": "tok_01jbx2m9k7q4r8t5v6w3y0z1tk",
          "name": "claude-code-on-stewart-laptop"
        },
        "on_behalf_of": {
          "id": "usr_01jbx2m9k7q4r8t5v6w3y0z1us",
          "display": "Stewart Webb"
        }
      },
      "kind": "note",
      "message": "string",
      "data": {}
    }
  ],
  "next_cursor": "string",
  "has_more": false
}

Add to the timeline

Section titled “Add to the timeline”
POST /v1/incidents/{incident_id}/events
  • Operation: addIncidentEvent
  • Scopes: incidents:write
  • Idempotency-Key: required

Parameters

Name In Type Description
incident_id * path string

Request body (application/json, required): IncidentEventCreate

Field Type Description
kind * note, signal, tool_call, policy_decision, customer_notice
message * string
data object

Responses

Status Meaning Body
201 Created Created. IncidentEvent

Errors: 400, 401, 403, 404, 409, 422, 429, 500, as problem+json with a stable code.

Example

Terminal window
curl -X POST https://api.guv.dev/v1/incidents/inc_01jbx2m9k7q4r8t5v6w3y0z1pr/events \
  -H "Authorization: Bearer $GUV_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "kind": "note",
  "message": "string",
  "data": {}
}'

Example response

{
  "id": "string",
  "incident_id": "string",
  "at": "2026-10-22T13:05:00Z",
  "actor": {
    "type": "agent",
    "id": "tok_01jbx2m9k7q4r8t5v6w3y0z1tk",
    "display": "Stewart Webb via agent claude-code-on-stewart-laptop",
    "via_agent": {
      "id": "tok_01jbx2m9k7q4r8t5v6w3y0z1tk",
      "name": "claude-code-on-stewart-laptop"
    },
    "on_behalf_of": {
      "id": "usr_01jbx2m9k7q4r8t5v6w3y0z1us",
      "display": "Stewart Webb"
    }
  },
  "kind": "note",
  "message": "string",
  "data": {}
}