Alert API

Send, deduplicate, acknowledge, and resolve alerts through HTTP.

Choose an endpoint

Endpoint	Authentication	Use
`POST /v1/ingest/{token}`	Source credential in the URL	One sender that always targets the same service.
`POST /v1/alerts`	`Authorization: Bearer ak_…`	A trusted sender that selects a service ID.
`POST /v2/enqueue`	PagerDuty-compatible routing key in the body	An existing PagerDuty Events API v2 sender.

Use a source ingest URL for most monitoring products. Use an API key when one trusted system sends alerts to several services.

A source ingest URL is a credential. Store it as a secret and rotate the source if the URL is exposed.

Send an alert

Create a webhook source on the service and copy its ingest URL. Then send an Acked payload:

curl -X POST "<YOUR-INGEST-URL>" \
  -H "content-type: application/json" \
  -d '{
    "event_key": "disk-full:db-1",
    "title": "Disk 91% full on db-1",
    "body": "/var is filling at 2 percent per hour.",
    "priority": "high"
  }'

A successful request returns 202 Accepted with an alert ID.

{"ok":true,"alert_id":"01KX…","deduped":false,"resolved":false}

Alert fields

Field	Required	Meaning
`service_id`	API key endpoint	The service that receives the signal.
`title`	Trigger	A short alert summary.
`event_key`	Resolve	A stable identifier for the monitored condition.
`body`	No	Additional incident details.
`priority`	No	`critical`, `high`, `medium`, `low`, or `info`.
`urgency`	No	`high` or `low`.
`source`	No	The sending system name.
`action`	No	`trigger` or `resolve`.

Priority classifies impact and controls sort order. Urgency controls notification delivery. High urgency requests critical delivery.

When urgency is absent, Info uses low urgency and every other priority uses high urgency.

Send with an API key

Create an alert-ingest API key and include the target service ID.

curl -X POST https://api.acked.dev/v1/alerts \
  -H "Authorization: Bearer ak_YOUR_KEY" \
  -H "content-type: application/json" \
  -d '{
    "service_id": "svc_01hexample",
    "event_key": "disk-full:db-1",
    "title": "Disk 91% full on db-1",
    "priority": "high"
  }'

See API keys for access levels and credential handling.

Deduplicate repeat signals

Signals with the same service and event key join one open alert. Acked increases the duplicate count without paging again.

A higher-priority repeat signal raises the existing alert priority and pages at the new urgency.

If the event key is absent, the service can use the title as a fallback. Provide an explicit key to prevent unrelated alerts with the same title from merging.

Do not include a timestamp in the event key unless every occurrence must open a separate alert.

Resolve with a recovery signal

Send the original event key with action: "resolve" when the condition clears. A resolve request does not require a title.

curl -X POST https://api.acked.dev/v1/alerts \
  -H "Authorization: Bearer ak_YOUR_KEY" \
  -H "content-type: application/json" \
  -d '{
    "service_id": "svc_01hexample",
    "event_key": "disk-full:db-1",
    "action": "resolve"
  }'

Resolving a closed or unknown condition succeeds without opening an alert.

Acknowledge or resolve by alert ID

An alert-ingest API key can call these idempotent routes:

PUT /v1/alerts/{alert_id}/ack
PUT /v1/alerts/{alert_id}/resolve

Repeated requests return the current result without repeating the state change.

Handle responses

Status	Meaning
`202`	Acked accepted the signal. A buffered response will be processed asynchronously.
`400`	The request is malformed. Read the response error and correct the payload.
`401`	The credential is invalid or revoked.
`403`	The credential does not permit the operation.
`404`	The requested service or alert is unavailable to the credential.

A response with "buffered":true means the edge accepted the signal for later processing. Store the alert ID for audit and support. Do not resend only because the response is buffered.

Send vendor payloads

The examples on this page use Acked's native JSON format. For a monitoring tool with its own payload format, use its supported adapter or a templated source. See Connect sources.