# Hark

> Hark is an inbox on your phone for scripts and AI agents. Over a small JSON HTTP API at https://api.harkapp.io, code can send cards and notifications, ask the user a question and wait for the answer (buttons, forms or free text, often answered straight from the notification), show live progress, and ring full-screen alarms.

Use Hark when an agent needs a human: to approve a deploy, choose between options, fill in a value, or just be told something happened. The user answers with a tap on their phone and the answer comes back to the calling code.

Auth: send `Authorization: Bearer hk_...` on every request (or `X-Hark-Token`, or `?token=`). The user makes API keys in the Hark app under Settings > API keys. Never print or log the key.

Essentials:

- Send a card: `POST /api/messages` with `{"agent": "my-bot", "title": "Backup finished", "body": "412 GB in 38 minutes"}`. Optional: `state` (idle, running, waiting, ok, warn, error, info), `progress` (0 to 1), `priority` (min to max), `blocks`, `image`, `links`, `notify: false` for no notification. Returns the message with its `id`.
- Update a card in place: post again with the same `agent` and `key` (for progress and builds). Only sent fields change.
- Ask and block until answered: `POST /api/ask?wait=600` with `{"agent": "deploy", "title": "Ship v2.14?", "choices": ["Deploy", "Cancel"], "timeout": "10m"}`. The response is the message; read `request.status` (`open`, `answered`, `expired`, `cancelled`) and `request.response` (`choice` is the choice id, a slug of the label such as `deploy`; also `label`, `fields`, `text`, `via`).
- Forms: `fields: [{"name": "wake", "type": "time"}, {"name": "gym", "type": "toggle"}]` (types: text, textarea, number, select with options, toggle, date, time). Free text: `/api/ask` with only a `title`.
- Wait on an existing question: `GET /api/messages/{id}/wait?timeout=60`, looping while `request.status` is `open`. Or set a webhook on the agent: `PUT /api/agents/{id}` with `{"webhook": "https://...", "secret": "..."}`.
- Default answer on timeout: `"timeout": "10m", "on_expire": "cancel"` records that choice with `via: "timeout"`.
- Alarms and timers: `POST /api/alarms` with `{"in": "25m", "label": "Pomodoro"}` or `{"at": "07:30", "repeat": "weekdays", "label": "Wake up"}`. Times are in the user's time zone. They ring full screen on the phone.
- Chat: the user can type to an agent; read it with `GET /api/agents/{id}/inbox?after=0&wait=30`, reply by posting a card with the same `agent`.
- Files: `POST /api/files?name=shot.png` with raw bytes and a Content-Type; use the returned `url` as `image`. Or put a `data:image/png;base64,...` URL in `image`.
- Errors are `{"error": "..."}` with 400, 401, 403, 404, 409 (question no longer open), 413 or 429. Limits: 20 requests a second per key (bursts of 60), 25,000 new cards a month.

Python, one file, standard library only: `curl -O https://docs.harkapp.io/hark.py`, then `from hark import Hark; h = Hark(token="hk_...", agent="my-bot"); ans = h.ask("Ship?", choices=["Deploy", "Cancel"], wait=600)`. `ans` is the response or `None`.

## Docs

- [Full reference](https://docs.harkapp.io/llms-full.txt): every endpoint, field, event and limit in one Markdown file
- [Quick start](https://docs.harkapp.io/#quick-start): first card, first question and first timer with curl, PowerShell and Python
- [Messages](https://docs.harkapp.io/#messages-cards): card fields, listing, updating, seen and dismiss
- [Questions](https://docs.harkapp.io/#questions): choices, forms, deadlines, waiting for and answering questions
- [Webhooks](https://docs.harkapp.io/#webhooks): signed POSTs when the user answers or chats
- [Alarms and timers](https://docs.harkapp.io/#alarms-and-timers): times, repeats, snooze and stop
- [Live updates](https://docs.harkapp.io/#live-updates): WebSocket and server-sent events

## Optional

- [Python client](https://docs.harkapp.io/hark.py): one-file client for scripts and agents
- [Blocks](https://docs.harkapp.io/#blocks): metrics, status pills, logs, key/value lists and other rich content
- [Account and settings](https://docs.harkapp.io/#account-and-settings): API keys, time zone, usage
- [Errors and limits](https://docs.harkapp.io/#errors-and-limits): status codes and size limits