incidents.upsert

Create or update an incident.

Facts


Method	`POST https://yourinstance.getdx.net/api/incidents.upsert`

Arguments

Required arguments

Name	Type	Description
`token`	`Token`	Auth token passed as an HTTP header.
`reference_id`	`Text`	Unique identifier for the incident to support idempotent updates. Example: `36b1f37a-e60f-4ccd-b0c4-878a6d1175fe`
`started_at`	`ISO-8601`	Timestamp for when the incident started. Example: `2024-01-01T11:22:33`

Optional arguments

Name	Type	Description
`name`	`Text`	The name of the incident. Example: `Invalid argument broke settings page`
`priority`	`Text`	Priority assigned to the incident. Example: `p1`
`source_url`	`Text`	URL to the incident in your incident management system. Example: `https://app.opsgenie.com/incidents/123`
`resolved_at`	`ISO-8601`	Timestamp for when the incident was resolved. Example: `2024-01-01T11:22:33`
`services`	`Array<Object>`	Array of services related to this incident. The `name` field is optional. How this field is applied depends on whether the key is present; see Metadata and services.
`metadata`	`JSON`	Additional key-value data you define about the incident. How this field is applied depends on whether the key is present; see Metadata and services

Metadata and services

For metadata and services, behavior depends on whether each key appears in the request body.

Key omitted — Existing metadata or services on the incident are left unchanged.
Key present with [] or null — If the incident already had services or metadata, that stored data is removed for the field you cleared.
Key present with new data — Whatever you send replaces the stored value for that field. This is a full replace, not a merge. For example, if incident A is linked to Service A and you send another request for the same reference_id with services listing only Service B, Service A is removed and only Service B remains.

Example request

This is a typical request:

curl -X POST https://yourinstance.getdx.net/api/incidents.upsert \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer xxxx-xxxxxxxxx-xxxx' \
  -H 'Content-Type: application/json' \
  --data '{
  "reference_id": "36b1f37a-e60f-4ccd-b0c4-878a6d1175fe",
  "name": "Invalid argument broke settings page",
  "priority": "p1",
  "source_url": "https://app.opsgenie.com/incidents/123",
  "services" : [
    {
      "name": "Payments",
      "identifier": "payments-service"
    },
    {
      "identifier": "auth-service"
    }
  ],
  "started_at": "2024-01-01T11:22:33",
  "resolved_at": null
}'

This table lists the expected errors that this method could return. However, other errors can be returned in the case where the service is down or other unexpected factors affect processing. Callers should always check the value of the ok param in the response.

Error Code	Description
`not_authed`	This error occurs if the API request does not include a valid API key for authentication.
`invalid_arguments`	The provided arguments are invalid. Ensure you’re passing a `reference_id`.
`invalid_json`	The JSON body of the request could not be parsed. This usually indicates a syntax error.
`invalid_timestamp`	The `started_at` or `resolved_at` format was not a readable ISO-8601 date format.
`metadata_invalid`	The metadata was not able to be processed. Metadata must be an object and keys may include letters, numbers, dashes and underscores.