Sending alerts

Send signals through the API or a service integration.

Endpoints

Endpoint	Authentication	Use
`POST /v1/alerts`	`Authorization: Bearer ak_…`	Custom senders that can set an HTTP header.
`POST /v1/ingest/{token}`	Integration token in the URL (`ik_…`)	Monitoring products configured with a webhook URL.

An ingest URL is a credential. Anyone holding it can raise alerts for its service. Rotate the integration if the URL is exposed.

Your first alert

Create a service in the dashboard and copy the ingest URL shown for its default integration. The API-key example below uses /v1/alerts instead:

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",
    "body": "/var is filling. Growth is ~2%/hour.",
    "priority": "high"
  }'

The response carries the alert id:

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

Fields

Field	Required	Notes
`service_id`	API-key endpoint	Service receiving the signal. Integration URLs already identify their service.
`title`	trigger	Short alert summary.
`event_key`	resolve	Stable identifier for the condition. Trigger requests use the title when it is omitted.
`body`	no	Additional detail shown on the alert.
`priority`	no	`critical`, `high`, `medium`, `low`, `info`. Defaults to `high`.
`urgency`	no	`high` or `low` — see below.
`source`	no	Name of the sending system.
`action`	no	`trigger` (default) or `resolve`.

Priority and urgency

Priority classifies impact and controls sort order. Urgency controls delivery: high requests critical delivery, while low sends an ordinary notification.

If urgency is omitted, info uses low urgency and every other priority uses high urgency.

Deduplication

Signals with the same service and event_key fold into one open alert. Acked increments the dedupe count without paging again. A higher-priority duplicate upgrades the alert and pages at the new urgency.

Use a key that identifies the condition, such as disk-full:db-1. Do not include a timestamp unless each occurrence must open a separate alert.

If event_key is omitted, Acked uses the title as the key. Repeated titles on one service will deduplicate.

Resolving

When the condition clears, send the same key with action: "resolve". 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 an alert that is already closed succeeds without changing state.

Responses

The API-key endpoint returns 202 Accepted with an alert id. A direct response includes "deduped": true|false. If the core is unavailable, the edge queues the signal and returns {"ok":true,"alert_id":"…","buffered":true}.

A buffered response means the signal was accepted for asynchronous processing. Store the alert id for support and audit lookup.