Docs

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

Quickstart

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.
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.

Send an event

Post JSON with the key as a bearer token. A 202 means Honk has saved the event.

Terminal

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":"…"}

Get the push

Install Honk for iPhone or enable notifications in the web app under Devices, then send a test with Honk me.

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.

Fields

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:[email protected]"}, {"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

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.

Light honk	`info` · `light`
Beep-beep	`success` · `beep`
Loud honk	`warning` · `loud`
Long honk	`error` · `long`
Blast	`critical` · `blast`

Concepts

Reference

The API for sending events, as an OpenAPI 3.1 document (openapi.yaml)
A plain-text map of these docs for coding assistants (llms.txt)
The libraries’ READMEs on GitHub: Node.js , PHP / Laravel , Go + CLI , Swift , Kotlin / Java , Rust , n8n

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