Post an Incident

Raise an incident from any script or system. Oppex routes it to the service you name and pages that service's on-call responders, exactly as it would for an alert from a monitoring tool.

Before you start

You need:

• An API key, sent in the X-API-KEY header.
• The integration key of the service the incident is for. Open the service and look under Integration Details. You can leave it out if your workspace uses routing rules to pick the service.

Request

POST https://api.oppex.ai/api/v1/incident/post

curl -X POST "https://api.oppex.ai/api/v1/incident/post" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: <your-api-key>" \
  -d '{
        "title": "Deploy failed on prod",
        "serviceKey": "<integration-key>",
        "severity": 2,
        "source": "GitHub Actions",
        "externalID": "deploy-run-58213",
        "detailsJSON": "{\"step\": \"3/5\", \"exitCode\": 1}"
      }'

Request body fields

Field	Required	Description
title	Yes	Short description, shown in notifications and the incident list.
serviceKey	Yes, unless routing rules pick the service	The integration key of the service to raise the incident on.
severity	No	A number from 1 (most severe) to 5. Defaults to 1, unless a routing rule sets one.
priority	No	A number from 1 (highest) to 5. Defaults to 1.
source	No	What raised the incident, up to 255 characters. Defaults to Oppex API.
externalID	No	Your own identifier for this alert. You can use it later to update the RCA without knowing the Oppex incident id.
detailsJSON	No	Extra details to show on the incident, as a JSON-encoded string (not an object).
srcTimestamp	No	When the alert happened in your system, in epoch milliseconds. Defaults to now.
group	No	A grouping label. See "Does Oppex deduplicate incidents?" in the FAQ below.
tenant, component, type	No	Free-text labels stored on the incident.

severity and priority must be numbers. A text value such as "critical" makes the whole body invalid, and the request is rejected with 400.

Response

{
  "success": true,
  "statusCode": 200,
  "message": "Incident created successfully",
  "data": "8GFB1ADE-1M3C-KJ2QX7PA"
}

data is the new incident's id. Keep it: you need it to acknowledge or resolve the incident.

If a routing rule in your workspace tells Oppex to ignore matching incidents, the response is still 200, but message is Incident ignored by routing rule and data is null. No incident is created.

Errors

Errors return the same JSON shape with success: false, and the message says exactly what went wrong. Two exceptions: a 401 has a plain-text body, and a body that isn't valid JSON for this endpoint (for example, a text severity) gets a bare 400 with no message.

Status	When
400	title is missing. serviceKey doesn't match a service (Invalid Service Key) or belongs to another workspace. No serviceKey was sent and routing rules aren't enabled. The body isn't valid JSON, or severity or priority isn't a number.
401	The API key is missing, wrong or disabled. See API Keys.
429	Too many requests in a short time. Wait and retry.
500	Something went wrong in Oppex. Retry. If it keeps happening, contact support with the message.

FAQ

Does Oppex deduplicate incidents I post?

No. Every call creates a new incident with its own id, even if the title is the same. To keep a noisy source from paging people again and again, set up incident grouping for the service, so repeat alerts are grouped under the first incident.

How do I close the incident when my system recovers?

Call Resolve an Incident with the id from this call's response.

Which severity should I use?

Severity 1 is the most severe, and 5 is the least. The severity decides which escalation rules apply, if the service escalates by severity.