# Honk docs: sending events

> Sending to Honk takes one endpoint, and this page covers all of it. The libraries wrap the same request with retries and helpers.

Source: https://honk-me.app/docs

## Quickstart

1. **Get an account.** Honk is invite-only for now. Request access; the invitation arrives by email and you sign in with a 6-digit code.
2. **Create a project and a key.** In the web app, open Projects, create one, then open its Keys tab and create an ingestion key. The key (honk_…) is shown only once, so save it somewhere safe right away.
3. **Send an event.** Post JSON with the key as a bearer token. A 202 means Honk has saved the event.
4. **Get the push.** Install Honk for iPhone or enable notifications in the web app under Devices, then send a test with Honk me.

```sh
curl -sS https://honk-me.app/v1/messages \
  -H "Authorization: Bearer $HONK_KEY" \
  -H "Idempotency-Key: backup-$(date +%Y%m%d)" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Backup failed",
    "message": "pg_dump exited with 1",
    "severity": "long",
    "group_key": "db/backup",
    "event_type": "problem"
  }'
# → 202 {"id":"msg_…","status":"accepted","duplicate":false,"received_at":"…"}
```

## The request

`POST https://honk-me.app/v1/messages` with `Content-Type: application/json` and `Authorization: Bearer <ingestion key>`. Unknown fields are rejected with `422`. The body can be up to 16 KiB.

| Field | Notes |
|---|---|
| `message` | Required. 1 to 8192 bytes of UTF-8; line breaks are kept. |
| `title` | One line, up to 160 characters. Defaults to the first line of the message. |
| `severity` | `info`, `success`, `warning`, `error`, `critical`, or the horn names `light`, `beep`, `loud`, `long`, `blast`. Defaults to `info`. |
| `priority` | `low`, `normal`, `high` or `urgent`. Defaults to `normal`. `urgent` needs a key that allows it. |
| `group_key` | Up to 128 characters. Events with the same key (and project, environment, source, channel) form one group. |
| `event_type` | `event`, `problem` or `recovery`. A recovery needs a `group_key` and closes the open problem. |
| `source, environment, channel` | Up to 64, 32 and 64 characters. Defaults: `api`, `default` and `general`. |
| `category` | `infrastructure`, `security`, `backups`, `deployments`, `payments`, `customers`, `sales`, `automation`, `personal` or `other`. |
| `url` | An `https://` link shown as “Open link”, opened only when you tap it. |
| `image_url` | An `https://` image the server fetches and shows with the notification (up to 1 MB on Free, 5 MB on Pro and Team). |
| `actions` | Up to 3 buttons in display order (the first is the main one), for example `[{"title": "Reply by email", "url": "mailto:emily@example.com"}, {"title": "Call", "url": "tel:+12025550147"}]`. A title has 1 to 40 characters; a URL starts with `https://`, `mailto:`, `tel:` or `sms:` and opens only when you tap its button. |
| `metadata` | Up to 16 keys with string, number or boolean values. Rules can match on them. |
| `occurred_at` | When it happened at the source, as an RFC 3339 timestamp. |
| `ttl_seconds` | How long a push can still be delivered, from 60 to 86400 seconds. Defaults to 3600. |
| `source_sequence` | An increasing number per source, so a delayed recovery never closes a newer problem. |

## Responses

| Status | Meaning |
|---|---|
| 202 | Stored. `{ "id", "status": "accepted", "duplicate", "received_at" }`. It doesn’t mean the event was pushed or read. |
| 401 | `invalid_key`: the key is wrong or revoked. |
| 403 | `priority_not_allowed`, `project_suspended` or `workspace_suspended`. |
| 409 | `idempotency_conflict`: the same key was used with a different payload. |
| 413, 415, 422 | Too large, not JSON, or invalid: `error.fields` lists every problem. |
| 429 | `quota_exceeded` (the daily message limit) or `rate_limited`, with `Retry-After`. |
| 503 | Honk can’t confirm right now that the event was saved safely. Retry with the same key after `Retry-After`. |

## Retrying safely

Send an `Idempotency-Key` header (up to 128 printable ASCII characters) that stays the same for the same event, for example `deploy-4812-finished`. Within 24 hours, the same key with the same payload returns the original id with `duplicate: true`; the same key with a different payload is a `409`. Retry only network errors, `429` and `5xx`, and honor `Retry-After`. The official libraries do all of this for you.

## Severity and the Honk scale

The horn names are aliases. Honk stores the standard value, so `"loud"` and `"warning"` mean the same thing, including for idempotency. `error` and `critical` are always pushed at High priority or above.

| Canonical | Alias | Name |
|---|---|---|
| `info` | `light` | Light honk |
| `success` | `beep` | Beep-beep |
| `warning` | `loud` | Loud honk |
| `error` | `long` | Long honk |
| `critical` | `blast` | Blast |

## Reference

- OpenAPI 3.1: https://honk-me.app/docs/openapi.yaml
- Libraries: https://github.com/honk-me/honk-node, https://github.com/honk-me/honk-php, https://github.com/honk-me/honk-go, https://github.com/honk-me/honk-swift, https://github.com/honk-me/honk-kotlin, https://github.com/honk-me/honk-rust, https://github.com/honk-me/honk-n8n

Only the API for sending events is public. The rest serves the Honk apps and may change between versions.