Hookable API documentation
Send an HTTP request to your Push URL and a push notification arrives on your phone. Copy your Push URL (recipient ID rcp_…) and sender API key (hk_…) from the My tab in the app.
Getting started
Every request needs an Authorization: Bearer hk_… header. The API key belongs to your account; each device has its own Push URL. You can regenerate both in the app.
GET | POST https://api.hookable.cc/functions/v1/push/{recipient_id}Send with GET
The shortest way to send. Use curl's --data-urlencode so spaces and special characters are encoded for you.
curl -G "https://api.hookable.cc/functions/v1/push/rcp_..." \
-H "Authorization: Bearer hk_..." \
--data-urlencode "title=Deploy complete" \
--data-urlencode "body=main succeeded (2m 13s)"Send with POST JSON
Besides title and body you can send data (any JSON object, up to 4KB). data is shown as-is in the history detail, and data.url becomes the link opened when the notification is tapped.
curl -X POST "https://api.hookable.cc/functions/v1/push/rcp_..." \
-H "Authorization: Bearer hk_..." \
-H "Content-Type: application/json" \
-d '{"title":"Deploy complete","body":"main succeeded (2m 13s)","data":{"url":"https://ci.example.com/build/123"}}'Open links and deep links
Set url and the link opens the moment the notification is tapped. Web addresses (https) open in the browser or in an app connected through universal links or app links, and custom schemes such as myapp:// open that app. If the scheme is missing or unsafe (javascript:, file:, intent:, …), the notification is sent without a link. Addresses with spaces or non-ASCII characters are encoded for you. When sending with GET, use --data-urlencode so &, #, and + inside the url survive.
curl -X POST "https://api.hookable.cc/functions/v1/push/rcp_..." \
-H "Authorization: Bearer hk_..." \
-H "Content-Type: application/json" \
-d '{"title":"Deploy complete","url":"https://github.com/me/app/actions/runs/123"}'
# App deep link
curl -G "https://api.hookable.cc/functions/v1/push/rcp_..." \
-H "Authorization: Bearer hk_..." \
--data-urlencode "title=Deploy complete" \
--data-urlencode "url=myapp://orders/1042"Attach an image
Set image to an https image address to attach a picture to the notification and show it in the history detail. JPEG, PNG, and GIF (plus HEIC on iOS) up to 10MB work best. Images are never stored on Hookable's servers — the phone downloads them directly and falls back to text if it can't.
curl -X POST "https://api.hookable.cc/functions/v1/push/rcp_..." \
-H "Authorization: Bearer hk_..." \
-H "Content-Type: application/json" \
-d '{"title":"Deploy complete","image":"https://example.com/chart.png"}'Send from a browser
The send API allows CORS, so JavaScript on a web page can call it directly. To try it, use the Send from web page. Code that contains your API key exposes it to anyone who can view the page, so keep it to tools only you use, such as local scripts or an internal dashboard. Send from web →
await fetch("https://api.hookable.cc/functions/v1/push/rcp_...", {
method: "POST",
headers: { Authorization: "Bearer hk_...", "Content-Type": "application/json" },
body: JSON.stringify({ title: "Deploy complete", body: "main succeeded (2m 13s)" }),
});Receive webhooks as-is
JSON without title or body keys is still turned into a notification: common keys such as subject, name, message, text, and content are detected. The raw JSON stays viewable in the notification detail for 30 days. Point any service that already sends webhooks at your Push URL.
curl -X POST "https://api.hookable.cc/functions/v1/push/rcp_..." \
-H "Authorization: Bearer hk_..." \
-H "Content-Type: application/json" \
-d '{"event":"invoice.paid","message":"Invoice #1042 paid"}'Parameters
| Name | Description |
|---|---|
title | Notification title, up to 64 characters |
body | Notification body, up to 256 characters |
image | Image https URL, up to 2048 characters. Invalid URLs are ignored and the text is still sent |
url | Link opened when the notification is tapped: an https URL or an app deep link like myapp://, up to 2048 characters. POST also accepts data.url |
shortcut | Name of an iOS Shortcut to run from the notification |
urgent | true bypasses quiet hours and keyword mutes |
data | POST only. Any JSON object, up to 4KB |
Responses and errors
| Status | Body | Meaning |
|---|---|---|
| 200 | {"ok":true,"delivered":1} | Handed to FCM/APNs. During quiet hours or a mute, delivered is 0 and a code is included |
| 400 | payload_too_large | Request over 32KB or data over 4KB |
| 401 | missing_api_key / invalid_api_key | No API key, or the key is not from this device's account |
| 404 | invalid_recipient | Unknown or regenerated Push URL |
| 429 | rate_limited | More than 30 sends a minute to one device |
| 429 | quota_exceeded | Monthly send limit reached |
Limits
| Sends per month | Free 100 · Pro 10,000 |
|---|---|
| Burst | 30 per minute per device |
| History | Free: last 30 per device · Pro: last 10,000 per account |
| Request size | 32KB (data 4KB) |
Use it from an AI agent
Copy the AI agent skill from the My tab in the app and paste it into Claude Code, Codex, Cursor, or any agent's chat, or save it to CLAUDE.md / AGENTS.md. The agent will push to your phone when it finishes a task or needs your input. The skill contains your sender API key, so share it only with agents you trust.
A summary for AI tools is at /llms.txt and the full documentation at /llms-full.txt. Pricing →