Request fields
Required fields, allowed values, and response conventions for POST /v1/incident.
Common fields
| Field | Required | Description |
|---|---|---|
client_key | Yes | Organisation API client key |
client_secret | Yes | Corresponding secret |
service_id | Yes | Permanent 32-character lowercase hexadecimal service ID |
action | No | trigger (default), acknowledge, or resolve |
source | No | Human-readable monitoring source, up to 100 characters |
idempotency_key | No | Exact-request retry identifier, 1–128 characters |
Trigger fields
| Field | Required | Description |
|---|---|---|
title | For trigger | Incident title, up to 255 characters; surrounding whitespace is trimmed |
body | No | Description, up to 10,000 characters |
severity | No | low, medium, high (default), or critical |
deduplication_key | No | Recurring alert identifier, up to 255 characters |
A service must be active to accept a new trigger. Explicit keys do not override a service’s disabled deduplication setting or extend its window.
Lifecycle fields
For acknowledge and resolve, provide at least one of:
| Field | Description |
|---|---|
incident_id | Public incident number, for example INC-1000000 |
deduplication_key | Find the latest open incident with this key on the selected service |
When both are supplied, incident_id identifies the incident. A title is not required for lifecycle updates.
The API has no unacknowledge, reopen, or delete action. Use the workspace for unacknowledging or reopening.
Idempotency header
You can send Idempotency-Key instead of the idempotency_key form field. When both are sent, the header takes precedence. See Deduplication and retries.
Unsupported fields and formats
Do not send organizations_id, assigned_users_id, or status; these are not accepted public request fields. Choose a supported action rather than attempting to set status directly.
Do not send query parameters, JSON bodies, or uploaded files. The server limits request bodies to 64 KiB; individual field limits still apply.
Response conventions
Success responses use success: true and a data object. The incident includes its public identifier, public service ID, title, severity, status, deduplication result, and timestamps.
Errors use a non-2xx HTTP status. Inspect the returned JSON message and any validation errors rather than assuming every response body represents success.