Declare an incident · On-Call API

POST/api/v1/incidents

Declares an incident. It starts investigating, with the caller as commander unless commander_id names someone else, who must be a member who can respond to alerts.

To record an incident that already ended, send both started_at and resolved_at: it is stored resolved, with those times.

Permission (API-key scope): oncall:incident:write.

Authorization

Any one of:

bearerAuth (oncall:incident:write)
apiKeyHeader (oncall:incident:write)

Request body required

Content type: application/json

Type: IncidentCreate

title string required
Not blank.
Max length: 200
severity IncidentSeverity required
One of: none minor major critical
summary string
commander_id string
Defaults to the caller.
started_at string (date-time)
With resolved_at: record an incident that already ended.
resolved_at string (date-time)
With started_at: record an incident that already ended. Must be after started_at and not in the future.

Responses

`201`

The incident.

Content type: application/json

Type: object

data Incident required
Show Incident properties
- id string required
- org_id string
- number integer required
  Sequential number within the organization.
- title string required
- summary string
- severity IncidentSeverity required
  One of: none minor major critical
- status IncidentStatus required
  One of: investigating identified monitoring resolved
- commander_id string
- started_at string (date-time) required
- identified_at string (date-time)
- resolved_at string (date-time)
- timeline array of IncidentTimelineEntry
  The timeline entries, oldest first. Only in the answer of Get an incident.
  Show IncidentTimelineEntry properties
  - id string
  - incident_id string
  - author_id string
  - status string
    The incident's status when the entry was written.
  - message string
  - created_at string (date-time)
- created_at string (date-time)
- updated_at string (date-time)
- version integer
  Goes up by one on every edit of the title, summary, severity or commander (not on acknowledge or resolve). Send it with an update to refuse the edit if someone else changed the incident first.
success boolean required
Value: true

`400`

The body is not JSON (INVALID_BODY); title or severity is missing, title is blank or longer than 200 characters, severity is not one of the four values, or the past times are not a start before an end that has already happened (VALIDATION_FAILED).

Content type: application/json

Type: ValidationError

error object required
- code string required
  Value: VALIDATION_FAILED
- message string required
- request_id string
  The request's X-Request-ID. Quote it to support.
- details array of object required
  - field string
  - message string

`401`

No API key was sent, or it is unknown, revoked or expired (UNAUTHORIZED).

Content type: application/json

Type: Error

error object required
- code string required
  Machine-readable code. Branch on this.
- message string required
  Human-readable explanation.
- request_id string
  The request's X-Request-ID. Quote it to support.

`403`

The key lacks the scope this endpoint needs (FORBIDDEN).

Content type: application/json

Type: Error

error object required
- code string required
  Machine-readable code. Branch on this.
- message string required
  Human-readable explanation.
- request_id string
  The request's X-Request-ID. Quote it to support.

`404`

commander_id is not a member of the organization (NOT_A_MEMBER).

Content type: application/json

Type: Error

error object required
- code string required
  Machine-readable code. Branch on this.
- message string required
  Human-readable explanation.
- request_id string
  The request's X-Request-ID. Quote it to support.

`422`

The person cannot respond to alerts: they do not hold oncall:alert:respond (CANNOT_RESPOND).

Content type: application/json

Type: Error

error object required
- code string required
  Machine-readable code. Branch on this.
- message string required
  Human-readable explanation.
- request_id string
  The request's X-Request-ID. Quote it to support.

`429`

Too many requests (RATE_LIMITED). Wait Retry-After seconds.

Headers

Retry-After integer
Seconds to wait.

Content type: application/json

Type: Error

error object required
- code string required
  Machine-readable code. Branch on this.
- message string required
  Human-readable explanation.
- request_id string
  The request's X-Request-ID. Quote it to support.

`500`

Something went wrong on EvoHub's side (INTERNAL_ERROR). Retry later.

Content type: application/json

Type: Error

error object required
- code string required
  Machine-readable code. Branch on this.
- message string required
  Human-readable explanation.
- request_id string
  The request's X-Request-ID. Quote it to support.

`503`

Whether the person may be paged could not be checked right now; nothing was changed (MEMBER_CHECK_UNAVAILABLE). Retry shortly.

Content type: application/json

Type: Error

error object required
- code string required
  Machine-readable code. Branch on this.
- message string required
  Human-readable explanation.
- request_id string
  The request's X-Request-ID. Quote it to support.

Example request

curl -X POST 'https://evohub.io/api/v1/incidents' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <TOKEN>' \
  -d '{
  "title": "Checkout payments failing",
  "summary": "Card payments time out for about 30% of customers.",
  "severity": "major"
}'